implicit-cad

Implicit CAD

使用此技能處理應直接在 CAD Viewer 中以瀏覽器 JS 模組執行的隱式 CAD 模型。主要產出為 .implicit.js 或 .implicit.mjs 檔案。

此技能為實驗性功能。除非使用者明確要求隱式模型，否則一律優先使用傳統的 STEP 優先 CAD 工作流程。

檔案格式

隱式 CAD 檔案是一個匯出 implicit.js/0.1.0 物件的 ES 模組。結構定義的原始碼位於套件中的 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: "半徑",
      min: 12,
      max: 34,
      default: 22,
      unit: "mm",
    },
  },
  animations: {
    breathe: {
      label: "呼吸",
      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>.implicit.js 對應 <model>.glb。使用 node scripts/export.mjs --help 取得完整的目前命令介面。