Model
The document the script runs against. Get it from activeModel.
Properties
Section titled “Properties”activeEntities
Section titled “activeEntities”
readonlyactiveEntities:Entities
The entities of the context being edited, such as an open group.
activePath
Section titled “activePath”
readonlyactivePath: readonly (ComponentInstance|Group)[]
The groups and instances being edited, from the model root down; empty at the root.
activeTransformation
Section titled “activeTransformation”
readonlyactiveTransformation:Transformation
Maps the coordinates of activeEntities to world coordinates: the transformations of activePath multiplied together.
activeView
Section titled “activeView”
readonlyactiveView:View
The view for image export.
definitions
Section titled “definitions”
readonlydefinitions: readonlyComponentDefinition[]
All component and group definitions, including ones nothing uses any more, such as a group’s after it was erased or exploded, until Model.purgeUnused removes them. Group definitions have empty names.
entities
Section titled “entities”
readonlyentities:Entities
The entities at the model root.
layers
Section titled “layers”
readonlylayers: readonlyLayer[]
All layers, in the order they were added; the default layer isn’t one. Needs the "layers" feature.
materials
Section titled “materials”
readonlymaterials: readonlyMaterial[]
All materials.
scenes
Section titled “scenes”
readonlyscenes: readonlyScene[]
The model’s scenes, in the order the Scenes panel lists them. Show one in the desktop
window with Viewport.setCamera, or render it by assigning its camera to
View.camera. Needs the "scenes" feature.
Example
Section titled “Example”const model = modlumi.activeModel;for (const scene of model.scenes) { model.activeView.camera = scene.camera; model.activeView.writeImage(`${scene.name}.png`);}selection
Section titled “selection”
readonlyselection:Selection
The current selection.
readonlyunits:UnitSettings
How the model shows lengths.
Methods
Section titled “Methods”addLayer()
Section titled “addLayer()”addLayer(
name,options?):Layer
Adds a visible layer, gray by default, inside Model.operation. Throws RangeError
for color components outside 0 to 1. Needs the "layers" feature.
Parameters
Section titled “Parameters”string
options?
Section titled “options?”color?
Section titled “color?”Color | { a?: number; b: number; g: number; r: number; }
Returns
Section titled “Returns”addMaterial()
Section titled “addMaterial()”addMaterial(
name,options?):Material
Adds a material, white by default, with an optional texture, inside
Model.operation. Throws RangeError for color components outside 0 to 1 or a
texture that isn’t a PNG or JPEG file.
Parameters
Section titled “Parameters”string
options?
Section titled “options?”color?
Section titled “color?”Color | { a?: number; b: number; g: number; r: number; }
texture?
Section titled “texture?”Texture | null
Returns
Section titled “Returns”addScene()
Section titled “addScene()”addScene(
name,camera):Scene
Adds a scene at the end of scenes inside Model.operation and returns it.
Throws RangeError for an empty name.
Parameters
Section titled “Parameters”string
camera
Section titled “camera”Returns
Section titled “Returns”Example
Section titled “Example”const front = new modlumi.Camera([0, -20, 1.5], [0, 0, 1.5]);model.operation("Add scene", () => model.addScene("Front", front));formatArea()
Section titled “formatArea()”formatArea(
squareMeters):string
Formats an area in square meters in the model’s units, such as "6.000 m²".
Parameters
Section titled “Parameters”squareMeters
Section titled “squareMeters”number
Returns
Section titled “Returns”string
formatLength()
Section titled “formatLength()”formatLength(
meters):string
Formats a length in meters the way the model shows lengths, such as "1.200 m".
Parameters
Section titled “Parameters”meters
Section titled “meters”number
Returns
Section titled “Returns”string
formatVolume()
Section titled “formatVolume()”formatVolume(
cubicMeters):string
Formats a volume in cubic meters in the model’s units, such as "2.000 m³".
Parameters
Section titled “Parameters”cubicMeters
Section titled “cubicMeters”number
Returns
Section titled “Returns”string
getLayer()
Section titled “getLayer()”getLayer(
name):Layer|null
Returns the first layer named name, or null. Needs the "layers" feature.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Layer | null
getMaterial()
Section titled “getMaterial()”getMaterial(
name):Material|null
Returns the first material named name, or null. Names needn’t be unique, so plugins that
add materials by name look them up first:
model.getMaterial("Oak") ?? model.addMaterial("Oak", { color }). Needs the
"materialLookup" feature.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Material | null
isDrawingElementVisible()
Section titled “isDrawingElementVisible()”isDrawingElementVisible(
path,options?):boolean
Whether an element is visible, taking hidden ancestors into account. path lists the
element’s ancestors from the model root down to the element itself.
Parameters
Section titled “Parameters”readonly DrawingElement[]
options?
Section titled “options?”Returns
Section titled “Returns”boolean
moveScene()
Section titled “moveScene()”moveScene(
index,newIndex):Scene
Moves the scene at index in scenes to newIndex inside Model.operation,
as dragging it in the Scenes panel does, and returns it. The scenes between shift over by
one. Throws RangeError when either index has no scene. Needs the "sceneOrder" feature.
Parameters
Section titled “Parameters”number
newIndex
Section titled “newIndex”number
Returns
Section titled “Returns”Example
Section titled “Example”// Put the last scene first.model.operation("Move scene", () => model.moveScene(model.scenes.length - 1, 0));operation()
Section titled “operation()”operation<
T>(name,body):T
Runs body as one named undo step and returns its result. Every edit must happen
inside an operation. A thrown error, or any failed edit inside body (even when
caught), rolls the whole operation back. Empty operations add no undo step.
Operations can’t be nested, and body must be synchronous.
In a panel’s, dialog’s or Properties section’s draw, the operations that apply changes the user makes while holding one widget, such as dragging a slider or typing into a text field, join one undo step: the first operation of the drag names it, and later ones add to it, so one undo goes back to before the drag. Releasing the widget, or changing another one, starts a new step, as does anything else that changes the model in between, such as an undo during the drag.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”string
() => T
Returns
Section titled “Returns”T
parseLength()
Section titled “parseLength()”parseLength(
text):number|null
Reads a length the way the measurements box does, such as "1.2m", "18cm", "7\"" or
"5' 3 1/2\"", and returns it in meters. A number without a unit is in the model’s
UnitSettings.lengthUnit. Returns null for text that isn’t a length.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”number | null
purgeUnused()
Section titled “purgeUnused()”purgeUnused():
object
Removes component definitions that no group or instance reachable from the model root
uses, with their contents, and then materials and layers nothing left uses. Call it inside
Model.operation. Returns how many of each went; layers needs the "layers"
feature.
Returns
Section titled “Returns”object
definitions
Section titled “definitions”
readonlydefinitions:number
layers
Section titled “layers”
readonlylayers:number
materials
Section titled “materials”
readonlymaterials:number
raytest()
Section titled “raytest()”raytest(
origin,direction,options?):RayHit|null
Casts a ray from origin along direction, both in world coordinates, through the whole
model, and returns the nearest face it hits from either side, or null. Hidden faces and
faces in hidden groups and instances are skipped unless includeHidden is set. Faces on
hidden layers, or in groups and instances on them, are always skipped.
Parameters
Section titled “Parameters”origin
Section titled “origin”direction
Section titled “direction”options?
Section titled “options?”includeHidden?
Section titled “includeHidden?”boolean
Returns
Section titled “Returns”RayHit | null
redo()
Section titled “redo()”redo():
void
Redoes the last undone operation. Not allowed inside an operation.
Returns
Section titled “Returns”void
removeLayer()
Section titled “removeLayer()”removeLayer(
layer):void
Removes a layer inside Model.operation. Everything on it moves to the default
layer. Needs the "layers" feature.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”void
removeMaterial()
Section titled “removeMaterial()”removeMaterial(
material):void
Removes a material inside Model.operation. Faces, groups and instances that use it show their default or inherited appearance again.
Parameters
Section titled “Parameters”material
Section titled “material”Returns
Section titled “Returns”void
removeScene()
Section titled “removeScene()”removeScene(
index):void
Removes the scene at index in scenes inside Model.operation; later
scenes move up one. Throws RangeError for an index without a scene.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”void
undo()
Section titled “undo()”undo():
void
Undoes the last operation. Not allowed inside an operation.
Returns
Section titled “Returns”void
updateScene()
Section titled “updateScene()”updateScene(
index,changes):Scene
Renames a scene, saves another camera to it, or both, inside Model.operation, and
returns the scene as it is now. index is the scene’s position in scenes.
Throws RangeError for an index without a scene or an empty name.
Parameters
Section titled “Parameters”number