Geometry
Units and values
Section titled “Units and values”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)); // 1console.log(inches(12)); // about 0.3048console.log(toMm(0.25)); // 250Point3d,
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); // Vector3dconsole.log(offset.length); // 5console.log(a.offset(new Vector3d(0, 0, 1)).toArray()); // [0, 0, 1]console.log(a.distance([0, 0, 2])); // 2To 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.18console.log(model.parseLength("2")); // 2 meters, or 2 inches in an inch modelparseLength reads what the measurements box reads, and returns null for
text that isn’t a length.
Measuring
Section titled “Measuring”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); // 4console.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`);}Drawing edges
Section titled “Drawing edges”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.
Curves and arcs
Section titled “Curves and arcs”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);});Drawing shapes
Section titled “Drawing shapes”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 24Shapes 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.
Extruding faces
Section titled “Extruding faces”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.
Sweeping faces
Section titled “Sweeping faces”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.
Rounding, chamfering and beveling edges
Section titled “Rounding, chamfering and beveling edges”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.
Solids
Section titled “Solids”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.
Offsetting, merging and exploding
Section titled “Offsetting, merging and exploding”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()andgroup.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);});Meshes
Section titled “Meshes”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 eachEditing vertices and edges
Section titled “Editing vertices and edges”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]));});Combining solids
Section titled “Combining solids”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 litersA 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.
Erasing
Section titled “Erasing”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.
Moving and rotating
Section titled “Moving and rotating”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)applieston top of the current transformation.container.transformation = treplaces the transformation.
Both work in the parent’s coordinates and leave the shared definition unchanged.
Copying elements
Section titled “Copying elements”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); }});