Cavalry Module

Pro Feature

Pro features are only available with a Professional licence. To upgrade, visit cavalry.scenegroup.co.

Introduction​

This module gives access to the Path class, functions for creating noise and random numbers along with a number of utilities to make working with color easier, and, a whole host of maths functions such as clamp, norm, map and dist. The following methods are available to the JavaScript Utility, and the JavaScript Editor. Everything in this module is in the cavalry namespace and so methods need prefixing with cavalry. e.g var distance = cavalry.dist(0,0,100,200);

The examples given are for use in the JavaScript Editor (less setup required to run examples).

Member Functions​

Path Class​

The Cavalry module contains a Path class which can be used to construct paths which can then be drawn on screen. Path itself contains several methods.

Several of these methods use the word 'param' or 'parameter'. This is a number between 0..1 which represents a progression along the curve's control cage from 0 (the beginning) to 1 (the end). The control cage, formed by the curve's control points, outlines the basic shape of the curve. Note that a 'param' value of 0.5 does not necessarily represent a position half way along the curve. This is because the relationship between the param value and the curve's length is not linear due to the influence of the curve's control points and its resulting shape. To convert length values into param values, use paramAtLength.

Copying Shapes

Right clicking on a Shape in the Viewport and choosing Copy as JavaScript will copy the Shape's information to the clipboard as JavaScript code.

Drawing a path:​

var path = new cavalry.Path();path.moveTo(0.,0.);path.lineTo(0.,-100.);path.lineTo(300.,-100.);path.cubicTo(210., 110., 240., 140., 280., 260);path.close();path.translate(-300,-30);path.addText("hello world", 274, -700, 300);path.addRect(-300,-300,-200,-250);path.addEllipse(250, -300, 100,60);// this path can then be returned if on the JavaScript layer// or used to create an Editable Shape like soapi.createEditable(path, "My Path");

moveTo(x:number, y:number)​

Start a new contour.

lineTo(x:number, y:number)​

Draw a line to x,y.

cubicTo(cp1X:number, cp1Y:number, cp2X:number, cp2Y:number, endX:number, endY:number)​

Draw a cubic bezier with two control points and an end point.

conicTo(cp1X:number, cp1Y:number, andX:number, endY:number, weight:number)​

Adds a conic to the path. Where weight:

• = 1 - the curve is a quadratic Bézier curve (a conic with a weight of 1 is mathematically equivalent to a quadratic curve).
• < 1 - the curve approximates an ellipse. The smaller the weight, the more the curve leans towards being circular, with smaller weights resulting in sharper curves.
• > 0 - the curve begins to resemble a hyperbola. As the weight increases, the curve opens up more.
• = 0 (or a very low value) - these may produce degenerate cases or curves that don't visually change much from a straight line or a very sharp curve.

Convert any conic verbs to quad verbs. This might be useful as not all features in Cavalry support conic verbs.

close()​

Close the path.

Add text to the path and position it. The text could be added to a separate path and then .append() it into this one if needed. The position arguments may be removed as a result of this.

var path = new cavalry.Path();path.addText("hello world", 274, -700, 300);api.createEditable(path, "My Path");

Convenience method for drawing a rectangle.

Convenience method for drawing an ellipse.

Empty the path.

isClosed → bool​

Returns a boolean signifying if the path is closed.

translate(x:number, y:number)​

Move the path by x and y.

Rotate the path.

Scale the path.

intersect(intersectPath:path)​

Perform a Boolean intersection.

unite(unitePath:path)​

Perform a Boolean unite.

difference(differencePath:path)​

Perform a Boolean difference.

The below example can be set on the JavaScript Shape.

function boolTest() {    var mainPath = new cavalry.Path();    mainPath.addRect(-100,100,100,-100);        var boolTest = new cavalry.Path();    boolTest.addEllipse(0,0,200,40);    mainPath.difference(boolTest);    return mainPath;}boolTest();

