render

---
name: render
description: Start or reuse the CAD Explorer viewer, return review links, and create saved snapshots for explicit CAD and robot-description files. Use when rendering or visually reviewing `.step`, `.stp`, `.glb`, `.stl`, `.3mf`, `.dxf`, `.urdf`, `.srdf`, or `.sdf` files, especially when handed off from CAD, URDF, SRDF, or SDF generation skills.
license: MIT
---

# Render

Use this skill to open generated or modified CAD and robot-description files in CAD Explorer. The expected input is one or more explicit file paths that already exist or were just generated by another skill.

Supported files: `.step`, `.stp`, `.glb`, `.stl`, `.3mf`, `.dxf`, `.urdf`, `.srdf`, `.sdf`.

## Handoff Contract

- Accept explicit file paths from CAD, URDF, SRDF, SDF, SendCutSend, or standard-part workflows.
- Start or reuse CAD Explorer with `dev:ensure`; do not assume a fixed port. Treat `dev:ensure` as the viewer liveness check for returned links.
- Treat port reuse as mandatory: if `dev:ensure` reports local binding/probing denial such as `EPERM` or `EACCES`, rerun the same `dev:ensure` command with the needed local-binding permission/escalation instead of choosing a new port yourself.
- Do not use `npm run dev -- --port ...`, raw `vite dev`, or raw `vite preview` for normal agent handoffs; those bypass the reuse policy and can leave duplicate localhost Explorer servers running.
- Return the printed Explorer URL for each requested file.
- For generation review or visual feedback, prefer the snapshot CLI over opening the viewer manually or using Playwright. Viewer links are still returned for handoff/live review.
- Generate GIFs only for CAD STEP-module parameter animation review. Otherwise use still snapshots, not GIFs.
- If startup fails, report the failure and let the owning skill continue with its non-GUI validation.

## Commands

From this skill directory:

```bash
npm --prefix scripts/viewer run dev:ensure -- --file path/to/model.step
```

For saved headless snapshots, use the skill-level snapshot wrapper. It delegates into the viewer package's `scripts/viewer/snapshot` implementation:

```bash
python3 scripts/snapshot --job path/to/render-job.json
python3 scripts/snapshot --job -
```

Shortcut flags are available for common theme snapshots only:

```bash
python3 scripts/snapshot \
  --input path/to/model.step \
  --output /tmp/model.png \
  --mode view \
  --theme technical \
  --camera iso \
  --view-labels
```

STEP module sidecar parameters can be supplied with `--params` for stills or animated parameter GIFs:

```bash
python3 scripts/snapshot \
  --input path/to/model.step \
  --output /tmp/model.png \
  --params '{"drive":180,"ringVisible":false}'

python3 scripts/snapshot \
  --input path/to/model.step \
  --output /tmp/model.gif \
  --params '{"values":{"ringVisible":true},"animate":{"drive":{"from":0,"to":1260}},"durationSeconds":6,"fps":18,"loop":true}'
```

The snapshot CLI defaults to `--theme technical`, a flat, high-contrast theme intended for visual diagnosis rather than presentation. `--theme` accepts a built-in theme name, an inline JSON theme object, or a path to a JSON theme file; set `theme.display.mode` to `solid` or `wireframe` for surface/wire output. `--params` targets Explorer `.step.js` STEP module sidecar parameters, not Python/build123d regeneration parameters. The snapshot CLI chooses default dimensions by request context when width/height are omitted: diagnostic stills 1600x1200, simple unlabeled parts 1200x900, sections/labeled/dimensioned views at least 1600x1200, complex assemblies 1800x1200 or 1920x1440 via `render.sizeProfile`, presentation renders 2400x1600 or 2800x1800 via `render.sizeProfile`, STEP-module parameter GIFs 960x640, and contact sheets at least 2400 px wide. Keep transparent snapshots presentation-oriented unless transparency answers a concrete overlap, collision, or internal-relationship question. Use JSON jobs for custom theme settings, selections, sections, orbit settings, robot joint values, STEP module params, DXF thickness/bend options, and multi-output snapshots. Supported render modes are `view`, `orbit`, `section`, and `list`. Supported inputs are `.step`, `.stp`, `.glb`, `.stl`, `.3mf`, `.dxf`, `.urdf`, `.srdf`, and `.sdf`.

