Skip to content

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

Entities

The elements of one drawing context: the model root, a group or a component definition. Iteration takes a snapshot. All edits must happen inside Model.operation.

readonly activeSectionPlane: SectionPlane | null

This context’s active section plane, or null.


readonly bounds: BoundingBox | null

The bounds of everything in this context, in its coordinates, or null when it’s empty.


readonly isSolid: boolean

Whether this context holds a closed solid: only faces and edges, with every edge bounding exactly two faces that run along it in opposite directions. Guides don’t count.


readonly length: number

Number of elements.


readonly vertices: readonly Vertex[]

All vertices in this context.


readonly volume: number | null

The volume the solid in this context encloses, in cubic meters, or null when it isn’t a solid. Shells inside other shells are cavities.

[iterator](): Iterator<AnyDrawingElement>

Iterator<AnyDrawingElement>

Iterable.[iterator]


addArc(center, radius, startAngle, endAngle, options?): readonly Curve[]

Draws an arc of radius around center from startAngle to endAngle in radians, measured from the plane’s first axis toward its second, as a curve of segments straight edges: by default one per 15°. A full turn closes it. Returns the curves drawn, like addCurve.

Point3dLike

number

number

number

PlaneOptions & object

readonly Curve[]


addBox(origin, width, depth, height, options?): Group

Adds a box as a new group. One corner sits at origin; width, depth and height run along the plane’s first axis, its second axis and its normal.

Solids are groups, so 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 Group.transformation places it. Move or rotate it afterward with Group.transform.

Point3dLike

number

number

number

PlaneOptions

Group


addCircle(center, radius, options?): Face

Draws a circle and returns its face. The boundary is a true circle: its edges share an ArcCurve with the center and radius. See addFace for how the outline merges and when it throws.

Point3dLike

number

RoundOptions

Face


addComponent(elements, name?): ComponentInstance

Moves elements of this context into a new component definition and returns its first instance. name names the definition and defaults to "Component".

Iterable<DrawingElement>

string

ComponentInstance


addCone(center, radius, height, options?): Group

Adds a cone as a new group, with its base circle around center and its tip height along the plane’s normal. See addBox for how solids are placed.

Point3dLike

number

number

RoundOptions

Group


addCurve(points): readonly Curve[]

Draws a curve through two or more points, like the Freehand tool: connected edges that are edited as one. Repeat the first point at the end to close it. Returns the curves drawn: one, or more where the stroke runs over existing curves, which stay as they are, or none when it runs over them entirely. Like addEdges, closing it makes no face.

Iterable<Point3dLike>

readonly Curve[]


addCylinder(center, radius, height, options?): Group

Adds a cylinder as a new group, with its base circle around center and its height along the plane’s normal. See addBox for how solids are placed.

Point3dLike

number

number

RoundOptions

Group


addDimension(start, end, offset, text?): LinearDimension

Adds a dimension measuring from start to end, with its dimension line moved by offset; the part of offset along the measured points is dropped. text overrides the label, with <> standing for the length. Points closer than a nanometer throw.

model.operation("Dimension", () => model.activeEntities.addDimension([0, 0, 0], [2, 0, 0], [0, -0.5, 0]));

Point3dLike

Point3dLike

Vector3dLike

string

LinearDimension


addEdges(points): Edge[]

Draws connected line segments through two or more points. Segments split where they cross existing edges, and a segment across a face splits it. Closing an outline makes no face, as with SketchUp’s add_edges: use addFace, or findFaces on one of its edges. Returns the edges that now lie on the requested segments, in model order; there isn’t necessarily one edge per segment.

Iterable<Point3dLike>

Edge[]


addFace(points): Face

Draws a closed planar outline through three or more points and returns the face it bounds. The outline closes itself, so the first point needn’t be repeated. The face’s front is the side the points run counterclockwise around.

Like addEdges, the outline merges with the geometry it touches. An outline drawn on a larger face cuts its own face out of it, and one over existing edges fills them. Retracing an existing face returns that face with its orientation unchanged. Only the outline’s own region becomes a new face: other loops its edges close, such as one made with the bottom edges of neighboring faces, stay open. Throws ModelError when the outline doesn’t end up bounding exactly one face: when it isn’t planar, or crosses itself or existing edges.

Iterable<Point3dLike>

Face


addGroup(elements?): Group