convertToCurves()​

Resample lines as curves (the algorithm used by the Pencil Tool).

convertToLines(linesPerCurve:int)​

Convert (vectorise) any curves into a series of lines.

toObject() → object​

Converts the Path to an object that can be saved.

var path = new cavalry.Path();path.moveTo(0.,0.);path.lineTo(0.,-100.);path.lineTo(300.,-100.);// Convert to an Objectvar js = path.toObject();// Convert from a saved objectpath.fromObject(js);console.log(path.length);

Sets the path from an object.

var path = new cavalry.Path();path.moveTo(0.,0.);path.lineTo(0.,-100.);path.lineTo(300.,-100.);// Convert to an Objectvar js = path.toObject();// Convert from a saved objectpath.fromObject(js);console.log(path.length);

Draw an arc with two control points and a radius.

back → {x:number, y:number}​

Return an object containing x and y keys describing the final point in a path.

var path = new cavalry.Path();path.addText("Cavalry", 30, 0, 10);console.log(JSON.stringify(path.back));

boundingBox() → {x:number, y:number, width:number, height:number, centre:{x:number, y:number}, left:number, right:number, top:number, bottom:number}​

Return the bounding box of a path.

var path = new cavalry.Path();path.addText("Some text!", 22, 0, 10);let bbox = path.boundingBox();console.log(JSON.stringify(bbox));

empty() → bool​

Return if a path is empty or not.

pointCount() → int​

Return the number of points in the path.

contains(x:number, y:number) → bool​

Return if the point specified by x,y is inside the path (only works on a closed path).

pathData() → object​

This returns an array of dictionaries and provides a convenient way to iterate and change an existing path as opposed to creating a new Path Class. Each dictionary contains the verb type variable e.g. moveTo or lineTo along with any 'point' objects relevant to the verb.

The dictionary will contain different objects depending on the verb type:

• moveTo: contains a point object (with x and y variables).
• lineTo: contains a point object (with x and y variables).
• quadTo: contains a cp1 object representing the control point (with x and y variables) along with a point object (with x and y variables). This is the end point of the quadTo verb.
• cubicTo: contains cp1 and cp2 objects representing the first and second control points (both with x and y variables) along with a point object (with x and y variables). This is the end point of the cubicTo verb.
• close: contains no points.

setPathData(data:object)​

Set the path based on a pathData object.

offset(distance:number, round:bool)​

Grow or shrink a closed Path. The round argument determines whether the joins of the rebuilt Path's line segments are rounded or not.

function getPath() {    var path = new cavalry.Path()    path.addRect(0, 0, 200, 200);    path.offset(n0, true);    return path;}getPath();

trim(start:number, end:number, travel:number, reverse:bool)​

Reduce the length of a Path by clipping it from its start/end points.

function getPath() {    var path = new cavalry.Path()    path.addEllipse(0,0,200,200);    path.trim(0.2, 0.5, 0.0, false);    return path;}getPath();

resample(edgeLength:number)​

Rebuilds the path by sampling points based on a desired 'edgeLength'.

/*1. Create a Text Shape.2. Click the + button on the Text Shape's 'Deformers' attribute and choose 'JavaScript Deformer'.3. Paste the below into the JavaScript expression.*/var depth = 3;var frequency = 5;var multiplier = n0;var meshes = def.getMeshesAtDepth(depth);for (var mesh of meshes) {    var path = mesh.getPathAtIndex(0);    path.resample(5);        var pd = path.pathData();    for (var idx = 0; idx < pd.length; idx++) {        if (idx % frequency == 0) {            let line = new cavalry.Line(0,0,pd[idx].point.x, pd[idx].point.y);            line.setLength(line.length()+multiplier);            pd[idx].point = line.end();        }    }    path.setPathData(pd);    mesh.setPathAtIndex(0, path);}def.setMeshesAtDepth(depth, meshes);

lineIntersections(cavalry.Line) → array[object]​

