How to Use Clip Plane and Section View Features in the CAD Viewer

The CAD Viewer in earthtojake/text-to-cad enables interactive geometry inspection through dynamic clip planes and static section views, both powered by the reusable cadjs visualization package.

The text-to-cad repository provides a sophisticated CAD Viewer built on the modular cadjs library for Three.js rendering. The clip plane and section view features allow you to isolate interior model geometry for interactive analysis or automated documentation generation. These capabilities share a common architecture that normalizes user input, computes world-space clipping boundaries, and synchronizes clipping planes across all scene materials.

Clip Plane Architecture and Core Implementation

The interactive clip plane system follows a three-layer architecture spanning core logic, runtime integration, and UI controls.

Core Logic in clipPlane.js

The foundation resides in packages/cadjs/src/lib/viewer/clipPlane.js, which exports configuration constants and normalization utilities:

• DEFAULT_STEP_CLIP_SETTINGS – Baseline configuration defining default axis, offset, and enabled state.
• normalizeStepClipSettings(value) – Sanitizes user-provided objects (such as UI slider values) into complete settings objects.
• buildStepClipPatch(settings, patch) – Merges partial updates into existing configurations without overwriting unspecified fields.
• clipAxisPosition(bounds, settings) – Calculates the world-space position of the clipping plane based on model bounding boxes and selected axis orientation.

These utilities ensure that any input source—whether programmatic API calls or UI interactions—produces consistent, validated clipping parameters before reaching the rendering pipeline.

Runtime Integration via modelRuntime.js

When the viewer loads a model, packages/cadjs/src/lib/viewer/modelRuntime.js executes the clipping pipeline. The runtime calls internal buildStepClipPlane functions and subsequently invokes syncObjectClipPlanes and syncMaterialClipPlanes to attach the clipping plane to every material participating in the scene.

This synchronization ensures that geometry is truly clipped at the shader level rather than merely hidden from view, preventing z-fighting and visual artifacts during inspection. The runtime maintains a single active clip plane reference at runtime.activeClipPlane while storing normalized settings in runtime.activeClipPlanes as an array for material propagation.

UI Controls in ThemeSettingsPopover.js

User-facing controls reside in viewer/src/client/components/workbench/ThemeSettingsPopover.js. This File Sheet component imports clipping helpers (buildStepClipPatch, normalizeStepClipSettings) and presents:

• A toggle for enabling/disabling the clip plane.
• An axis selector (x, y, or z).
• A slider controlling the offset percentage along the selected axis.

Component state changes flow through the normalization utilities before updating the viewer's display settings, which the runtime consumes via the synchronization functions described above.

Working with Section Views

While clip planes provide interactive exploration, section views generate static renderings with clipping applied for documentation purposes.

Section View Render Mode

A section view is essentially a snapshot rendered with the clipping plane permanently applied. The snapshot CLI (text-to-cad’s snapshot command) accepts a display.mode of "section" in its JSON configuration. Internally, the CLI reuses the same cadjs clipping logic—creating a clip plane based on normalized settings, rendering the scene headlessly, and outputting PNG or SVG assets.

This mode is documented in packages/cadjs/docs/render-pipeline.md, which describes how the "section" display mode triggers the clipping pipeline before capture.

Snapshot CLI Integration

To generate section view documentation, configure the snapshot with explicit clip parameters. The skills/cad/references/snapshot-review.md file explains how the "Display/appearance" sheet in the viewer UI maps directly to the section-view clip plane configuration used by the CLI.

The snapshot command respects the same stepClip settings as the interactive viewer, ensuring visual consistency between live inspection and generated documentation.

Programmatic Control and Code Examples

Enable a Clip Plane Programmatically

Control the clip plane from custom toolbars or automation scripts by importing the normalization utilities:

import { normalizeStepClipSettings, buildStepClipPatch } from "cadjs/lib/viewer/clipPlane";

// Retrieve current viewer state
let currentSettings = { 
  enabled: false, 
  axis: "x", 
  offset: 0.2, 
  offsets: { x: 0.2, y: 0, z: 0 }, 
  invert: false 
};

// Create patch to enable plane and set X-axis offset to 30%
const patch = { enabled: true, offset: 0.3 };
const newSettings = buildStepClipPatch(currentSettings, patch);

// Apply to viewer - runtime automatically syncs to materials
viewer.setDisplaySettings({ stepClip: newSettings });

Generate Static Section Views via CLI

Create a JSON configuration file for automated section rendering:

{
  "input": "models/example.step",
  "display": {
    "mode": "section",
    "stepClip": {
      "enabled": true,
      "axis": "z",
      "offset": 0.5
    }
  },
  "render": {
    "sizeProfile": "assembly"
  }
}

Execute the snapshot command:

npx text-to-cad snapshot --config section.json

UI Implementation Reference

The following snippet from ThemeSettingsPopover.js demonstrates how to wire clip plane controls:

<FileSheetSection title="Clip Plane">
  <FileSheetToggleRow
    label="Enable"
    value={settings.enabled}
    onChange={v => update({ enabled: v })}
  />
  <FileSheetSliderField
    label="Offset"
    value={settings.offset}
    min={0}
    max={1}
    step={0.01}
    onChange={v => update({ offset: v })}
  />
  <FileSheetSelect
    label="Axis"
    options={["x","y","z"]}
    value={settings.axis}
    onChange={v => update({ axis: v })}
  />
</FileSheetSection>

Summary

• Clip planes in the CAD Viewer rely on packages/cadjs/src/lib/viewer/clipPlane.js for normalization logic and packages/cadjs/src/lib/viewer/modelRuntime.js for Three.js material synchronization.
• Section views utilize the same clipping architecture but render statically via the snapshot CLI with "display.mode": "section".
• UI controls in ThemeSettingsPopover.js provide interactive sliders and toggles that propagate through buildStepClipPatch and normalizeStepClipSettings.
• Both features share the cadjs visualization pipeline, ensuring consistent geometry clipping across interactive and automated workflows.

Frequently Asked Questions

What is the difference between clip plane and section view features?

Clip planes provide interactive, real-time geometry slicing within the viewer UI, allowing you to drag sliders and change axes dynamically. Section views generate static image exports (PNG/SVG) using the same clipping mathematics but captured via the snapshot CLI with display.mode set to "section" for documentation purposes.

How do I enable clip planes programmatically?

Import buildStepClipPatch and normalizeStepClipSettings from cadjs/lib/viewer/clipPlane, construct a settings patch with enabled: true and your desired axis/offset values, then pass the normalized result to viewer.setDisplaySettings({ stepClip: newSettings }). The runtime automatically synchronizes these settings to all scene materials via syncMaterialClipPlanes.

Can I use multiple clip planes simultaneously?

The viewer maintains a single active clip plane at runtime.activeClipPlane, though settings are stored in runtime.activeClipPlanes as an array for material synchronization purposes. The current architecture supports one clipping plane at a time per view, defined by a single axis and offset percentage.

Where are clip plane settings stored and documented?

Settings are defined by DEFAULT_STEP_CLIP_SETTINGS in packages/cadjs/src/lib/viewer/clipPlane.js and documented in skills/cad-viewer/references/viewer-features.md. The snapshot CLI integration is covered in skills/cad/references/snapshot-review.md, while the render pipeline specifics appear in packages/cadjs/docs/render-pipeline.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}