Moves elements of this context into a new group and returns it. Faces take their boundary edges along. Without elements it returns an empty group; draw into its Group.entities to build geometry that doesn’t merge with its surroundings.

Iterable<DrawingElement, any, any>

Group


addGuideLine(position, direction): Guide

Adds an infinite construction line through position along direction.

Point3dLike

Vector3dLike

Guide


addGuidePoint(position): Guide

Adds a construction point.

Point3dLike

Guide


addInstance(definition, transformation?): ComponentInstance

Places another instance of a component definition in this context, such as a second wheel, and returns it. transformation maps definition coordinates into this context and defaults to none. A group’s definition, or a definition this context is inside, throws.

const wheel = model.entities.ofType("ComponentInstance").find((i) => i.definition.name === "Wheel");
model.operation("Rear wheel", () =>
model.entities.addInstance(wheel.definition, modlumi.Transformation.translation([-2.6, 0, 0]).multiply(wheel.transformation)));

ComponentDefinition

Transformation

ComponentInstance


addMesh(mesh, options?): readonly Face[]

Adds a mesh’s polygons as faces, much faster than drawing them one by one: a hundred thousand faces take seconds. Corners at the same position share vertices and edges. A polygon that isn’t planar becomes a fan of triangles from its first corner, with soft and smooth diagonals; keep such polygons convex. Edges between faces that meet at less than smoothAngle radians are softened and smoothed. The mesh doesn’t merge with geometry already here, so add it to an empty group. Returns the faces, in polygon order. Call it inside Model.operation. A mesh has at most 1,048,576 points, 1,048,576 polygons and 4,194,304 polygon corners; add bigger ones in parts.

MeshBuilder

number

readonly Face[]


addPolygon(center, radius, sides, options?): Face

Draws a regular polygon with sides corners (3 to 360) at radius from center, and returns its face. The first corner lies along the plane’s first axis. See addFace for how the outline merges and when it throws.

Point3dLike

number

number

PlaneOptions

Face


addRectangle(origin, width, height, options?): Face

Draws a rectangle with one corner at origin, width along the plane’s first axis and height along its second, and returns its face. By default it lies flat with its front facing up, so addRectangle([0, 0, 0], 4, 3).extrude(2) makes a box. See addFace for how the outline merges and when it throws.

Point3dLike

number

number

PlaneOptions

Face


addScreenText(text, position): Text

Adds screen text at a fixed place on the screen, given as fractions of the view’s width and height from its top-left corner, such as { x: 0.05, y: 0.05 }.

string

number

number

Text


addSectionPlane(point, normal, options?): SectionPlane

Adds an inactive section plane through point that keeps the side normal points to. Set its active to make it cut. A zero normal throws.

model.operation("Section", () => {
model.activeEntities.addSectionPlane([0, 0, 1], [0, 0, -1], { name: "Plan", symbol: "A" }).active = true;
});

Point3dLike

Vector3dLike

string

string

SectionPlane


addSphere(center, radius, options?): Group

Adds a sphere around center as a new group. Its poles lie along the plane’s normal. See addBox for how solids are placed.

Point3dLike

number

RoundOptions

Group


addText(text, point, leader?): Text

Adds a text label pinned to point, shown at point plus leader and joined to it by a leader line. Without leader the label sits on the point. Empty text throws.

model.operation("Label", () => model.activeEntities.addText("Door", [1, 0, 2], [0.5, 0, 0.5]));

string

Point3dLike

Vector3dLike

Text


at(index): AnyDrawingElement | undefined

Returns the element at index, counting from the end when negative.

number

AnyDrawingElement | undefined


bevel(edges, referenceFaces, distance, options?): void

Cuts edges of this context with one flat face at any angle, like the Bevel tool. The cut is set back distance meters along each edge’s reference face: referenceFaces is one face adjacent to every edge, or one adjacent face per edge in order. angle is the angle between the cut and the reference face in degrees, default 45; secondDistance instead sets the setback in meters along the other face. A cut that would remove a whole face throws ModelError. The same edge and corner rules as fillet apply.

Iterable<Edge>

Face | Iterable<Face, any, any>

number

number

number

void


chamfer(edges, distance): void

Cuts edges of this context with one flat face set back distance meters along both adjacent faces, like the Chamfer tool. The same edge and corner rules as fillet apply.

Iterable<Edge>

number

void


copyEntities(transformation, entities): AnyDrawingElement[]

