企业官网建设流程全解析

text-to-cad快照机制深度剖析：无头浏览器如何拍摄三维截图与GIF

【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad

text-to-cad 是一个面向 CAD、CAE 与 CAM 的 Agent 技能库，而它的「快照（Snapshot）」机制，正是让 AI 无需打开任何图形界面，就能用无头浏览器（headless browser）把 STEP、GLB、STL 等三维模型拍成高清 PNG 截图与 360° 旋转 GIF的核心能力。本文带你拆解这套机制的三层架构、拍摄流程与工程细节。

什么是快照机制：给 AI 的“三维照相机” 📸

在 text-to-cad 的工作流里，Agent 用 build123d 写出 Python 几何生成器，构建出 STEP 模型后，必须“亲眼确认”模型长对了——但它没有显示器。

快照机制就解决了这个问题：一条命令启动一个看不见的 Chromium 浏览器，把模型按指定相机、主题、尺寸渲染出来，再把渲染结果编码成 base64 数据交还给 Python 进程落盘，最终得到一张 PNG 或一段 GIF。

它还承担了「视觉验证」的职责：CAD 技能规定，每次创建或修改主 STEP 工件后都必须跑快照审查，而不是只靠确定性检查。策略细节见 snapshot-review.md。

三层架构：入口、引擎、浏览器运行时

快照功能被清晰地拆成三层，各层职责明确、可复用：

1️⃣ 命令行入口：每个技能自带scripts/snapshot

CAD 技能的入口只有约 50 行代码（main.py），它声明两件事：

• 本技能接受哪些输入：STEP/STP/3MF/GLB/STL（见 KINDS 定义）
• 本技能的浏览器运行时放在哪：runtime/目录

而参数解析、任务归一化等重活全部交给共享库。如果给 CAD 技能喂一个它不认的.implicit.js，它会明确告知该找 implicit-cad 技能，而不是莫名其妙地报错。

2️⃣ 共享引擎：cadgen里的 CLI 与 Core

真正干活的是 cadgen 包中的两个模块：

• snapshot_cli.py：负责命令行与「每种输入类型各自是什么」的解析。五种渲染模式定义在 模式说明：

  • view：每个输出一张静态图（默认）
  • orbit：360° 转台 GIF
  • animate：GIF 扫描模型自带动画
  • section：剖切扫掠
  • list：输出零件引用 JSON，不写文件

• snapshot_core.py：格式无关的核心——无头浏览器驱动、相机/主题/显示/尺寸归一化、输出落盘。它被 CAD、DXF、URDF、SRDF、SDF 等多个技能共用。

3️⃣ 浏览器运行时：19 行的 HTML + 一个渲染模块

运行时目录只有两个文件：

• render.html：仅 19 行，透明背景、无滚动条，唯一作用就是加载渲染脚本
• snapshot-render.js：打包了 Three.js、STEP 解析器与 raymarching 后端的单文件模块，向页面暴露window.__snapshotRender函数

无头浏览器拍摄的完整流程

核心流程在 BatchSnapshotRenderer 中，可以概括为五步：

1. 启动 Chromium：通过 Playwright 以headless=True启动无头浏览器，15 秒启动超时兜底
2. 拦截一切网络请求：页面绑定到虚拟域名http://snapshot.local（见 SNAPSHOT_ORIGIN），所有请求都不走真实网络，而是由 Python 从本地文件系统按路由规则读取——/render.html返回运行时文件，/__render_asset/...返回模型文件（还带 SHA-256 缓存键防脏读）
3. 等待就绪：轮询直到页面暴露出window.__snapshotRender函数
4. 执行渲染任务：把归一化好的 job（输入 URL、模式、相机、主题、输出尺寸）塞给浏览器执行，浏览器返回 base64 数据 URL
5. 落盘：Python 侧把 base64 解码写入 PNG/GIF 文件，并用 write_render_outputs 递归处理批量任务

整个过程不落地任何中间临时图，浏览器即拍即毁。

如何拍出一张“会说话”的截图 ✨

默认主题：为截图而生的snapshot主题

快照的默认主题是 snapshot——它源自 Workbench Light，但移除了地面网格和坐标轴。原因很微妙：在实时视口里它们是帮助定位的参考，但在静态图里会变成横穿模型的直线，被误认成轮廓边。材料、光照、背景则与查看器完全一致，零件所见即所得。

尺寸档位：不同用途不同分辨率

--size-profile对应一组预置分辨率：

防翻车设计：GIF 帧预算预警

动画渲染的每一帧都要驻留内存直到 GIF 编码完成，代价是「帧数 × 像素」。核心代码实测发现超过约 120 Mpx 时，无头浏览器会在长时间计算后被系统杀掉（TargetClosedError），辛苦白干。于是 帧预算预检 会在启动前就发出警告，建议降帧率、缩时长或缩小输出。

同理，非 orbit 模式下指定.gif输出会被直接拒绝——否则会得到一个只有一帧、看似坏掉的 GIF。

快速上手：一条命令拍出你的第一张图

安装技能后（npx skills install earthtojake/text-to-cad），典型用法非常简洁：

# 拍一张等轴测静态图 python scripts/snapshot --input models/part.step --output /tmp/part.png # 拍一段 360° 转台 GIF python scripts/snapshot -i models/part.step -o /tmp/part.gif --mode orbit # 批量多视角：一个 JSON 作业，四个相机 python scripts/snapshot --job views.json

每个输出文件会自动加上共享的 UTC 秒级时间戳（如part_20260527T163012Z.png），便于 Agent 追踪；加--json可得到紧凑的机器可读结果。完整选项可用--help查看，策略参考 SKILL.md。

关键文件路径速查表

总结

text-to-cad 的快照机制把「打开三维软件、摆相机、截图」这件人类手工活，变成了一条可复现、可批量化、可机器读取的命令。三层架构（技能入口 / 共享引擎 / 浏览器运行时）让同一套无头浏览器拍摄能力被 CAD、DXF、URDF、SRDF、SDF 等多个技能复用；而主题设计、尺寸档位、GIF 帧预算等细节，则处处体现着「截图主要给 AI 看」这一产品决策。这正是 Agent 技能库把工程经验沉淀成可执行工作流的最佳范例。

【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad