CAD Viewer Component in text-to-cad: Local CAD and Robot Model Inspection

The CAD Viewer component is a local, filesystem-based web application that lets users inspect, navigate, and interact with CAD and robot-description artifacts such as .step, .stl, .urdf, and .sdf files through a browser-based interface.

The CAD Viewer component in the earthtojake/text-to-cad repository provides a self-contained review environment for validating generated models. This lightweight tool bridges the gap between file generation and visual confirmation, allowing developers to launch a local server that renders CAD assets and robot descriptions without complex setup.

Architecture of the CAD Viewer Component

The CAD Viewer consists of two tightly coupled parts: a Python backend that manages the HTTP server and instance registry, and a React frontend that provides the visualization interface.

Python Backend (cadgen.viewer)

Located in packages/cadgen/src/cadgen/viewer/main.py, the backend implements a lightweight HTTP server with the following responsibilities:

• Serves a single directory: The server always hosts the current working directory where it was launched. There is no configuration flag to change the root; users must cd into the target directory before starting the viewer.
• Exposes API endpoints: The server provides two critical endpoints: /__cad and /__tess_cache. These handle model data requests and tessellation caching respectively.
• Manages instance registry: The backend tracks running viewer instances, handling port allocation, automatic reuse logic, and graceful shutdown procedures.
• Port allocation strategy: The launcher selects the first available port beginning at 3245 (0xCAD), ensuring users never need to manually configure ports.

React Frontend (apps/viewer)

The frontend, defined in apps/viewer/README.md, is a Vite-built React application that provides the user interface:

• Rendering engine: Displays CAD models with support for measurement tools, animation controls, and theme switching.
• Catalog view: Offers a file browser interface for navigating complex project structures.
• Production bundling: The client is compiled and bundled into the cadgen Python wheel at cadgen/_runtime/viewer, allowing the Python package to serve the UI without separate Node.js dependencies.
• Development mode: When running npm run dev, the backend can operate in --api-only mode, serving only the API prefixes while Vite provides the client assets.

Key Behaviors and Limitations

Understanding the CAD Viewer component's operational constraints ensures effective usage within the earthtojake/text-to-cad workflow.

Directory Serving Strategy The Viewer operates on a "serve-once-directory" principle. It always serves the current working directory at launch time, and this cannot be changed via command-line flags. To view a different directory, you must change to that directory (cd) before invoking the viewer.

Automatic Instance Reuse If a CAD Viewer instance is already running for the same real filesystem path and using the same version of the Viewer code, the launcher reuses the existing server rather than spawning a new process. This produces a JSON response with "action":"reused" instead of "action":"started", preventing port exhaustion and redundant processes.

Static Visualization Only The CAD Viewer component does not compile or generate CAD files. It strictly reads and visualizes existing artifacts produced by other skills in the repository. This separation of concerns ensures the viewer remains lightweight and focused on inspection rather than generation.

Using the CAD Viewer Component

Launching a Viewer Session

Navigate to your project directory containing CAD assets and execute the viewer command:

cd /path/to/project/models
cadgen viewer --host 127.0.0.1 --json

The command outputs a JSON line containing the access URL:

{"url":"http://127.0.0.1:3245/","port":3245,"action":"started"}

Open the URL in a browser and append ?file= to load a specific artifact:

http://127.0.0.1:3245/?file=gripper/STEP/gear_rack_gripper.step

Reusing an Existing Instance

When invoking the viewer from a directory that already has an active instance, the system detects the running server and returns:

{"url":"http://127.0.0.1:3245/","port":3245,"action":"reused"}

No new process is created; the existing server handles the request.

Listing Active Viewer Instances

To see all running CAD Viewer processes managed by the registry:

cadgen viewer list --json

Sample output:

[
  {
    "host":"127.0.0.1",
    "port":3245,
    "pid":12345,
    "root":"/path/to/project/models",
    "version":"0.5.1",
    "startedAt":1681234567,
    "token":"ab3c..."
  }
]

Stopping a Viewer

Terminate a specific instance by specifying its port:

cadgen viewer stop --port 3245

This sends a termination signal to the registered process and removes its entry from the instance registry.

Implementation Files and Source Code

The CAD Viewer component spans multiple directories in the earthtojake/text-to-cad repository:

• packages/cadgen/src/cadgen/viewer/main.py: Implements the HTTP server, argument parsing, reuse logic, and instance registry management.
• apps/viewer/README.md: Documents the React client architecture, build process, and UI features.
• packages/cadgen/src/cadgen/cli/viewer.py: Provides the thin CLI wrapper that exposes the cadgen viewer command interface.
• skills/cad-viewer/SKILL.md: Contains high-level skill descriptions for AI agents, including URL construction and launch workflows.
• tests/python/skills/cad-viewer/test_packaged_viewer.py: Integration tests verifying the packaged viewer launches correctly within the wheel distribution.

Summary

• The CAD Viewer component combines a Python HTTP server with a React frontend to provide local, browser-based CAD inspection.
• It supports formats including .step, .stl, .glb, .urdf, and .sdf through the cadgen viewer CLI.
• The server always serves the current working directory and automatically reuses instances when launched from the same path and version.
• Port allocation begins at 3245 (0xCAD) and increments automatically to find available ports.
• The frontend is bundled into the Python wheel at cadgen/_runtime/viewer, ensuring zero-dependency deployment for end users.

Frequently Asked Questions

What file formats does the CAD Viewer support?

The CAD Viewer component handles standard CAD and robot-description formats including STEP (.step), STL (.stl), GLB (.glb), URDF (.urdf), and SDF (.sdf). These formats cover most mechanical CAD exports and robotics simulation descriptors used in the text-to-cad pipeline.

How does the CAD Viewer component handle port conflicts?

According to the implementation in packages/cadgen/src/cadgen/viewer/main.py, the viewer uses a port-agnostic allocation strategy. It begins scanning at port 3245 (hexadecimal 0xCAD) and automatically binds to the first available port. Users never manually specify ports; the launcher prints the definitive URL after successful binding.

Can I run the CAD Viewer on a remote server or bind to external interfaces?

While the --host parameter accepts any IP address (including 0.0.0.0), the CAD Viewer component is designed as a local development tool. It serves the local filesystem directory where it was launched and does not include authentication mechanisms. Exposing it to public networks requires additional security considerations beyond the default configuration.

How do I develop new features for the CAD Viewer frontend?

Development requires running the backend in API-only mode using the --api-only flag, which serves only the /__cad and /__tess_cache endpoints. Meanwhile, the React client in apps/viewer runs via npm run dev with Vite supplying hot-reload capabilities. This decoupled approach allows frontend modification without rebuilding the Python wheel.

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