# How the cadjs Package Facilitates CAD Visualization

> Discover how the cadjs package enables seamless CAD visualization. It parses files, builds Three.js scenes, manages viewports, and captures snapshots for the text-to-cad repository.

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

---

**The cadjs package provides a framework-agnostic, four-stage JavaScript runtime that parses CAD files, constructs Three.js scene graphs, manages interactive viewports, and captures deterministic snapshots for the text-to-cad repository.**

The `cadjs` package serves as the core visualization engine within the `earthtojake/text-to-cad` repository, enabling robust 3D rendering without framework dependencies. This modular library facilitates CAD visualization through a clean separation of concerns, handling everything from STEP and STL parsing to interactive viewport management. Because it operates independently of React or other UI frameworks, `cadjs` powers everything from interactive web viewers to server-side documentation generators.

## The Four-Stage Render Pipeline

The `cadjs` package implements a deterministic pipeline that cleanly separates data ingestion, scene construction, rendering, and capture.

### Loading and Normalizing Sources

The pipeline begins in [`src/common/source.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/common/source.js) with the **`loadSource`** function. This utility parses incoming CAD data—whether STEP, STL, GLB, 3MF, or other formats—and validates the file type. It constructs a unified source object containing mesh data, selector runtimes, side-car information, and STEP parameters, ensuring consistent data structures regardless of input format.

### Building the Model Graph

Next, **`buildModel`** in [`src/common/cadScene.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/common/cadScene.js) transforms the normalized source into a full Three.js scene graph. Accepting a `THREE` context and the source object, it generates groups for geometry, edges, and display records while configuring clipping planes, material handling, topology edges, and STEP-parameter effects. The returned model API maintains mutable state—including `runtime`, `bounds`, and `radius`—and exposes `update` and `dispose` methods for lifecycle management.

### Rendering the Viewport

The **`renderModel`** function in [`src/common/renderModel.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/common/renderModel.js) initializes the Three.js renderer, scene, and camera. It applies theme settings, lighting configurations, floor planes, and framing logic to produce a viewport API. This API drives the animation loop, handles canvas resizing, and enables real-time interaction while remaining agnostic to the surrounding application framework.

### Capturing Snapshots

Finally, **`captureModel`** executes the renderer against an off-screen canvas to produce deterministic output. Located in [`src/common/captureModel.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/common/captureModel.js), this stage returns image data as PNG blobs or serialized GLB files without filesystem dependencies, supporting both the Python snapshot CLI and documentation hero components.

## Interactive Viewer Extensions

Beyond the core pipeline, `cadjs` includes viewer-specific helpers in `src/lib/viewer/` that extend functionality for interactive applications.

### Scene Scaling and Bounds Management

