Model and entities
The model
Section titled “The model”modlumi.activeModel is the Model the script
runs against. From it you reach everything else:
| Property | Contents |
|---|---|
model.entities |
Elements at the model root |
model.activeEntities |
Elements of the context being edited, such as an open group |
model.selection |
The current selection |
model.definitions |
All group and component definitions |
model.materials |
All materials |
model.layers |
All layers, as the Layers panel lists them |
model.activeView |
A view for image export |
model.scenes |
Saved views, as the Scenes panel lists them |
Entities
Section titled “Entities”Everything stored in the model is an Entity.
Iterating an Entities collection yields its
elements: edges, faces, groups, component instances and guides. Every entity
has a type property naming its class, so a switch can tell them apart:
const model = modlumi.activeModel;for (const entity of model.entities) { switch (entity.type) { case "Edge": console.log("Edge", entity.length, "m"); break; case "Face": console.log("Face", entity.area, "m²"); break; case "Group": case "ComponentInstance": console.log("Container", entity.name || entity.definition.name); break; }}instanceof works too, for example entity instanceof modlumi.Face. To get
all elements of one type, use ofType:
const faces = modlumi.activeModel.entities.ofType("Face");console.log(`${faces.length} faces`);Collections have a length, can be iterated, and support at(index),
which counts from the end for negative indices, and toArray(). Iteration
works on a snapshot, so editing the model inside the loop doesn’t change what
the loop visits. Vertices aren’t elements; get them from entities.vertices
or from an edge’s start and end.
Each model entity is represented by one object, so ===, Set and Map
work as identity. Every entity also has an entityId that stays the same
across undo and redo. An edit can delete an entity, for example when a face
is replaced. Check isDeleted or isValid before using an entity you kept
from earlier.
Faces, loops and edges
Section titled “Faces, loops and edges”A Face is bounded by loops: one outerLoop and
one loop per hole. Each Loop lists its edges in
order. The EdgeUse objects in edgeUses
also tell you which way the loop runs along each edge:
for (const face of modlumi.activeModel.entities.ofType("Face")) { const corners = face.outerLoop.edgeUses.map((use) => use.start.position); console.log(`Face with ${corners.length} corners and ${face.loops.length - 1} holes`);}Edges drawn by a curve tool belong to a Curve,
or to an ArcCurve with a center and radius
for arcs and circles. edge.curve returns it, or null.
Groups and components
Section titled “Groups and components”A Group or
ComponentInstance places a
ComponentDefinition in its parent
with a transformation. The definition’s entities use their own local
coordinates. Multiply by the transformation to get coordinates in the parent:
/** * @param {modlumi.Entities} entities * @param {modlumi.Transformation} toWorld */function walk(entities, toWorld, depth = 0) { const indent = " ".repeat(depth); for (const entity of entities) { if (entity.type === "Group" || entity.type === "ComponentInstance") { console.log(indent + (entity.name || entity.definition.name)); walk(entity.definition.entities, toWorld.multiply(entity.transformation), depth + 1); } else if (entity.type === "Edge") { const start = toWorld.multiply(entity.start.position); console.log(`${indent}edge from ${start}`); } }}
walk(modlumi.activeModel.entities, new modlumi.Transformation());Measurements such as edge.length and face.area are in the entity’s own
context; they don’t include the containers above it.
All instances of a component share one definition, so editing the
definition’s entities changes every instance. Renaming a definition renames
it for all instances, while instance.name names only that container. Groups
have a name of their own too.
entities.addGroup(elements) moves elements into a new group, and
entities.addComponent(elements, name) into a new component definition with
one instance. Faces take their boundary edges along. Without elements,
addGroup() returns an empty group. Geometry drawn into its entities
doesn’t merge with anything outside it:
const model = modlumi.activeModel;const post = model.operation("Post", () => { const group = model.entities.addGroup(); group.entities.addRectangle([0, 0, 0], 0.1, 0.1).extrude(2); group.name = "Post"; return group;});console.log(post.entities.ofType("Face").length); // 6Guides
Section titled “Guides”A Guide is a construction point or an infinite
construction line, like the ones the Measure tool places. Guides
don’t form faces. isPoint tells them apart; a guide line has a position
on the line and a direction. entities.addGuidePoint(position) and
entities.addGuideLine(position, direction) create them.
Text and dimensions
Section titled “Text and dimensions”A Text label is pinned to a point and shows its
text at point plus leader, or stays at a screenPosition on the screen. A
LinearDimension shows the length
between its start and end, with its dimension line moved by offset. Its
text overrides the label, with <> standing for the length. Both follow
vertices they sit on when an edit moves them.
const model = modlumi.activeModel;model.operation("Annotate", () => { const entities = model.activeEntities; entities.addDimension([0, 0, 0], [2.4, 0, 0], [0, -0.5, 0], "Width <>"); entities.addText("Door", [1, 0, 2], [0.5, 0, 0.5]); entities.addScreenText("Ground floor", { x: 0.05, y: 0.05 });});Visibility
Section titled “Visibility”Edges, faces, groups and component instances have hidden and visible
properties for their own hidden flag. Changing them requires an operation:
const model = modlumi.activeModel;model.operation("Hide selected", () => { for (const entity of model.selection) { entity.hidden = true; }});Hiding a group hides everything in it without changing its definition. A
hidden layer also hides what’s on it, without changing hidden.
To check whether an element is actually visible, including hidden groups above
it and hidden layers, pass its path from the model root to
model.isDrawingElementVisible().
Selection
Section titled “Selection”model.selection is the selection in the
window. Changing it doesn’t need an operation and isn’t part of undo. You
can only select drawing elements in the active editing context:
const model = modlumi.activeModel;model.selection.clear();for (const face of model.activeEntities.ofType("Face")) { if (face.area > 1.0) { model.selection.add(face); }}console.log(`Selected ${model.selection.length} faces larger than 1 m²`);Materials
Section titled “Materials”Material objects have a name, a color
with r, g, b and a components from 0 to 1, and an optional texture.
Faces, edges, groups and instances have a material, which on a face covers
both of its sides. Each is null when nothing is applied.
Inside an operation, scripts add and remove materials, change them, and assign them to faces, groups and instances:
const model = modlumi.activeModel;model.operation("Paint the floor", () => { const oak = model.addMaterial("Oak", { color: { r: 0.62, g: 0.45, b: 0.28 } }); for (const face of model.activeEntities.ofType("Face")) { if (face.normal && face.normal.z > 0.99) { face.material = oak; } } oak.name = "Floor oak";});A texture is the bytes of a PNG or JPEG file and the size of one repeat in
meters: material.texture = { image, width: 0.5, height: 0.5 }. Assign null
to remove it. Removing a material with model.removeMaterial() shows the
default or inherited appearance again wherever it was used.
Materials also have a physically based surface, which shows in
PBR shading:
metallic and roughness, each from 0 to 1, and image maps of the kinds
"metallic", "roughness", "normal" and "opacity", read with
material.getMap(kind) and set with material.setMap(kind, image), or
null to remove one. These need the "materialSurface"
plugin feature.
const model = modlumi.activeModel;model.operation("Brushed steel", () => { const steel = model.addMaterial("Steel", { color: { r: 0.56, g: 0.57, b: 0.58 } }); steel.metallic = 1; steel.roughness = 0.35;});Layers
Section titled “Layers”A Layer groups drawing elements for showing and
hiding, as in the Layers panel. Each has a name,
a color and visible. Every drawing element has a layer, which is null
on the default layer. The default layer has no Layer object and is always
shown. Layers only change what shows: geometry on different layers still
connects.
Inside an operation, scripts add and remove layers, change them, and put elements on them:
const model = modlumi.activeModel;model.operation("Put furniture on a layer", () => { const furniture = model.getLayer("Furniture") ?? model.addLayer("Furniture"); for (const instance of model.entities.ofType("ComponentInstance")) { instance.layer = furniture; } furniture.visible = false;});Hiding a layer hides the faces, edges, guides and annotations on it, and every
group and instance on it with everything inside. model.removeLayer() moves
what was on the layer to the default layer. These need the "layers"
plugin feature.
Scenes
Section titled “Scenes”model.scenes lists the model’s scenes in the order of the
Scenes panel, including the ones a
SketchUp file came with. Each is a frozen
Scene with a name and a
Camera. Scenes have no identity of their own:
methods take a scene’s position in model.scenes, and editing one returns
the scene as it is now.
Inside an operation, scripts add, change and remove scenes. Each operation is one undo step, however many scenes it changes:
const model = modlumi.activeModel;model.operation("Add views", () => { const front = new modlumi.Camera([0, -20, 1.5], [0, 0, 1.5]); model.addScene("Front", front); model.updateScene(0, { name: "Street" }); model.removeScene(model.scenes.length - 1);});updateScene(index, { name, camera }) keeps what it isn’t given. Names can’t
be empty. Scenes added by scripts only save a camera; the layers a scene shows
and hides are set in the Scenes panel, and updateScene keeps them. moveScene(index, newIndex) puts a scene in another place, as
dragging it in the Scenes panel does, and shifts the scenes between by one; it
needs the "sceneOrder" plugin feature.
To show a scene, give its camera to the
image export view with
model.activeView.camera = scene.camera, or, from a plugin, to the
desktop viewport.