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.
Implements
Section titled “Implements”Iterable<AnyElement>
Properties
Section titled “Properties”activeSectionPlane
Section titled “activeSectionPlane”
readonlyactiveSectionPlane:SectionPlane|null
This context’s active section plane, or null.
bounds
Section titled “bounds”
readonlybounds:BoundingBox|null
The bounds of everything in this context, in its coordinates, or null when it’s empty.
isSolid
Section titled “isSolid”
readonlyisSolid: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.
length
Section titled “length”
readonlylength:number
Number of elements.
vertices
Section titled “vertices”
readonlyvertices: readonlyVertex[]
All vertices in this context.
volume
Section titled “volume”
readonlyvolume: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.
Methods
Section titled “Methods”[iterator]()
Section titled “[iterator]()”[iterator]():
Iterator<AnyDrawingElement>
Returns
Section titled “Returns”Iterator<AnyDrawingElement>
Implementation of
Section titled “Implementation of”Iterable.[iterator]
addArc()
Section titled “addArc()”addArc(
center,radius,startAngle,endAngle,options?): readonlyCurve[]
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.
Parameters
Section titled “Parameters”center
Section titled “center”radius
Section titled “radius”number
startAngle
Section titled “startAngle”number
endAngle
Section titled “endAngle”number
options?
Section titled “options?”PlaneOptions & object
Returns
Section titled “Returns”readonly Curve[]
addBox()
Section titled “addBox()”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.
Parameters
Section titled “Parameters”origin
Section titled “origin”number
number
height
Section titled “height”number
options?
Section titled “options?”Returns
Section titled “Returns”addCircle()
Section titled “addCircle()”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.
Parameters
Section titled “Parameters”center
Section titled “center”radius
Section titled “radius”number
options?
Section titled “options?”Returns
Section titled “Returns”addComponent()
Section titled “addComponent()”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".
Parameters
Section titled “Parameters”elements
Section titled “elements”Iterable<DrawingElement>
string
Returns
Section titled “Returns”addCone()
Section titled “addCone()”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.
Parameters
Section titled “Parameters”center
Section titled “center”radius
Section titled “radius”number
height
Section titled “height”number
options?
Section titled “options?”Returns
Section titled “Returns”addCurve()
Section titled “addCurve()”addCurve(
points): readonlyCurve[]
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.
Parameters
Section titled “Parameters”points
Section titled “points”Iterable<Point3dLike>
Returns
Section titled “Returns”readonly Curve[]
addCylinder()
Section titled “addCylinder()”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.
Parameters
Section titled “Parameters”center
Section titled “center”radius
Section titled “radius”number
height
Section titled “height”number
options?
Section titled “options?”Returns
Section titled “Returns”addDimension()
Section titled “addDimension()”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]));Parameters
Section titled “Parameters”offset
Section titled “offset”string
Returns
Section titled “Returns”addEdges()
Section titled “addEdges()”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.
Parameters
Section titled “Parameters”points
Section titled “points”Iterable<Point3dLike>
Returns
Section titled “Returns”Edge[]
addFace()
Section titled “addFace()”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.
Parameters
Section titled “Parameters”points
Section titled “points”Iterable<Point3dLike>
Returns
Section titled “Returns”addGroup()
Section titled “addGroup()”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.
Parameters
Section titled “Parameters”elements?
Section titled “elements?”Iterable<DrawingElement, any, any>
Returns
Section titled “Returns”addGuideLine()
Section titled “addGuideLine()”addGuideLine(
position,direction):Guide
Adds an infinite construction line through position along direction.
Parameters
Section titled “Parameters”position
Section titled “position”direction
Section titled “direction”Returns
Section titled “Returns”addGuidePoint()
Section titled “addGuidePoint()”addGuidePoint(
position):Guide
Adds a construction point.
Parameters
Section titled “Parameters”position
Section titled “position”Returns
Section titled “Returns”addInstance()
Section titled “addInstance()”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)));Parameters
Section titled “Parameters”definition
Section titled “definition”transformation?
Section titled “transformation?”Returns
Section titled “Returns”addMesh()
Section titled “addMesh()”addMesh(
mesh,options?): readonlyFace[]
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.
Parameters
Section titled “Parameters”options?
Section titled “options?”smoothAngle?
Section titled “smoothAngle?”number
Returns
Section titled “Returns”readonly Face[]
addPolygon()
Section titled “addPolygon()”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.
Parameters
Section titled “Parameters”center
Section titled “center”radius
Section titled “radius”number
number
options?
Section titled “options?”Returns
Section titled “Returns”addRectangle()
Section titled “addRectangle()”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.
Parameters
Section titled “Parameters”origin
Section titled “origin”number
height
Section titled “height”number
options?
Section titled “options?”Returns
Section titled “Returns”addScreenText()
Section titled “addScreenText()”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 }.
Parameters
Section titled “Parameters”string
position
Section titled “position”number
number
Returns
Section titled “Returns”addSectionPlane()
Section titled “addSectionPlane()”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;});Parameters
Section titled “Parameters”normal
Section titled “normal”options?
Section titled “options?”string
symbol?
Section titled “symbol?”string
Returns
Section titled “Returns”addSphere()
Section titled “addSphere()”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.
Parameters
Section titled “Parameters”center
Section titled “center”radius
Section titled “radius”number
options?
Section titled “options?”Returns
Section titled “Returns”addText()
Section titled “addText()”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]));Parameters
Section titled “Parameters”string
leader?
Section titled “leader?”Returns
Section titled “Returns”at(
index):AnyDrawingElement|undefined
Returns the element at index, counting from the end when negative.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”AnyDrawingElement | undefined
bevel()
Section titled “bevel()”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.
Parameters
Section titled “Parameters”Iterable<Edge>
referenceFaces
Section titled “referenceFaces”Face | Iterable<Face, any, any>
distance
Section titled “distance”number
options?
Section titled “options?”angle?
Section titled “angle?”number
secondDistance?
Section titled “secondDistance?”number
Returns
Section titled “Returns”void
chamfer()
Section titled “chamfer()”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.
Parameters
Section titled “Parameters”Iterable<Edge>
distance
Section titled “distance”number
Returns
Section titled “Returns”void
copyEntities()
Section titled “copyEntities()”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.
Parameters
Section titled “Parameters”transformation
Section titled “transformation”entities
Section titled “entities”Iterable<DrawingElement>
Returns
Section titled “Returns”erase()
Section titled “erase()”erase(
entity):void
Erases one entity, subject to the model’s topology rules.
Parameters
Section titled “Parameters”entity
Section titled “entity”Returns
Section titled “Returns”void
eraseEdges()
Section titled “eraseEdges()”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.
Parameters
Section titled “Parameters”Iterable<Edge>
Returns
Section titled “Returns”void
explode()
Section titled “explode()”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.
Parameters
Section titled “Parameters”containers
Section titled “containers”Iterable<ComponentInstance | Group>
Returns
Section titled “Returns”fillet()
Section titled “fillet()”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.
Parameters
Section titled “Parameters”Iterable<Edge>
radius
Section titled “radius”number
options?
Section titled “options?”segments?
Section titled “segments?”number
Returns
Section titled “Returns”void
findFaces()
Section titled “findFaces()”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);});Parameters
Section titled “Parameters”Returns
Section titled “Returns”Face[]
intersect()
Section titled “intersect()”intersect(
solids):Group
Replaces two or more solids with a group holding only what all of them share. See union.
Parameters
Section titled “Parameters”solids
Section titled “solids”Iterable<ComponentInstance | Group>
Returns
Section titled “Returns”intersectFaces()
Section titled “intersectFaces()”intersectFaces(
faces,others): readonlyEdge[]
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.
Parameters
Section titled “Parameters”Iterable<Face | { face: Face; transformation: Transformation; }>
others
Section titled “others”Iterable<Face | { face: Face; transformation: Transformation; }>
Returns
Section titled “Returns”readonly Edge[]
Example
Section titled “Example”// 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()
Section titled “intersectWith()”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.
Parameters
Section titled “Parameters”elements
Section titled “elements”Iterable<DrawingElement>
others?
Section titled “others?”Iterable<DrawingElement, any, any>
Returns
Section titled “Returns”Edge[]
mergeCollinearEdges()
Section titled “mergeCollinearEdges()”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.
Parameters
Section titled “Parameters”vertices?
Section titled “vertices?”Iterable<Vertex, any, any>
Returns
Section titled “Returns”number
mergeCoplanarFaces()
Section titled “mergeCoplanarFaces()”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.
Parameters
Section titled “Parameters”options?
Section titled “options?”sameMaterials?
Section titled “sameMaterials?”boolean
Returns
Section titled “Returns”number
mergeVertices()
Section titled “mergeVertices()”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.
Parameters
Section titled “Parameters”merged
Section titled “merged”Returns
Section titled “Returns”void
modifySolid()
Section titled “modifySolid()”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.
Parameters
Section titled “Parameters”target
Section titled “target”modifier
Section titled “modifier”operation
Section titled “operation”"union" | "subtract" | "intersect"
Returns
Section titled “Returns”void
moveVertices()
Section titled “moveVertices()”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.
Parameters
Section titled “Parameters”vertices
Section titled “vertices”Iterable<Vertex>
offsets
Section titled “offsets”Iterable<Vector3dLike>
Returns
Section titled “Returns”void
offsetFace()
Section titled “offsetFace()”offsetFace(
face,distance): readonlyCurve[]
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.
Parameters
Section titled “Parameters”distance
Section titled “distance”number
Returns
Section titled “Returns”readonly Curve[]
ofType()
Section titled “ofType()”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.
Type Parameters
Section titled “Type Parameters”T extends "Edge" | "Face" | "ComponentInstance" | "Group" | "Guide" | "Text" | "LinearDimension" | "SectionPlane"
Parameters
Section titled “Parameters”T
Returns
Section titled “Returns”(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()
Section titled “outerShell()”outerShell(
solids):Group
Replaces one or more solids with a group holding the outside of their union, without inner faces or hollows. See union.
Parameters
Section titled “Parameters”solids
Section titled “solids”Iterable<ComponentInstance | Group>
Returns
Section titled “Returns”split()
Section titled “split()”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.
Parameters
Section titled “Parameters”second
Section titled “second”Returns
Section titled “Returns”Group[]
splitEdge()
Section titled “splitEdge()”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.
Parameters
Section titled “Parameters”number | Point3dLike
Returns
Section titled “Returns”subtract()
Section titled “subtract()”subtract(
target,cutter):Group
Replaces two solids with a group holding target with cutter removed. See union.
Parameters
Section titled “Parameters”target
Section titled “target”cutter
Section titled “cutter”Returns
Section titled “Returns”toArray()
Section titled “toArray()”toArray():
AnyDrawingElement[]
A snapshot of the elements.
Returns
Section titled “Returns”toJSON()
Section titled “toJSON()”toJSON():
AnyDrawingElement[]
JSON.stringify writes the elements as an array.
Returns
Section titled “Returns”transformEntities()
Section titled “transformEntities()”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.
Parameters
Section titled “Parameters”transformation
Section titled “transformation”entities
Section titled “entities”Iterable<DrawingElement>
Returns
Section titled “Returns”boolean
trim()
Section titled “trim()”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.
Parameters
Section titled “Parameters”target
Section titled “target”cutter
Section titled “cutter”Returns
Section titled “Returns”Group | null
union()
Section titled “union()”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.
Parameters
Section titled “Parameters”solids
Section titled “solids”Iterable<ComponentInstance | Group>
Returns
Section titled “Returns”weld()
Section titled “weld()”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.
Parameters
Section titled “Parameters”Iterable<Edge>