an isometric graphics library for HTML5 canvas
Isomer allows you to draw isometric graphics with ease. Let's draw a simple cube.
var Shape = Isomer.Shape;
var Point = Isomer.Point;
iso.add(Shape.Prism(new Point(0, 0, 0)));
Here is the same cube overlayed with a 3D grid. This is how objects look under an isometric projection.
/**
* This is the 3D isometric grid that
* we will be drawing on.
*
* The blue grid is the xy-plane.
* The red line is the z-axis.
*/
After a couple clever renames, we add a Shape.Prism to our
scene. The first argument is the position of our shape. In this case,
we use new Point(0, 0, 0) to place the cube at the origin.
(Note: we can also use Point.ORIGIN)
We can also specify a width, length, and height of our prism, but these all default to 1.
var Shape = Isomer.Shape;
var Point = Isomer.Point;
iso.add(Shape.Prism(Point.ORIGIN, 2, 1, 3));
Isomer contains a number of smaller classes, including Shape, Point, and Color. Instead of writing out "Isomer.Point" many times, I will often use the pattern "var Point = Isomer.Point" (for example)
This is just for convenience.
To start using Isomer, you first need to include a small (7kb minified) script wherever you see fit:
<script src="/path/to/isomer.min.js"></script>After which you'll need to place a canvas in your document that we can later refer to. Be sure to give it a width and height!
<canvas width="800" height="600" id="art"></canvas>Note: To improve the look of your canvas on retina displays, declare the width and height of your canvas element as double how you want it to appear. Then style your canvas with CSS to include the original dimensions.
#art {
width: 400px;
height: 300px;
}At this point we can finally instantiate an Isomer object. Pass it a reference to your canvas like so:
var iso = new Isomer(document.getElementById("art"));And you're ready to start drawing!
Isomer is divided into 3 basic components: points, paths, and shapes. A path consists of many points, and a shape consists of many paths. To get up and running, we can play with some of the built-ins.
These shapes take an origin point, followed by 3 measurements along the x, y, and z axes respectively. These measurements default to 1.
Prisms have six rectangular faces, a width, length, and height.
var Shape = Isomer.Shape;
var Point = Isomer.Point;
/* add() also accepts arrays */
iso.add([
Shape.Prism(Point.ORIGIN, 4, 4, 2),
Shape.Prism(new Point(-1, 1, 0), 1, 2, 1),
Shape.Prism(new Point(1, -1, 0), 2, 1, 1)
]);
Pyramids have a rectangular base and four triangles extending to the top.
var Shape = Isomer.Shape;
var Point = Isomer.Point;
iso.add([
Shape.Prism(Point.ORIGIN, 3, 3, 1),
Shape.Pyramid(new Point(0, 0, 1)),
Shape.Pyramid(new Point(0, 2, 1)),
Shape.Pyramid(new Point(2, 0, 1)),
Shape.Pyramid(new Point(2, 2, 1))
]);
Isomer makes it easy to add colors to your shapes: simply specify a
color as the second argument to add(). Colors are built
using three arguments: a red, green, and blue component respectively –
the RGB representation of the color.
var Shape = Isomer.Shape;
var Point = Isomer.Point;
var Color = Isomer.Color;
var red = new Color(160, 60, 50);
var blue = new Color(50, 60, 160);
iso.add(Shape.Prism(Point.ORIGIN, 3, 3, 1));
/* You can leave out the `new` keyword
for most Isomer classes */
iso.add(Shape.Pyramid(Point(0, 2, 1)), red);
iso.add(Shape.Prism(Point(2, 0, 1)), blue);
Paths are two-dimensional and are commonly used as the faces for shapes. You can draw and color paths just like you would shapes.
Creating a path involves specifying a list of points. The path will connect the last point to the starting point.
var Shape = Isomer.Shape;
var Path = Isomer.Path;
var Point = Isomer.Point;
var Color = Isomer.Color;
iso.add(Shape.Prism(Point.ORIGIN, 3, 3, 1));
iso.add(new Path([
Point(1, 1, 1),
Point(2, 1, 1),
Point(2, 2, 1),
Point(1, 2, 1)
]), new Color(50, 160, 60));
The method Shape.extrude accepts a path and a height
(default 1), and allows you to create a 3D model by popping out a 2D
path along the z-axis.
var Shape = Isomer.Shape;
var Path = Isomer.Path;
var Point = Isomer.Point;
var Color = Isomer.Color;
iso.add(Shape.Prism(Point.ORIGIN, 3, 3, 1));
iso.add(Shape.extrude(new Path([
Point(1, 1, 1),
Point(2, 1, 1),
Point(2, 3, 1)
]), 0.3), new Color(50, 160, 60));
All of the Isomer base classes (Point, Path, and Shape) support the following methods. They each return a new object from the one they were originally called on.
Translate accepts a distance in the x, y, and z directions. Translating does not modify the original shape.
var Shape = Isomer.Shape;
var Point = Isomer.Point;
var blue = new Isomer.Color(50, 60, 160);
var red = new Isomer.Color(160, 50, 60);
var cube = Shape.Prism(Point.ORIGIN);
iso.add(cube);
/* These methods do not modify the
original shape/path/point */
iso.add(cube.translate(0, 0, 1.1), blue);
iso.add(cube.translate(0, 0, 2.2), red);
Scale accepts a reference point, and 3 scaling factors in the x, y, and z directions respectively.
var Shape = Isomer.Shape;
var Point = Isomer.Point;
var blue = new Isomer.Color(50, 60, 160);
var cube = Shape.Prism(Point.ORIGIN);
iso.add(cube.scale(Point.ORIGIN, 3, 3, 0.5));
iso.add(cube
/* Grow outward from the origin */
.scale(Point.ORIGIN, 3, 3, 0.5)
/* We can chain these transformations */
.translate(0, 0, 0.6)
, blue);
RotateZ accepts an reference point, and an angle in radians on the xy-plane (where an angle of 0 runs along the position x-axis).
Note: To rotate an object about its center, you will need to specify the midpoint of the object as the reference point.
var Shape = Isomer.Shape;
var Point = Isomer.Point;
var blue = new Isomer.Color(50, 60, 160);
var cube = Shape.Prism(Point.ORIGIN, 3, 3, 1);
iso.add(cube);
iso.add(cube
/* (1.5, 1.5) is the center of the prism */
.rotateZ(Point(1.5, 1.5, 0), Math.PI / 12)
.translate(0, 0, 1.1)
, blue);
On GitHub. Made with <3 by @jdan. MIT Licensed.