Copies elements of this context, transformed, and returns the new elements. The originals don’t change. Face boundaries, complete curves and holes are copied too, groups and instances keep their definitions, and copies don’t merge with geometry they intersect.

Transformation

Iterable<DrawingElement>

AnyDrawingElement[]


erase(entity): void

Erases one entity, subject to the model’s topology rules.

AnyEntity

void


eraseEdges(edges): void

Erases several edges at once and heals the faces around them. Erasing any edge of a curve erases the whole curve. Collinear edges left meeting at an erased edge’s end that nothing else reaches are joined into one, as after erasing a line drawn across a face, and an erased edge’s end that no edge reaches any more is removed.

Iterable<Edge>

void


explode(containers): AnyDrawingElement[]

Replaces groups and component instances of this context with their contents, placed by their transformations, and returns the elements that took their place. The definitions stay in Model.definitions, even a group’s, until Model.purgeUnused removes the ones nothing uses.

Iterable<ComponentInstance | Group>

AnyDrawingElement[]


fillet(edges, radius, options?): void

Rounds edges of this context with a circular arc of radius meters tangent to both faces, like the Bevel tool. Each edge must join two noncoplanar faces, and each edge end must be a corner where exactly three edges meet. segments, 1 to 64, defaults to 6. Throws ModelError without changing anything when the radius doesn’t fit.

Iterable<Edge>

number

number

void


findFaces(edge): Face[]

Fills every planar region bounded by an edge of this context that has no face yet, like SketchUp’s Edge#find_faces, inside Model.operation, and returns the new faces.

model.operation("Square", () => {
const [side] = model.activeEntities.addEdges([[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0], [0, 0, 0]]);
return model.activeEntities.findFaces(side);
});

Edge

Face[]


intersect(solids): Group

Replaces two or more solids with a group holding only what all of them share. See union.

Iterable<ComponentInstance | Group>

Group


intersectFaces(faces, others): readonly Edge[]

Draws edges into this context wherever a face of faces crosses a face of others, like Intersect Faces, splitting the faces of this context they cross. Like drawn edges, new edges that close a planar loop fill it with a face, such as across the inside of a box cut by a plane. Faces of this context are passed as they are; faces of other contexts come with the transformation that maps their coordinates into this one, so a sibling group’s faces can cut this one. Coplanar overlapping faces each receive the other’s outline. Returns the edges along the intersections, including existing ones. Call it inside Model.operation.

Iterable<Face | { face: Face; transformation: Transformation; }>

Iterable<Face | { face: Face; transformation: Transformation; }>

readonly Edge[]

// Cuts the faces of a group with a large square in its parent, then removes the square.
const cutter = model.entities.addGroup();
const square = cutter.entities.addFace([[-5, -5, 0.5], [5, -5, 0.5], [5, 5, 0.5], [-5, 5, 0.5]]);
const toGroup = group.transformation.inverse();
group.entities.intersectFaces(group.entities.ofType("Face"), [{ face: square, transformation: toGroup }]);
model.entities.erase(cutter);

intersectWith(elements, others?): Edge[]

Adds edges to this context where the faces among elements cross those among others, like Intersect Faces, and returns the edges along the crossings. Faces of this context are split by the new edges. Loose geometry of this context whose faces overlap in one plane, such as a box moved onto a slab, is welded into one surface first. Groups and components contribute their faces, nested ones included, but their own geometry doesn’t change. Without others, the elements are intersected with each other. Call it inside Model.operation.

Iterable<DrawingElement>

Iterable<DrawingElement, any, any>

Edge[]


mergeCollinearEdges(vertices?): number

Joins pairs of collinear edges that meet at a vertex no other edge reaches, removing that vertex, when both bound the same faces and share flags, material and curve: the split edges imports and some edits leave behind. Considers the given vertices of this context, or all of them. Returns how many vertices went.

Iterable<Vertex, any, any>

number


mergeCoplanarFaces(options?): number

Erases edges between faces that lie in one plane and face the same way, merging those faces, and returns how many edges went. With sameMaterials, the default, only faces with the same material merge. A curve goes only when all its edges may, and faces the model can’t merge, such as overlapping ones, keep the edges between them.

boolean

number


mergeVertices(kept, merged): void

