Skip to content

Vibe coding a plugin? Teach your agent Modlumi first. Works with Claude Code, Codex, Cursor and more.

Geometry

Lengths are meters, areas square meters and angles radians, whatever unit the document displays. modlumi.mm(), modlumi.inches() and their inverses convert other units:

const { inches, mm, toMm } = modlumi;
console.log(mm(1000)); // 1
console.log(inches(12)); // about 0.3048
console.log(toMm(0.25)); // 250

Point3d, Vector3d and Transformation are immutable values. Wherever the API takes a point or vector, an [x, y, z] array works too.

const { Point3d, Vector3d } = modlumi;
const a = new Point3d(0, 0, 0);
const b = new Point3d(3, 4, 0);
const offset = a.vectorTo(b); // Vector3d
console.log(offset.length); // 5
console.log(a.offset(new Vector3d(0, 0, 1)).toArray()); // [0, 0, 1]
console.log(a.distance([0, 0, 2])); // 2

To show or read lengths the way the document does, use the model’s units:

const model = modlumi.activeModel;
console.log(model.units.lengthUnit); // "m", "mm", "in", ...
console.log(model.formatLength(1.2)); // "1.200 m"
console.log(model.parseLength("18cm")); // 0.18
console.log(model.parseLength("2")); // 2 meters, or 2 inches in an inch model

parseLength reads what the measurements box reads, and returns null for text that isn’t a length.

Drawing elements and drawing contexts have bounds, a BoundingBox in their own coordinates. Groups, instances and contexts tell whether they hold a closed solid, and its volume:

const model = modlumi.activeModel;
const box = model.operation("Box", () => model.entities.addBox([0, 0, 0], 2, 3, 4));
console.log(box.bounds?.height); // 4
console.log(box.isSolid, model.formatVolume(box.volume ?? 0)); // true "24.000 m³"

A face’s area and an edge’s length are measured in their own context. For a scaled group or instance, or in world coordinates, pass the transformation:

const model = modlumi.activeModel;
const world = model.activeTransformation;
for (const face of model.activeEntities.ofType("Face")) {
console.log(model.formatArea(face.transformedArea(world)));
}

model.raytest() finds the first face a ray hits in world coordinates, with the groups and instances it is in. It skips hidden faces unless you pass { includeHidden: true }, and always skips faces on hidden layers:

const model = modlumi.activeModel;
const hit = model.raytest([0, 0, 100], [0, 0, -1]);
if (hit) {
console.log(`Hit ${hit.face} at ${hit.point}, inside ${hit.path.length} containers`);
}

entities.addEdges(points) draws connected segments through two or more points. New segments split existing edges where they cross, and a segment across a face splits it. As with SketchUp’s add_edges, closing an outline makes no face: draw faces with addFace(), or fill the regions around an edge with entities.findFaces(edge):

const model = modlumi.activeModel;
const edges = model.operation("Rectangle", () =>
model.activeEntities.addEdges([[0, 0, 0], [4, 0, 0], [4, 3, 0], [0, 3, 0], [0, 0, 0]]),
);
const faces = model.operation("Fill", () => model.activeEntities.findFaces(edges[0]));
console.log(edges.length, "edges and", faces.length, "face");

The returned edges are the ones that lie on the segments you asked for, in model order. Splits mean there isn’t always one edge per segment.

A curve is a chain of edges edited as one, like a stroke of the Freehand tool. addCurve() draws one through points, addArc() draws a circular arc as one, and weld() joins existing edges:

const model = modlumi.activeModel;
const e = model.activeEntities;
model.operation("Curves", () => {
e.addCurve([[0, 0, 0], [1, 0.5, 0], [2, 0, 0]]);
// A quarter circle of radius 2, from the X axis toward Y, in six segments.
const [arc] = e.addArc([5, 0, 0], 2, 0, Math.PI / 2);
console.log(arc.edges.length); // 6
const loose = [...e.addEdges([[0, 3, 0], [1, 3, 0]]), ...e.addEdges([[1, 3, 0], [2, 4, 0]])];
e.weld(loose);
});

The shape methods of Entities draw a closed outline and return the face it bounds, ready to extrude:

Method Draws
addRectangle(origin, width, height) A rectangle with one corner at origin
addCircle(center, radius) A true circle, with an ArcCurve boundary
addPolygon(center, radius, sides) A regular polygon with its corners at radius
addFace(points) Any planar outline; it closes itself
const model = modlumi.activeModel;
const [floor, disc] = model.operation("Shapes", () => [
model.entities.addRectangle([0, 0, 0], 4, 3),
model.entities.addCircle([6, 1.5, 0], 1),
]);
console.log(floor.area, disc.outerLoop.edges.length); // 12 24

Shapes lie flat with their front facing up unless you pass a normal. On a tilted plane, the first axis (a rectangle’s width) is horizontal and the second points up; pass xAxis to choose the first axis yourself. Round shapes take segments, 24 by default.

const model = modlumi.activeModel;
const windowFace = model.operation("Window", () =>
// Stands upright in the XZ plane, facing the negative Y direction.
model.entities.addRectangle([1, 0, 1], 1.2, 0.9, { normal: [0, -1, 0] }),
);
console.log(String(windowFace.normal)); // Vector3d(0, -1, 0)