The **[`sceneScale.js`](https://github.com/earthtojake/text-to-cad/blob/main/sceneScale.js)** module normalizes CAD versus URDF scene scales and computes shadow camera settings. Working alongside **[`modelRuntime.js`](https://github.com/earthtojake/text-to-cad/blob/main/modelRuntime.js)**, these utilities calculate model radius, update shadow maps, and synchronize clipping planes across all display records and pick groups, ensuring consistent visual presentation regardless of model complexity.

### Picking, Clipping, and Visual State

Interactive selection relies on **[`selectorPickGroups.js`](https://github.com/earthtojake/text-to-cad/blob/main/selectorPickGroups.js)** and **[`clipPlane.js`](https://github.com/earthtojake/text-to-cad/blob/main/clipPlane.js)**, which provide utilities for part selection and per-model clipping planes. Visual state management falls to **[`partVisualState.js`](https://github.com/earthtojake/text-to-cad/blob/main/partVisualState.js)** and **[`surfaceMaterials.js`](https://github.com/earthtojake/text-to-cad/blob/main/surfaceMaterials.js)**, handling material overrides for selected or hidden parts, wireframe rendering toggles, and edge display configurations. These modules enable the viewer UI to highlight, isolate, or modify geometry appearance dynamically.

## Framework-Agnostic Architecture

A defining characteristic of `cadjs` is its zero-dependency approach to UI frameworks. The package exports a modular, testable stack importable via `import { loadSource, buildModel, renderModel } from "cadjs"`. This architecture ensures that the same visualization logic powers plain WebGL canvases, server-side snapshot generators, React-based interactive viewers, or any future frontend implementation without code duplication.

## Practical Implementation Examples

### Basic Visualization Workflow

```javascript
import * as THREE from "three";
import { loadSource, buildModel, renderModel } from "cadjs";

// Load the CAD source from URL, File object, or raw mesh data
const source = await loadSource(
  { url: "/models/example.step" },
  { kind: "step" }
);

// Build the Three.js scene graph with theme and scale options
const model = buildModel(THREE, source, {
  theme: "dark",
  displayMode: "solid",
  scale: "cad",
  clip: { enabled: false }
});

// Render into an existing canvas element
const canvas = document.getElementById("cad-canvas");
const viewport = renderModel(THREE, model, { canvas, autoStart: true });

// Capture a high-resolution PNG snapshot
const pngBlob = await viewport.capturePng({ pixelRatio: 2 });

```

### Updating Visual State Programmatically

```javascript
// Hide specific parts and enable wireframe mode
model.update({
  hiddenPartIds: ["link_2", "link_3"],
  displayMode: "wireframe"
});

```

### Camera Framing Utilities

```javascript
import { fitCameraToModel } from "cadjs/common/cadScene.js";

// Fit camera to model bounds with padding and directional alignment
fitCameraToModel(THREE, viewport.camera, model.bounds, {
  padding: 0.1,
  direction: [0, 0, 1]
});

```

## Summary

- **Four-stage pipeline**: `loadSource`, `buildModel`, `renderModel`, and `captureModel` in `packages/cadjs/src/common/` provide end-to-end CAD visualization capabilities.
- **Framework independence**: Zero dependencies on React or specific UI frameworks enable reuse across web clients, CLI tools, and documentation pipelines.
- **Comprehensive format support**: Native handling of STEP, STL, GLB, 3MF, and other CAD formats through unified source normalization.
- **Interactive extensions**: Viewer helpers in `src/lib/viewer/` manage scene scaling, bounds calculation, picking, clipping, and visual state.
- **Deterministic snapshots**: Off-screen rendering capabilities support both client-side downloads and server-side documentation generation.

## Frequently Asked Questions

### What file formats does the cadjs package support?

The `cadjs` package supports STEP, STL, GLB, 3MF, and other standard CAD formats. The `loadSource` function in [`src/common/source.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/common/source.js) validates and normalizes these inputs into a unified source object, ensuring consistent downstream processing regardless of the original file type.

### Is cadjs dependent on React or specific UI frameworks?

No, `cadjs` is explicitly framework-agnostic according to the `earthtojake/text-to-cad` source code. It depends only on Three.js for 3D rendering and can be used in plain JavaScript applications, React components, Vue applications, or server-side Node.js environments without modification.

### How does cadjs handle camera framing and model bounds?

The package calculates model bounds during the `buildModel` stage in [`src/common/cadScene.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/common/cadScene.js) and provides `fitCameraToModel` for automatic camera positioning. Additionally, [`src/lib/viewer/modelRuntime.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/lib/viewer/modelRuntime.js) manages shadow map updates and clipping plane synchronization based on calculated model radius and scene scale.

### Can cadjs be used for server-side rendering?

Yes, the `captureModel` functionality in [`src/common/captureModel.js`](https://github.com/earthtojake/text-to-cad/blob/main/src/common/captureModel.js) runs the Three.js renderer to an off-screen canvas, returning PNG or GLB data without DOM dependencies. This enables server-side usage for documentation generation, automated testing, and CLI tooling as implemented in the repository's Python snapshot utilities.