Joins merged into kept, which stays where it is: merged’s edges end at kept instead, an edge that would repeat one of kept’s joins it, and the edge between the two goes. Faces stay the same faces; one left with fewer than three sides goes, keeping its edges. Throws ModelError, changing nothing, when a face would pinch at kept, bend out of its plane or lose its area. Curves and arcs through merged become plain edges. Call it inside Model.operation.

Vertex

Vertex

void


modifySolid(target, modifier, operation): void

Changes target in place to its union with, difference from or intersection with modifier, which stays. Unlike the other solid tools, target keeps its container, name, paint and placement, and its unpainted faces, including those it takes from modifier, go on showing its paint. Every instance of a shared component definition changes; a group whose copies share its definition is made unique first. Throws ModelError without changing anything when an input isn’t a solid or the result would be empty or no solid. Call it inside Model.operation.

ComponentInstance | Group

ComponentInstance | Group

"union" | "subtract" | "intersect"

void


moveVertices(vertices, offsets): void

Moves each vertex of this context by its own offset, in one step: the equivalent of moving many points of a mesh at once. Faces the moves bend fold into planar faces, as when moving with the Move tool; moves that collapse an edge or face throw ModelError. Arcs stay arcs only when all their vertices move alike.

Iterable<Vertex>

Iterable<Vector3dLike>

void


offsetFace(face, distance): readonly Curve[]

Draws the outline of a face of this context, holes included, moved distance meters into the face, or out of it for a negative distance, like the Offset tool, and returns the curves drawn. Throws ModelError when the offset collapses the outline.

Face

number

readonly Curve[]


ofType<T>(type): (Extract<Edge, { type: T; }> | Extract<Face, { type: T; }> | Extract<ComponentInstance, { type: T; }> | Extract<Group, { type: T; }> | Extract<Guide, { type: T; }> | Extract<Text, { type: T; }> | Extract<LinearDimension, { type: T; }> | Extract<SectionPlane, { type: T; }>)[]

Returns the elements of the given type.

T extends "Edge" | "Face" | "ComponentInstance" | "Group" | "Guide" | "Text" | "LinearDimension" | "SectionPlane"

T

(Extract<Edge, { type: T; }> | Extract<Face, { type: T; }> | Extract<ComponentInstance, { type: T; }> | Extract<Group, { type: T; }> | Extract<Guide, { type: T; }> | Extract<Text, { type: T; }> | Extract<LinearDimension, { type: T; }> | Extract<SectionPlane, { type: T; }>)[]


outerShell(solids): Group

Replaces one or more solids with a group holding the outside of their union, without inner faces or hollows. See union.

Iterable<ComponentInstance | Group>

Group


split(first, second): Group[]

Replaces two solids with up to three groups: what lies only in first, in both, and only in second, in that order. Empty parts are left out. Throws ModelError when the solids don’t overlap. See union.

ComponentInstance | Group

ComponentInstance | Group

Group[]


splitEdge(edge, at): readonly [Edge, Edge]

Splits an edge of this context at a point on it, or at a parameter from 0 at its start to 1 at its end, and returns the two edges. Both keep the edge’s faces, curve and flags.

Edge

number | Point3dLike

readonly [Edge, Edge]


subtract(target, cutter): Group

Replaces two solids with a group holding target with cutter removed. See union.

ComponentInstance | Group

ComponentInstance | Group

Group


toArray(): AnyDrawingElement[]

A snapshot of the elements.

AnyDrawingElement[]


toJSON(): AnyDrawingElement[]

JSON.stringify writes the elements as an array.

AnyDrawingElement[]


transformEntities(transformation, entities): boolean

Moves elements of this context by a transformation in this context’s coordinates. Shared boundary vertices move once. Returns false when entities is empty.

Transformation

Iterable<DrawingElement>

boolean


trim(target, cutter): Group | null

Cuts cutter out of target and keeps cutter. Returns the group replacing target, or null when nothing of it is left. See union.

ComponentInstance | Group

ComponentInstance | Group

Group | null


union(solids): Group

Replaces solid groups and components of this context with one group holding their union. All solid tools need Group.isSolid solids, replace their inputs with new groups, and throw ModelError without changing anything when the result wouldn’t be a solid. Call them inside Model.operation.

Iterable<ComponentInstance | Group>

Group


weld(edges): Curve

Joins edges of this context into one curve, in order along their chain. They must form one open or closed chain without branches. Edges leave the curves they were in; what remains of those stays curved in its unbroken runs.

Iterable<Edge>

Curve