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

> Learn to use clip plane and section view in the CAD Viewer for interactive geometry inspection. Discover powerful visualization tools in earthtojake/text-to-cad.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-08-01

---

**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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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:

```javascript
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:

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

```

Execute the snapshot command:

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

```

### UI Implementation Reference

The following snippet from [`ThemeSettingsPopover.js`](https://github.com/earthtojake/text-to-cad/blob/main/ThemeSettingsPopover.js) demonstrates how to wire clip plane controls:

```javascript
<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`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/src/lib/viewer/clipPlane.js) for normalization logic and [`packages/cadjs/src/lib/viewer/modelRuntime.js`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/src/lib/viewer/clipPlane.js) and documented in [`skills/cad-viewer/references/viewer-features.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/references/viewer-features.md). The snapshot CLI integration is covered in [`skills/cad/references/snapshot-review.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/references/snapshot-review.md), while the render pipeline specifics appear in [`packages/cadjs/docs/render-pipeline.md`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/docs/render-pipeline.md).