render

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

使用此技能在CAD Explorer中打开生成或修改后的CAD和机器人描述文件。预期输入为一个或多个已存在或刚由其他技能生成的明确文件路径。

支持的文件格式：

.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.

接收来自CAD、URDF、SRDF、SDF、SendCutSend或标准零件工作流的明确文件路径。
使用
```
dev:ensure
```
启动或复用CAD Explorer；不要假设固定端口。将
```
dev:ensure
```
视为返回链接的查看器活性检查。
端口复用为强制要求：如果
```
dev:ensure
```
报告本地绑定/探测拒绝（如
```
EPERM
```
或
```
EACCES
```
），则使用所需的本地绑定权限/提升重新运行相同的
```
dev:ensure
```
命令，而非自行选择新端口。
常规Agent移交时，不要使用
```
npm run dev -- --port ...
```
、原始
```
vite dev
```
或原始
```
vite preview
```
；这些会绕过复用策略，可能导致本地运行多个重复的Explorer服务器。
为每个请求的文件返回打印的Explorer URL。
对于生成审阅或视觉反馈，优先使用快照CLI而非手动打开查看器或使用Playwright。仍需返回查看器链接用于移交/实时审阅。
仅为CAD STEP模块参数动画审阅生成GIF。否则使用静态快照，而非GIF。
如果启动失败，报告失败情况并让所属技能继续执行其非GUI验证流程。

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

solid

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.

在此技能目录下执行：

bash

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

如需保存无头快照，请使用技能级别的快照包装器。它会委托给查看器包的

scripts/viewer/snapshot

实现：

bash

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

仅针对常见主题快照提供快捷标志：

bash

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

可以使用

--params

提供STEP模块副文件参数，用于静态快照或参数动画GIF：

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}'

快照CLI默认使用

--theme technical

，这是一种扁平化、高对比度的主题，用于视觉诊断而非展示。

--theme

接受内置主题名称、内联JSON主题对象或JSON主题文件路径；将

theme.display.mode

设置为

solid

或

wireframe

可输出曲面/线框效果。

--params

针对的是Explorer的

.step.js

STEP模块副文件参数，而非Python/build123d重新生成参数。当省略宽度/高度时，快照CLI会根据请求上下文选择默认尺寸：诊断静态图为1600x1200，无标签简单零件为1200x900，截面/带标签/标注视图至少为1600x1200，复杂装配体通过

render.sizeProfile

设置为1800x1200或1920x1440，展示渲染图通过

render.sizeProfile

设置为2400x1600或2800x1800，STEP模块参数GIF为960x640，联系表宽度至少为2400像素。除非透明度能解决具体的重叠、碰撞或内部关系问题，否则透明快照应面向展示用途。自定义主题设置、选择项、截面、轨道设置、机器人关节值、STEP模块参数、DXF厚度/折弯选项以及多输出快照请使用JSON任务。支持的渲染模式包括

view

、

orbit

、

section

和

list

。支持的输入格式为

.step

、

.stp

、

.glb

、

.stl

、

.3mf

、

.dxf

、

.urdf

、

.srdf

和

.sdf

。

当已知工作区根目录时，请显式传递：

bash

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

仅在手动开发Explorer时使用前台Vite：

bash

npm --prefix scripts/viewer run dev

dev:ensure

会首先在其完整端口范围内探测并检查已注册的本地CAD Explorer服务器，尽可能复用具有匹配扫描根目录的服务器，仅在必要时才在第一个可用端口启动一个后台Vite服务器。使用它打印的URL。

MoveIt2 Controls

MoveIt2 控制

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.

对于SRDF Explorer审阅，仅当用户需要交互式逆运动学（IK）或路径规划控制时才启动MoveIt2服务器。SRDF生成和普通Explorer链接不需要它。

在此技能目录下执行：

bash

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

服务器默认地址为

ws://127.0.0.1:8765/ws

。本地开发环境中，CAD Explorer会连接到此URL，除非设置了

EXPLORER_MOVEIT2_WS_URL

或浏览器

?moveit2Ws=

查询参数进行覆盖。

有关协议和报告的详细信息，请阅读

references/moveit2-server.md

。

实用的Explorer环境变量：

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

当通过remotehost/Tailscale Serve暴露CAD Explorer时，在启动或重启

dev:ensure

之前，将

EXPLORER_ALLOWED_HOSTS

设置为Serve主机名：

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

返回远程链接之前，请在本地验证主机头路径：

bash

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

预期响应为

200 OK

。

如果远程手机通过Vite开发服务器加载页面框架但显示空白/黑屏，请在进行更深层次的渲染更改前尝试生产预览。使用相同的扫描根目录和默认文件进行构建，使用相同的

EXPLORER_ALLOWED_HOSTS

主机名启动

vite preview

，验证主机头路径，然后将remotehost/Tailscale Serve重新指向预览端口：

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

这会从手机的访问路径中移除Vite的开发客户端和HMR websocket，同时保留相同的

?file=

URL。

保持GUI工作轻量化：仅在需要链接/审阅时启动服务器，Agent工作流优先使用

dev:ensure

，除非用户要求，否则不要停止现有Explorer服务器。