A point is represented by an array with 2 elements. The first element is x, the second element is y.
Maker.js uses the same coordinate system from basic mathematics and traditional drafting, where x values increase from left to right, and y values increase from bottom to top. Negative values are allowed.
Note that the SVG coordinate system is slightly different (Y values increase from top to bottom, and negative values do not appear), but Maker.js will handle that for us automatically.
A path is represented by an object with these mandatory properties:
- type: string - "line", "circle", or "arc"
- origin: point
A line is a path with the type "line" and this additional property:
- end: point
A circle is a path with the type "circle" and this additional property:
- radius: number
An arc is a path with the type "arc" and these additional properties:
- radius: number
- startAngle: number
- endAngle: number
Note: Property names are case-sensitive.(additional optional properties covered in advanced lessons)
Basic rendering in SVG
Call the makerjs.exporter.toSVG function and pass your path as a parameter:
You may also call makerjs.exporter.toSVG with an array of paths as a parameter:
Models are the heart of Maker.js. A model is represented by an object with these optional properties:
- origin: point
- paths: object map of paths
- models: object map of models
Let's look at paths first, using the example above.
Note that we can also pass a model to makerjs.exporter.toSVG.
If we wrap our model code in a function we can call it multiple times. There are several ways to do this. First we will leave the code as is, and return the model variable.
Alternatively, we can change our function to be usable with the new operator, and our model properties are set using the this keyword:
The example output should be the same as above. While we changed the way we defined our model, we haven't yet changed the functionality:
Now we are better set up to look at models and origin. We will create a new model which has 2 instances of myModel:(additional optional properties covered in advanced lessons)
We also illustrated 3 ways of defining an object: using a var, using a function that returns a var, and using a constructor function (for use by the new keyword). Let's revisit our simple line path example, and convert it to a constructor function.
Of course this example is not very useful because it only produces a line with the same origin and end every time. Instead, these should be passed as parameters.
Since this is a common scenario, Maker.js provides constructors for all primitive paths: line, circle and arc:
Path independence and Chains
All paths in a drawing are atomic elements of either line, arc, or circle. Paths may happen to touch each other or they may not. When any two paths have the same endpoint, this is called a chain. A chain can continue with any number of paths that meet end to end. If the chain begins and ends at the same point, this is called an endless chain.
Chains are an important concept that we will build upon, yet they are not a thing that you specify in your code. Rather, chains are "found" by Maker.js when it processes your drawing model. Paths in your drawing model are independent elements which may be added, modified or deleted by you or another developer. As you work with paths, bear in mind that you are also implicitly working with chains.
Maker.js provides these fundamental models:
Models and paths can be moved to an absolute location, or moved by an [x, y] amount relative to their current location. Keep in mind that since paths are contained within models, and models may be contained within models, that their coordinates will be relative to the containing model.
To illustrate this, let's create a model that has a few squares:
The way to move a model to an absolute position is to set its origin property. The makerjs.model.move function does just that, but it also lets you do more operations on one line of code.
To move a model by a relative amount, use makerjs.model.moveRelative:
Notice that the 2nd square had an origin of [120, 0] but we moved a line within the square to an absolute point [30, 20]. Since the line is contained within the square model, its coordinates are in terms of the square, which is why it appears to be at [150, 20].
Given the fundamental models and ability to move instances of them, we can now start modeling. Here are a few examples to illustrate how you might use these:
Circular adapter plate:
It's Just JSON
Now let's pass tabletFaceMount through JSON.stringify and look at the result:
We can copy and paste this same JSON and re-use it directly as a model:
Note that you might obtain JSON from some other source, perhaps generated by a tool. The only requirement for it to work with Maker.js is it must have the properties as described above.
Paths and points are unitless. Models may also be unitless, or they may specify a unit system. When it comes time to make your model on a laser cutter or waterjet etc., you will probably want to specify units. You can do this two different ways:
- Specify units during export. [See exporting for details per format.]
- Specify units on your model.
To specify units on your model, add a
units property to it with a value from the makerjs.unitType object:
These properties are case sensitive. They contain the values "cm", "foot", "inch", "m" and "mm" respectively. It is your choice whether to use the named property or the string value directly.
If a model that you wish to use has a different unit system than your own model, you can call makerjs.model.convertUnits(modeltoScale: model, units: string). to convert it.
Let's use our skateboard example above and mix Inch and Centimeter units:
Browse to the makerjs.measure module documentation to see all functions related to measuring.
To get the bounding rectangle of a path or a model, use:
- makerjs.measure.pathExtents(path: object)
- makerjs.model.modelExtents(model: object)
These functions return a measurement object with high and low points.
Measure path example:
Measure model example:
Frequently used functions
It's good to be aware of these functions which apply to many drawing scenarios. Also, browse the APIs of each module for lesser used specialized functions.
Functions for working with points in the makerjs.point module:
Add two points together and return the result as a new point.
Subtract a point from another point and return the result as a new point.
Get the average of two points and return the result as a new point.
Get a point from its polar coordinates: angle (in radians) and radius.
Given a reference point and an array of points, find the closest point in the array to the reference point.
Proportionately scale a point and return the result as a new point.
Disproportionately scale a point and return the result as a new point.
Rotate a point and return the result as a new point.
Return the two end points of a given path (null if path is a circle).
Functions for working with angles in the makerjs.angle module:
Convert an angle from radians to degrees.
Convert an angle from degrees to radians.
Given a line, returns its angle in degrees.
Given two points, returns the angle of the line through them, in degrees.
Given two points, returns the angle of the line through them, in radians.
Given a polar angle in degrees, returns the same angle cast between -360 and 360. For example, 725 degrees = 5 degrees.
Given an arc, returns total angle span between its start and end angles.
Functions for working with measurements in the makerjs.measure module:
Calculates the distance between two points using the Pythagorean theorem.
Measures the length of a path.
Given two points, determine if they are equal within a distance of accuracy.
Given two measurements, determine if they are overlapping. Also known as "bounding box overlap".
Given two angles, determine if they are equal within a margin of accuracy.
Next: learn more in Intermediate drawing.