implicit-cad

隐式 CAD

当你要创建可直接在 CAD Viewer 中作为浏览器 JS 模块运行的隐式 CAD 模型时，使用此技能。主要产物是 .implicit.js 或 .implicit.mjs。

此技能为实验性功能。除非用户明确要求隐式模型，否则始终优先采用传统的 STEP 优先 CAD 工作流。

文件格式

隐式 CAD 文件是一个 ES 模块，导出一个 implicit.js/0.1.0 对象。Schema 的权威来源位于捆绑包中的 scripts/packages/implicitjs/src/lib/implicitCad/schema.js；对于由辅助工具编写的模块，scripts/lib/implicit-cad.mjs 会将其重新导出为 SCHEMA。

export default {
  schema: "implicit.js/0.1.0",
  name: "rounded capsule block",
  glsl: `
float sdf(vec3 p) {
  float sphere = implicit_sphere(p, vec3(0.0), 22.0);
  float block = implicit_box_centered(p, vec3(34.0, 18.0, 18.0), vec3(0.0));
  return implicit_union_round(sphere, block, 3.0);
}

vec3 color(vec3 p, vec3 normal) {
  return mix(vec3(0.20, 0.55, 0.95), vec3(0.95, 0.45, 0.20), smoothstep(-15.0, 20.0, p.z));
}
`,
};

模型还可以声明 params 和 animations。参数定义使用 implicitjs 控件 schema：number、boolean、enum/select、color、string 和 button。Number、boolean、color 和 button 参数会自动成为同名 GLSL uniform；不要另行添加 uniforms 对象。bounds 为可选项，省略时会根据 SDF 进行估算；只有当自动估算范围过宽、速度过慢或未涵盖特殊场时，才添加显式 bounds。bounds 和 render 可以是 JavaScript 函数，接收 { ...params, params, animation, animationState, elapsedSec, progress, t }。

内置 GLSL 辅助函数使用 implicit_* 命名空间，例如 implicit_sphere、implicit_box_centered 和 implicit_union_round。

export default {
  schema: "implicit.js/0.1.0",
  name: "breathing orb",
  params: {
    radius: {
      type: "number",
      label: "Radius",
      min: 12,
      max: 34,
      default: 22,
      unit: "mm",
    },
  },
  animations: {
    breathe: {
      label: "Breathe",
      duration: 3,
      update({ progress, set }) {
        set("radius", 18 + Math.sin(progress * Math.PI) * 10);
      },
    },
  },
  render: { steps: 224, epsilon: 0.004 },
  glsl: `
float sdf(vec3 p) {
  return length(p) - radius;
}

vec3 color(vec3 p, vec3 normal) {
  return mix(vec3(0.10, 0.58, 0.95), vec3(1.0, 0.34, 0.12), smoothstep(-18.0, 18.0, p.z));
}
`,
};

不要将捆绑的辅助文件复制到此技能之外。如果需要使用辅助函数，请在编写过程中使用 scripts/lib/implicit-cad.mjs，或将独立 GLSL 代码直接写入最终的 .implicit.js/.implicit.mjs 模块。

编写工作流

1. 编写自然语言建模说明，包含尺寸、坐标假设、程序化颜色意图和视觉检查项。
2. 创建或编辑用户指定的 .implicit.js/.implicit.mjs 模块。
3. 需要时，使用 scripts/lib/implicit-cad.mjs 辅助函数处理基本图元和场的组合：
   • 基本图元：sphere、circle、boxCentered、plane、lineSegment、torus、axis、cylinder、cylinderCapped、capsule、cone、coneCapped、coneCapsule
   • 布尔运算/混合：unionSharp、intersectSharp、unionRound、intersectRound、unionChamfer、intersectChamfer、unionExp、intersectExp、unionLpNorm、intersectLpNorm、unionRvachev、intersectRvachev、difference
   • 修改器/晶格：shell、rotateAxis、repeatCentered、remapCylindrical、cubicGrid、squareHoneycomb、squareHoneycombReinforced、squareDiagonalHoneycomb、octetHoneycomb、hexagonalHoneycomb、triangularHoneycomb
   • TPMS 场：tpmsGyroid、tpmsSchwarz、tpmsDiamond、tpmsLidinoid、tpmsNeovius、tpmsSplitP、tpmsIwp
   • 着色器封装函数：distanceFunction 会生成 float sdf(vec3 p)，colorFunction 会生成 vec3 color(vec3 p, vec3 normal)
