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

> Explore your local CAD files with the text-to-cad viewer. Inspect STEP, STL, URDF, and SDF models directly in your browser. Navigate and interact with designs effortlessly.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: component-overview
- Published: 2026-09-11

---

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

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

```

The command outputs a JSON line containing the access URL:

```json
{"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:

```json
{"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:

```bash
cadgen viewer list --json

```

Sample output:

```json
[
  {
    "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:

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/viewer/main.py)**: Implements the HTTP server, argument parsing, reuse logic, and instance registry management.
- **[`apps/viewer/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/apps/viewer/README.md)**: Documents the React client architecture, build process, and UI features.
- **[`packages/cadgen/src/cadgen/cli/viewer.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cli/viewer.py)**: Provides the thin CLI wrapper that exposes the `cadgen viewer` command interface.
- **[`skills/cad-viewer/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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.