Returns an array of points at which the path and line intersect.

/*1. Create 2 Nulls, an Ellipse and a JavaScript Shape.2. Right click the JavaScript Shape's n0 attribute and choose 'Delete Selected Attribute'.3. Use the + button to add 2 x Double2 and 1 x Layer attributes.4. Connect each of the Null's positions to the Double2 attributes.5. Connect the Ellipse to the Layer attribute.6. Copy and paste the below into the JavaScript Shape's Expression.7. Move the Nulls outside the Ellipse.*/function getPath() {    var intersectionPath = n2.path;        var path = new cavalry.Path()    var line = new cavalry.Line(n0.x, n0.y, n1.x, n1.y);        var intersections = intersectionPath.lineIntersections(line);        for (let pt of intersections) {       path.addEllipse(pt.x,pt.y,20,20);    }    return path;}getPath();

pathIntersections(cavalry.Path) → array[object]​

Returns an array of points at which this path and the given path intersect.

/*1. Create a Star, an Ellipse and a JavaScript Shape.2. Use the + button under the JavaScript Shape's 'Javascript' tab to add 2 x Layer attributes.3. Connect the Star and Ellipse to the new Layer attribute.4. Copy and paste the below into the JavaScript Shape's Expression.5. Increase the Star's Radius.*/function getPath() {    var pathA = n1.path;    var pathB = n2.path;    var intersections = pathA.pathIntersections(pathB);        var path = new cavalry.Path()    for (let pt of intersections) {       path.addEllipse(pt.x,pt.y,20,20);    }    return path;}getPath();

Relax the points in the path away from each other.

// See 'Create > Demo Scenes > JavaScript > Differential Line Growth'.

smooth(iterations:int, smoothStrength:number)​

Smooths the points by averaging their positions.

// See 'Create > Demo Scenes > JavaScript > Differential Line Growth'.

scatter(numberOfPoints:int, seed:int, sequence:int, relaxIterations:int, relaxDistance:number) → array[object]​

Scatter points inside the path via dart throwing. Points are relaxed by default.

length() → number​

Return the length of the path.

pointAtParam(param:number) → {x:number, y:number}​

Return the position of a point at a given parameter along the path.

tangentAtParam(param:number) → {x:number, y:number}​

Return a point object with x,y variables that corresponds to a tangent a given parameter along the path.

normalAtParam(param:number) → {x:number, y:number}​

Calculate the normal vector at the given parameter along the path.

angleAtParam(param:number) → number​

Return an angle in degrees representing the tangent a given parameter along the path.

paramAtLength(length:number) → number​

Given a length, return the corresponding parameter value for that length value.

findClosestPoint(x:number, y:number) → {position:{x:number, y:number},tangent:{x:number,y:number},normal:{x:number,y:number}}​

Find the closest point on a path to the given x,y values and return an object with position, normal and tangent variables, each of which has x,y variables.

mergeOverlaps()​

Converts the path into a set of non-overlapping contours that describe the same area as the original path.

reverse()​

Reverses the Path direction.

var path = new cavalry.Path();path.moveTo(0.,0.);path.lineTo(0.,-100.);path.lineTo(300.,-100.);path.cubicTo(210., 110., 240., 140., 280., 260);path.close();console.log(path.isClockwise());path.reverse();console.log(path.isClockwise());

isClockwise() → bool​

Returns true if the path is clockwise.

var path = new cavalry.Path();path.moveTo(0.,0.);path.lineTo(0.,-100.);path.lineTo(300.,-100.);path.cubicTo(210., 110., 240., 140., 280., 260);path.close();console.log(path.isClockwise());path.reverse();console.log(path.isClockwise());

Line Class​

Represent a line defined by two points with various geometric operations.

var line = new cavalry.Line(0,0,100,100);console.log(line.length())
var line = new cavalry.Line(0,0,100,100);console.log(JSON.stringify(line.closestPointTo({"x":100,"y":50})))

