How the cadjs Package Facilitates CAD Visualization

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 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 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 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, 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 module normalizes CAD versus URDF scene scales and computes shadow camera settings. Working alongside 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 and clipPlane.js, which provide utilities for part selection and per-model clipping planes. Visual state management falls to partVisualState.js and 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

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

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

Camera Framing Utilities

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 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 and provides fitCameraToModel for automatic camera positioning. Additionally, 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 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.

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