4. 可以添加可选的 params 和 animations，用于控制尺寸、开关、调色板、模式切换和动画探索。在 GLSL 中直接使用参数名称；运行时会声明匹配的 uniform。
5. 如果模型适合使用局部材质变化，可添加可选的程序化颜色 vec3 color(vec3 p, vec3 normal)。颜色值应保持在 0..1 RGB 范围内。
6. 首先依赖自动 SDF 边界。对于动画模型、周期模型、平移模型或非常薄的模型，如果需要更紧凑或更可靠的取景/导出采样，再添加显式 bounds。
7. 对可见几何、颜色、params、动画、bounds、render 或影响导出的内容进行更改后，运行下方的轻量级视觉验证流程。
8. 运行 python scripts/gen <model.implicit.js> 进行构建（或刷新）CAD Viewer 打开的渲染包。如果还需要生成同级的 <name>.glb，添加 --write；如需导出 STL/3MF、使用非默认参数或导出动画，则使用 node scripts/export.mjs --input <model.implicit.js> --glb。

视觉验证

将此技能的快照工具用作快速视觉检查，而非确定性导入／导出验证的替代方案。让输出包保持精简且有明确目的。

对于简单的静态编辑，一张图就够了：

python scripts/snapshot --input models/implicit-cad/<model>.implicit.js --output /tmp/implicit-review/<model>.png

对于拓扑、周期性、细小特征、布尔混合、对象标识、颜色或疑似取景问题，请在一次 CLI 调用中渲染一个小型输出包，以便复用浏览器、模块和运行时模型：

python scripts/snapshot --job - <<'JSON'
{
  "input": "models/implicit-cad/<model>.implicit.js",
  "mode": "view",
  "render": { "sizeProfile": "simple", "frameMargin": 1.55 },
  "graphics": { "modelColors": true, "detail": 1.2, "shadows": true, "ambientOcclusion": true },
  "outputs": [
    { "path": "/tmp/implicit-review/<model>-iso.png", "camera": "iso" },
    { "path": "/tmp/implicit-review/<model>-front.png", "camera": "front" },
    { "path": "/tmp/implicit-review/<model>-top.png", "camera": "top" },
    { "path": "/tmp/implicit-review/<model>-right.png", "camera": "right" }
  ]
}
JSON

如果只需一种参数状态，请在作业级别添加 implicitParameters；如果审查重点是比较不同参数变体，则在各个输出上分别添加。模型靠近边缘时，将 render.frameMargin 设为约 1.5；如果快照仍然看起来被裁切，请先检查源 bounds 是否正在裁切光线步进本身。

只有当请求涉及运动时，才为动画创建短 GIF：

python scripts/snapshot --job - <<'JSON'
{
  "input": "models/implicit-cad/<model>.implicit.js",
  "mode": "animate",
  "outputs": [{ "path": "/tmp/implicit-review/<model>-animation.gif" }],
  "implicitAnimation": { "activeId": "<animation-id>", "durationSeconds": 3, "fps": 12 }
}
JSON

检查生成的 PNG/GIF，确认取景居中、顶部／底部／侧面均未被裁切、轮廓和拓扑符合预期、参数差异清晰可见、颜色由 GLSL 定义、没有意外的孔洞／间隙，并且边缘平滑度符合所需的图形设置。如果快照揭示了不匹配，请修复隐式源文件或边界，并仅重新运行相关输出包。

交接