For examples see the Closest Point, Intersections and Spikes Demo Scenes via the Create > Demo Scenes > JavaScript menu.

length() → number​

Gets the length of the line.

angle() → number​

Returns the angle of the line in degrees.

setLength(length:number)​

Sets the length of the line.

setAngle(angle:number)​

Sets the angle of the line in radians.

start() → {x:number,y:number}​

Retrieves the start point of the line.

end() → {x:number,y:number}​

Retrieves the end point of the line.

delta() → {x:number,y:number}​

Calculates the delta (difference in coordinates) between the start and end points of the line.

pointAt(param:number) → {x:number,y:number}​

Calculates the point at a given parameter along the line.

normalAt(param:number) → {x:number,y:number}​

Calculates the normal vector at a given parameter along the line.

translate({x:number,y:number})​

Translates the line by a given point vector.

distance({x:number,y:number}) → number​

Calculates the shortest distance from the line to a given point.

closestPointTo ({x:number,y:number}) → {x:number,y:number}​

Calculates the closest point on the line to a given point.

lineIntersection(cavalry.Line) → {x:number,y:number}​

Returns the point at which two lines intersect, or null if there's no intersection.

Point Cloud Class​

Represents a collection of Points. These objects can be used as Distributions on the Duplicator (for example) via a Custom Distribution.

See Create > Demo Scenes > JavaScript > Spirograph Distribution or Create > Demo Scenes > JavaScript > Circle Packing with Gradient Descent for examples.

appendPoint(point:Point)​

Append a Point to the cloud.

appendRotation(rotation:number)​

Append a rotation in degrees to the cloud. Make sure there's a corresponding point.

appendSize(point:Point)​

Append a size to the cloud. Make sure there's a corresponding point.

Point Class​

Represents a simple point for use in a Point Cloud.

See Create > Demo Scenes > JavaScript > Spirograph Distribution or Create > Demo Scenes > JavaScript > Circle Packing with Gradient Descent for examples.

Mesh Class​

The Mesh class is a container which can be used to construct multiple Paths and include materials. If unique Materials for each Path are not required, use path.append() to add Paths together.

Add a Path and Material to a Mesh.

count() → int​

Returns the number of paths in a Mesh.

empty() → bool​

Returns whether or not the Mesh is empty.

clear()​

Erases all Paths on the Mesh.

getBoundingBox() → {x:number, y:number, width:number, height:number, centre:{x:number, y:number}, left:number, right:number, top:number, bottom:number}​

Returns a standard bounding box object.

getPathDataAtIndex(index: int) → array[object]​

Returns a pathData array, which includes verbs and points. This data is designed for point level modification.

setPathAtIndex(index: int, path:Path object)​

Overwrite a path at a given index with a different Path object.

setPathDataAtIndex(index: int, pathData:object)​

Sets the pathData at a given depth and index.

setMaterialAtIndex(index: int, material: Material object)​

Overwrites the material at a given index with a different Material object.

function getMesh() {    var path = new cavalry.Path()    path.addEllipse(0,0,100,200);        var mesh = new cavalry.Mesh();    var material = new cavalry.Material();    material.fillColor = "#ff24e0";    material.stroke = true;    material.strokeColor = "#000000";    material.strokeWidth = 10;        mesh.addPath(path, material);    return mesh;}getMesh();

getPathAtIndex(index:int) → Path object​

Retrieves the Path object at the specified index. Useful for adding to a path.

// Open 'Create > Demo Scenes > JavaScript > Spikes'.

Adds a child-mesh to this Mesh.

clearChildMeshes()​

Deletes all the child-meshes on this Mesh.

childMeshCount() → int​

Returns the number of child-meshes.

getChildMeshAtIndex(index:int) → Mesh​

Returns the child-mesh at the given index.

Material Class​

Add materials (Fill and Stroke) to a Mesh.

fill(true:bool)​