The front of a new face is the side you named with normal; for addFace it is the side the points run counterclockwise around. Shapes merge with what they touch, like addEdges: a rectangle drawn on a wall cuts its own face out of the wall. The methods throw ModelError when the outline doesn’t end up bounding exactly one face, for example when it crosses an existing edge. face.reverse() swaps a face’s front and back.

face.extrude(distance) does what the Extrude tool does. A positive distance moves along the face’s normal:

const model = modlumi.activeModel;
const cap = model.operation("Box", () => model.entities.addRectangle([0, 0, 0], 4, 3).extrude(2));
console.log("Top face area:", cap?.area);
  • The result is the cap face. Keep it for further extrusions, because the original face may be replaced.
  • A distance of zero returns the same face and adds nothing to the history.
  • Extruding into a solid until you reach the opposite side cuts a hole and returns null.
  • Concave faces and faces with holes are supported. Going past the first parallel opposite face, or into geometry Extrude doesn’t support, throws ModelError.
  • Extruding a face inside a component changes the shared definition, so every instance changes.

face.sweep(path) does what the Sweep tool does: it carries the face along a path of points. The swept surface replaces the face, so the face you called it on is deleted afterward.

const model = modlumi.activeModel;
model.operation("Rail", () => {
const profile = model.entities.addRectangle([0, -0.05, -0.05], 0.1, 0.1, { normal: [1, 0, 0] });
profile.sweep([[0, 0, 0], [2, 0, 0], [2, 2, 0], [2, 2, 1]]);
});

Repeat the first point at the end to close the path. A closed path around an axis through the face’s own vertices revolves the face around that axis.

entities.fillet(edges, radius), entities.chamfer(edges, distance) and entities.bevel(edges, faces, distance) do what the Fillet, Chamfer and Bevel tools do. A fillet takes an optional segments count, 1 to 64, which defaults to 6. A bevel measures distance along a reference face next to each edge: pass one face shared by all the edges, or one face per edge. Its options set the angle from that face in degrees, 45 by default, or a secondDistance along the other face.

const model = modlumi.activeModel;
model.operation("Tabletop", () => {
const top = model.entities.addBox([0, 0, 0], 1.6, 0.9, 0.04);
top.entities.fillet(top.entities.ofType("Edge"), 0.01, { segments: 4 });
});
model.operation("Plinth", () => {
const plinth = model.entities.addBox([2, 0, 0], 1, 1, 0.2);
// Bevel the rim of the top face, measuring 5 cm across it at 30 degrees.
for (const face of plinth.entities.ofType("Face").filter((f) => (f.normal?.z ?? 0) > 0.5)) {
plinth.entities.bevel(face.loops[0].edges, face, 0.05, { angle: 30 });
}
});

Each edge must join two faces that aren’t coplanar, and each edge end must be a corner where exactly three edges meet. A size that doesn’t fit throws ModelError and changes nothing.

addBox, addCylinder, addCone and addSphere each add a finished solid as a Group:

const model = modlumi.activeModel;
model.operation("Table", () => {
const entities = model.entities;
entities.addBox([0, 0, 0.7], 1.6, 0.8, 0.05);
for (const [x, y] of [[0.1, 0.1], [1.5, 0.1], [1.5, 0.7], [0.1, 0.7]]) {
entities.addCylinder([x, y, 0], 0.03, 0.7);
}
});

A box starts at a corner; the round solids start at the center of their base, and a sphere at its center. They take the same normal, xAxis and segments options as shapes: normal is the direction the height runs, so addCylinder([0, 0, 1], 0.1, 2, { normal: [1, 0, 0] }) lies along the X axis.

Because solids are groups, they never merge with geometry they touch. Inside the group the solid sits at the origin with its height along Z, and the group’s transformation places it. To move or turn one afterward, see Moving and rotating. The facet edges of round solids are soft, so the surface shows no lines; edge.soft reads and changes that.

  • entities.offsetFace(face, distance) draws a face’s outline moved into the face, or out of it for a negative distance, like the Offset tool.
  • entities.mergeCoplanarFaces() erases the edges between faces in one plane, merging them. By default only faces with the same materials merge.
  • entities.explode(containers) replaces groups and component instances with their contents.
  • instance.makeUnique() and group.makeUnique() give a container its own copy of a shared definition before you edit it.
const model = modlumi.activeModel;
const e = model.activeEntities;
model.operation("Inset", () => {
const slab = e.addRectangle([0, 0, 0], 4, 3);
e.offsetFace(slab, 0.5);
});

Drawing faces one by one merges each with what it touches, which gets slow for thousands of faces. A MeshBuilder collects points and polygons, and entities.addMesh() adds them all at once, sharing vertices and edges between polygons. The mesh doesn’t merge with existing geometry, so add it to an empty group:

