Drawings

The drawings module turns a Scene's 3D content into a technical-drawing-style 2D view. Output is a new SceneModel whose hierarchy mirrors the source one-to-one (one SceneObject per source SceneObject, one SceneMesh per source mesh), so picks on the drawing can be mapped back to the source model.

classDiagram
direction TB
   class sourceModel["sourceModel : SceneModel"] {
     +objects : SceneObject[]
     +meshes : SceneMesh[]
     +geometries : SceneGeometry[]
     +aabb : AABB3
   }
   class params["params : DrawingProjectionParams"] {
     +sourceModel
     +targetModel
     +direction : "top"|"front"|...|Ray
     +clip? : DrawingClipSpec
     +panel? : PanelSpec
     +titleBlock? : TitleBlockSpec
     +progressive? : ProgressiveSpec
   }
   class targetModel["targetModel : SceneModel"] {
     +objects : SceneObject[] (mirrors source 1:1)
     +meshes : LinesPrimitive + TrianglesPrimitive
     +chrome : panel + title block
   }
   class buildDrawing["buildDrawing(params)"]
   sourceModel --o params : sourceModel
   targetModel --o params : targetModel
   params --> buildDrawing : consumes
   buildDrawing --> targetModel : populates
   buildDrawing ..> hle : edges + depth buffer
   buildDrawing ..> fills : silhouettes
   buildDrawing ..> chrome : panel + cartouche

Pipeline

flowchart TD
    src[Source SceneModel] --> basis
    params[DrawingProjectionParams] --> basis
    basis[Resolve projection basis]
    basis --> hle[hle]
    basis --> fills[fills]
    basis --> chrome[chrome]
    hle --> emit
    fills --> emit
    chrome --> emit
    emit[Emit meshes one-to-one with source]
    emit --> tgt[Target SceneModel]

buildDrawing accepts DrawingProjectionParams and writes into the caller's target SceneModel. Internally it uses three stages, each exposed as a submodule:

• hle — CPU-side orthographic depth-buffer rasterisation and edge-visibility testing.
• fills — per-source-object filled silhouette extraction. Shares the HLE depth buffer for pixel-aligned boundaries.
• chrome — backing panel and title-block metadata.

Behavior

• Wireframe projection — projects crease and boundary edges as LinesPrimitive meshes, with optional hidden-line elimination.
• Solid fills — emits per-source-object filled silhouettes with hidden-surface removal.
• Section cut-aways — clips the source against a plane for plans, sections, and oblique slices.
• Six face presets plus arbitrary {forward, up} rays for diagonal and isometric views.
• Title-block chrome — adds a backing quad and title block sized to the projection frame.
• Progressive emission — yields between batches so large drawings can appear incrementally.
• One-to-one pickback — output SceneObject ids encode their source.

Usage

These snippets assume a Scene with a source SceneModel already loaded (via any of the SDK importers, for example DotBIMLoader or GLTFLoader).

1) Import the entry points

import {
  buildDrawing,
  canBuildDrawing,
  clearDrawing
} from "@xeokit/sdk/presentations/drawings";
Copy

2) Project onto an AABB face

The caller creates the target SceneModel and passes it in; buildDrawing populates it. Six face presets resolve to axis-aligned views of the source AABB: "top", "bottom", "front", "back", "left", "right".

const targetResult = scene.createModel({ id: "myModel__top" });
if (!targetResult.ok) {
  console.error(targetResult.error);
}
const targetModel = targetResult.value;

const result = await buildDrawing({
  sourceModel: scene.models["myModel"],
  targetModel,
  direction:   "top"
});

if (!result.ok) {
  console.error(result.error);
  targetModel.destroy();                 // partial state may exist
}
Copy

The target SceneModel renders alongside the source in the same View and picks back to source SceneObjects by stripping "__" + targetModel.id from the picked object's id.

Source and target may also live in different Scenes. buildDrawing reads world orientation and collision data from sourceModel.scene and writes only to targetModel.

3) Project along an arbitrary ray

Pass a DrawingProjectionRay for oblique, diagonal, or isometric views. forward is the camera-look direction; up (optional) selects which world direction reads as "up" on the image.

const targetModel = scene.createModel({ id: "myModel__iso" }).value;

await buildDrawing({
  sourceModel: scene.models["myModel"],
  targetModel,
  direction: {
    forward: [1, -1, 1],     // looking down-and-forward
    up:      [0, 1, 0]       // world Y reads as "up" on the image
  }
});
Copy

