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:
,
,
,
,
,
,
,
,
.
Handoff Contract
- Accept explicit file paths from CAD, URDF, SRDF, SDF, SendCutSend, or standard-part workflows.
- Start or reuse CAD Explorer with ; do not assume a fixed port. Treat as the viewer liveness check for returned links.
- Treat port reuse as mandatory: if reports local binding/probing denial such as or , rerun the same command with the needed local-binding permission/escalation instead of choosing a new port yourself.
- Do not use
npm run dev -- --port ...
- 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
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
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
, a flat, high-contrast theme intended for visual diagnosis rather than presentation.
accepts a built-in theme name, an inline JSON theme object, or a path to a JSON theme file; set
to
or
for surface/wire output.
targets Explorer
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
, presentation renders 2400x1600 or 2800x1800 via
, 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
,
,
, and
. Supported inputs are
,
,
,
,
,
,
,
, and
.
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
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
. CAD Explorer connects to that URL in local dev unless
or the browser
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
to the Serve hostname before starting or restarting
:
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
.
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
with the same
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
URL.
Keep GUI work lightweight: start the server only when a link/review is needed, prefer
for agent workflows, and do not stop an existing Explorer server unless the user asks.