text-to-cad CAD Viewer使用完全指南：URL构造、文件浏览器与显示设置
【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad
text-to-cad 是一个面向 AI 代理的 CAD 技能库，其中的CAD Viewer技能可以在本地浏览器中预览 STEP、STL、URDF、SRDF 等各类 CAD 文件。本指南带你快速掌握 CAD Viewer 的三大核心能力：URL 构造、文件浏览器和显示设置，让你无需打开专业 CAD 软件，就能在网页里检查、标注和导出任何模型。
一、什么是 CAD Viewer：本地浏览器里的 CAD 预览器
CAD Viewer 是 text-to-cad 技能库中的一个独立技能，位于 skills/cad-viewer/SKILL.md。它的工作方式非常简洁：
- 在本地启动一个**固定端口（3245）**的 Web 服务，同时提供 Viewer 界面和 CAD API
- URL 的路径部分直接指向一个绝对目录，
file=参数指定目录中的某个模型文件 - 一个 Viewer 实例可以服务任意文件夹，无需针对某个目录重复启动
💡 小知识：默认端口
3245其实就是十六进制0xCAD——"CAD" 的十六进制写法，是不是很巧妙？
它支持的文件类型覆盖 CAD 和机器人描述的绝大部分场景，完整列表见 skills/cad-viewer/references/viewer-features.md：
| 文件类型 | 预览能力 |
|---|---|
.step/.stp | 装配树、部件显隐、面/边/顶点选择、剖切面、参数动画 |
.stl/.3mf/.glb | 网格查看、旋转/平移/缩放、截图、实体/线框显示 |
.dxf | 只读 3D 展开图预览（自动生成拉伸实体） |
.implicit.js/.implicit.mjs | GPU 光线步进实时渲染，参数可交互调节 |
.urdf | 机器人连杆/网格查看、关节滑杆、姿态复位 |
.srdf | 规划组、组姿态预设、关节控制，可选 MoveIt2 IK |
.sdf | 仿真模型/世界查看、元数据与警告、关节控制 |
二、一键启动步骤：3 条命令搞定环境准备
启动 Viewer 只需一条命令（在cad-viewer技能目录下执行）：
npm --prefix scripts/viewer run start -- --host 127.0.0.1启动器会打印出生成的 URL，形如http://127.0.0.1:3245/你的目录，直接复制到浏览器打开即可。
启动时的几个关键点：
- 端口固定为 3245。如果端口被占用，启动器会直接报错退出（不会自动换端口），此时加上
--port <n>指定一个空闲端口，并使用它打印的新 URL - 机器可读输出：加上
--json参数后，stdout 最后一行会输出{"url": ..., "port": ..., "action": "start"}，方便脚本解析 - 启动失败不影响其他流程，技能会回退到非 GUI 的校验方式
启动逻辑的入口脚本是 skills/cad-viewer/scripts/viewer/start_viewer.py，npm 脚本定义见 skills/cad-viewer/scripts/viewer/package.json。
三、URL构造：CAD Viewer 最核心的技巧
这是新手最容易踩坑的部分，掌握后你会发现链接构造其实有严格的"公式"。
URL 的标准形态
http://127.0.0.1:3245/absolute/project/models?file=mechanisms/lift_table.step.py可以拆解为三个部分：
- 主机 + 端口：
http://127.0.0.1:3245 - 路径 = 绝对目录：
/absolute/project/models，就像file://URL 里的目录 - file= 参数 = 相对路径：
mechanisms/lift_table.step.py，相对于上面那个目录
三条黄金法则
法则一：路径必须用绝对目录。Viewer 运行时的工作目录是随机的（通常是技能安装目录，而不是你的模型目录），相对路径会解析到错误位置，务必使用绝对路径构造。
法则二：Windows 盘符放在 URL 首个斜杠之后，用正斜杠。例如D:\project\models应写成：
http://127.0.0.1:3245/D:/project/models法则三：路径是"工作区"，而不是文件所在的文件夹。Viewer 会递归扫描该目录，文件浏览器会列出下面所有模型，你可以不换链接自由切换文件。推荐选择用户心目中的模型工作区——通常是项目的models/目录，或待审文件的最近公共父目录。
⚠️ 反例：把路径指到
.../models/step/mechanisms?file=lift_table.step.py这种文件的深层目录，虽然能打开同一个模型，但会隐藏项目里的其他文件——几乎不是用户想要的结果。
链接的返回规范
按 SKILL.md 中的约定，返回链接前必须确认<目录>/<文件>真实存在；对于生成的模型传生成器源码（如lift_table.step.py），后端会按需构建渲染产物，无需.step文件存在；对于导入的STEP 则直接传.step/.stp文件。同一会话内的所有链接应共享同一个根目录，保证共用一个可浏览的文件目录。
四、文件浏览器：不换链接切换任意模型
URL 指到工作区目录后，左侧的文件浏览器（File Browser）就是自由切换文件的入口：
- 搜索：按文件名、ID 或路径搜索文件
- 展开文件夹：逐级浏览目录树
- 面包屑菜单：快速跳转到任意层级的目录
- 侧边栏开关：左侧 CAD Viewer 侧边栏可整体收起/展开，保持视口干净
配合"路径即工作区"的设计，一个链接就够整个团队浏览整个项目的所有模型。
五、显示设置：模式、剖切面与爆炸图
右侧的**文件面板（File Sheet）**的Display 标签页集中了所有单文件显示控制，这也是查看模型细节最实用的区域。
1. 显示模式（Mode 下拉框）
提供 7 种模式一键切换：
- solid（实体）：默认外观
- rendered（渲染）：带光影的真实感
- x-ray（X 光）：透视查看内部结构
- hidden（隐藏线）：去掉被遮挡的线条
- lines（线条）/flat（平面）/wire（线框）
2. 剖切面（Clip）
三个 X/Y/Z 方向的位置滑杆，加Flip（翻转）和Reset（重置）按钮。偏移量为 0 即不切割——调一调滑杆就能"切开"模型看内部装配关系。
3. 爆炸视图（Exploded）
一个开关即可把装配体"炸开"：
- Amount（数量）：控制爆炸程度
- Automatic / Custom：自动布局或手动微调每个部件的移动
- Direction：Auto / X / Y / Z / Radial 五种爆炸方向
- 还有 Reverse、Spread、Detail、Order、爆炸线显示和 Reset 等精细控制
4. 主题设置（Theme）
导航栏的主题按钮打开主题侧边栏，管理全局持久主题：预设下拉框（系统 + 内置预设）、表面颜色、背景、地板/网格、光照和颜色模式。所有设置都保存在唯一的"Custom"槽位中——修改任何设置即写入 Custom，重新选择某个预设即可重置，无需手动保存。
📌 注意区分：Display 标签页管的是单个文件的视图状态（模式、剖切、爆炸）；主题侧边栏管的是全局外观。两者互斥——文件面板和主题侧边栏同一时间只能打开一个。
六、操作速查：导航与浮动工具栏
导航操作（所有文件通用）：
| 操作 | 效果 |
|---|---|
| 左键拖动 | 旋转视角 |
| 右键 / 中键拖动 | 平移 |
| 滚轮 / 双指捏合 | 缩放 |
| 方向键 / WASD | 旋转视角 |
| 视图球 | 快速切换上/下/前/后/左/右视图 |
| 点击视图球中心 | 回到默认等轴测视图 |
浮动工具栏：Select复制 STEP 拓扑引用（复制出的#...参考可以粘贴到 AI 提示词中，精确定位要修改的部件）、Draw打开标注工具（自由笔、直线、箭头、矩形、圆形、填充、擦除等）、Select Pose机器人目标拾取、Open orbit preview自动旋转预览，以及截图复制/下载按钮。
首次使用小技巧：第一次选中部件时会出现一次性提示，解释"复制的#...参考可以粘贴进提示词来编辑特定部件"。如果提示消失了想重新看，在 URL 后加?resetTips=1即可恢复。
七、进阶：SRDF 文件搭配 MoveIt2 做逆运动学
对于机器人描述文件，CAD Viewer 还支持可选的 MoveIt2 集成：打开.srdf文件后展开右侧MoveIt2面板，即可完成目标姿态求解（IK）和路径规划——包括规划组选择、IK 超时/容差设置、规划管线与速度/加速度缩放等完整控制。
配置流程（在cad-viewer技能目录下依次执行）：
npm --prefix scripts/viewer run moveit2:setup npm --prefix scripts/viewer run moveit2:check npm --prefix scripts/viewer run moveit2:serveMoveIt2 服务默认运行在ws://127.0.0.1:8765/ws，详细参数说明见 skills/cad-viewer/references/moveit2-server.md。
八、常见问题快速排查
Q1：端口 3245 被占用，启动报错？加--port <n>指定空闲端口，使用新打印的 URL 即可。
Q2：链接打不开 / 文件找不到？回到法则一：确认 URL 路径是绝对目录，且file=值是相对于该目录的真实存在路径。注意 Windows 盘符要放在 URL 首个斜杠之后（/D:/...）。
Q3：为什么生成的模型链接是.step.py而不是.step？这是刻意的：生成器源码是目录（catalog）登记的格式，后端会按需直接构建渲染产物，且只有它携带params参数侧车文件。
Q4：如何一次查看整个项目的所有模型？把 URL 路径指向项目的工作区根目录（如models/），不加file=参数——递归扫描会让文件浏览器列出全部模型。
总结：CAD Viewer 的核心就是记住一句口诀——"绝对目录进路径，相对文件进 file="。掌握这条 URL 构造规则，再配合文件浏览器和 Display 标签页里的模式/剖切/爆炸三大显示设置，你就能在浏览器里完成绝大多数 CAD 模型的检查与评审工作。更多细节可查阅 skills/cad-viewer/references/viewer-features.md 和 skills/cad-viewer/SKILL.md。
【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
