implicit-cad

Implicit CAD

使用此技能处理应在CAD Viewer中作为浏览器JS模块直接运行的隐式CAD模型。主要产物是 .implicit.js 或 .implicit.mjs 文件。

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

文件格式

隐式CAD文件是一个ES模块，导出 implicit.js/0.1.0 对象。模式源文件位于打包包中的 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));
}
`,
};

模型还可以声明参数和动画。参数定义使用implicitjs控制模式：number、boolean、enum/select、color、string 和 button。数字、布尔、颜色和按钮参数会自动成为同名的GLSL uniform；不要添加单独的 uniforms 对象。bounds 是可选的，省略时会从SDF自动估算；仅在自动估算范围过大、过慢或遗漏异常场时添加显式边界。bounds 和 render 可以是接收 { ...params, params, animation, animationState, elapsedSec, progress, t } 的JavaScript函数。

内置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边界。当动画、周期性、平移或非常薄的模型需要更紧或更可靠的帧/导出采样时，添加显式边界。
7. 在对可见几何体、颜色、参数、动画、边界、渲染或导出影响进行更改后，运行下面的轻量级视觉验证流程。
8. 当需要为下游查看器、切片器或文件交接提供网格工件时，运行 node scripts/export.mjs --input <model.implicit.js> --format glb。

视觉验证

使用此技能的快照工具作为快速视觉检查，而不是确定性导入/导出验证的替代。保持数据包小巧且有目的性。

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

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

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

node scripts/snapshot.mjs --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：

node scripts/snapshot.mjs --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快照。如果没有适用的快照，或快照生成失败，说明原因并报告仍然运行的确定性验证。

快照工具

在此技能目录中：

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

使用 node scripts/snapshot.mjs --help 获取完整的当前命令接口。该工具会在输出扩展名前附加UTC时间戳。JSON作业可以是单个作业、一个包含多个 outputs 的作业、原始作业数组，或 { "jobs": [...] }；对于审查数据包，优先使用多输出作业，因为它避免了为每个相机重建相同工件。

导出工具

在此技能目录中：

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

支持的导出格式为 glb、stl 和 3mf。导出器在声明的边界内采样隐式SDF并提取三角形网格。如果省略 --output，网格将写入源文件旁边，使用相同的主文件名，例如 <model>.glb 对应 <model>.implicit.js。使用 node scripts/export.mjs --help 获取完整的当前命令接口。