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.

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:

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:

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

Shortcut flags are available for common theme snapshots only:

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:

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:

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:

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:

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:

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:

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:

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:

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.