When the workspace root is known, pass it explicitly:

```bash
npm --prefix scripts/viewer run dev:ensure -- \
  --workspace-root /path/to/workspace \
  --file path/to/model.step
```

Use foreground Vite only for manual Explorer development:

```bash
npm --prefix scripts/viewer run dev
```

`dev:ensure` probes and checks registered local CAD Explorer servers across its full port range first, reuses one with a matching scan root whenever possible, and only then starts a detached Vite server on the first available port. Use the URL it prints.

## MoveIt2 Controls

For SRDF Explorer reviews, start the MoveIt2 server only when the user needs interactive IK or path-planning controls. SRDF generation and plain Explorer links do not require it.

From this skill directory:

```bash
scripts/moveit2_server/setup.sh
scripts/moveit2_server/check-moveit2-server.sh
scripts/moveit2_server/run-moveit2-server.sh
```

The server defaults to `ws://127.0.0.1:8765/ws`. CAD Explorer connects to that URL in local dev unless `EXPLORER_MOVEIT2_WS_URL` or the browser `?moveit2Ws=` query override is set.

For protocol and reporting details, read `references/moveit2-server.md`.

Useful Explorer environment variables:

```text
EXPLORER_PORT
EXPLORER_PORT_END
EXPLORER_ROOT_DIR
EXPLORER_DEFAULT_FILE
EXPLORER_WORKSPACE_ROOT
EXPLORER_GITHUB_URL
EXPLORER_MOVEIT2_WS_URL
EXPLORER_ALLOWED_HOSTS
EXPLORER_SERVER_REGISTRY
```

When exposing CAD Explorer through remotehost/Tailscale Serve, set `EXPLORER_ALLOWED_HOSTS` to the Serve hostname before starting or restarting `dev:ensure`:

```bash
EXPLORER_ALLOWED_HOSTS=macbook-pro-108.tail3c8ded.ts.net \
  npm --prefix scripts/viewer run dev:ensure -- \
    --workspace-root /path/to/workspace \
    --root-dir models \
    --file path/to/model.urdf
```

Before returning the remote link, verify the host-header path locally:

```bash
curl -I -H 'Host: macbook-pro-108.tail3c8ded.ts.net' \
  'http://127.0.0.1:PORT/?file=path/to/model.urdf'
```

The expected response is `200 OK`.

If a remote phone loads the page shell but shows a blank/black screen through a Vite dev server, try a production preview before deeper rendering changes. Build with the same scan root and default file, start `vite preview` with the same `EXPLORER_ALLOWED_HOSTS` hostname, verify the Host-header path, then repoint remotehost/Tailscale Serve to the preview port:

```bash
EXPLORER_WORKSPACE_ROOT=/path/to/workspace \
EXPLORER_ROOT_DIR=models \
EXPLORER_DEFAULT_FILE=robots/elrobot/elrobot-follower.urdf \
  npm --prefix scripts/viewer run build

cd scripts/viewer
EXPLORER_WORKSPACE_ROOT=/path/to/workspace \
EXPLORER_ROOT_DIR=models \
EXPLORER_DEFAULT_FILE=robots/elrobot/elrobot-follower.urdf \
EXPLORER_ALLOWED_HOSTS=macbook-pro-108.tail3c8ded.ts.net \
EXPLORER_PORT=4202 \
  npm exec vite preview -- --host 127.0.0.1 --port 4202 --strictPort
```

This removes Vite's dev client and HMR websocket from the phone path while preserving the same `?file=` URL.

Keep GUI work lightweight: start the server only when a link/review is needed, prefer `dev:ensure` for agent workflows, and do not stop an existing Explorer server unless the user asks.