@coloopx/colocad 0.1.0-alpha.5 → 0.1.0-alpha.7
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/CHANGELOG.md +44 -0
- package/README.md +115 -172
- package/README.zh-CN.md +118 -125
- package/bin/colocad.mjs +17 -9
- package/docs/README.md +10 -3
- package/docs/README.zh-CN.md +11 -2
- package/docs/agent-modeling-handbook.md +1 -1
- package/docs/agent-modeling-handbook.zh-CN.md +2 -2
- package/docs/api.md +9 -6
- package/docs/engineering-queries.md +122 -0
- package/docs/engineering-queries.zh-CN.md +74 -0
- package/docs/getting-started.md +1 -1
- package/docs/integrations/claude-code.md +1 -1
- package/docs/integrations/codex.md +1 -1
- package/docs/integrations/pi.md +17 -4
- package/docs/integrations/verification.md +7 -1
- package/docs/native-solidworks.md +12 -0
- package/docs/performance.md +62 -0
- package/examples/integrations/README.md +11 -2
- package/examples/integrations/compact-tools.mjs +1 -1
- package/kernel/dist/client.d.ts +5 -2
- package/kernel/dist/client.js +35 -7
- package/kernel/dist/generated.d.ts +297 -4
- package/kernel/dist/process.d.ts +1 -1
- package/kernel/dist/process.js +3 -3
- package/kernel/dist/query-generated.d.ts +181 -0
- package/kernel/dist/query-generated.js +1 -0
- package/kernel/dist/tools.d.ts +35 -0
- package/kernel/dist/tools.js +11 -2
- package/kernel/dist/types.d.ts +9 -0
- package/kernel/native/darwin-arm64/agent-cad +2 -2
- package/kernel/native/darwin-arm64/manifest.json +2 -2
- package/kernel/native/linux-arm64/agent-cad +2 -2
- package/kernel/native/linux-arm64/manifest.json +2 -2
- package/kernel/native/linux-x64/agent-cad +2 -2
- package/kernel/native/linux-x64/manifest.json +2 -2
- package/kernel/release.json +4 -4
- package/kernel/schemas/model.schema.json +1752 -135
- package/kernel/schemas/query.schema.json +1150 -0
- package/package.json +5 -2
- package/skills/colocad/references/tool-contracts.md +14 -2
- package/src/build.mjs +3 -2
- package/src/index.d.mts +2 -1
- package/src/session.d.mts +5 -3
- package/src/session.mjs +26 -10
- package/viewer/dist/index.js +179 -179
- package/viewer/dist/standalone.js +179 -179
- package/viewer/index.d.ts +2 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Notable user-facing changes are recorded here. Colocad remains alpha software; supported geometry and measured workloads define each release's scope.
|
|
4
|
+
|
|
5
|
+
## [0.1.0-alpha.7](https://github.com/Coloopx/colocad/releases/tag/v0.1.0-alpha.7) — 2026-11-09
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- Exact, revision-bound B-rep queries through `CadClient.query`, `ModelingSession.query`, `cad_query` and `colocad query`. Reopened or relocated snapshots preserve identity; edits invalidate old observations.
|
|
10
|
+
- Bounded composable topology selection, trim-aware face evaluation, primitive named datums and datum-driven assembly mates with explicit direction and physical residuals.
|
|
11
|
+
- Analytic through/blind/counterbored hole recognition, plane-scoped hole groups, declared/recognized `planar_hole_mount/v1` interfaces, all-hole compatibility checks and geometry-driven external STEP replacement.
|
|
12
|
+
- Explicit part-pair separation, contact, overlap and containment measurements, plus required checks at bounded pose samples. Read-only queries perform no geometry rebuild, STEP export or tessellation.
|
|
13
|
+
- Geometry-reference highlights in recorded CLI/offline review, revision-aware compact agent feedback, capability-gated Pi query tools and updated English/Chinese modeling guidance.
|
|
14
|
+
|
|
15
|
+
### Fixed
|
|
16
|
+
|
|
17
|
+
- Required disjoint or tangent cuts now fail with `NO_MATERIAL_REMOVED` instead of silently returning unchanged stock.
|
|
18
|
+
- Selection tolerance is validated separately from minimum feature size, permitting the specified `1e-5 mm` query precision.
|
|
19
|
+
- Checkpoint reuse requires a source/compiler/target execution fingerprint, preventing an unchanged development version from restoring geometry made under old feature semantics.
|
|
20
|
+
- The process-interruption regression now resolves the packaged native when no development override is set.
|
|
21
|
+
|
|
22
|
+
### Verification
|
|
23
|
+
|
|
24
|
+
- G1–G3 accepted in their declared domains: 127 Rust tests, 41 Node tests, six deterministic integration tests, offline browser checks, and all 24 frozen geometry cases (18 positives, six correct rejections).
|
|
25
|
+
- Independent OCCT readback validates significant exact deliveries, including the 82-solid KK60/accessory reconstruction and geometry-driven foreign replacements.
|
|
26
|
+
- Two actual Pi inference tasks run with agent, harness, SDK and native in the same Linux arm64 1 vCPU / 512 MiB cgroup. The product task edits an existing sourced assembly; it does not reconstruct that product from images. Its measured peak is 370.57 MiB with no OOM.
|
|
27
|
+
- Fresh archive installations verify the SDK, CLI, packaged native, query/edit/reopen behavior and foreign mounting replacements on macOS arm64, Linux arm64 and Linux x64. Linux checks run offline at 1 vCPU / 512 MiB; x64 uses emulation.
|
|
28
|
+
|
|
29
|
+
See [G1 evidence](specs/experiments/0004/README.md), [G2/G3 evidence and failures](specs/experiments/0005/README.md), [release archive evidence](docs/evidence/release-alpha.7.json) and the [query guide](docs/engineering-queries.md).
|
|
30
|
+
|
|
31
|
+
### Compatibility and limits
|
|
32
|
+
|
|
33
|
+
- This is Colocad's JSON/TypeScript API, not a CadQuery Python or API compatibility layer. Existing modeling entry points remain available.
|
|
34
|
+
- Conical, intersecting, side-open and spline-based bore recognition can be partial. Certified allowed contact is bounded to supported opposing planar polyhedral faces; curved-contact certification and region-restricted measurement remain unsupported.
|
|
35
|
+
- Semantic intent is re-evaluated after edits. Missing or ambiguous references fail explicitly; arbitrary topology changes do not guarantee one-to-one identity.
|
|
36
|
+
- Resource figures apply to the recorded workloads. G4 has not started, and this release establishes no new speed/memory ratio against build123d. Native editable SOLIDWORKS acceptance is unchanged.
|
|
37
|
+
|
|
38
|
+
## [0.1.0-alpha.6](https://github.com/Coloopx/colocad/releases/tag/v0.1.0-alpha.6) — 2026-11-07
|
|
39
|
+
|
|
40
|
+
- Documented the SDK → CLI/tools → skill workflow, agent integration examples, CLI visualization and source-backed HIWIN KK60 showcase.
|
|
41
|
+
- Improved release verification and publishing integrity checks. Native geometry binaries were unchanged from alpha.4.
|
|
42
|
+
- Exact engineering queries and mounting-interface APIs were not included in this version.
|
|
43
|
+
|
|
44
|
+
Earlier release notes remain in [GitHub Releases](https://github.com/Coloopx/colocad/releases).
|
package/README.md
CHANGED
|
@@ -2,257 +2,200 @@
|
|
|
2
2
|
|
|
3
3
|

|
|
4
4
|
|
|
5
|
-
**
|
|
5
|
+
**Parametric CAD for agents. Local Rust geometry, a TypeScript SDK, a CLI, and an inspectable modeling history.**
|
|
6
6
|
|
|
7
|
-
[
|
|
7
|
+
[中文](README.zh-CN.md) · [Documentation](docs/README.md) · [npm](https://www.npmjs.com/package/@coloopx/colocad) · [Changelog](CHANGELOG.md) · [Releases](https://github.com/Coloopx/colocad/releases) · [Model behind the cover](examples/hiwin-kk60/README.md)
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Colocad turns explicit modeling instructions into editable source, exact STEP geometry and visual review artifacts. It runs alongside the agent and its harness **inside the same sandbox**. The npm package includes the compiled Rust kernel; installed modeling needs no Python, Rust toolchain, network or separate CAD service.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
**Alpha software:** useful for supported mechanical parts and assemblies, with measured performance and reproducible examples. It is not a complete replacement for build123d or a manufacturing-certified CAD system. See [support and limits](#support-and-limits).
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
## What you can build
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
- **Parts and assemblies:** parametric features, repeated part definitions, exact STEP and PNG/GLB/STL previews.
|
|
16
|
+
- **Engineering queries (alpha.7):** exact topology, composable selection, datums, holes/groups, mounting interfaces and measured assembly relationships. [Supported domains](docs/engineering-queries.md).
|
|
17
|
+
- **Agent workflows:** SDK tools and a bundled skill for interpreting dimensions, planning features, editing and checking results.
|
|
18
|
+
- **Human review:** persistent build attempts, source/receipt inspection, offline single-file HTML and four-view MP4/GIF replay.
|
|
19
|
+
|
|
20
|
+
The SDK is the foundation; the CLI and tool adapters expose it to your harness; the skill guides modeling decisions. Images and drawings are evidence the agent interprets. Colocad executes explicit geometry instructions.
|
|
16
21
|
|
|
17
22
|
```mermaid
|
|
18
23
|
flowchart LR
|
|
19
|
-
A[Agent +
|
|
20
|
-
H --> C[
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
K --> F[STEP + model + receipts + meshes]
|
|
25
|
-
F --> V[CLI viewer / HTML / MP4 / GIF]
|
|
24
|
+
A[Agent + skill] --> H[Existing harness]
|
|
25
|
+
H --> C[CLI / SDK tools]
|
|
26
|
+
C --> K[Local Rust kernel]
|
|
27
|
+
K --> F[STEP + source + receipts + meshes]
|
|
28
|
+
F --> V[CLI viewer / HTML / animation]
|
|
26
29
|
```
|
|
27
30
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
```sh
|
|
31
|
-
npm install @coloopx/colocad@0.1.0-alpha.5
|
|
31
|
+
## Install
|
|
32
32
|
|
|
33
|
-
|
|
34
|
-
npx colocad record node_modules/@coloopx/colocad/examples/manifold.json ./history \
|
|
35
|
-
--label "Build the manifold"
|
|
33
|
+
Requires **Node.js 22+** on **Linux x64, Linux arm64 or macOS arm64**.
|
|
36
34
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
# Export one self-contained HTML file, including the final STEP download.
|
|
41
|
-
npx colocad replay ./history ./review.html
|
|
35
|
+
```sh
|
|
36
|
+
npm install @coloopx/colocad@0.1.0-alpha.7
|
|
42
37
|
```
|
|
43
38
|
|
|
44
|
-
|
|
39
|
+
The package ships JS/TS APIs, the CLI, native executables, viewer and complete skill. Rust source is in [crates/agent-cad](crates/agent-cad); the npm tarball contains compiled binaries. [Package and model formats](docs/concepts.md).
|
|
45
40
|
|
|
46
|
-
|
|
47
|
-
| --- | --- | --- |
|
|
48
|
-
| `colocad plan TREE.json` | `colocad/1` feature tree | Compile a native modeling job without building geometry |
|
|
49
|
-
| `colocad build TREE.json NEW_DIR --preview` | `colocad/1` feature tree | STEP, editable tree, report and previews |
|
|
50
|
-
| `colocad record MODEL.json SESSION --label TEXT` | Feature tree **or** kernel model JSON | Build and append a persistent modeling milestone |
|
|
51
|
-
| `colocad view SESSION` | Recorded session | Local interactive viewer; optional `--export review.html` |
|
|
52
|
-
| `colocad replay SESSION review.html` | Recorded session | Single offline HTML, no listening process |
|
|
53
|
-
| `colocad render SESSION modeling.mp4` | Recorded session | Four-view animation, timing/hash manifest and poster; `.gif` also supported |
|
|
41
|
+
## Quick start
|
|
54
42
|
|
|
55
|
-
|
|
43
|
+
Run these commands from your Node project:
|
|
56
44
|
|
|
57
|
-
|
|
45
|
+
```sh
|
|
46
|
+
# Build the packaged manifold and save its source, receipt and geometry.
|
|
47
|
+
npx colocad record node_modules/@coloopx/colocad/examples/manifold.json ./history \
|
|
48
|
+
--label "Build the manifold"
|
|
58
49
|
|
|
59
|
-
|
|
50
|
+
# Launch the interactive viewer.
|
|
51
|
+
npx colocad view ./history
|
|
60
52
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
npm install -D playwright
|
|
64
|
-
npx playwright install chromium
|
|
65
|
-
# Install FFmpeg on your host, then export from the same persisted session:
|
|
66
|
-
npx colocad render ./history ./modeling.mp4 --width 1280 --height 800 --fps 15
|
|
67
|
-
npx colocad render ./history ./modeling.gif --width 960 --height 600 --fps 10
|
|
53
|
+
# Export one offline HTML file, including a final STEP download.
|
|
54
|
+
npx colocad replay ./history ./review.html
|
|
68
55
|
```
|
|
69
56
|
|
|
70
|
-
|
|
57
|
+
The manifold includes an extrusion, blind cut, fillet, linear pattern and pocket. Record an edited JSON into the same history directory to append a revision; failed attempts remain visible. `view` serves a snapshot, so reopen it after adding revisions. [First part and parameter edit](docs/getting-started.md).
|
|
71
58
|
|
|
72
|
-
|
|
59
|
+
Prefer an API? Use the same kernel through a persistent session:
|
|
73
60
|
|
|
74
61
|
```js
|
|
75
62
|
import { ModelingSession } from '@coloopx/colocad/session';
|
|
76
63
|
|
|
77
|
-
const session = await ModelingSession.create('./history'
|
|
78
|
-
const
|
|
64
|
+
const session = await ModelingSession.create('./sdk-history');
|
|
65
|
+
const result = await session.build({
|
|
79
66
|
version: 1, units: 'mm', parameters: { length: 60 },
|
|
80
67
|
features: [{ id: 'stock', op: 'box', origin: [0, 0, 0],
|
|
81
68
|
size: [{ param: 'length' }, 30, 8] }],
|
|
82
69
|
output: 'stock',
|
|
83
|
-
};
|
|
84
|
-
const result = await session.build(model, { label: 'Extrude the stock' });
|
|
70
|
+
});
|
|
85
71
|
if (!result.ok) throw new Error(JSON.stringify(result.error));
|
|
86
|
-
await session.edit({ length: 80 }
|
|
72
|
+
await session.edit({ length: 80 });
|
|
87
73
|
```
|
|
88
74
|
|
|
89
|
-
Use `CadClient` for direct builds
|
|
90
|
-
|
|
91
|
-
### Skill: give the agent the complete modeling guide
|
|
75
|
+
Use `CadClient` for direct builds without session recording. [SDK, CLI and tool API](docs/api.md).
|
|
92
76
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
```sh
|
|
96
|
-
# Codex project skill
|
|
97
|
-
mkdir -p .agents/skills
|
|
98
|
-
cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
|
|
99
|
-
|
|
100
|
-
# For Claude Code, use .claude/skills/colocad instead.
|
|
101
|
-
```
|
|
77
|
+
## Visualize and export from the CLI
|
|
102
78
|
|
|
103
|
-
|
|
79
|
+

|
|
104
80
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
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.
|
|
81
|
+
Inspect the timeline, source, features, receipts and selected parts. Switch cameras, show display sections or explosion, and download artifacts. The offline HTML embeds its rendering code and geometry. Hosts can also embed `@coloopx/colocad/viewer`.
|
|
108
82
|
|
|
83
|
+
| Command | Input | Result |
|
|
84
|
+
| --- | --- | --- |
|
|
85
|
+
| `colocad plan TREE.json` | `colocad/1` feature tree | Compile and inspect a native job |
|
|
86
|
+
| `colocad build TREE.json NEW_DIR --preview` | Feature tree | STEP, editable source and previews |
|
|
87
|
+
| `colocad record MODEL.json SESSION` | Feature tree or kernel JSON | Build and persist a milestone |
|
|
88
|
+
| `colocad view SESSION` | Saved session | Interactive local viewer |
|
|
89
|
+
| `colocad replay SESSION review.html` | Saved session | Self-contained offline HTML |
|
|
90
|
+
| `colocad render SESSION modeling.mp4` | Saved session | Four-view animation; `.gif` also supported |
|
|
109
91
|
|
|
110
|
-
|
|
92
|
+
In a headless sandbox, use `colocad view ./history --no-open --port 8787` with the harness's port forwarding; the listener binds to `127.0.0.1`.
|
|
111
93
|
|
|
112
94
|
```sh
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
npx
|
|
116
|
-
|
|
117
|
-
npx colocad render ./actuator/session ./modeling.mp4
|
|
95
|
+
# Optional movie dependencies; install FFmpeg on the host as well.
|
|
96
|
+
npm install -D playwright
|
|
97
|
+
npx playwright install chromium
|
|
98
|
+
npx colocad render ./history ./modeling.mp4 --width 1280 --height 800 --fps 15
|
|
118
99
|
```
|
|
119
100
|
|
|
120
|
-
|
|
101
|
+
Movies replay **actual saved revisions**. Recorded call times and edited playback duration are separate. Building geometry and exporting HTML do not need Chromium or FFmpeg. [History, viewer and rendering guide](docs/modeling-history.md).
|
|
121
102
|
|
|
122
|
-
##
|
|
103
|
+
## Use with your agent
|
|
123
104
|
|
|
124
|
-
|
|
105
|
+
Copy the whole skill, including its references, scripts and editable shape assets:
|
|
125
106
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|---|---:|---:|
|
|
132
|
-
| Complete hands delivered in 100 s | **44** | 33 |
|
|
133
|
-
| First STEP | **2.223 s** | 3.010 s |
|
|
134
|
-
| Median job time on the same first 33 inputs | **2.234 s** | 2.855 s |
|
|
135
|
-
| Highest sampled cgroup memory over the 100 s window | **130.9 MiB** | 304.9 MiB |
|
|
136
|
-
|
|
137
|
-
One measured window per backend, with a new CAD process for each revision. The original run used the alpha.2 SDK and the optimized Linux arm64 kernel now bundled in alpha.3. Memory samples taken about every 25 ms include subprocesses, tmpfs and charged file cache. Every counted STEP reopened successfully. [Measurement method](showcase/tendon-hand/window/README.md) · [Detailed build and single-call replay](showcase/tendon-hand/assembly-performance.md)
|
|
138
|
-
|
|
139
|
-
The static scorecard below uses the **published alpha.2 binary**. With fresh tool processes the sensor rail and manifold reached STEP 22.0× and 12.9× faster than build123d, using 7.7% and 8.0% of its peak memory.
|
|
140
|
-
|
|
141
|
-
<details>
|
|
142
|
-
<summary>See the static comparison across four workloads</summary>
|
|
143
|
-
|
|
144
|
-

|
|
145
|
-
|
|
146
|
-
</details>
|
|
147
|
-
|
|
148
|
-
| Deliverable | Time to STEP: colocad / build123d | Speedup¹ | Peak memory: colocad / build123d | Share of build123d peak |
|
|
149
|
-
| :--- | ---: | ---: | ---: | ---: |
|
|
150
|
-
| Sensor rail | 113 / 2,485 ms | **22.0×** | 20.0 / 259.3 MiB | **7.7%** |
|
|
151
|
-
| Port manifold | 230 / 2,963 ms | **12.9×** | 20.7 / 258.7 MiB | **8.0%** |
|
|
152
|
-
| Tendon-hand proximal link | 259 / 2,244 ms | **8.6×** | 21.4 / 260.1 MiB | **8.2%** |
|
|
153
|
-
| Complete 43-solid hand | 3,952 / 3,293 ms | **0.83×** | 52.7 / 271.3 MiB | **19.4%** |
|
|
154
|
-
|
|
155
|
-
¹ build123d time divided by colocad time from unrounded observations. Same Linux arm64 image, 1 vCPU, 512 MiB. Five fresh processes and cgroups per part and backend after warm-up. Time is the median wall clock including startup, imports, modeling, backend checks and STEP export. Memory is the maximum measured cgroup peak; charged pages, temporary outputs and tool descendants count. Installation, container startup, previews, inference and a resident agent are excluded.
|
|
156
|
-
|
|
157
|
-
[Rail/manifold samples](docs/benchmarks/runs.json) · [Finger/hand samples](showcase/tendon-hand/evidence/scope.json) · [Four-view hand study and CAD downloads](showcase/tendon-hand/README.md) · [Offline scorecard](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/time-to-step.html)
|
|
158
|
-
|
|
159
|
-
**Historical alpha.2 result.** in a separate 100-second sweep of complete hand revisions, colocad delivered 24 STEPs to build123d’s 30. Every counted file reopened as a valid 43-solid assembly. [Timestamped outputs and paired geometry checks](showcase/tendon-hand/evidence/window.json)
|
|
107
|
+
```sh
|
|
108
|
+
# Codex project skill; use .claude/skills for Claude Code.
|
|
109
|
+
mkdir -p .agents/skills
|
|
110
|
+
cp -R node_modules/@coloopx/colocad/skills/colocad .agents/skills/colocad
|
|
111
|
+
```
|
|
160
112
|
|
|
161
|
-
|
|
113
|
+
If that skill already exists, preserve local customizations before updating it. Then ask:
|
|
162
114
|
|
|
163
|
-
|
|
115
|
+
> Use the colocad skill to build a 100 × 50 × 6 mm plate with a centered 3 × 2 grid of Ø6 through-holes on 32 × 30 mm pitches. Keep editable source and modeling history, verify the dimensions, and export STEP and an offline HTML review through the CLI.
|
|
164
116
|
|
|
165
|
-
|
|
|
117
|
+
| Harness | Integration |
|
|
166
118
|
| --- | --- |
|
|
167
|
-
|
|
|
168
|
-
| Claude Code | [Project skill and local
|
|
169
|
-
|
|
|
170
|
-
|
|
|
171
|
-
|
|
172
|
-
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).
|
|
173
|
-
|
|
174
|
-
Install with `npm install @coloopx/colocad@0.1.0-alpha.5`. 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.
|
|
119
|
+
| Codex | [Project skill and CLI](docs/integrations/codex.md) |
|
|
120
|
+
| Claude Code | [Project skill and local tools](docs/integrations/claude-code.md) |
|
|
121
|
+
| Pi core / coding agent | [Typed tool adapter and extension](docs/integrations/pi.md) |
|
|
122
|
+
| Your own harness | [SDK schemas, state and artifact lifecycle](docs/integrations/overview.md) |
|
|
175
123
|
|
|
176
|
-
|
|
124
|
+
The [end-to-end handbook](docs/agent-modeling-handbook.md) covers source preparation, dimension uncertainty, tool abstraction, prompts, modeling loops, validation and tuning. A [runnable guided workflow](examples/integrations/README.md) demonstrates real builds, quantitative edits and recovery; its decisions are scripted, not a live-LLM benchmark.
|
|
177
125
|
|
|
178
|
-
|
|
179
|
-
- **In a shell or agent tool call:** install `npm install @coloopx/colocad@0.1.0-alpha.5`. Run `./node_modules/.bin/colocad plan tree.json`, then `./node_modules/.bin/colocad build tree.json ./new-part --preview`. Open `new-part/part/model.step`.
|
|
180
|
-
- **From drawings with an agent:** install the [colocad skill](skills/colocad/SKILL.md). Start the next turn with “Use `$colocad` to reconstruct these four views, export STEP, and flag any internal details you inferred.” [Installation and assembly replay](showcase/tendon-hand/README.md#try-it-with-your-agent).
|
|
126
|
+
## Example: a complete linear actuator
|
|
181
127
|
|
|
182
|
-
|
|
128
|
+
The cover reconstructs a **HIWIN KK60, 300 mm rail, 5 mm lead, 210 mm travel** from manufacturer drawings: **52 final features, 81 named solid occurrences and 16 modeling milestones**. It includes a physically cut helical screw groove, rail tracks, mounting holes, carriage, bearings and coupling.
|
|
183
129
|
|
|
184
|
-
|
|
130
|
+
```sh
|
|
131
|
+
node node_modules/@coloopx/colocad/examples/hiwin-kk60/run.mjs ./actuator
|
|
132
|
+
npx colocad view ./actuator/session
|
|
133
|
+
npx colocad render ./actuator/session ./modeling.mp4
|
|
134
|
+
```
|
|
185
135
|
|
|
186
|
-
|
|
136
|
+
Independent OCCT checks cover all 16 STEP revisions, 64 material probes and selected rail/carriage clearances. Proprietary internals are explicitly approximated or omitted; this is a catalog reconstruction, not a production drawing package. The animation is not a speed benchmark.
|
|
187
137
|
|
|
188
|
-
|
|
138
|
+
[MP4](showcase/hiwin-kk60/modeling.mp4) · [Editable model](showcase/hiwin-kk60/model.json) · [Checks](showcase/hiwin-kk60/verification.json) · [Dimensions and assumptions](examples/hiwin-kk60/sources.json) · [Full offline delivery](https://github.com/Coloopx/colocad/releases/download/v0.1.0-alpha.4/hiwin-kk60-delivery.zip)
|
|
189
139
|
|
|
190
|
-
|
|
140
|
+
## Performance
|
|
191
141
|
|
|
192
|
-
|
|
142
|
+
Performance depends on geometry and execution mode. In a measured 100-second queue of the same **43-solid tendon hand**, Colocad delivered **44 complete STEP revisions versus build123d's 33**, with **57.1% lower highest sampled sandbox memory**.
|
|
193
143
|
|
|
194
|
-
|
|
195
|
-
| :--- | ---: | ---: | ---: |
|
|
196
|
-
| Sensor rail | 108.8 ms | 19.4 ms | **5.6×** |
|
|
197
|
-
| Port manifold | 223.8 ms | 13.3 ms | **16.8×** |
|
|
144
|
+

|
|
198
145
|
|
|
199
|
-
|
|
146
|
+
| Same revision queue, 1 vCPU / 512 MiB | Colocad | build123d |
|
|
147
|
+
| --- | ---: | ---: |
|
|
148
|
+
| Complete STEP deliveries in 100 s | **44** | 33 |
|
|
149
|
+
| First STEP | **2.223 s** | 3.010 s |
|
|
150
|
+
| Median job, same first 33 inputs | **2.234 s** | 2.855 s |
|
|
151
|
+
| Highest sampled cgroup memory | **130.9 MiB** | 304.9 MiB |
|
|
200
152
|
|
|
201
|
-
|
|
153
|
+
One window per backend; a fresh CAD process per revision; approximately 25 ms memory sampling includes subprocesses, temporary files and charged file cache. Every counted STEP reopened successfully. This run used the alpha.2 SDK and the optimized kernel first bundled in alpha.3; it is not a new alpha.6 measurement. The GIF plots the highest sample so far, not instantaneous usage. [Method and samples](showcase/tendon-hand/window/README.md).
|
|
202
154
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
| Agent skill, CLI, JavaScript API, TypeScript declarations and precompiled Rust executables for **Linux x64, Linux arm64 and macOS arm64**. Node.js 22+. | [Rust CAD source](crates/agent-cad/src), [TypeScript kernel SDK](kernel/src), [feature compiler](src/tree.mjs), tests and [pinned SolidCore dependency](third_party/solidcore.lock.json). |
|
|
155
|
+
<details>
|
|
156
|
+
<summary>Cold-start parts and cached previews</summary>
|
|
206
157
|
|
|
207
|
-
|
|
158
|
+

|
|
208
159
|
|
|
209
|
-
**
|
|
160
|
+
The published alpha.2 kernel reached STEP **22.0× faster** for a sensor rail and **12.9× faster** for a manifold, using **7.7% and 8.0%** of build123d's peak memory. Five fresh processes/cgroups per part and backend after warm-up; Linux arm64, 1 vCPU / 512 MiB. Startup/imports, modeling, checks and export count; installation, previews, inference and a resident agent do not. These gains do not apply to every operation: manifold geometry alone took 53.7 ms versus build123d's 43.8 ms, and the old complete-hand result was slower.
|
|
210
161
|
|
|
211
|
-
|
|
162
|
+
For unchanged geometry, saved-mesh observation was 5.6×–16.8× faster than Colocad's own rebuild-and-render path on two parts. This is an internal cache comparison, not a build123d result.
|
|
212
163
|
|
|
213
|
-
|
|
214
|
-
npm install @coloopx/colocad@alpha
|
|
215
|
-
npx colocad build node_modules/@coloopx/colocad/examples/manifold.json ./manifold --preview
|
|
216
|
-
npx colocad build node_modules/@coloopx/colocad/examples/sensor-rail.json ./rail
|
|
217
|
-
```
|
|
164
|
+
</details>
|
|
218
165
|
|
|
219
|
-
|
|
166
|
+
[Full performance evidence and limitations](docs/performance.md) · [Offline comparison with STEP downloads](https://github.com/Coloopx/colocad/raw/refs/heads/main/docs/benchmarks/comparison.html).
|
|
220
167
|
|
|
221
|
-
|
|
168
|
+
## Support and limits
|
|
222
169
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
await build(tree, './original');
|
|
229
|
-
tree.parameters.instances = 3;
|
|
230
|
-
const edited = await build(tree, './edited');
|
|
231
|
-
console.log(edited.geometry.volume_mm3);
|
|
232
|
-
```
|
|
170
|
+
- Native packages: Linux x64/arm64 and macOS arm64, Node.js 22+. [Release verification](docs/evidence/release-alpha.7.json).
|
|
171
|
+
- Editable JSON/programs and exact STEP are supported; STEP does not preserve a commercial CAD application's native feature tree.
|
|
172
|
+
- General editable SOLIDWORKS output on Linux remains incomplete. The experimental Windows author requires licensed SOLIDWORKS, and a native rebuild pass is still unverified. [Native author status](docs/native-solidworks.md).
|
|
173
|
+
- CAD checks, drawing interpretation, edit preservation, fit and manufacturing readiness are separate claims. [Validation scope](docs/validation.md).
|
|
174
|
+
- A 512 MiB CAD test is not a memory guarantee for an entire resident agent, browser or video encoder.
|
|
233
175
|
|
|
234
|
-
|
|
176
|
+
## Documentation and help
|
|
235
177
|
|
|
236
|
-
|
|
178
|
+
Available in alpha.7: [exact queries and geometry-backed assembly](docs/engineering-queries.md), with a [runnable external STEP example](examples/engineering-queries/README.md). The [four ordered goals](specs/0005-capability-reliability-and-optimization.md) track functional coverage, geometry reliability, engineering usability, then benchmark-driven optimization. The SDK, CLI, tool schema and all three native targets ship together; this is a Colocad API, not CadQuery Python/API compatibility.
|
|
237
179
|
|
|
238
|
-
|
|
180
|
+
G1–G3 are accepted for the [declared workloads](specs/experiments/0005/README.md): 24/24 geometry cases independently verified, 127 Rust / 41 Node tests, and two live Pi tasks in Linux arm64 **1 vCPU / 512 MiB**. Peak cgroup memory was **256 MiB** for the corpus with a minimal supervisor and **371 MiB** for resident Pi/harness plus the 82-solid actuator edit and preview; zero OOM. This is resource/correctness acceptance, not a new build123d speed comparison or full industry-wide parity. G4 has not started.
|
|
239
181
|
|
|
240
|
-
The Windows entry point consumes the same job. It starts a blank part using the application's configured default, builds sketches with native lines and circles, calls extrusion/cut/fillet/pattern APIs and names the resulting features. The fillet uses body edges and the native pattern selects the original seed feature. There are no part-specific model files. Running it requires local Windows, .NET 8 and a licensed SOLIDWORKS installation with a valid default blank part configuration.
|
|
241
182
|
|
|
242
|
-
|
|
243
|
-
colocad solidworks .\manifold\part\native-job.json .\manifold.SLDPRT
|
|
244
|
-
```
|
|
183
|
+
[Getting started](docs/getting-started.md) · [API](docs/api.md) · [Agent handbook](docs/agent-modeling-handbook.md) · [Skill](skills/colocad/SKILL.md) · [Troubleshooting](docs/troubleshooting.md) · [All documentation](docs/README.md)
|
|
245
184
|
|
|
246
|
-
|
|
185
|
+
For a bug or feature request, [open an issue](https://github.com/Coloopx/colocad/issues) with the package version, platform, minimal model and relevant receipt. Remove credentials and private source material.
|
|
247
186
|
|
|
248
|
-
##
|
|
187
|
+
## Develop and contribute
|
|
249
188
|
|
|
250
189
|
```sh
|
|
190
|
+
git clone https://github.com/Coloopx/colocad.git
|
|
191
|
+
cd colocad
|
|
192
|
+
npm ci
|
|
251
193
|
npm run build:kernel
|
|
252
194
|
npm test
|
|
253
|
-
node bin/colocad.mjs build examples/manifold.json ./out/manifold --preview
|
|
254
195
|
```
|
|
255
196
|
|
|
256
|
-
|
|
197
|
+
Building from source requires the Rust toolchain and fetches the pinned SolidCore dependency. Viewer/render and Pi integration checks have additional dependencies; see [CONTRIBUTING.md](CONTRIBUTING.md) for setup, tests and release instructions. Contributions are welcome as issues and pull requests.
|
|
198
|
+
|
|
199
|
+
## License and acknowledgments
|
|
257
200
|
|
|
258
|
-
|
|
201
|
+
Colocad application code is [MIT licensed](LICENSE). The kernel builds on [SolidCore](https://github.com/tangency-labs/solidcore), including work derived from NVIDIA USD BRep / SMLib; the viewer uses Three.js. Dependency licenses and attribution are in [NOTICE.md](NOTICE.md) and [kernel/licenses](kernel/licenses). The industrial example is not affiliated with or endorsed by HIWIN.
|