4) Hidden-line elimination

Pass hideHidden: true to drop edges occluded by other source meshes along the projection direction. Pass an HLEOptions to tune resolution, per-edge sample count, and depth bias.

const targetModel = scene.createModel({ id: "myModel__front" }).value;

await buildDrawing({
  sourceModel: scene.models["myModel"],
  targetModel,
  direction:   "front",
  hideHidden: {
    resolution: 4096,        // depth-buffer pixels (longer axis)
    samples:    8,           // per-edge visibility test points
    tolerance:  0.005        // 5 mm depth bias
  }
});
Copy

5) Solid fills

Pass fill: true to emit a TrianglesPrimitive silhouette per source SceneObject alongside the wireframe. Fill and wireframe derive from the same depth buffer, so silhouette boundaries are pixel-aligned with the line work. Pass a FillSpec to customise.

const targetModel = scene.createModel({ id: "myModel__solid" }).value;

await buildDrawing({
  sourceModel: scene.models["myModel"],
  targetModel,
  direction:   "front",
  hideHidden:  true,
  fill: {
    color:   [0.92, 0.93, 0.95],
    opacity: 1.0
  }
});
Copy

To emit fills without wireframe lines, also set lines: false.

6) Section cut-away

Pass clip to render a sliced cross-section. Two shapes:

• {depth} — plane perpendicular to the projection direction, at the given basis-space depth. The side closer to the camera is discarded.
• {point, normal} — arbitrary world-space plane. The side normal points toward is kept.

// Architectural plan: cut at floor level, keep everything below.
const targetModel = scene.createModel({ id: "myModel__plan" }).value;

await buildDrawing({
  sourceModel: scene.models["myModel"],
  targetModel,
  direction:   "top",
  hideHidden:  true,
  fill:        true,
  clip: { depth: -1.2 }      // basis-space d of the cut plane
});
Copy

7) Frame, panel, and title block

The frame is a rectangle around the projected geometry; the panel is a backing quad; the title block is placed in the bottom-right corner.

const targetModel = scene.createModel({ id: "myModel__sheet" }).value;

await buildDrawing({
  sourceModel: scene.models["myModel"],
  targetModel,
  direction:   "front",
  hideHidden:  true,
  fill:        true,

  frame:      1.5,                       // 1.5 world-unit margin
  frameColor: [0.05, 0.25, 0.85],

  panel: {
    color:   [0.96, 0.97, 0.99],
    opacity: 0.55
  },

  titleBlock: {
    title: "BUILDING A — FRONT ELEVATION",
    rows: [
      { label: "PROJECT", value: "TOWER 42"   },
      { label: "SCALE",   value: "1 : 100"    },
      { label: "DATE",    value: "2026-05-14" }
    ]
  }
});
Copy

8) Progressive emission

For drawings of large source models, pass progressive: true so the function yields between batches of createObject calls and the target model can update during a long build. Pass a ProgressiveSpec for batch size and yield control.

const targetModel = scene.createModel({ id: "myModel__progressive" }).value;

await buildDrawing({
  sourceModel: scene.models["myModel"],
  targetModel,
  direction:   "top",
  hideHidden:  true,
  progressive: {
    batchSize: 50,                       // SceneObjects per yield
    yield: () => new Promise(resolve =>
      requestAnimationFrame(() => resolve())
    )
  }
});
Copy

9) Park drawings on their own ViewLayer

Pass layerId to assign every emitted SceneObject to a named ViewLayer. The host can then hide, show, or style the drawing without touching the source model.

const targetModel = scene.createModel({ id: "myModel__top" }).value;

await buildDrawing({
  sourceModel: scene.models["myModel"],
  targetModel,
  direction:   "top",
  layerId:     "drawings"
});
Copy

10) Guard against unprojectable sources

Point clouds, line-only models, and surface meshes without edgeIndices produce empty drawings. canBuildDrawing reports whether the source has geometry the projector can emit, so callers can skip the call instead of letting it fail with a "no projectable edges or fills" error.

const sourceModel = scene.models["myModel"];

if (canBuildDrawing(sourceModel, "either")) {
  const targetModel = scene.createModel({ id: "myModel__top" }).value;
  await buildDrawing({ sourceModel, targetModel, / *…* / });
}
Copy

11) Tearing down

The caller owns the target SceneModel, so teardown is just targetModel.destroy(). clearDrawing is a convenience wrapper that no-ops if the target is null or already destroyed.

clearDrawing(targetModel);
Copy