Model - entity producers
Every producer whose return is entity[] — what it creates is concatenated into the entity stream. Authored as a step in an objects[] chain.
| Method | Description | Arg | Type | Default | Meaning |
|---|---|---|---|---|---|
arcCenterStartEnd | Arc (Center) | center | point | [0,0] | Arc center [x,y]; the radius = distance from center to start. |
startPoint | point | [10,0] | Where the arc begins; sets the radius. | ||
endPoint | point | [0,10] | Direction the arc sweeps toward (snapped onto the radius). | ||
arcTangentEnd | Arc (Tangent) | axis | axis | { origin: [0,0,0], direction: [0,1,0] } | Start point + leaving tangent direction, as an axis (magnitude irrelevant). |
endPoint | point | [10,0] | Where the arc ends. | ||
arcThreePoints | Arc (3 Points) | startPoint | point | [0,0] | First endpoint the arc passes through. |
middlePoint | point | [5,5] | Point on the arc between start and end (defines the bulge). | ||
endPoint | point | [10,0] | Last endpoint the arc passes through. | ||
circle | Circle | center | point | [0,0] | Circle center [x,y] in the XY plane. |
radius | length | 10 | Circle radius. | ||
clone | Clone | source | entity[] | [] | Node to copy — returns an independent deep copy with fresh ids. |
container | Container | ||||
cubicBezier | Cubic Bezier | start | point | [0,0,0] | Start point (on curve). |
control1 | point | [3,10,0] | First tangent control point. | ||
control2 | point | [7,10,0] | Second tangent control point. | ||
end | point | [10,0,0] | End point (on curve). | ||
curveFromFace | Curves From Face — Extract every boundary loop of the referenced face(s) as closed curves — the outer ring and each hole ring become one curve apiece. Reference another node by key (nested blocks are flattened; non-faces are ignored). Feed the result to offset/extrude/fill or use it as a construction outline. | source | faceEntity[] | Expression referencing the node whose faces to outline (e.g. a container key like box). | |
curveFunction | NurbsCurve From Function — Sample a formula t => [x,y,z] over t in [0,1] into a curve — helix, spiral, sine profile: the shapes no fixed primitive covers. | point | function | (t) => [50 * Math.cos(t * 6 * Math.PI), 50 * Math.sin(t * 6 * Math.PI), t * 300] | Callback t => [x,y,z], t in [0,1]. The default draws a 3-turn helix, radius 50, height 300. |
samples | number | 64 | Points sampled along t — higher follows the formula closer at higher cost. | ||
degree | number | 3 | NurbsCurve smoothness through the samples: 1 = exact polyline, 3 = smooth cubic. | ||
closed | binary | 0 | true joins the end back to the start — author the formula with matching endpoints. | ||
ellipseArc | Ellipse Arc | center | point | [0,0] | Ellipse center [x,y]. |
xAxis | vector | [10,0] | Major-axis vector; its length is the X radius. | ||
yAxis | vector | [0,5] | Minor-axis vector (perpendicular to xAxis); its length is the Y radius. | ||
angle | angle | 360 | Sweep in degrees: 360 = full closed ellipse, under 360 = open arc. | ||
hatch | Hatch — Fill a planar region with a repeating unit-cell pattern (hatch). Cell content is point/curve/face entities in a lattice basis — all periodicity is the 2×2 basis (brick/hex/etc.), not an enum. Whole-face non-repeating mode: default basis + scale 1. | face | faceEntity | null | The face (one-face shell) whose UV domain is filled. |
cell | entity[] | [] | Pattern content in the unit cell (points/curves/faces). Freehand content is bbox-normalized to [0,1]². | ||
angle | angle | 0 | Pattern rotation in degrees (DXF/.pat convention). | ||
scale | number | 1 | Uniform scale in UV. Anisotropy belongs in the basis. | ||
light | Light — One emitting object. A light is an ordinary entity whose GEOMETRY is the emitting shape, so it moves, groups and exports like everything else. Its housing (can, shade, glass) is separate solid geometry — group them to move together. | shape | string | 'point' | What emits: 'point' (a bare filament, no extent), 'sphere' (a bulb), 'disk' (a downlight), 'rectangle' (a panel or a window), 'cylinder' (a tube). NOT a light type — a spot is a Cone Angle on any of these. |
position | point | [0, 0, 2000] | Emitter centre [x,y,z] mm. | ||
direction | vector | Axis the emitter faces. REQUIRED for disk/rectangle/cylinder (a flat emitter has a front); empty on a point/sphere means it radiates every way. This is the aim — there is no target point. | |||
lumens | number | 800 | Luminous flux of the whole emitter (lm). A 60W-equivalent household bulb ≈ 800; a 600×600 office panel ≈ 4000. | ||
kelvin | number | 3000 | Colour temperature (K) — 2700-3000 warm, 4000 neutral, 5500-6500 daylight. | ||
color | string | Hex colour override ('#ffd6aa'). When set, Kelvin is ignored. | |||
size | length | The shape's first extent (mm): a sphere/disk/cylinder RADIUS, a rectangle WIDTH. Ignored by 'point'. | |||
size2 | length | The shape's second extent (mm): a rectangle HEIGHT, a cylinder LENGTH. Nothing else uses it. | |||
coneAngle | angle | FULL cone in degrees about Direction — this is what a 'spot light' is, a property rather than a kind. Empty = radiate over whatever the shape can see. | |||
penumbra | number | Soft-edge fraction of the cone, 0 (hard) to 1 (fully soft). Needs Cone Angle. | |||
ies | string | A manufacturer's measured distribution: a url-method parameter key or a URI. Supersedes Cone Angle wherever a consumer can read it. | |||
nesting | Nesting — Only valid inside a sheet's own operations (flat lane): packs parts onto stock — 2D sheet outlines (seeded genetic-algorithm nesting) and/or 1D bar stock (deterministic first-fit-decreasing cutting-stock), dispatched per part by whether it's a sheet or a linear part (a section parameter). A mixed part list nests into both outputs at once. Part keys name components[] entries — their view:"pattern" content is what gets nested. | parts | object | [] | Optional array of { key, quantity } overrides naming components[] entries to nest — e.g. [{key:'bracket',quantity}]. Empty (default) = nest every part actually placed in the 3D scene (via placePart), with quantity = its placement count. |
stockWidth | length | 1220 | 2D stock sheet width in mm — sheet parts only. | ||
stockHeight | length | 2440 | 2D stock sheet height in mm — sheet parts only. | ||
spacing | length | 5 | Gap between nested 2D outlines, mm. | ||
seed | number | 1 | Deterministic packing seed for the 2D layout — the same seed always produces the same layout. | ||
stockLength | length | 3000 | 1D stock bar length in mm — linear parts only. | ||
kerfWidth | length | 3 | 1D saw-blade kerf consumed between adjacent cuts on the same bar, mm — linear parts only. | ||
nurbsCurve | NURBS NurbsCurve | points | point[] | [[0,0,0],[3,5,0],[7,5,0],[10,0,0]] | Control points [x,y,z] of the hull; the curve is pulled toward them, not through. |
degree | number | 3 | Polynomial degree (clamped to points.length-1): 1 = polyline, 3 = smooth cubic. | ||
knots | number[] | [] | Knot vector (length = points.length + degree + 1, non-decreasing). Empty = auto clamped-uniform. | ||
weights | number[] | [] | Per-point weight, > 0 (length = points.length). Empty = uniform 1; higher pulls the curve toward that point. | ||
nurbsSurface | NURBS Surface | controlPoints | point[] | [[0,0,0],[100,0,40],[200,0,0],[0,100,40],[100,100,120],[200,100,40],[0,200,0],[100,200,40],[200,200,0]] | Flat ROW-MAJOR list of control points [x,y,z] — the surface is pulled toward them. Row length = Columns. |
columns | number | 3 | Points per row; the number of rows is total points / columns. | ||
degreeU | number | 3 | Smoothness along rows (clamped to rows - 1). | ||
degreeV | number | 3 | Smoothness along columns (clamped to columns - 1). | ||
patchFromCorners | Patch From Corners | corner0 | point | [0,0,0] | First corner [x,y,z]; corners wind in order 0→1→2→3. |
corner1 | point | [100,0,0] | Second corner [x,y,z]. | ||
corner2 | point | [100,100,0] | Third corner [x,y,z], diagonal from corner 0. | ||
corner3 | point | [0,100,0] | Fourth corner [x,y,z]. | ||
placeComponent | Place Component — Places a components[] entry into a 3D chain (root scene[], or another component's own operations/opening): an instanced group placement, and — when the component declares opening — cuts those volumes out of whatever this chain already built before this step. NOT a paper placement: a sheet places a VIEW, so frame the component with a views[] entry (viewDetail head) and place that view instead. | source | string | Key of a components[] entry to place. | |
at | vector | [0, 0, 0] | Position offset (world space in a 3D chain; this space's local plane in a flat context). | ||
rotate | angle | 0 | Rotation in degrees about Z, applied at the local origin before the at offset. | ||
scale | number | 1 | |||
args | object | Optional object literal overriding the component's own parameter values for THIS placement only - e.g. { width: 500 }. Two placements with different args render independently (Type/Instance split). | |||
placePart | Place Part — Folds a part's flat pattern into 3D and places it at a position — sheet-metal bend / wood kerf-bend for an ordinary part, or a swept bar/profile (round bar, box section…) for a part with a section parameter set. The source names a components[] entry whose view:"pattern" entities are the flat pattern; fold metadata (thickness/material/grain/section/…) is read from the component's own parameters. | source | string | Key of the components[] entry to fold and place — its view:"pattern" entities are the flat pattern. | |
at | vector | [0, 0, 0] | Position offset. | ||
args | object | {} | Optional parameter overrides for THIS placement, e.g. { thickness: 5 } — wins over the component's own parameter defaults (same contract as placeComponent's args). | ||
angles | object | {} | Optional per-bend angle override for THIS placement, keyed by the tagged bend/crease curve's own operation key — e.g. { lid: 0, flap1: 180 }. Empty = every bend at its own tagged default (fully folded). A key can reference an animated parameter for a fold-open/close animation. | ||
pointEntity | Render Points | positions | point[] | [[0,0,0]] | Marker positions [x,y,z] to visualize (render-only, not construction geometry). |
polygon | Polygon | center | point | [0,0] | Polygon center [x,y] in the XY plane. |
radius | length | 50 | Circumradius — distance from center to each vertex. | ||
sides | number | 6 | Number of edges, minimum 3. | ||
polyline | Polyline | points | point[] | [[0,0,0],[100,0,0],[100,0,100]] | Ordered vertices [x,y,z] (z optional, defaults 0). |
closed | binary | 0 | true closes the loop back to the first point; false leaves it open. | ||
quadraticBezier | Quadratic Bezier | start | point | [0,0,0] | Start point (on curve). |
control | point | [5,10,0] | Tangent control (pulled toward, not on curve). | ||
end | point | [10,0,0] | End point (on curve). | ||
rectangle | Rectangle | point1 | point | [0,0,0] | One corner of the rectangle. |
point2 | point | [100,100,0] | Opposite corner. The axis with the smallest difference from Point 1 becomes the rectangle's plane (XY/XZ/YZ) — no separate rotate needed to place it on a different plane. | ||
revisionCloud | Revision Cloud — Drafting revision cloud: redraws a closed boundary as a chain of small outward-bulging arcs — the standard mark for a region changed since the last issue. Add a separate note/leader annotation near a corner to label the revision number. | boundary | point[] | [[0,0,0],[100,0,0],[100,100,0],[0,100,0]] | Ordered [x,y,z] vertices of the changed region (z optional, defaults 0). |
bumpRadius | length | 15 | How far each arc bulges outward. Clamped per edge when it would exceed 45% of that edge's own bump spacing (a valid 3-point arc can't bulge past half its chord). | ||
bumpSpacing | length | 40 | Target arc-chord length along each edge before starting the next bump. | ||
spline | Spline | points | point[] | [[0,0,0],[50,0,50],[100,0,100]] | Control points [x,y,z] the smooth curve passes through/near. |
degree | number | 3 | NurbsCurve smoothness: 1 = polyline, 2 = quadratic, 3 = cubic (most common). | ||
straightSkeleton | Straight Skeleton — Straight skeleton of a simple polygon, returned as lifted roof faces (one per boundary edge). Pitch 0 = the flat 2D skeleton partition; pitch > 0 = a hip roof. Reflex vertices (an L-shape's inner corner) are handled via split events. | boundary | point[] | [[0,0,0],[6000,0,0],[6000,4000,0],[0,4000,0]] | Ordered [x,y,z] vertices of a simple (non-self-intersecting) polygon, no holes. |
pitch | angle | 30 | Roof slope: each face rises at this angle from horizontal, away from its boundary edge. | ||
surfaceDivide | Divide Surface — Revit-style Divide Surface: UV-divide a surface into a Count U x Count V cell grid, each drawn as isocurve grid lines by default. Trim (optional, in the surface's own normalized UV space [0,1]x[0,1], z=0) drops cells fully outside it and clips border cells. Pattern (optional) names a components[] entry naming an adaptive pattern that exposes its own Region parameter — resolved per cell (sized to that cell's physical mm footprint) and mapped onto the surface; falls back to grid lines when empty, unresolved, or a cell's pattern produces nothing. | surface | surface | [[0,0,0],[1000,0,0],[0,1000,0],[1000,1000,0]] | The surface to divide — a surface parameter reference, a literal control-point grid, or a raw NurbsSurface (same forms the surface parameter itself accepts). |
countU | number | 4 | Cells along U (columns). | ||
countV | number | 4 | Cells along V (rows). | ||
trim | faceEntity | curveEntity[] | point[] | [] | Optional: closed loops in the surface's own normalized UV space [0,1]x[0,1] (z=0) — face, closed curves, or point rings. Cells fully outside are dropped; border cells are clipped. Empty = the full domain. | ||
pattern | string | '' | Optional: key of a components[] entry naming an adaptive pattern (exposing a boundary parameter) to fill each cell with, instead of grid lines. | ||
sweepMorph | Morph Sweep | profiles | curveEntity[] | [] | Ordered cross-section curves (2+); the sweep morphs from the first at the path start to the last at the path end. |
path | curveEntity | [] | Path the morphing cross-section travels along. | ||
samples | number | 48 | Cross-sections placed along the path (higher = smoother along its length). | ||
tableEntity | Table Entity — Renders a tables[] chain's computed rows (same grid sheets.ts builds for a "table" placement) at a local position/scale. PAPER ONLY — a sheet's own operations (or another flat context); authored in root operations[] or a components[] body it is a validation error, since a report about the scene belongs on paper, not back inside the scene. | source | string | Key of a tables[] chain to render into this flat space. | |
at | vector | [0, 0, 0] | Position offset in this space's local plane. | ||
rotate | angle | 0 | Rotation in degrees about Z, applied at the local origin BEFORE the at offset. | ||
scale | number | 1 | |||
textCurve | Text NurbsCurve | text | string | 'Hello' | The string to render as outline curves; single-quote the literal. |
font | font | Font reference; leave '' to use the built-in fallback font. | |||
fontSize | length | 10 | Cap height of the glyphs in model units. | ||
width | length | 0 | Word-wrap into lines no wider than this (mm); 0 = single line. A \n in the text always breaks. | ||
tree | Tree — Procedural deciduous tree (ported from ez-tree, github.com/dgreenheck/ez-tree) — recursive branch tubes + billboard leaf quads. bark.type/leaves.type select a small builtin bark/leaf material set by name ('oak' | 'aspen', unrecognized falls back to 'oak') — the tree stamps its faces with that name, resolved once the registry's builtin materials reach the render path (RegistryInput.builtinMaterials). seed reseeds the branch/leaf variation deterministically; branch mirrors ez-tree's own option group verbatim (every geometry-shaping field); bark/leaves keep only the fields with geometric or material-dispatch meaning. | seed | number | 12345 | Random seed for branch/leaf variation — the same seed always regenerates the identical tree. |
bark | object | { type: 'oak' } | type selects the builtin bark material by name ('oak' | 'aspen' — unrecognized falls back to 'oak'). | ||
branch | object | { levels: 3, angle: { 1: 54, 2: 58, 3: 32 }, children: { 0: 4, 1: 2, 2: 3 }, force: { direction: { x: 0, y: 1, z: 0 }, strength: 0.01 }, gnarliness: { 0: 0.07, 1: -0.08, 2: 0.11, 3: 0.09 }, length: { 0: 28.08, 1: 4.55, 2: 9.78, 3: 7.16 }, radius: { 0: 1, 1: 1.02, 2: 0.69, 3: 1.19 }, sections: { 0: 16, 1: 9, 2: 8, 3: 1 }, segments: { 0: 7, 1: 5, 2: 3, 3: 3 }, start: { 1: 0.49, 2: 0.06, 3: 0.12 }, taper: { 0: 0.73, 1: 0.42, 2: 0.69, 3: 0.75 }, twist: { 0: -0.23, 1: 0.42, 2: 0, 3: 0 } } | Per-recursion-level branch shape, verbatim ez-tree TreeOptions.branch: levels (recursion depth, 0 = trunk only), angle/children/gnarliness/length/radius/sections/segments/start/taper/twist keyed by level (0..levels, or 1..levels where ez-tree has no level-0 value), plus force { direction, strength } steering overall growth toward a direction. | ||
leaves | object | { type: 'oak', billboard: 'double', angle: 42, count: 14, start: 0.16, size: 1.38, sizeVariance: 0.7 } | Leaf quads grown on the terminal branch level — type selects the builtin leaf material by name ('oak' | 'aspen'), billboard ('single' or 'double' perpendicular quads), angle off the parent branch, count per qualifying branch, start (0..1, where along the branch leaves begin), size, sizeVariance. | ||
triangulate | Triangulate — Delaunay triangulation of scattered points into a TIN (triangulated irregular network) — one triangle Face per Delaunay triangle, computed on XY with Z carried through per vertex (a 2.5D site/terrain surface). | points | point[] | [[0,0,0],[1000,0,0],[1000,1000,0],[0,1000,50],[500,500,150]] | Scattered survey points [x,y,z] — triangulated on XY; Z is carried through to the output vertices unchanged. |
viewEntity | View Entity — Embeds a views[] query's resolved 2D drawing (camera + filter + crop over the 3D scene) at a local position/scale. PAPER ONLY — a sheet's own operations (or another flat context); authored in root operations[] or a components[] body it is a validation error, since a drawing of the scene belongs on paper, not back inside the scene. | source | string | Key of a views[] entry to embed into this flat space. | |
at | vector | [0, 0, 0] | Position offset in this space's local plane. | ||
rotate | angle | 0 | Rotation in degrees about Z, applied at the local origin (the view camera's own projected origin) BEFORE the at offset — so rotating about the drawing's visual centre also shifts at. | ||
scale | number | 1 | |||
voronoi | Voronoi Cells — 2D Voronoi cell layout — one closed curve per cell, clipped to Boundary. Feed curveExtrude/curveFill downstream for panel/partition layouts. Explicit Points override Count/Seed; a Point outside Boundary owns no cell. | points | point[] | [] | Explicit seed positions [x,y] (z ignored). Non-empty overrides Count/Seed entirely. |
count | number | 12 | Number of random seeds generated inside Boundary. Ignored when Points is non-empty. | ||
seed | number | 1 | Deterministic RNG seed for the random seeds (same seed = same layout). Ignored when Points is non-empty. | ||
boundary | point[] | [[0,0,0],[1000,0,0],[1000,1000,0],[0,1000,0]] | Ordered [x,y,z] vertices of the (convex) region cells are clipped to. | ||
relax | number | 2 | Lloyd relaxation iterations — moves each seed to its cell's centroid and recomputes, for more even cell sizes. |