How to Use the CAD Viewer to Preview STEP, STL, URDF, and Other CAD File Types

The CAD Viewer is a browser-based workbench that previews CAD and robot-description files by scanning directories via ?dir= and loading specific files via ?file= URL parameters.

The CAD Viewer in the earthtojake/text-to-cad repository renders 3-D meshes, 2-D toolpaths, and robot descriptions directly in your browser without installing heavy desktop software. It supports industrial formats ranging from STEP assemblies to MoveIt2-compatible robot configurations, serving files either from your local filesystem or Vercel Blob storage.

Supported File Types

The Viewer recognizes specific extensions to determine parsing and rendering strategies. According to viewer/README.md (lines 13-15), supported formats include:

• STEP (.step, .stp) – 3-D CAD assemblies requiring topological analysis
• Mesh formats (.stl, .3mf, .glb) – Direct 3-D geometry display
• 2-D manufacturing (.gcode, .dxf) – Toolpath and flat-pattern previews
• Robot descriptions (.urdf, .srdf, .sdf) – Articulated model visualization with optional kinematic controls

Launching the CAD Viewer

To start the local server, navigate to the viewer directory and install dependencies:

cd viewer
npm install
npm run build

Run the agent with a target directory:

npm run agent:start -- --dir /path/to/models

The command outputs a local URL (typically http://127.0.0.1:4178). The server remains active for the duration specified by the VIEWER_SERVER_LIFETIME_MS environment variable.

Loading Files via URL Parameters

The Viewer uses two required query parameters to locate assets. As documented in viewer/docs/backend.md (line 95), the URL contract follows this structure:

http://127.0.0.1:4178?dir=/absolute/root&file=model.step

Replace components based on your file type:

File Type	Example URL Path
STEP assembly	?dir=/home/cad&file=assembly/robot-arm.step
STL mesh	?dir=/home/cad&file=parts/gear.stl
GLB binary	?dir=/home/cad&file=meshes/part.glb
DXF drawing	?dir=/home/cad&file=drawings/flat.dxf
G-code toolpath	?dir=/home/cad&file=toolpaths/contour.gcode
URDF robot	?dir=/home/cad&file=robots/my_robot.urdf
SRDF configuration	?dir=/home/cad&file=robots/my_robot.srdf
SDF world	?dir=/home/cad&file=worlds/example.sdf

The backend adapter in viewer/src/server/ handles file reading and optional side-car generation, while the React frontend in viewer/src/client/ renders the scene using utilities from packages/cadjs/.

Regenerating STEP Assets

STEP files require hidden side-car GLB and topology assets for performant rendering. When you update a source STEP file, trigger regeneration using the Python CAD runtime:

python -m pip install -r requirements.txt

Restart the Viewer or click the Regenerate button in the UI to force recreation of these cached assets. This process utilizes the implicit CAD runtime in packages/implicitjs/ to extract topology and generate optimized meshes.

MoveIt2 Integration for Robot Descriptions

When previewing SRDF files, the Viewer can launch interactive inverse kinematics (IK) and planning controls via an optional MoveIt2 WebSocket server located in viewer/moveit2_server.

Enable this integration by setting the environment variable before starting the server:

export VIEWER_MOVEIT2_WS_URL=http://127.0.0.1:8765
npm run agent:start -- --dir /path/to/models

Open an SRDF file via URL (?file=robots/my_robot.srdf) to access the planning interface documented in viewer/docs/moveit2-server.md.

Session Persistence and Storage

The Viewer stores the active directory in the browser's sessionStorage, allowing you to omit the ?dir= parameter after the initial load during a single tab session. For backend configuration details, see viewer/docs/storage.md.

Summary

• The CAD Viewer supports STEP, STL, GLB, DXF, G-code, URDF, SRDF, and SDF formats through a browser interface.
• Launch the viewer using npm run agent:start -- --dir /absolute/path from the viewer directory.
• Access files via URL parameters ?dir= and ?file= to load specific models instantly.
• STEP files require Python runtime regeneration of hidden GLB/topology assets when source files change.
• SRDF files enable optional MoveIt2 WebSocket controls for robot planning and IK.

Frequently Asked Questions

How do I view a STEP file without installing the Python CAD runtime?

You can view previously generated STEP files if the hidden side-car GLB assets already exist in the directory. However, to import a new STEP file or update an existing one, you must install the Python dependencies (pip install -r requirements.txt) to generate the required topology and mesh data.

What is the difference between URDF and SRDF support in the Viewer?

URDF files display the robot's visual and collision geometry along with joint hierarchies. SRDF files extend this with semantic information (planning groups, end effectors) and enable the optional MoveIt2 WebSocket integration for interactive planning controls in the browser.

Can the CAD Viewer run entirely in the cloud without local files?

Yes. The Viewer supports Vercel Blob storage as an alternative backend to the local filesystem. Instead of using ?dir= with an absolute path, configure the backend to point to a hosted catalog, allowing you to preview models stored in cloud object storage.

Why does my file not appear in the sidebar tree?

The Viewer scans the directory specified by ?dir= only for supported extensions listed in the README. Ensure your file uses lowercase extensions (.step, .stl, etc.) and that the absolute path in ?dir= matches exactly where the file resides on disk or in storage.

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