@coloopx/colocad 0.1.0-alpha.3 → 0.1.0-alpha.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/NOTICE.md +2 -0
- package/README.md +30 -1
- package/README.zh-CN.md +30 -1
- package/bin/colocad.mjs +28 -4
- package/docs/README.md +27 -0
- package/docs/README.zh-CN.md +81 -0
- package/docs/modeling-history.md +60 -0
- package/examples/hiwin-kk60/README.md +55 -0
- package/examples/hiwin-kk60/model.mjs +94 -0
- package/examples/hiwin-kk60/run.mjs +14 -0
- package/examples/hiwin-kk60/sources.json +88 -0
- package/kernel/native/darwin-arm64/agent-cad +1 -1
- package/kernel/native/darwin-arm64/manifest.json +1 -2
- package/kernel/native/linux-arm64/agent-cad +1 -1
- package/kernel/native/linux-arm64/manifest.json +1 -2
- package/kernel/native/linux-x64/agent-cad +2 -2
- package/kernel/native/linux-x64/manifest.json +2 -3
- package/kernel/release.json +4 -4
- package/package.json +37 -4
- package/skills/colocad/SKILL.md +2 -0
- package/skills/colocad/references/history.md +19 -0
- package/src/render.mjs +72 -0
- package/src/session.d.mts +34 -0
- package/src/session.mjs +140 -0
- package/src/view-server.mjs +50 -0
- package/viewer/THREE-LICENSE +21 -0
- package/viewer/dist/index.js +4236 -0
- package/viewer/dist/standalone.js +4236 -0
- package/viewer/index.d.ts +18 -0
package/NOTICE.md
CHANGED
|
@@ -3,3 +3,5 @@
|
|
|
3
3
|
Colocad and the included Agent CAD application code are distributed under the MIT license. The Rust application builds against SolidCore at revision bff1569a4c3347ed9af67faab71578cadf84fde2. SolidCore includes work derived from NVIDIA USD BRep / SMLib. The kernel's Apache-2.0 license, notices, attribution and licenses of Rust dependencies ship in `kernel/licenses`. Source provenance is also recorded in `third_party`.
|
|
4
4
|
|
|
5
5
|
The .NET author references SOLIDWORKS 2024 interop APIs. SOLIDWORKS is a trademark of its respective owner. A local licensed installation provides the proprietary COM application and its interop assemblies. The package contains Colocad's own managed assembly and source in the repository. The experimental file-format investigation uses the independently licensed cadmpeg project at d77e2dd2a9d154e7b432afb022c147864f2618bb.
|
|
6
|
+
|
|
7
|
+
The browser viewer bundles Three.js under the MIT license; its license is included in `viewer/THREE-LICENSE`. HIWIN and product names in the actuator reconstruction identify the source product; this project is not affiliated with or endorsed by the manufacturer. No manufacturer CAD or catalog PDF is redistributed.
|
package/README.md
CHANGED
|
@@ -1,9 +1,27 @@
|
|
|
1
1
|
# colocad
|
|
2
2
|
|
|
3
|
-
[中文说明](README.zh-CN.md) · [npm package](https://www.npmjs.com/package/@coloopx/colocad) · [Download the offline comparison](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html)
|
|
3
|
+
[中文说明](README.zh-CN.md) · [Developer docs](docs/README.md) · [npm package](https://www.npmjs.com/package/@coloopx/colocad) · [Download the offline comparison](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html)
|
|
4
4
|
|
|
5
5
|
Generate a mechanical part from a JSON feature tree, export an exact STEP solid, and give an agent a PNG or 3D preview to inspect. **The npm package ships the compiled Rust CAD kernel.** The agent and harness call it locally in the same sandbox through the Node CLI or TypeScript API. No Python, Rust toolchain, network or separate service is required to build a part after installation.
|
|
6
6
|
|
|
7
|
+
## Reconstruct a real industrial product and replay its modeling history
|
|
8
|
+
|
|
9
|
+
The [HIWIN KK60 actuator example](examples/hiwin-kk60/README.md) reconstructs a specific manufacturer catalog configuration: 300 mm rail, 5 mm lead, 210 mm travel. Its **52 native features, 81 named occurrences and 16 persisted milestones** include a physically cut helical screw groove, guide tracks, mounting holes, bearings, carriage and coupling.
|
|
10
|
+
|
|
11
|
+

|
|
12
|
+
|
|
13
|
+
[Watch the MP4](showcase/hiwin-kk60/modeling.mp4) · [Edit the model](showcase/hiwin-kk60/model.json) · [Read the independent checks](showcase/hiwin-kk60/verification.json) · [Dimensions and assumptions](examples/hiwin-kk60/sources.json)
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
|
|
17
|
+
npx colocad view ./actuator/session
|
|
18
|
+
npx colocad replay ./actuator/session ./actuator.html
|
|
19
|
+
# Optional: Playwright/Chromium + FFmpeg are required for video encoding.
|
|
20
|
+
npx colocad render ./actuator/session ./modeling.mp4
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
This is a catalog-based product reconstruction, with explicitly approximated internal races/bearings and no manufacturing certification. The animation reads actual saved CAD revisions; measured call times appear separately from edited playback. It is not a performance comparison. See [CLI history/rendering](docs/modeling-history.md) and the [actual agent modeling workflow](docs/modeling-workflow.zh-CN.md).
|
|
24
|
+
|
|
7
25
|
## How many tendon hands can an agent deliver in 100 seconds?
|
|
8
26
|
|
|
9
27
|
**colocad delivered 44 complete revisions to build123d’s 33 (+33.3%), with 57.1% lower peak sampled sandbox memory.** Both tools rebuilt and assembled the same 43-solid hand at each revision. Each tick marks a complete STEP handed off to storage.
|
|
@@ -45,6 +63,17 @@ The static scorecard below uses the **published alpha.2 binary**. With fresh too
|
|
|
45
63
|
|
|
46
64
|
## SDK, CLI or skill?
|
|
47
65
|
|
|
66
|
+
**Start here:** [first part and edit](docs/getting-started.md) · [SDK/API reference](docs/api.md) · [modeling best practices](docs/best-practices.md).
|
|
67
|
+
|
|
68
|
+
| Your harness | Integration guide |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| Pi agent core / Pi coding agent | [Typed tool adapter, extension and skill](docs/integrations/pi.md) |
|
|
71
|
+
| Claude Code | [Project skill and local CLI](docs/integrations/claude-code.md) |
|
|
72
|
+
| Codex | [Project skill, invocation and artifact inspection](docs/integrations/codex.md) |
|
|
73
|
+
| Other harnesses | [Sandbox architecture, revision state and artifact lifecycle](docs/integrations/overview.md) |
|
|
74
|
+
|
|
75
|
+
The [runnable examples](examples/integrations/README.md) exercise the published package, real native builds and Pi tool-loop error recovery. See [what was verified](docs/integrations/verification.md) and [how to contribute](CONTRIBUTING.md).
|
|
76
|
+
|
|
48
77
|
Install with `npm install @coloopx/colocad@0.1.0-alpha.3`. This version bundles the optimized assembly kernel and the complete agent skill. The skill lives at `node_modules/@coloopx/colocad/skills/colocad/`. Point your harness at its `SKILL.md` or copy the whole directory into your agent’s skill collection.
|
|
49
78
|
|
|
50
79
|
For a dimensioned part, try “Make a 100 × 50 × 6 mm plate with a centered 3 × 2 grid of Ø6 through-holes on 32 × 30 mm pitches.” The skill includes editable stock, hole grids, sleeves, brackets and open housings. [Quick-build commands and examples](skills/colocad/references/quick-build.md)
|
package/README.zh-CN.md
CHANGED
|
@@ -1,9 +1,27 @@
|
|
|
1
1
|
# colocad
|
|
2
2
|
|
|
3
|
-
[English](README.md) · [npm 包](https://www.npmjs.com/package/@coloopx/colocad) · [下载单文件对比报告:含四份 STEP](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html)
|
|
3
|
+
[English](README.md) · [开发与接入指南](docs/README.zh-CN.md) · [npm 包](https://www.npmjs.com/package/@coloopx/colocad) · [下载单文件对比报告:含四份 STEP](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html)
|
|
4
4
|
|
|
5
5
|
让沙箱内的 agent 用 JSON 描述可改参的机械零件,输出 STEP 实体、PNG 预览和 GLB/STL 网格。**npm 包自带编译好的 Rust CAD 内核**:Linux x64、Linux arm64 和 macOS arm64 各一份。agent 和 harness 在同一沙箱里调用 Node CLI 或 TypeScript API,CLI 直接启动本地 Rust 程序。安装后建模不需要网络、Python、Rust 工具链或额外服务。[Rust 源码](crates/agent-cad/src)和[内核依赖版本](third_party/solidcore.lock.json)在本仓库。
|
|
6
6
|
|
|
7
|
+
## 真实工业产品:从厂家图纸到整机及建模动画
|
|
8
|
+
|
|
9
|
+
[HIWIN KK60 执行器实例](examples/hiwin-kk60/README.md)对应真实目录配置:300 mm 导轨、5 mm 导程、210 mm 行程,包含 **52 个原生特征、81 个命名实例、16 个持久化建模阶段**。螺旋槽、安装孔、导轨滚道均为实际 B-rep 几何。
|
|
10
|
+
|
|
11
|
+

|
|
12
|
+
|
|
13
|
+
[MP4 动画](showcase/hiwin-kk60/modeling.mp4) · [可编辑模型](showcase/hiwin-kk60/model.json) · [独立验证](showcase/hiwin-kk60/verification.json) · [尺寸来源与假设](examples/hiwin-kk60/sources.json)
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
|
|
17
|
+
npx colocad view ./actuator/session
|
|
18
|
+
npx colocad replay ./actuator/session ./actuator.html
|
|
19
|
+
# 视频导出另需 Playwright/Chromium 和 FFmpeg。
|
|
20
|
+
npx colocad render ./actuator/session ./modeling.mp4
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
这是依据厂家目录进行的整机复建,未公开的轴承、滚道与回珠细节有明确近似/缺失标注,不能作为制造认证模型。动画读取实际保存的建模结果,播放节奏与实测构建耗时分开显示,不构成 build123d 性能比较。参见[实际操作流程](docs/modeling-workflow.zh-CN.md)和 [CLI 可视化与导出](docs/modeling-history.md)。
|
|
24
|
+
|
|
7
25
|
## 100 秒能交付多少版绳驱灵巧手?
|
|
8
26
|
|
|
9
27
|
**colocad 交付 44 版,build123d 交付 33 版:交付量多 33.3%,采样峰值内存低 57.1%。** 两边按同一组参数逐版建模、装配。每条刻线代表一份含 43 个实体的整手 STEP 已写入持久存储。
|
|
@@ -45,6 +63,17 @@
|
|
|
45
63
|
|
|
46
64
|
## SDK、CLI、skill 怎么选?
|
|
47
65
|
|
|
66
|
+
SDK 是基础,CLI / 工具负责执行,skill 提供建模步骤与常用结构。完整文档从[中文开发指南](docs/README.zh-CN.md)开始,包含模型格式、改参、预览复用、失败处理和产物保存。
|
|
67
|
+
|
|
68
|
+
| 使用环境 | 接入文档 |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| Pi agent core / Pi coding agent | [工具适配器、extension 与 skill](docs/integrations/pi.md) |
|
|
71
|
+
| Claude Code | [项目 skill + 本地 CLI](docs/integrations/claude-code.md) |
|
|
72
|
+
| Codex | [skill 安装、调用与产物检查](docs/integrations/codex.md) |
|
|
73
|
+
| 自建 harness | [同沙箱架构、会话状态与产物生命周期](docs/integrations/overview.md) |
|
|
74
|
+
|
|
75
|
+
[可运行示例与接入回归](examples/integrations/README.md) · [建模最佳实践](docs/best-practices.md) · [常见故障](docs/troubleshooting.md) · [贡献指南](CONTRIBUTING.md)
|
|
76
|
+
|
|
48
77
|
运行 `npm install @coloopx/colocad@0.1.0-alpha.3` 即可安装优化后的装配内核和完整 skill。沙箱内的 harness 可加载 `node_modules/@coloopx/colocad/skills/colocad/SKILL.md`,也可以把整个 `colocad` skill 目录复制到 agent 的技能目录。
|
|
49
78
|
|
|
50
79
|
常见机械件可以让 agent 直接按尺寸搭建。例如「做一块 100 × 50 × 6 mm 的安装板,钻 3 × 2 个 Ø6 通孔,两向孔距 32 和 30 mm」。skill 自带可改参的孔阵列、轴套、角码、开口壳和四种基础实体。参见[基础形状与结构的命令示例](skills/colocad/references/quick-build.md)。
|
package/bin/colocad.mjs
CHANGED
|
@@ -1,20 +1,44 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import { readFile } from "node:fs/promises";
|
|
3
|
-
import { compileTree, build } from "../src/index.mjs";
|
|
3
|
+
import { compileTree, build, kernelModel } from "../src/index.mjs";
|
|
4
|
+
import { ModelingSession, exportSessionHtml } from "../src/session.mjs";
|
|
5
|
+
import { startViewer, parseViewOptions } from "../src/view-server.mjs";
|
|
6
|
+
import { renderSession, parseRenderOptions } from "../src/render.mjs";
|
|
4
7
|
import { writeSolidWorks } from "../src/solidworks.mjs";
|
|
5
8
|
const [cmd, input, output, ...flags] = process.argv.slice(2);
|
|
6
9
|
const help =
|
|
7
|
-
"colocad build TREE.json NEW_DIRECTORY [--preview]\ncolocad plan TREE.json\ncolocad solidworks NATIVE-JOB.json NEW_FILE.SLDPRT";
|
|
10
|
+
"colocad build TREE.json NEW_DIRECTORY [--preview]\ncolocad plan TREE.json\ncolocad record MODEL.json SESSION_DIRECTORY [--label TEXT]\ncolocad replay SESSION_DIRECTORY OUTPUT.html\ncolocad view SESSION_DIRECTORY [--no-open] [--port PORT] [--export OUTPUT.html] [--cutaway] [--view iso|front|side|top]\ncolocad render SESSION_DIRECTORY OUTPUT.mp4|OUTPUT.gif [--width N] [--height N] [--fps N] [--seconds-per-step N]\ncolocad solidworks NATIVE-JOB.json NEW_FILE.SLDPRT";
|
|
8
11
|
try {
|
|
9
12
|
if (cmd === "--help" || cmd === "-h" || !cmd) console.log(help);
|
|
13
|
+
else if (cmd === "render" && input && output) {
|
|
14
|
+
console.log(JSON.stringify(await renderSession(input,output,parseRenderOptions(flags))));
|
|
15
|
+
}
|
|
16
|
+
else if (cmd === "view" && input) {
|
|
17
|
+
const options=parseViewOptions(process.argv.slice(4));
|
|
18
|
+
const viewer=await startViewer(input,options);
|
|
19
|
+
console.log(JSON.stringify({event:'viewer-ready',url:viewer.url,exportedHtml:viewer.exportedHtml}));
|
|
20
|
+
let closing=false;
|
|
21
|
+
const close=async()=>{if(closing)return;closing=true;await viewer.close();process.exitCode=0;};
|
|
22
|
+
process.once('SIGINT',close);process.once('SIGTERM',close);
|
|
23
|
+
}
|
|
24
|
+
else if (cmd === "replay" && input && output && !flags.length) {
|
|
25
|
+
console.log(JSON.stringify(await exportSessionHtml(input, output)));
|
|
26
|
+
}
|
|
10
27
|
else {
|
|
11
|
-
if (!input || !["plan", "build", "solidworks"].includes(cmd))
|
|
28
|
+
if (!input || !["plan", "build", "solidworks", "record"].includes(cmd))
|
|
12
29
|
throw Error(help);
|
|
13
30
|
const raw = await readFile(input);
|
|
14
31
|
if (raw.length > 2 * 1024 * 1024) throw Error("Input exceeds 2 MiB");
|
|
15
32
|
const spec = JSON.parse(raw.toString("utf8"));
|
|
16
33
|
let res;
|
|
17
|
-
if (cmd === "
|
|
34
|
+
if (cmd === "record" && output && (!flags.length || (flags.length===2 && flags[0]==="--label"))) {
|
|
35
|
+
let session;
|
|
36
|
+
try { session=await ModelingSession.create(output,{wallMs:120000}); }
|
|
37
|
+
catch(error) { if(error.code!=="EEXIST") throw error; session=await ModelingSession.open(output,{wallMs:120000}); }
|
|
38
|
+
res=await session.build(spec.format==="colocad/1"?kernelModel(spec):spec,{label:flags[1]??input});
|
|
39
|
+
if(!res.ok) process.exitCode=1;
|
|
40
|
+
}
|
|
41
|
+
else if (cmd === "plan" && !output) res = compileTree(spec);
|
|
18
42
|
else if (
|
|
19
43
|
cmd === "build" &&
|
|
20
44
|
output &&
|
package/docs/README.md
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Developer documentation
|
|
2
|
+
|
|
3
|
+
[Actual modeling workflow](modeling-workflow.zh-CN.md) · [CLI modeling history and viewer (development)](modeling-history.md)
|
|
4
|
+
|
|
5
|
+
Build locally with **SDK → CLI/tools → skill**. The skill guides modeling decisions; the SDK and Rust kernel execute them. Agent, harness and CAD process share the same sandbox and filesystem.
|
|
6
|
+
|
|
7
|
+
These guides target **@coloopx/colocad 0.1.0-alpha.3**, Node.js 22+, Linux x64/arm64 or macOS arm64. The project is still alpha; documentation does not imply complete CAD coverage.
|
|
8
|
+
|
|
9
|
+
[中文开发指南](README.zh-CN.md)
|
|
10
|
+
|
|
11
|
+
| Your task | Start here |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| Create a part and edit a dimension | [Getting started](getting-started.md) |
|
|
14
|
+
| Choose the model format and understand editability | [Models and artifacts](concepts.md) |
|
|
15
|
+
| Call the SDK, CLI or tools | [API reference](api.md) |
|
|
16
|
+
| Integrate with an existing sandbox/harness | [Integration architecture](integrations/overview.md) |
|
|
17
|
+
| Register tools in Pi agent core or Pi coding agent | [Pi integration](integrations/pi.md) |
|
|
18
|
+
| Use Claude Code | [Claude Code integration](integrations/claude-code.md) |
|
|
19
|
+
| Use Codex | [Codex integration](integrations/codex.md) |
|
|
20
|
+
| Model efficiently from dimensions or views | [Best practices](best-practices.md) |
|
|
21
|
+
| Diagnose a failed call or installation | [Troubleshooting](troubleshooting.md) |
|
|
22
|
+
| Run examples and contribute a change | [Contributing](../CONTRIBUTING.md) |
|
|
23
|
+
| Understand what has actually been tested | [Integration verification](integrations/verification.md), [geometry validation](validation.md) |
|
|
24
|
+
|
|
25
|
+
Runnable adapters and their regression tests live in [examples/integrations](../examples/integrations/README.md). They install the published npm release. This example project is in GitHub; it is not included in the alpha.3 npm tarball. The skill, assets and its helper scripts **are** included.
|
|
26
|
+
|
|
27
|
+
Performance depends on workload and execution mode. See the [README measurements](../README.md#how-many-tendon-hands-can-an-agent-deliver-in-100-seconds), with their startup, geometry and memory accounting, before choosing a budget. A 512 MiB CAD benchmark is not a 512 MiB guarantee for a resident LLM harness plus CAD.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# 开发与接入指南
|
|
2
|
+
|
|
3
|
+
[实际操作、输入输出与效果提升方法](modeling-workflow.zh-CN.md) · [CLI 查看器与离线导出(开发分支)](modeling-history.md)
|
|
4
|
+
|
|
5
|
+
colocad 的分层是 **SDK 为基础,CLI / 工具负责调用,skill 指导建模流程**。Agent、harness 和 Rust CAD 进程都在同一个沙箱内,共享项目目录。现有 harness 负责模型推理、权限、会话和产物保存,不需要额外部署 CAD 服务。
|
|
6
|
+
|
|
7
|
+
本文对应 `@coloopx/colocad@0.1.0-alpha.3`,要求 Node.js 22+;预编译内核支持 Linux x64/arm64、macOS arm64。工程仍处于 alpha 阶段。
|
|
8
|
+
|
|
9
|
+
## 先跑通一个零件
|
|
10
|
+
|
|
11
|
+
在已有 Node 项目根目录执行;没有 `package.json` 时先运行 `npm init -y`:
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npm install --save-exact @coloopx/colocad@0.1.0-alpha.3
|
|
15
|
+
./node_modules/.bin/colocad build \
|
|
16
|
+
node_modules/@coloopx/colocad/examples/manifold.json ./manifold-v1 --preview
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
查看 `manifold-v1/part/preview.png`,交付 `model.step`,保留 `feature-tree.json` 和 `report.json`。输出目录必须是新目录。这个示例包含拉伸、盲孔切除、圆角和阵列。
|
|
20
|
+
|
|
21
|
+
常用结构可以从 skill 的参数模型开始:
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
node node_modules/@coloopx/colocad/skills/colocad/scripts/build.mjs \
|
|
25
|
+
node_modules/@coloopx/colocad/skills/colocad/assets/plate-grid.json \
|
|
26
|
+
./plate-v1 --set length=100 --set xCount=3 --set xPitch=32 --preview
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
命令返回实际 `directory`,其中有 `model.json`、STEP 和预览。这里是 kernel model;上面的歧管是 feature tree。两种格式的入口不同,不能混用。[格式与产物说明](concepts.md) · [完整入门](getting-started.md)
|
|
30
|
+
|
|
31
|
+
## 接入哪个 harness
|
|
32
|
+
|
|
33
|
+
| 环境 | 推荐方式 | 安装位置 / 调用 |
|
|
34
|
+
| --- | --- | --- |
|
|
35
|
+
| Codex | 完整 skill + 自带终端和图像工具 | 项目 `.agents/skills/colocad`;`$colocad` |
|
|
36
|
+
| Claude Code | 完整 skill + Bash/Read | 项目 `.claude/skills/colocad`;`/colocad` |
|
|
37
|
+
| Pi coding agent | skill;需要直接工具时加 extension | `.agents/skills/colocad` 或 `--skill`;`/skill:colocad` |
|
|
38
|
+
| Pi agent core / 自建 TS harness | `createCadTools` 适配到现有工具注册机制 | 模型、鉴权、输出目录由现有 harness 提供 |
|
|
39
|
+
|
|
40
|
+
以 Codex 为例,在项目根目录复制完整 skill:
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
mkdir -p .agents/skills
|
|
44
|
+
test ! -e .agents/skills/colocad && \
|
|
45
|
+
cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
已有 skill 时先检查本地修改,再替换整个目录。Claude Code 将目标目录换为 `.claude/skills/colocad`。不要只复制 `SKILL.md`:脚本、资产和参考文档都需要。
|
|
49
|
+
|
|
50
|
+
可直接给 agent 的任务:
|
|
51
|
+
|
|
52
|
+
> 用 colocad 做一块 100 × 50 × 6 mm 的安装板,中心对称布置 3 × 2 个 Ø6 通孔,两向孔距 32、30 mm。保留可改参 JSON,导出 STEP,检查俯视和等轴视图,说明采用的基准与推断尺寸,返回产物路径。
|
|
53
|
+
|
|
54
|
+
各环境的完整命令和验收方法见 [Codex](integrations/codex.md)、[Claude Code](integrations/claude-code.md)、[Pi core / coding agent](integrations/pi.md)。Pi 示例固定到 1.5.0;不要为了接入 CAD 自动升级已有 harness 的 Pi 依赖。旧版本可先采用 skill + CLI,并对自定义工具适配单独回归。
|
|
55
|
+
|
|
56
|
+
## SDK 接入需要处理的事情
|
|
57
|
+
|
|
58
|
+
实例化 `new CadClient({ outputRoot, wallMs: 30000 })`,按顺序执行 `validate → build/preview → 检查 → 接受版本`。`outputRoot` 由 harness 决定。`createCadTools` 提供 schema 和执行函数;Pi 适配示例将失败回执变成错误工具结果,并将 PNG 作为图像传回模型。
|
|
59
|
+
|
|
60
|
+
每个独立建模会话使用自己的 client 和输出根目录;同一会话顺序执行,便于复用特征检查点和网格。`edit` 不会修改传入的模型对象,接受修改后必须保存新 `model.json` 或合并参数,避免下一次改参回退到旧版本。
|
|
61
|
+
|
|
62
|
+
仅转视角使用缓存预览。观察产物目录可能只有预览;STEP 在 `source_artifact_directory` 指向的几何版本中。沙箱销毁前,用现有 harness 的产物机制保存 JSON、STEP、回执和预览。SDK 没有内置云存储或会话数据库。
|
|
63
|
+
|
|
64
|
+
[架构与生命周期](integrations/overview.md) · [SDK / CLI / 工具 API](api.md) · [可运行示例](../examples/integrations/README.md)
|
|
65
|
+
|
|
66
|
+
## 建模最佳实践
|
|
67
|
+
|
|
68
|
+
- 从控制外形的截面或毛坯开始;板、轴套、角码、壳体优先参考[快速搭建指南](../skills/colocad/references/quick-build.md),按实际图纸改参数和特征。
|
|
69
|
+
- 先确定单位、基准、接口尺寸和未知项;稳定特征 ID,保留每次接受的参数源。四视图看不到的内部结构要明确标注推断。
|
|
70
|
+
- 重复零件只定义一次,用装配实例定位;物理上独立的关节不要随意融合成一个实体。
|
|
71
|
+
- `validate` 通过只代表预检查。验收还要看实体数、边界、体积、孔深和内部区域;重要交付独立回读 STEP。
|
|
72
|
+
- 失败要报告具体特征。不要为了生成图片静默跳过切孔或圆角;显式降级也应保留在交付说明中。
|
|
73
|
+
- 性能分别测冷启动到 STEP、连续改参、缓存预览、包含推理的完整 agent 周期。CAD 的 512 MiB 基准不等于整个 agent/harness 也只需 512 MiB。
|
|
74
|
+
|
|
75
|
+
[详细最佳实践](best-practices.md) · [常见故障](troubleshooting.md) · [贡献与回归](../CONTRIBUTING.md)
|
|
76
|
+
|
|
77
|
+
## 当前验证边界
|
|
78
|
+
|
|
79
|
+
接入示例用已发布 npm 包执行实际 Rust 建模,并经过 Pi core 工具循环、错误恢复、扩展加载和 skill 发现测试。模型回复采用确定性脚本,因此这是接入回归,不是未知图纸上的自主建模成功率测试。Claude Code 尚未做实机推理验收。
|
|
80
|
+
|
|
81
|
+
参数 JSON 可重建,STEP 是精确几何;二者不等于 SOLIDWORKS 原生特征树。Linux 通用可编辑 `.SLDPRT` 尚未完成,Windows author 尚缺授权软件内的完整回读重建验收。[接入验证范围](integrations/verification.md) · [几何与原生输出验证](validation.md)
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Modeling history: CLI first
|
|
2
|
+
|
|
3
|
+
Added in alpha.4. In a source checkout, use `node bin/colocad.mjs` in place of `colocad` below. The package entry points are `/session` for the recorder and `/viewer` for the browser component.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
# Build a real milestone and preserve its source, receipt and native preview.
|
|
7
|
+
colocad record model.json ./history --label "Bore the hub"
|
|
8
|
+
|
|
9
|
+
# Repeat record with the next model revision, using the same history directory.
|
|
10
|
+
# Launch the local viewer and open the default browser.
|
|
11
|
+
colocad view ./history
|
|
12
|
+
|
|
13
|
+
# Headless sandbox: print the URL; use the existing harness's port forwarding.
|
|
14
|
+
colocad view ./history --no-open --port 8787
|
|
15
|
+
|
|
16
|
+
# Start a display cutaway and also write a standalone offline file.
|
|
17
|
+
colocad view ./history --cutaway --export ./review.html
|
|
18
|
+
|
|
19
|
+
# Export only: no browser and no listening process.
|
|
20
|
+
colocad replay ./history ./review.html
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
`view` binds only to `127.0.0.1`; port 0 (the default) chooses an available port. It prints one JSON ready event with the actual URL. Ctrl+C shuts it down. No native GUI or separately provisioned CAD service is required. It serves a snapshot of the recorded session; rerun the command after adding milestones. `--export` writes the same HTML that the viewer serves. Only the HTML root is served, not an arbitrary directory of files.
|
|
24
|
+
|
|
25
|
+
A session records each actual build/inspection attempt, including failures and interrupted calls. Native artifacts use paths relative to the session. The recorder owns the last successful source so `edit` starts from an accepted model. Archive the whole session directory to preserve all intermediate STEP files. The standalone HTML embeds models, receipts, meshes and previews, plus the final successful geometry STEP.
|
|
26
|
+
|
|
27
|
+
The viewer supports stage selection, review playback, orbit/zoom, four camera presets, display clipping/explosion, part selection/visibility and input/receipt inspection. These display controls do not change exact CAD. Playback is a presentation cadence; measured call durations are shown separately. With no WebGL, native PNG previews provide a fallback.
|
|
28
|
+
|
|
29
|
+
## Export an animation from the CLI
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
# Optional media dependencies; not needed for CAD builds or the HTML viewer.
|
|
33
|
+
npm install -D playwright
|
|
34
|
+
npx playwright install chromium
|
|
35
|
+
# Install FFmpeg using your host package manager.
|
|
36
|
+
colocad render ./history ./modeling.mp4 --width 1280 --height 800 --fps 15
|
|
37
|
+
colocad render ./history ./modeling.gif --width 960 --height 600 --fps 10 --seconds-per-step 0.75
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The renderer reads the saved native meshes and starts Chromium and FFmpeg locally. It displays four synchronized cameras, measured call durations and the construction journal. The final segment explodes and reassembles the saved geometry for inspection. It writes the movie, a `.json` manifest (hashes, timings, frames, source revisions) and a `.poster.png`. Existing movies are not overwritten. Encoding does not invoke the CAD kernel. Video duration is edited review pacing and is **not** a performance benchmark. Rendering uses more memory than a geometry-only sandbox; run it where Chromium and FFmpeg are available.
|
|
41
|
+
|
|
42
|
+
[Real catalog product: HIWIN KK60](../examples/hiwin-kk60/README.md) includes the generation and independent STEP verification commands.
|
|
43
|
+
|
|
44
|
+
## SDK integration
|
|
45
|
+
|
|
46
|
+
```js
|
|
47
|
+
import { ModelingSession, exportSessionHtml, createSessionTools } from '@coloopx/colocad/session';
|
|
48
|
+
const session = await ModelingSession.create('./history', { title: 'Product reconstruction' });
|
|
49
|
+
const result = await session.build(model, { label: 'Main housing', kind: 'geometry' });
|
|
50
|
+
if (!result.ok) throw new Error(JSON.stringify(result.error));
|
|
51
|
+
await session.edit({ boreDiameter: 8 }, { label: 'Correct bore diameter' });
|
|
52
|
+
await exportSessionHtml(session.root, './review.html');
|
|
53
|
+
const tools = await createSessionTools(session);
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Use existing parameters when editing. `createSessionTools` changes `cad_edit` to `{ parameters }`: it uses the recorded accepted source, rather than accepting another model argument. Other modeling calls use their existing arguments. The Pi examples accept `cadSession` or `COLOCAD_SESSION_DIR` to opt into history. See [recorded-pi.mjs](../examples/integrations/recorded-pi.mjs).
|
|
57
|
+
|
|
58
|
+
For embedding into a host UI, `readSessionBundle(directory)` returns the viewer data. Import `@coloopx/colocad/viewer` in the browser, add `<colocad-viewer>`, and assign that data to its `session` property. This is optional host integration; the CLI remains the end-user entry point.
|
|
59
|
+
|
|
60
|
+
[Actual modeling workflow and proposed improvements](modeling-workflow.zh-CN.md) · [Specification and test mapping](../specs/0001-modeling-history.md)
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# HIWIN KK60: a whole industrial actuator reconstructed from its catalog
|
|
2
|
+
|
|
3
|
+
This example models one complete configuration of a real product: **HIWIN KK60 standard, 5 mm screw lead, 300 mm rail, one normal A block, open, without a motor or switches**. It contains 52 native geometric features, 81 named occurrences and 16 recorded construction/assembly milestones. The product is a catalog-based reconstruction, not an OEM manufacturing model.
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
[MP4](../../showcase/hiwin-kk60/modeling.mp4) · [Editable generated model](../../showcase/hiwin-kk60/model.json) · [Independent verification](../../showcase/hiwin-kk60/verification.json) · [Source dimensions and assumptions](sources.json)
|
|
8
|
+
|
|
9
|
+
## Build, view and export through the CLI
|
|
10
|
+
|
|
11
|
+
From a source checkout with `npm ci` (precompiled native executables must be installed or `npm run build:kernel` run):
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
node examples/hiwin-kk60/run.mjs ./out/hiwin-kk60
|
|
15
|
+
node bin/colocad.mjs view ./out/hiwin-kk60/session
|
|
16
|
+
node bin/colocad.mjs replay ./out/hiwin-kk60/session ./out/hiwin-kk60/review.html
|
|
17
|
+
|
|
18
|
+
# Optional movie tools; CAD and HTML export do not require these.
|
|
19
|
+
npx playwright install chromium
|
|
20
|
+
# Install FFmpeg on the host, then:
|
|
21
|
+
node bin/colocad.mjs render ./out/hiwin-kk60/session ./out/hiwin-kk60/modeling.mp4 \
|
|
22
|
+
--width 1280 --height 800 --fps 15 --seconds-per-step 1.25
|
|
23
|
+
node bin/colocad.mjs render ./out/hiwin-kk60/session ./out/hiwin-kk60/modeling.gif \
|
|
24
|
+
--width 960 --height 600 --fps 10 --seconds-per-step 0.75
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
With the npm alpha.4 package, the generator is included under `node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs`; the CLI is `npx colocad`. The generator requires a new output directory. It writes the actual per-stage sources/receipts/artifacts to `session/`, plus final `model.json` and `hiwin-kk60.step`. `replay` produces one self-contained HTML file, embedding meshes, source, receipts and final STEP. The interactive viewer supports four viewpoints, cutaway, explosion, part selection and the feature journal. Movie export is optional and runs locally; Chromium/FFmpeg have a separate resource cost from geometry builds.
|
|
28
|
+
|
|
29
|
+
The film shows the real intermediate B-reps: rail stock → guide grooves → six counterbores; saddle → nut seat → mounting pattern; stepped shaft → helical cuts; bearing plate and motor support → assembly. It does not interpolate or simulate machining. The final explode/reassemble segment changes displayed placements only. Recorded call times remain visible; the 26-second review is **not** a 26-second build or a build123d comparison.
|
|
30
|
+
|
|
31
|
+
## How the drawing became CAD in this example
|
|
32
|
+
|
|
33
|
+
The assistant downloaded the [manufacturer's catalog](https://hiwin.com/wp-content/uploads/2026/08/HIWIN-Ballscrew-Driven-Stages-Catalog-1.pdf), read the dimension table with `pdftotext`, rendered PDF page 25 with `pdftoppm`, and inspected enlarged drawing sections. The initial screw-axis interpretation was corrected from 15 to **23 mm** after inspecting SECTION A-A. The catalog was not passed to an automatic colocad image-to-CAD endpoint; no such endpoint is claimed.
|
|
34
|
+
|
|
35
|
+
The assistant then wrote [model.mjs](model.mjs): explicit cross-sections, feature dependencies, cutters and placements. That generator emits the same JSON schema accepted by a harness. `ModelingSession.build` executes each revision in the local Rust kernel. Rendering consumes the resulting saved meshes. This is an observed agent/tool workflow, not evidence that a trained image-to-CAD model reconstructed an arbitrary drawing autonomously.
|
|
36
|
+
|
|
37
|
+
The product's catalog interfaces are the acceptance target: rail length/width, carriage height, hole positions/depths, screw axis, total length and travel. [`sources.json`](sources.json) separates specified numbers, datum interpretations and approximated internals. The one exposed run-time parameter is `travel` (−105…105 mm); its screw rotation is linked at 72 degrees/mm. Other dimensions are explicit source constants or feature values; changing those requires rebuilding and rechecking interfaces. This is not a general KK-series configurator.
|
|
38
|
+
|
|
39
|
+
## Geometric details and verification
|
|
40
|
+
|
|
41
|
+
The screw's 56-turn groove is actual B-rep subtraction: four cubic lofted circular cutters per turn, repeated at 5 mm pitch. It is an approximation to a helical groove, not the proprietary gothic-arch race. The rail, carriage and motor support have real bores, counterbores, tracks, pockets and datum slots. Bolts include hex sockets. Repeated rolling elements share geometry definitions.
|
|
42
|
+
|
|
43
|
+
Run the independent verifier with a development Python environment containing `cadquery-ocp`:
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
python examples/hiwin-kk60/verify.py ./out/hiwin-kk60/session ./out/hiwin-kk60/verification.json
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
It reopens every successful STEP in OCCT, checks all solids, counts and volumes, probes the rail counterbores, carriage mounting holes and screw groove/crest, and measures selected rail/carriage overlap at −105/0/+105 mm travel. Tests in `test/kk60.test.mjs` also rebuild both carriage travel endpoints. The recorded result passed all 16 revisions and 64 material probes. Maximum relative volume disagreement was 0.002608%; the three selected rail/carriage overlap volumes were all zero. These checks do not certify every internal fit.
|
|
50
|
+
|
|
51
|
+
Unpublished rolling-element arrangement, bearing sizes, coupling details and nut recirculation are not recovered OEM specifications. The nut is an envelope with a screw bore; recirculation is omitted. Threaded holes are nominal bores; tolerance fits, load rating, fatigue, contact/preload and complete all-pairs interference are not certified. These limits are part of the delivered model, not hidden assumptions.
|
|
52
|
+
|
|
53
|
+
The first full assembly exposed a real library defect: internally generated STEP definitions above 100,000 records were rejected by the assembly writer. Alpha.4 separates the bounded internal export budget (1,000,000 records per definition) from the unchanged external import budget (100,000). A regression test and the full screw assembly cover this fix. The failed original attempt was retained separately during development; it is not counted as a successful build.
|
|
54
|
+
|
|
55
|
+
A complete build with a 640 × 480 preview also passed in a network-disabled Linux arm64 container limited to 1 vCPU and 512 MiB. Native reported total time was 24.192 seconds (one run). Peak memory was not sampled, and no build123d run was performed for this product. [Run evidence](../../showcase/hiwin-kk60/evidence.json).
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
// Catalog interfaces: HIWIN K99TE16-1906 p.22. Internal sections are reconstruction assumptions.
|
|
2
|
+
// X = width, Y = vertical, Z = travel; mm. See sources.json before using for integration.
|
|
3
|
+
export const specification={manufacturer:'HIWIN',series:'KK60 standard',configuration:'5 mm lead / 300 mm rail / A1 / open / no motor',railLength:300,width:60,carriageHeight:33,screwAxisHeight:23,length:370,stroke:210,lead:5,screwDiameter:12};
|
|
4
|
+
export const stages=[
|
|
5
|
+
['rail-stock','Extrude the U-section rail','geometry'],['rail-races','Cut the four guide raceways','geometry'],['rail-holes','Drill and counterbore the six mounting holes','geometry'],
|
|
6
|
+
['carriage-stock','Extrude the carriage saddle','geometry'],['carriage-bore','Machine the nut seat and ball tracks','geometry'],['carriage-holes','Drill the M5 mounting pattern and datum slots','geometry'],
|
|
7
|
+
['screw-blank','Revolve the stepped ballscrew blank','geometry'],['screw-groove','Cut 56 helical turns at 5 mm lead','geometry'],
|
|
8
|
+
['end-plate','Machine the end bearing plate','geometry'],['motor-bracket','Machine the motor support and register','geometry'],['coupling','Bore and split the coupling hubs','geometry'],
|
|
9
|
+
['base-assembly','Install the rail and end supports','assembly'],['screw-assembly','Install the ballscrew and support bearings','assembly'],['carriage-installed','Install the carriage and end caps','assembly'],
|
|
10
|
+
['rolling-assembly','Add the ball nut, guide balls and wipers','assembly'],['complete','Complete the actuator and mounting hardware','assembly'],
|
|
11
|
+
].map(([id,label,kind])=>({id,label,kind}));
|
|
12
|
+
const p=name=>({param:name}),mul=(a,b)=>({op:'mul',a,b}),add=(a,b)=>({op:'add',a,b});
|
|
13
|
+
export function kk60(stage='complete',{travel=0}={}){
|
|
14
|
+
if(!stages.some(s=>s.id===stage))throw Error('Unknown KK60 stage');
|
|
15
|
+
if(!Number.isFinite(travel)||Math.abs(travel)>105)throw Error('travel must be within -105..105 mm');
|
|
16
|
+
const features=[],all=[],f=(id,op,args)=>(features.push({id,op,...args}),id);
|
|
17
|
+
const box=(id,origin,size)=>f(id,'box',{origin,size});
|
|
18
|
+
const cut=(id,left,right)=>f(id,'cut',{left,right});
|
|
19
|
+
const extrude=(id,points,z,height)=>f(id,'extrude',{profile:{kind:'polygon',points},frame:{origin:[0,0,z],x_axis:[1,0,0],y_axis:[0,1,0]},height});
|
|
20
|
+
const ring=(id,ro,ri,z,h,y=0)=>f(id,'extrude',{profile:{kind:'circle',radius:ro},holes:[{kind:'circle',radius:ri}],frame:{origin:[0,y,z],x_axis:[1,0,0],y_axis:[0,1,0]},height:h});
|
|
21
|
+
const holes=(id,input,positions,r,depth,origin=[0,0,0],axes=[[1,0,0],[0,1,0]],counterbore)=>f(id,'holes',{input,positions,radius:r,depth,frame:{origin,x_axis:axes[0],y_axis:axes[1]},...(counterbore?{counterbore}:{})});
|
|
22
|
+
const faceholes=(id,input,face,positions,r,depth,counterbore)=>f(id,'face_holes',{input,face,positions,radius:r,depth,...(counterbore?{counterbore}:{})});
|
|
23
|
+
const inst=(id,input,translation=[0,0,0],rotation_deg=[0,0,0],phase='complete')=>all.push({id,input,translation,rotation_deg,phase});
|
|
24
|
+
const trackPositions=[[-20.5,12],[-20.5,20],[20.5,12],[20.5,20]];
|
|
25
|
+
const railStock=extrude('railStock',[[-30,0],[30,0],[30,21],[29,22],[21,22],[21,5],[-21,5],[-21,22],[-29,22],[-30,21]],7,300);
|
|
26
|
+
const railRaces=holes('railRaceways',railStock,trackPositions,1.65,302,[0,0,6]);
|
|
27
|
+
// Recessed rail floor is Y=5; explicit inward plane avoids drilling from the top of the sidewalls.
|
|
28
|
+
const railHoles=holes('railMounting',railRaces,[-15,15].flatMap(x=>[57,157,257].map(z=>[x,z])),2.75,6,[0,5,0],[[1,0,0],[0,0,1]],{radius:4.75,depth:4.7});
|
|
29
|
+
const rail=holes('railCoverTaps',railHoles,[-26,26].flatMap(x=>[57,257].map(z=>[x,z])),1.3,4,[0,22,0],[[1,0,0],[0,0,1]]);
|
|
30
|
+
const carriageSection=[[-19.7,8],[19.7,8],[19.7,23],[21,25],[21,32],[20,33],[-20,33],[-21,32],[-21,25],[-19.7,23]];
|
|
31
|
+
const carStock=extrude('carriageStock',carriageSection,-25.5,51);
|
|
32
|
+
const carSeat=holes('carriageNutSeat',carStock,[[0,23]],9.2,53,[0,0,-26.5]);
|
|
33
|
+
const carBore=holes('carriageRaceways',carSeat,trackPositions,1.65,53,[0,0,-26.5]);
|
|
34
|
+
const carHoles=faceholes('carriageMounting',carBore,'pos_y',[-15,15].flatMap(x=>[-15,15].map(z=>[x,z])),2.5,8);
|
|
35
|
+
let car=carHoles;
|
|
36
|
+
for(const z of [-23,23])car=f('datumSlot'+(z<0?'A':'B'),'face_cutout',{input:car,face:'pos_y',center:[0,z],profile:{kind:'rectangle',width:15,depth:5},depth:1.5});
|
|
37
|
+
const capStock=extrude('endCapStock',[[-19.5,8],[19.5,8],[21,25],[21,31.5],[-21,31.5],[-21,25]],0,15.5);
|
|
38
|
+
const capBore=holes('endCapBore',capStock,[[0,23]],6.5,15.5,[0,0,0],undefined,{radius:8.6,depth:1.1});
|
|
39
|
+
const cap=faceholes('endCapWiperSeat',capBore,'pos_z',[[0,23]],8.6,1.1);
|
|
40
|
+
const wiper=ring('wiper',8.5,6.2,0,1,23);
|
|
41
|
+
const nut=ring('ballNut',9,6.05,-21,42,23);
|
|
42
|
+
const shaftBlank=f('shaftBlank','revolve',{profile:{kind:'polygon',points:[[0,-7],[6,-7],[6,286],[4,286],[4,306],[3,306],[3,340],[0,340]]},frame:{origin:[0,0,0],x_axis:[1,0,0],y_axis:[0,0,1]},axis_origin:[0,0,0],axis:[0,0,1],angle_deg:360});
|
|
43
|
+
let screw=shaftBlank;
|
|
44
|
+
// Four cubic lofts approximate a circular helical cutter, then exact native booleans.
|
|
45
|
+
// It is NOT an exact analytical helix, gothic-arch ball race or OEM ground profile.
|
|
46
|
+
for(let q=0;q<4;q++){
|
|
47
|
+
const tool=f('helixQuarter'+q,'profile_loft',{degree:3,sections:Array.from({length:4},(_,i)=>{const theta=(q+i/3)*Math.PI/2;return {profile:{kind:'circle',radius:1},frame:{origin:[6.2*Math.cos(theta),6.2*Math.sin(theta),5+(q+i/3)*1.25],x_axis:[Math.cos(theta),Math.sin(theta),0],y_axis:[0,0,1]}};})});
|
|
48
|
+
const pattern=f('helicalTools'+q,'pattern',{input:tool,positions:Array.from({length:56},(_,i)=>[0,0,i*5])});
|
|
49
|
+
screw=cut('screwGroove'+q,screw,pattern);
|
|
50
|
+
}
|
|
51
|
+
const endStock=box('endPlateStock',[-29.8,.5,0],[59.6,44.5,11]);
|
|
52
|
+
const endBore=holes('endBearingSeat',endStock,[[0,23]],8,13,[0,0,-1]);
|
|
53
|
+
const endPlate=holes('endPlateScrews',endBore,[[-23,9],[23,9],[-23,35],[23,35]],1.5,11,[0,0,0],undefined,{radius:3,depth:3});
|
|
54
|
+
const motorStock=box('motorSupportStock',[-29.8,.5,311],[59.6,44.5,59]);
|
|
55
|
+
const motorWindow=f('motorSupportWindow','face_cutout',{input:motorStock,face:'pos_y',center:[0,340.5],profile:{kind:'rectangle',width:36,depth:39,radius:2},depth:41});
|
|
56
|
+
const motorBore=holes('motorBearingSeat',motorWindow,[[0,23]],10,61,[0,0,310]);
|
|
57
|
+
const motorRegister=faceholes('motorRegister',motorBore,'pos_z',[[0,23]],14,4);
|
|
58
|
+
// Nominal threaded holes: two four-hole patterns on PCD40; no cosmetic thread mesh.
|
|
59
|
+
const motorHoles=faceholes('motorM4Pattern',motorRegister,'pos_z',[45,135,225,315].map(a=>[20*Math.cos(a*Math.PI/180),23+20*Math.sin(a*Math.PI/180)]).filter(([x,y])=>y>.5),2,8);
|
|
60
|
+
const motorM3=faceholes('motorM3Pattern',motorHoles,'pos_z',[30,150,210,330].map(a=>[20*Math.cos(a*Math.PI/180),23+20*Math.sin(a*Math.PI/180)]),1.5,8);
|
|
61
|
+
const motor=faceholes('motorSupportBolts',motorM3,'pos_z',[-23,23].flatMap(x=>[9,35].map(y=>[x,y])),1.5,11,{radius:3,depth:3});
|
|
62
|
+
const couplingStock=ring('couplingHubStock',10,3,0,8);
|
|
63
|
+
const coupling=faceholes('couplingSetScrew',couplingStock,'pos_x',[[0,4]],1.5,7);
|
|
64
|
+
const couplingB=ring('couplingDrivenHub',10,3,0,8);
|
|
65
|
+
const spiderStock=extrude('couplingSpiderStock',Array.from({length:24},(_,i)=>{const a=i*Math.PI/12,r=i%4<2?9.8:6;return [r*Math.cos(a),r*Math.sin(a)];}),0,3);
|
|
66
|
+
const spider=holes('couplingSpider',spiderStock,[[0,0]],3.2,5,[0,0,-1]);
|
|
67
|
+
const boltStock=f('boltStock','revolve',{profile:{kind:'polygon',points:[[0,0],[1.4,0],[1.4,8],[2.7,8],[2.7,10.5],[0,10.5]]},frame:{origin:[0,0,0],x_axis:[1,0,0],y_axis:[0,0,1]},axis_origin:[0,0,0],axis:[0,0,1],angle_deg:360});
|
|
68
|
+
const bolt=f('socketBolt','face_cutout',{input:boltStock,face:'pos_z',center:[0,0],profile:{kind:'polygon',points:Array.from({length:6},(_,i)=>[1.3*Math.cos(i*Math.PI/3),1.3*Math.sin(i*Math.PI/3)])},depth:1.8});
|
|
69
|
+
const smallInner=ring('tailInnerRace',6.4,6,0,5),smallOuter=ring('tailOuterRace',8,7.2,0,5);
|
|
70
|
+
const driveInner=ring('driveInnerRace',5.6,4,0,7),driveOuter=ring('driveOuterRace',10,8.4,0,7);
|
|
71
|
+
const guideBall=f('guideBall','sphere',{center:[0,0,0],radius:1.5});
|
|
72
|
+
const bearingBall=f('bearingBall','sphere',{center:[0,0,0],radius:1.3});
|
|
73
|
+
const tailBall=f('tailBall','sphere',{center:[0,0,0],radius:.35});
|
|
74
|
+
inst('rail-machined',rail,undefined,undefined,'base-assembly');inst('end-bearing-plate',endPlate,undefined,undefined,'base-assembly');inst('motor-bearing-support',motor,undefined,undefined,'base-assembly');
|
|
75
|
+
inst('ballscrew-5mm-lead',screw,[0,23,11],[0,0,mul(p('travel'),72)],'screw-assembly');
|
|
76
|
+
inst('bearing-tail-inner',smallInner,[0,23,4],undefined,'screw-assembly');inst('bearing-tail-outer',smallOuter,[0,23,4],undefined,'screw-assembly');
|
|
77
|
+
inst('bearing-drive-inner',driveInner,[0,23,311],undefined,'screw-assembly');inst('bearing-drive-outer',driveOuter,[0,23,311],undefined,'screw-assembly');
|
|
78
|
+
for(let i=0;i<12;i++){const a=i*Math.PI/6;inst('bearing-drive-ball-'+i,bearingBall,[7*Math.cos(a),23+7*Math.sin(a),314.5],undefined,'screw-assembly');inst('bearing-tail-ball-'+i,tailBall,[6.8*Math.cos(a),23+6.8*Math.sin(a),6.5],undefined,'screw-assembly');}
|
|
79
|
+
const carriageZ=add(157,p('travel'));
|
|
80
|
+
inst('carriage-machined',car,[0,0,carriageZ],undefined,'carriage-installed');
|
|
81
|
+
inst('carriage-end-cap-a',cap,[0,0,add(carriageZ,-41)],undefined,'carriage-installed');inst('carriage-end-cap-b',cap,[0,0,add(carriageZ,25.5)],undefined,'carriage-installed');
|
|
82
|
+
inst('ball-nut',nut,[0,0,carriageZ],undefined,'rolling-assembly');inst('seal-wiper-a',wiper,[0,0,add(carriageZ,-41)],undefined,'rolling-assembly');inst('seal-wiper-b',wiper,[0,0,add(carriageZ,40)],undefined,'rolling-assembly');
|
|
83
|
+
for(let row=0;row<4;row++)for(let i=0;i<8;i++)inst('guide-ball-'+row+'-'+i,guideBall,[...trackPositions[row],add(carriageZ,-21+i*6)],undefined,'rolling-assembly');
|
|
84
|
+
inst('coupling-driven-hub',coupling,[0,23,330]);inst('coupling-spider',spider,[0,23,338]);inst('coupling-motor-hub',couplingB,[0,23,341]);
|
|
85
|
+
for(const x of [-23,23])for(const y of [9,35]){inst('bolt-tail-'+x+'-'+y,bolt,[x,y,10.5],[180,0,0]);inst('bolt-drive-'+x+'-'+y,bolt,[x,y,359.5]);}
|
|
86
|
+
const single={'rail-stock':railStock,'rail-races':railRaces,'rail-holes':rail,'carriage-stock':carStock,'carriage-bore':carBore,'carriage-holes':car,'screw-blank':shaftBlank,'screw-groove':screw,'end-plate':endPlate,'motor-bracket':motor,'coupling':coupling}[stage];
|
|
87
|
+
const at=stages.findIndex(s=>s.id===stage);
|
|
88
|
+
let assembly=all.filter(x=>stages.findIndex(s=>s.id===x.phase)<=at).map(({phase,...x})=>x);
|
|
89
|
+
// Separate inspection revision: carriage envelope at travel endpoints, before installing into whole assembly.
|
|
90
|
+
if(stage==='carriage-installed')assembly=assembly.filter(x=>x.id.startsWith('carriage-'));
|
|
91
|
+
const needed=new Set(single?[single]:assembly.map(x=>x.input));
|
|
92
|
+
for(const feat of [...features].reverse())if(needed.has(feat.id))for(const key of ['input','left','right'])if(feat[key])needed.add(feat[key]);
|
|
93
|
+
return {version:1,units:'mm',parameters:{travel},features:features.filter(x=>needed.has(x.id)),...(single?{output:single}:{assembly})};
|
|
94
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { resolve, join } from 'node:path';
|
|
2
|
+
import { writeFile,copyFile } from 'node:fs/promises';
|
|
3
|
+
import { ModelingSession } from '../../src/session.mjs';
|
|
4
|
+
import { kk60, stages } from './model.mjs';
|
|
5
|
+
const directory=resolve(process.argv[2]??'./out/hiwin-kk60');
|
|
6
|
+
const session=await ModelingSession.create(join(directory,'session'),{title:'HIWIN KK60 • catalog-based industrial actuator reconstruction',wallMs:120000});
|
|
7
|
+
for(const stage of stages){
|
|
8
|
+
const result=await session.build({...kk60(stage.id),preview:{chord_mm:.25,view:'iso',width:960,height:640}},stage);
|
|
9
|
+
console.log(JSON.stringify({stage:stage.id,ok:result.ok,solids:result.data?.geometry?.solids,time:result.data?.timing_ms,step:result.session_step,error:result.error}));
|
|
10
|
+
if(!result.ok)throw Error(JSON.stringify(result.error));
|
|
11
|
+
}
|
|
12
|
+
const model=kk60();await writeFile(join(directory,'model.json'),JSON.stringify(model,null,2)+'\n');
|
|
13
|
+
const last=(await session.read()).steps.at(-1);await copyFile(join(session.root,last.artifactDirectory,'model.step'),join(directory,'hiwin-kk60.step'));
|
|
14
|
+
console.log(JSON.stringify({directory,features:model.features.length,instances:model.assembly.length}));
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
{
|
|
2
|
+
"product": "HIWIN KK60 Standard, 5 mm lead, 300 mm rail, one A block, no motor/cover/switch",
|
|
3
|
+
"source": {
|
|
4
|
+
"publisher": "HIWIN Corporation",
|
|
5
|
+
"productUrl": "https://hiwin.com/products/kk-series-ballscrew-stages/kk-series/",
|
|
6
|
+
"catalogUrl": "https://hiwin.com/wp-content/uploads/2026/08/HIWIN-Ballscrew-Driven-Stages-Catalog-1.pdf",
|
|
7
|
+
"documentCode": "K99TE16-1906",
|
|
8
|
+
"downloaded": "2026-11-07",
|
|
9
|
+
"pages": {
|
|
10
|
+
"modelCode": 15,
|
|
11
|
+
"screwDiameterLead": 16,
|
|
12
|
+
"dimensionDrawing": 22
|
|
13
|
+
},
|
|
14
|
+
"pdfPages": {
|
|
15
|
+
"modelCode": 18,
|
|
16
|
+
"screwDiameterLead": 19,
|
|
17
|
+
"dimensionDrawing": 25
|
|
18
|
+
},
|
|
19
|
+
"sha256": "be54c5158ef723dfe2d97be26403b3970f5bc6c9290352e3d6b321d4560481c0"
|
|
20
|
+
},
|
|
21
|
+
"catalogDimensionsMm": {
|
|
22
|
+
"railLength": 300,
|
|
23
|
+
"overallLength": 370,
|
|
24
|
+
"railWidth": 60,
|
|
25
|
+
"carriageHeight": 33,
|
|
26
|
+
"screwAxisHeight": 23,
|
|
27
|
+
"railTopHeight": 22,
|
|
28
|
+
"carriageLength": 82,
|
|
29
|
+
"carriageMetalLength": 51,
|
|
30
|
+
"carriageWidth": 42,
|
|
31
|
+
"stroke": 210,
|
|
32
|
+
"screwDiameter": 12,
|
|
33
|
+
"lead": 5,
|
|
34
|
+
"driveShaftDiameter": 6,
|
|
35
|
+
"railMountHoles": {
|
|
36
|
+
"count": 6,
|
|
37
|
+
"diameter": 5.5,
|
|
38
|
+
"counterboreDiameter": 9.5,
|
|
39
|
+
"counterboreDepth": 4.7,
|
|
40
|
+
"xPitch": 30,
|
|
41
|
+
"zPitch": 100,
|
|
42
|
+
"G": 50
|
|
43
|
+
},
|
|
44
|
+
"carriageMountHoles": {
|
|
45
|
+
"count": 4,
|
|
46
|
+
"thread": "M5 x 0.8",
|
|
47
|
+
"depth": 8,
|
|
48
|
+
"pitch": [
|
|
49
|
+
30,
|
|
50
|
+
30
|
|
51
|
+
]
|
|
52
|
+
},
|
|
53
|
+
"motorSupport": {
|
|
54
|
+
"width": 59.6,
|
|
55
|
+
"height": 44.5,
|
|
56
|
+
"bottomOffset": 0.5,
|
|
57
|
+
"length": 59,
|
|
58
|
+
"registerDiameter": 28,
|
|
59
|
+
"boltCircleDiameter": 40
|
|
60
|
+
},
|
|
61
|
+
"datumSlots": {
|
|
62
|
+
"width": 15,
|
|
63
|
+
"depth": 1.5
|
|
64
|
+
}
|
|
65
|
+
},
|
|
66
|
+
"datumInterpretations": [
|
|
67
|
+
"X is width, Y is vertical, Z is the travel axis; overall Z=0..370.",
|
|
68
|
+
"Rail Z=7..307; three mounting stations Z=57,157,257, measured from the right rail end using G=50.",
|
|
69
|
+
"Mid-stroke carriage center Z=157; travel +/-105 gives full block envelope Z=11..303.",
|
|
70
|
+
"Screw axis Y=23 was checked on the enlarged SECTION A-A, not inferred from the 15 mm side-hole dimension."
|
|
71
|
+
],
|
|
72
|
+
"assumptions": [
|
|
73
|
+
"U-rail internal wall/floor profile, chamfers, groove radii and guide ball spacing are reconstructed. They are not manufacturing dimensions.",
|
|
74
|
+
"Screw groove uses four cubic circular-section lofts per turn, repeated 56 times. This is a geometric helix approximation, not the manufacturer's gothic-arch ground raceway.",
|
|
75
|
+
"Ball-nut internals and recirculation passages are not disclosed in the catalog. The nut is an annular envelope; no recirculation or load rating is claimed.",
|
|
76
|
+
"Support bearing race dimensions and rolling balls are illustrative and are not a sourced bearing SKU.",
|
|
77
|
+
"Motor bracket window, support screws, coupling/spider and wiper seats use documented example geometry where the catalog does not dimension them.",
|
|
78
|
+
"Threaded holes use nominal diameter cylinders; screws have plain shanks and real hex sockets. Thread geometry and tolerance fits are not modeled.",
|
|
79
|
+
"Motion uses the nominal screw relation 360 degrees per 5 mm; no dynamic/contact or preload simulation is performed.",
|
|
80
|
+
"Colors distinguish components; they do not establish manufacturer materials. No production mass or structural rating is claimed."
|
|
81
|
+
],
|
|
82
|
+
"notIncluded": [
|
|
83
|
+
"optional motor",
|
|
84
|
+
"optional cover/bellows",
|
|
85
|
+
"optional limit switches",
|
|
86
|
+
"proprietary recirculation geometry"
|
|
87
|
+
]
|
|
88
|
+
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
[diffend] Oversized file quarantined before diffing.
|
|
2
2
|
name: package/kernel/native/darwin-arm64/agent-cad
|
|
3
3
|
size: 35996736 bytes
|
|
4
|
-
sha256:
|
|
4
|
+
sha256: e3cbc7abf95cc0911e5e9a1dae565c52e7bafe927f5bf7a42901aa9a48f2bca9
|
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
[diffend] Oversized file quarantined before diffing.
|
|
2
2
|
name: package/kernel/native/linux-arm64/agent-cad
|
|
3
3
|
size: 35525448 bytes
|
|
4
|
-
sha256:
|
|
4
|
+
sha256: 9e2e965f2e136d2fe31009738be8c42e98b39ccccf838c6f22b07d7ead39e714
|