const model = modlumi.activeModel;
const mesh = new modlumi.MeshBuilder();
/** @param {number} x @param {number} y */
const height = (x, y) => 0.2 * Math.sin(x) * Math.cos(y);
for (let x = 0; x < 20; ++x) {
for (let y = 0; y < 20; ++y) {
mesh.addPolygon([
[x, y, height(x, y)],
[x + 1, y, height(x + 1, y)],
[x + 1, y + 1, height(x + 1, y + 1)],
[x, y + 1, height(x, y + 1)],
]);
}
}
const faces = model.operation("Terrain", () =>
model.entities.addGroup().entities.addMesh(mesh, { smoothAngle: Math.PI / 6 }),
);
console.log(faces.length); // bent quads split into two triangles each

Assigning a vertex’s position moves it; entities.moveVertices() moves many vertices, each by its own offset, in one step. Faces that the moves bend out of their plane fold into planar faces, as they do with the Move tool. entities.splitEdge() splits an edge at a point or at a parameter from 0 to 1, and edges have soft and smooth flags to assign.

const model = modlumi.activeModel;
const e = model.activeEntities;
model.operation("Wave", () => {
const plate = e.addGroup();
plate.entities.addRectangle([0, 0, 0], 4, 1);
const vertices = plate.entities.vertices;
// Lift each corner by its distance from the origin along X.
plate.entities.moveVertices(vertices, vertices.map((vertex) => [0, 0, vertex.position.x / 8]));
});

The solid tools combine groups and component instances that are closed solids. isSolid tells whether one is, and volume gives the volume it encloses in cubic meters. Each tool on Entities replaces its inputs with new groups:

Method Result
union(solids) Everything inside any of them
subtract(target, cutter) target with cutter removed
intersect(solids) Only what all of them share
trim(target, cutter) Like subtract, but cutter stays
split(first, second) Up to three groups: only in first, in both, only in second
outerShell(solids) The outside of their union, without inner faces or hollows
const model = modlumi.activeModel;
const plate = model.operation("Drilled plate", () => {
const entities = model.entities;
let plate = entities.addBox([0, 0, 0], 1, 0.6, 0.05);
for (const x of [0.2, 0.5, 0.8]) {
const drill = entities.addCylinder([x, 0.3, -0.01], 0.05, 0.07);
plate = entities.subtract(plate, drill);
}
return plate;
});
console.log(`${((plate.volume ?? 0) * 1000).toFixed(1)} liters`); // 28.8 liters

A tool throws ModelError and changes nothing when an input isn’t a solid or the result wouldn’t be one. Imported meshes whose faces aren’t quite flat can cause that.

intersectWith(elements, others) is Intersect Faces: it adds edges to the context where the faces among elements cross those among others, and returns the edges along the crossings. Groups and components contribute their faces without changing. Leave out others to intersect the elements with each other.

entities.erase(entity) erases one entity. entities.eraseEdges(edges) erases several edges at once and heals the faces around them. Erasing any edge of a curve this way erases the whole curve.

Build a transformation and apply it to elements of one context with transformEntities. Edges that share a vertex stay connected:

const { Transformation } = modlumi;
const model = modlumi.activeModel;
model.operation("Square", () => {
model.activeEntities.addFace([[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0]]);
});
const elements = model.activeEntities.toArray().filter((e) => e.type !== "Guide");
const move = Transformation.translation([2, 0, 0]);
const turn = Transformation.rotation([2, 0, 0], [0, 0, 1], Math.PI / 4);
model.operation("Move and turn", () => {
model.activeEntities.transformEntities(turn.multiply(move), elements);
});

a.multiply(b) composes two transformations, applying b first. Multiplying a point includes the translation, and multiplying a vector doesn’t. The transformation is in the coordinates of the Entities you call it on.

Transformation.scaling() takes one factor, or one per axis, and an origin to scale about; Transformation.axes() maps local coordinates to a frame. A transformation’s origin and xAxis, yAxis and zAxis tell where it puts them:

const { Transformation } = modlumi;
const stretch = Transformation.scaling([2, 1, 0.5], [1, 1, 0]);
console.log(String(stretch.multiply(new modlumi.Point3d(2, 2, 2)))); // Point3d(3, 2, 1)
console.log(String(stretch.xAxis)); // Vector3d(2, 0, 0)

To move a whole group or component instance, change its transformation:

  • container.transform(t) applies t on top of the current transformation.
  • container.transformation = t replaces the transformation.

Both work in the parent’s coordinates and leave the shared definition unchanged.

copyEntities copies elements with a transformation and returns the copies. Face boundaries, complete curves and holes come along, groups and instances keep their definitions, and copies don’t merge with geometry they overlap. This makes a radial array of six copies around the Z axis:

const { Transformation } = modlumi;
const model = modlumi.activeModel;
const post = model.operation("Post", () =>
model.activeEntities.addFace([[3, 0, 0], [3.2, 0, 0], [3.2, 0.2, 0], [3, 0.2, 0]]),
);
const elements = [post, ...post.outerLoop.edges];
const count = 6;
model.operation("Radial array", () => {
for (let i = 1; i < count; i++) {
const angle = (2 * Math.PI * i) / count;
model.activeEntities.copyEntities(Transformation.rotation([0, 0, 0], [0, 0, 1], angle), elements);
}
});