Enable Fill (defaults to true).

stroke(true:bool)​

Enable Stroke (defaults to false).

fillColor(hex:string)​

Set the Fill's hex color.

strokeColor(hex:string)​

Set the Stroke's hex color.

strokeWidth(width:number)​

Set the Stroke's width.

Enable trim.

trimStart(startPoint:number)​

Set the start point of the trim (0..1).

trimEnd(endPoint:number)​

Set the end point of the trim (0..1).

trimTravel(travel:number)​

Move the trim along the path. 1.0 is a complete cycle of a closed path.

trimReversed(reverse:bool)​

Reverses the path direction for the trim effect.

// Example using the n0 Attribute to control the trim.function getMesh() {    var path = new cavalry.Path()    path.addEllipse(0,0,100,200);        var mesh = new cavalry.Mesh();    var material = new cavalry.Material();    material.fillColor = "#ff24e0";    material.stroke = true;    material.strokeColor = "#000000";    material.strokeWidth = 10;        material.trim = true;    material.trimStart = 0.45;    material.trimEnd = 0.75;    material.trimTravel = n0*0.01;    mesh.addPath(path, material);    return mesh;}getMesh();

Matrix Class​

Represent a 2D transformation matrix.

setPosition(x:number, y:number)​

Sets the position (translation) of the matrix.

setRotation(angle:number)​

Sets the rotation of the matrix in degrees.

setScale(x:number, y:number)​

Sets the scale factors of the matrix.

setSkew(x:number, y:number)​

Sets the skew factors of the matrix.

Return the skew.

scale → object​

Gets the scale factors of the matrix.

position → {x:number, y:number}​

Gets the position (translation) of the matrix.

rotation → number​

Gets the rotation of the matrix in degrees.

multiply(matrix:matrix) → matrix​

Returns a new matrix that is the result of multiplying this matrix with another matrix.

inverted → matrix​

Returns a new matrix that is the inverse of this matrix.

invert​

Inverts this matrix in place.

isFinite → bool​

Checks if all elements of the matrix are finite.

isIdentity → bool​

Checks if the matrix is an identity matrix.

mapRect(rect:object) → {x:number, y:number, width:number, height:number, centre:{x:number, y:number}, left:number, right:number, top:number, bottom:number}​

Maps a rectangle {x:number, y:number, width:number, height:number} using this matrix and returns the resulting rectangle.

mapPoint(point:object) → {x:number, y:number}​

Maps a point using this matrix and returns the resulting point.

mapPoints(points:array[object]) → array[object]​

Maps an array of points using this matrix and returns the resulting array of points.

var mat = new cavalry.Matrix();mat.setRotation(180);mat.setScale(2,2);let pt = {"x": 50, "y":0}let finalPt = mat.mapPoint(pt);console.log(JSON.stringify(finalPt));

setFromArray([number])​

Set the 3x3 matrix from an array of 9 numbers.

Example usage:

// Get the global position of a Shapelet shapeId = api.primitive("circle", "Circle");api.set(shapeId, {"position": [500,500]});let groupId = api.create("group");api.parent(shapeId, groupId);api.set(groupId, {"rotation": 45});let matArray = api.get(shapeId, "globalTransform");let matrix = new cavalry.Matrix();matrix.setFromArray(matArray);console.log(JSON.stringify(matrix.position()));

Math​

random(min:number, max:number, seed:int) → number​

Returns a random number

for (var i = 1; i < 10; i +=1){    console.log(cavalry.random(0, 10, i));}

uniform(min:number, max:number, seed:int) → number​

Returns random numbers with a uniform distribution.

for (var i = 1; i < 10; i +=1){    console.log(cavalry.uniform(0, 10, i));}

noise1d(x:number, seed:int, frequency:number) → number​

Returns 1d Improved Perlin noise.

for (var i = 1; i < 10; i +=1){    console.log(cavalry.noise1d(i, 0, 1));}

noise2d(x:number, y:number, seed:int, frequency:number) → number​

Returns 2d Improved Perlin noise.

for (var i = 1; i < 10; i +=1){    console.log(cavalry.noise2d(i, api.getFrame(), 0, 1));}

noise3d(x:number, y:number, z.number, seed:int, frequency:number) → number​

Returns 3d Improved Perlin noise.

for (var i = 1; i < 10; i +=1){    console.log(cavalry.noise3d(i, i+100, api.getFrame(), 0, 0.1));}

dist(x1:number, y1:number, x2:number, y2:number) → number​

Get the distance between two points.

var d = cavalry.dist(0,0,100,100)console.log(d);

map(value:number, inMin:number, inMax:number, outMin:number, outMax:number) → number​

Remap a value into a new range.

// remap 30 from the range 0..60 to the range 100..300. Prints 200.console.log(cavalry.map(30,0,60,100,300));

norm(value:number, min:number, max:number) → number​

Normalise a value between 0..1.

// Prints 0.55;console.log(cavalry.norm(55,0,100));

clamp(value:number, min:number, max:number) → number​

Clamp a value min and max.

// Prints 100;console.log(cavalry.clamp(150,0,100));

lerp(min:number, max:number, t:number) → number​

Interpolate between a minimum and maximum value. The value returned is the value at t (between 0 and 1).

angleFromVector(x:number, y:number) → number​

Convert a vector into an angle (radians).

var ang = cavalry.angleFromVector(1,0);console.log(ang);var vec = cavalry.vectorFromAngle(ang);console.log(vec["x"]+" "+vec["y"]);

vectorFromAngle(angle:number) → {x:number, y:number}​

Convert an angle (radians) into a vector (x, y) with values between 0..1.

var ang = cavalry.angleFromVector(1,0);console.log(ang);var vec = cavalry.vectorFromAngle(ang);console.log(vec["x"]+" "+vec["y"]);

Convert a value from radians to degrees.

console.log(cavalry.radiansToDegrees(2));

Convert a value from degrees to radians.

console.log(cavalry.degreesToRadians(90));

Color​

rgbToHsv(r:number, g:number, b:number, scaled=true) → {h:number, s:number, v:number}​

Convert an RGB color to HSV. If the scaled argument is set to true (default) then RGB values should be in the range 0..1. If set to false then RGB values should be in the 0..255 range.

var unscaled = cavalry.rgbToHsv(255,0,255, false);var scaled = cavalry.rgbToHsv(1,0,1, true);console.log('Unscaled = ' + JSON.stringify(unscaled) + ' - Scaled = ' + JSON.stringify(scaled));

rgbToHex(r:number, g:number, b:number, scaled=true) → string​

Convert an RGB color to a Hex string. If the scaled argument is set to true (default) then RGB values should be in the range 0..1. If set to false then RGB values should be in the 0..255 range.

const label1 = new ui.Label('Unscaled');label1.setTextColor("#"+cavalry.rgbToHex(255,0,255,false));ui.add(label1);const label2 = new ui.Label('Scaled');label2.setTextColor("#"+cavalry.rgbToHex(1,0,1,true));ui.add(label2);ui.show();

hsvToRgba(h:number, s:number, v:number, scaled=false) → {r:int, g:int, b:int, a:int}​

Convert an HSV color value to its RGBA representation, optionally scaled to the range of 0..1.

var result = cavalry.hsvToRgba(180,1,0.5);console.log(JSON.stringify(result));

hsvToHex(h:number, s:number, v:number) → string​

Convert a HSV color to a Hex string.

var result = cavalry.rgbToHex(79,253,122);console.log(result);

hexToRgba(hex:string, scaled=false) → {r:int, g:int, b:int, a:int}​