完成创建或修改 .implicit.js、.implicit.mjs、.glb、.stl 或 .3mf 工件的隐式 CAD 工作后，如果已安装 $cad-viewer 技能，你必须始终将明确的文件路径交给 $cad-viewer。如果 CAD Viewer 尚未运行，$cad-viewer 必须启动它，并返回相关新建或更新文件的链接；请在最终回复中附上这些实时查看器链接。如果 $cad-viewer 不可用或启动失败，请说明原因，不要默默省略交接。

生成验证快照时，也请在最终回复中附上已保存的 PNG/GIF 快照。如果不适用快照，或快照生成失败，请说明原因，并报告仍已执行的确定性验证。

快照工具

在此技能目录中：

python scripts/snapshot --input <model.implicit.js> --output <snapshot.png>
python scripts/snapshot --input <model.implicit.js> --output <orbit.gif> --mode orbit
python scripts/snapshot --job <render-job.json>
python scripts/snapshot --job - --json
python scripts/snapshot --help

使用 python scripts/snapshot --help 查看当前完整的命令接口。此快照 CLI 与所有其他渲染技能共享（cadgen.snapshot_cli），并由 CAD Viewer 使用的同一浏览器运行时驱动，因此几何体、材质和照明的渲染结果完全一致。默认的 snapshot 主题与视口的唯一区别是去除了网格、原点轴和阴影；此技能仅启用 .implicit.js。主题设置通过单个 --theme 指定，隐式光线步进质量通过 --graphics 指定，与查看器中的 Theme 和 Graphics 选项卡一致。没有 --display：显示设置属于 CAD 拓扑设置，而隐式模型不包含此类设置。默认主题为 snapshot——Workbench Light，但不含地面网格、原点轴或阴影；此处默认也会关闭光线步进阴影，因此隐式快照与无阴影的网格路径一致（传入 --graphics '{"shadows":true}' 可恢复阴影）。工具会在输出扩展名前附加 UTC 时间戳。JSON 作业可以是单个作业、包含多个 outputs 的单个作业、原始作业数组，或 { "jobs": [...] }；对于审查输出包，优先使用多输出作业，因为这样无需为每个相机重复构建同一工件。

生成工具

在此技能目录中：

python scripts/gen <model.implicit.js>
python scripts/gen <model.implicit.js> --write
python scripts/gen models/implicits/*.implicit.js --force
python scripts/gen <model.implicit.js> --resolution 128 --threads 4
python scripts/gen --help

scripts/gen 会构建模型的 渲染包——CAD Viewer 打开时使用的烘焙网格，位于模型文件夹的 __cadgen__/models/<name>.implicit.js/ 下（包含 implicit.json 和 model.glb）。该包基于模型参数的默认值烘焙，不包含实时参数或动画。查看器也会按需通过同一个生成器构建此包，因此在此处构建的包与打开模型时构建的包是同一份产物。

当前包未过期的模型会被跳过；使用 --force 可强制重新构建。--write 还会将同一网格处理过程生成的同名 <name>.glb 保存在源文件旁边。该文件是普通的导出预设 GLB（包内的 model.glb 已压缩以供查看器使用，不能替代它）。如果需要 STL 或 3MF、非默认参数或动画，请使用 scripts/export。

导出工具

在此技能目录中：

node scripts/export.mjs --input <model.implicit.js> --glb
node scripts/export.mjs --input <model.implicit.js> --stl <mesh.stl> --resolution <resolution>
node scripts/export.mjs --input <model.implicit.js> --stl --3mf --glb
node scripts/export.mjs --input <model.implicit.js> --3mf --params '<parameter-json>' --json
node scripts/export.mjs --help

每种格式对应一个标志——--stl、--3mf、--glb——可在一次运行中指定多个，与 CAD 技能的导出 CLI 一致。至少需要指定一个；否则命令会以状态码 2 退出。每次运行只会对模型进行一次网格处理，因此所有请求的格式都基于相同的几何形状。格式标志未指定路径时，会使用相同的文件名主体将文件写在源文件旁边，例如 <model>.implicit.js 对应 <model>.glb；指定的路径则相对于当前目录解析。使用 node scripts/export.mjs --help 查看完整的当前命令接口。