Converts a hex color value (e.g #ffffff) to its RGBA representation, optionally scaled to the range of 0..1.

var result = cavalry.hexToRgba("#fc5900");console.log(JSON.stringify(result));

hexToHsv(hexValue:string) → {h:number, s:number, v:number}​

Convert a Hex value (e.g #ffffff) color to HSV.

var result = cavalry.hexToHsv("#ff9801");console.log(JSON.stringify(result));

Text​

fontExists(fontFamily:string, fontStyle:string) → bool​

Returns true if a font is available to Cavalry.

console.log(cavalry.fontExists("Lato", "Regular")); // prints true

getFontFamilies() → [string]​

Returns a list of all the font families available to Cavalry.

console.log(cavalry.getFontFamilies());

getFontStyles(string:fontFamily) → [string]​

Returns a list of all the available styles for the given font family.

console.log(cavalry.getFontStyles("Lato"));

measureText(string:string, fontFamily:string, fontStyle:string, fontSize:int) → {width:number, height:number, x:number, y:number, centreX:number, centreY:number}​

Returns an object representing the bounding box of some text without the need to actually create a text shape.

• width - The width of the text
• height - The height of the text
• x - The left edge of the text
• y - The top edge of the text
• centreX - The average of the left and right edges
• centreY - The average of the top and bottom edges
const measure = cavalry.measureText("Some text to measure", "Lato", "Regular", 72);console.log(JSON.stringify(measure));

fontMetrics(fontFamily:string, fontStyle:string, fontSize:int) → {top:number, ascent:number, descent:number, bottom:number, leading:int, averageCharacterWidth:number, maxCharacterWidth:number, xMin:number, xMax:number, xHeight:number, capHeight:number}​

Returns an object containing information about the given font. The resulting metrics are scaled by the font size.

• top - greatest extent above origin of any glyph bounding box, typically negative; deprecated with variable fonts
• ascent - distance to reserve above baseline, typically negative
• descent - distance to reserve below baseline, typically positive
• bottom - greatest extent below origin of any glyph bounding box, typically positive; deprecated with variable fonts
• leading - distance to add between lines, typically positive or zero
• averageCharacterWidth - average character width, zero if unknown
• maxCharacterWidth - maximum character width, zero if unknown
• xMin - greatest extent to left of origin of any glyph bounding box, typically negative; deprecated with variable fonts
• xMax - greatest extent to right of origin of any glyph bounding box, typically positive; deprecated with variable fonts
• xHeight - height of lower-case 'x', zero if unknown, typically negative
• capHeight - height of an upper-case letter, zero if unknown, typically negative
const metrics = cavalry.fontMetrics("Lato", "Regular", 72);console.log(JSON.stringify(metrics));

Utilities​

versionLessThan(version:string) → bool​

This will return true if the version of Cavalry in use is less than the specified version. This is useful to add support for features in scripts that depend on the version of Cavalry.

// This will return true in Cavalry 1.3.1, and false in Cavalry 1.5.0console.log(cavalry.versionLessThan("1.4.0"));
SEMVER

Cavalry uses Semantic Versioning for version numbers.

MAJOR.MINOR.PATCH (e.g. 1.5.0) is used for official releases.

MAJOR.MINOR.PATCH.PRE-RELEASE-TYPE.NUMBER (e.g. 1.6.0-beta.1) is used for pre-release builds.

transformationMatrix() → matrix​

Returns the upstream local 2D transformation matrix, or null if there isn't one.

/*1. Create a Shape.2. On the Shape's Deformers attribute, click the + button and choose JavaScript Deformer.3. Copy the below in the JavaScript Deformer's Expression.*/var tm = ctx.transformationMatrix();console.log(tm.position().x);

globalTransformMatrix() → matrix​

Returns the upstream global 2D transformation matrix, or null if there isn't one.

/*1. Create a Shape.2. On the Shape's Deformers attribute, click the + button and choose JavaScript Deformer.3. Copy the below into the JavaScript Deformer's Expression.4. Group the Shape.*/var tm = ctx.globalTransformationMatrix();console.log(tm.position().x);