SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
README: shorter front page; details move to docs (#3275)
bherbruck4d99d7920502
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex d3b01c62ca..55bfb4c994 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -72,7 +72,7 @@ desktop integration and how to distinguish an old executable on `PATH`.## How the code is laid out-The [README](README.md#architecture) has the layer table. The short version:+The [architecture page](docs/architecture.md) has the layer table. The short version:- `crates/geom`: vectors, planes, meshes, measures.- `crates/sketch`: our own constraint solver, plus profile finding.diff --git a/README.md b/README.mdindex 5229cdd14c..8021324303 100644--- a/README.md+++ b/README.md@@ -46,281 +46,65 @@## Download-- **Windows:** download and run the [installer][windows-msi].- Also for [ARM64][windows-arm64-msi] and [32-bit][windows-x86-msi] PCs, or as a- [portable zip][windows-portable] that runs without installing.- With [WinGet](https://learn.microsoft.com/windows/package-manager/winget/):- `winget install bherbruck.SolidCraft`.-- **macOS:** open the [disk image][macos-dmg] and drag SolidCraft into Applications- (Apple silicon and Intel).-- **Linux:** download the [AppImage][linux-appimage], allow it to run as a program and open it.- Or install the [.deb][linux-deb] (Ubuntu, Debian, Mint) or [.rpm][linux-rpm] (Fedora,- openSUSE), or use [Flatpak](https://docs.solidcraft.io/guide/getting-started.html#linux-flatpak).- With Snap: `sudo snap install solidcraft` ([Snap Store][snap-store], or the [.snap file][linux-snap]).- For ARM64: [AppImage][linux-arm64-appimage], [.deb][linux-arm64-deb], [.rpm][linux-arm64-rpm].+- **Windows:** the [installer][windows-msi], or `winget install bherbruck.SolidCraft`.+- **macOS:** the [disk image][macos-dmg] (Apple silicon and Intel).+- **Linux:** the [AppImage][linux-appimage], or `sudo snap install solidcraft` ([Snap Store][snap-store]).- **Web:** [try it in your browser][web-app], no install.-The downloads aren't signed yet. On Windows, if SmartScreen warns you, choose **More info**, then-**Run anyway**. On macOS, the first time, right-click SolidCraft in Applications and choose **Open**.--**On SolidCraft 0.11 to 0.14?** Its **Update now** can't install 0.15.0 or later, because the-releases moved to a new address. Download the new version once from the links above; after that,-updating from inside SolidCraft works again ([details](https://docs.solidcraft.io/guide/updates.html#updating-from-011-to-014)).--Older versions, checksums and other formats are on the [releases page](https://github.com/tangency-labs/solidcraft/releases).-Install details, upgrading from earlier builds and building from source are in-[Getting started](https://docs.solidcraft.io/guide/getting-started.html).--[badge-windows]: https://img.shields.io/badge/Windows-Download-0078D6?style=for-the-badge&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0yIDJoOS41djkuNUgyek0xMi41IDJIMjJ2OS41aC05LjV6TTIgMTIuNWg5LjVWMjJIMnpNMTIuNSAxMi41SDIyVjIyaC05LjV6Ii8%2BPC9zdmc%2B-[badge-macos]: https://img.shields.io/badge/macOS-Download-333333?style=for-the-badge&logo=apple&logoColor=white-[badge-linux]: https://img.shields.io/badge/Linux-AppImage-E95420?style=for-the-badge&logo=linux&logoColor=white-[badge-snap]: https://img.shields.io/badge/Snap-Snap_Store-82BEA0?style=for-the-badge&logo=snapcraft&logoColor=white-[badge-web]: https://img.shields.io/badge/Web-Try_in_browser-2EA44F?style=for-the-badge&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIyIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIvPjxwYXRoIGQ9Ik0yIDEyaDIwTTEyIDJhMTUgMTUgMCAwIDEgMCAyME0xMiAyYTE1IDE1IDAgMCAwIDAgMjAiLz48L3N2Zz4%3D-[windows-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x64.msi-[windows-arm64-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-arm64.msi-[windows-x86-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x86.msi-[windows-portable]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x64-portable.zip-[macos-dmg]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-macos-universal.dmg-[linux-appimage]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.AppImage-[linux-deb]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.deb-[linux-rpm]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.rpm-[linux-arm64-appimage]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-aarch64.AppImage-[linux-arm64-deb]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-aarch64.deb-[linux-arm64-rpm]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-aarch64.rpm-[linux-snap]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.snap-[snap-store]: https://snapcraft.io/solidcraft-[web-app]: https://solidcraft.io/app--**Documentation:** the [SolidCraft book](https://docs.solidcraft.io/) (user guide,-developer guide and command reference; sources in [docs/book](docs/book)).--**Community:** chat with users and contributors on [Discord](https://discord.gg/FtU4NQNVDH).--**Status: early but usable for simple parts.** 75 of 76 public reference parts-match their analytic or FreeCAD-computed volume, area, centre of mass and bounding box-([docs/oracle.md](docs/oracle.md)); the other is a tracked bug.-These checks do not establish complete geometric or workflow equivalence. The commands SolidCraft has-are listed by area in [docs/features.md](docs/features.md); status and plans are in [ROADMAP.md](ROADMAP.md).-Open work and known bugs are in [GitHub issues](https://github.com/tangency-labs/solidcraft/issues),-and help is welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).--## Built with SolidCraft--<a href="https://github.com/0xlillith/solidcraft-rover"><img src="docs/screenshots/rover-build.gif" alt="SELENE, a scientific rover by 0xlillith, assembling itself as the timeline plays through its 3,323 steps in SolidCraft: tub, wheels, electronics, suspension, sampling arm, solar wings, dish and camera turret" loading="lazy"></a>--*SELENE, a scientific rover built entirely through SolidCraft's MCP server by-[@0xlillith](https://github.com/0xlillith/solidcraft-rover): 3,323 editable timeline steps that-rebuild with no errors, replayed here at 2× speed.-[Full video](https://github.com/tangency-labs/solidcraft/raw/refs/heads/main/docs/screenshots/rover-build.mp4)-· [download the editable model](https://github.com/0xlillith/solidcraft-rover/releases/tag/v1.0.0).*+ARM64 and 32-bit builds, portable zip, .deb, .rpm, Flatpak and the other packages are on the+[downloads page](docs/downloads.md). The downloads aren't signed yet: on Windows choose+**More info**, then **Run anyway** in SmartScreen; on macOS right-click SolidCraft and choose **Open**+the first time. On SolidCraft 0.11 to 0.14, download once by hand; see+[updating](https://docs.solidcraft.io/guide/updates.html#updating-from-011-to-014).## What works-- **Current-view DXF export** from File → Export Current View as DXF, with hidden edges- omitted or dashed, shown body placements and the current camera. See [view DXF](docs/view-dxf.md).+Early but usable for simple parts: 75 of 76 public reference parts match their analytic or+FreeCAD-computed volume, area, centre of mass and bounding box ([oracle](docs/oracle.md)); the+other is a tracked bug.++- **Sketches and constraints:** lines, arcs, splines, text and more, solved by our own constraint solver, with parameter-driven dimensions.+- **Features:** extrude, revolve, sweep, loft, fillet, chamfer, shell, draft, holes, threads, patterns, mirror, split and combine on an editable parametric timeline.+- **Parameters and configurations** with unit-aware expressions.+- **Assemblies** with joints, motion studies, contact sets, interference and mass properties.+- **Sheet metal** with flanges, hems, fold/unfold and flat patterns, and plastic enclosure features.+- **Files:** STEP, IGES, 3MF, STL, OBJ and glTF in and out where supported, URDF export, `.solidcraft` designs.+- **Desktop app, browser app, headless CLI and MCP server**, all running the same commands.-- **Sketches** on origin planes, offset planes or planar faces: lines, rectangles, circles,- arcs, polygons, slots, ellipses, fit/control splines, conics and text; construction geometry,- projection, trimming, fillets and chamfers, including corners at the origin.- New face attachments retain supported construction identities and chosen occurrences;- missing sources expose an explicit plane repair workflow. See [face attachments](docs/face-attachments.md).- Explicitly closed fit splines and closed associative offsets use periodic C2 interpolation.- Supported convex line-and-arc offsets retain their identity when an inset consumes corner- arcs, and linked extrusions follow the current boundary. Breaking the association freezes- the boundary and keeps existing extrusions usable.- Curve drawing and picking adapt together to zoom and display scale, including small circles- at Fit and sketches in placed components.-- **Constraints and dimensions** solved by our own solver. Points the constraints fix relative- to known geometry are placed exactly by construction (loci intersections and rigid-cluster- decomposition, after Owen 1991 and Fudos–Hoffmann 1997); Levenberg–Marquardt solves the rest,- and the rank of its Jacobian gives the remaining degrees of freedom. Constraints: coincident,- point on curve, horizontal/vertical, parallel, perpendicular, tangent, curvature (G2), equal,- concentric, collinear, midpoint, symmetry, fix; linear, aligned, horizontal, vertical,- point-to-line, radius, diameter, angle, arc sweep, arc length and slot length dimensions driven- by parameters. Over-constraining edits are rejected; fully constrained geometry turns black.- Dragging solves the sketch every frame and rebuilds the model once, when the drag ends.- Select a line or its two endpoints, type its dimension and press Enter to commit one undo- step; with Sketch Dimension it's D, click, type, Enter. Fit keeps sketch geometry clear of the palette and navigation controls.-- **Profiles** found automatically, including regions split by lines and holes inside outlines.- Newly captured complete adaptive boundaries retain their outer and hole source identities- when spline span counts change. Partial or ambiguous boundaries do not qualify.-- **Features** on a parametric timeline: extrude, revolve, sweep, loft, fillet/chamfer,- shell, draft, holes, threads, patterns, mirror, split, combine, move and construction geometry.- The timeline rebuilds incrementally; features can be edited, suppressed, renamed, reordered- and deleted. Supported geometry and current limitations are described in [ROADMAP.md](ROADMAP.md).- New revolves preserve symmetric and two-sided angular placement across reversed axes;- older designs retain their saved convention when reopened or edited.-- **Parameters and configurations** with unit-aware expressions (`2 * width + 5 mm`,- `angle / 2`), ordered rules, feature suppression and per-row body materials/appearances.-- **Assemblies** with nested components and occurrences, joints, motion studies, contact sets,- interference and material-aware mass properties. Recorded body transfers preserve modelling- history and world placement; 3D sketch wires retain their coordinate frames through edits.-- **Sheet metal** with flanges, hems, fold/unfold/refold, material cutouts, flat patterns,- retained shallow prismatic pockets, exact line/arc/circle DXF outlines and bend tables;- plastic enclosure features and rules. Pocket depth and side survive unfold/refold and appear- separately from through-hole outlines in the flat preview and DXF.-- **Files**: design containers (`.solidcraft`) with lossless binary mesh payloads;- plain JSON remains supported for opening, Save As and export. Desktop Open can show a saved- provisional picture from warm geometry caches while rebuilding before editing; caches never- replace the parametric design. Export to STEP (AP242 with body names, colours and- components as assemblies; revolved faces as native planes, cylinders, cones, spheres and tori),- IGES 5.3 (manifold solid B-reps with names and colours), 3MF, STL (binary/ASCII) and OBJ, and- assemblies with joints as URDF for robot simulators (docs/urdf.md);- 3MF, STL, OBJ and glTF 2.0 (`.glb`/`.gltf`, its node tree as components and its materials as- appearances) import as mesh bodies (they render, measure, move and export; solid features- need B-rep bodies). The `mesh.convert` command reconstructs supported closed constant-section parts- as parametric solids with planar and circular cylindrical faces;- STEP import (AP203/AP214/AP242 solids, assemblies, units, names, colours) and IGES import- (manifold solid B-reps, or trimmed and bounded surfaces sewn into solids) as a base feature- that later features build on — open a `.step`/`.stp`/`.igs`/`.iges` file, insert one into a- design, or drop it on the window ([docs/step-import.md](docs/step-import.md)); FreeCAD- `.FCStd` and Rhino `.3dm` solids import the same way through- [cadmpeg](https://github.com/cadmpeg/cadmpeg) in the desktop app and CLI.-- **Render:** opaque surfaces can use metal fraction, roughness and dielectric IOR in the- integrated product viewport and CPU preview PNGs. Existing simple colors remain supported.- Fixed direct lighting is a preview; HDRI, refraction and texture maps are not implemented.- See [opaque surfaces](docs/render-opaque-pbr.md).-- **Display meshes** from our own tessellation planner: each face becomes a plan of (u, v)- points and triangles that shares its edge nodes with its neighbours, so the mesh is watertight.- Facets follow the chord tolerance, the facet angle and a longest side, with cells at most 2:1- along straight directions. Box-bounded and four-cornered faces mesh as structured grids.- Trimmed faces are cut into four-sided patches: squares around holes, butterflies in round- faces, motorcycle traces from concave corners (after Lyon et al. 2019). Each patch then meshes- as a Coons grid. Intersection edges are evaluated by Newton on both surfaces. A compute shader- evaluates the plans for the whole scene in one dispatch, with a CPU fallback when the GPU- can't build it. Planning and evaluating the 78 reference bodies takes about 65 ms, 50–65×- faster than the previous mesher.-- **Desktop app** (egui + wgpu): toolbar with workspace tabs, browser, timeline, 3D viewport with- axis view and navigation bar, sketch tools, feature dialogs, command palette, and a JSON-lines- control channel so agents and tests can drive it.- Feature errors and Help can open an editable **Create Issue** draft with relevant context- and an optional reviewed screenshot; opening GitHub does not submit the report.-- **Headless CLI** `solidcraft-cli`: run command scripts, measure (volume, area, centre of mass,- face/edge/vertex counts), export, render PNG snapshots and replay reference recipes.- A snapshot can draw a body see-through and another solid in a colour of its own, and cut- the model at a plane, so a picture shows the body a cut would remove inside the material- it meets.-- **MCP server** `solidcraft-cli mcp`: AI agents model, measure and look at parts headless or- in the running app (see below).+The full list is in [docs/capabilities.md](docs/capabilities.md) and [docs/features.md](docs/features.md);+status and plans are in [ROADMAP.md](ROADMAP.md). See also [what people built](docs/showcase.md),+[3D mouse support](docs/3d-mouse.md) and the [architecture](docs/architecture.md).-## Build and run+## Build from source```sh-cargo run --release -p solidcraft -- --sample # desktop app with a sample part-cargo run --release -p solidcraft-cli -- commands # the command registry+cargo run --release -p solidcraft -- --sample # desktop app with a sample part+cargo run --release -p solidcraft-cli -- commands # the command registrycargo run --release -p solidcraft-cli -- run examples/bracket.json --out bracket.step-cargo run --release -p solidcraft-cli -- snapshot examples/bracket.json --out bracket.png-cargo run --release -p solidcraft-cli -- snapshot part.solidcraft --out preview.png --tool Pin --section z=12-cargo run --release -p solidcraft-cli -- render examples/render-studio.json --out product.png-cargo run --release -p solidcraft -- part.step # open a STEP file as a new design-cargo run --release -p solidcraft-cli -- eval part.step # measure an imported STEP file-cargo xtask ci # fmt, clippy, tests, icons, assets, layers, wasm+cargo xtask ci # fmt, clippy, tests, icons, assets, layers, wasm```-UI artwork changes follow the [icon specification](assets/icons/ui/STYLE_GUIDE.md).-The [included review tool](assets/icons/ui/README.md) discovers new icons and keeps-unaccepted artwork Open; run `cargo xtask icons` to check the collection.--Windows builds: `cargo xwin build --release --target x86_64-pc-windows-msvc -p solidcraft`.--On Windows, macOS and Linux, SolidCraft detects a connected 3D mouse through its HID multi-axis-controller interface: a 3Dconnexion SpaceNavigator or SpaceMouse, or a homemade device that-declares itself one. Move the cap to pan and zoom, and tilt or twist it to rotate the 3D view.-While editing a sketch, the cap pans and zooms without changing the sketch view. The Navigation-page in Preferences has an on/off switch, a speed control and, for each of the cap's six axes, an-invert switch and a speed for the 3D mouse. The web app reads-it too, through the browser; Firefox needs a 3DxWare setting first (see-[Getting started › 3D mouse in the browser](docs/book/src/guide/getting-started.md#3d-mouse-in-the-browser)).--With 3DxWare on Windows, SolidCraft follows 3DxWare's profile for it when there is one, and-3DxWare's object mode (tilt to roll, twist to spin) until there is. The mouse-wheel turns that-3DxWare makes from the cap's motion are ignored, so the view doesn't zoom in steps as the cap tilts.--On Linux SolidCraft reads the 3D mouse through `spacenavd` when that daemon runs (its socket-`/var/run/spnav.sock`), so what you set in `spnavcfg` (swapped or inverted axes, sensitivity, dead-zones) applies as it does in other programs, and no udev rule is needed. With nothing set there,-the motion is the same as without the daemon. Without `spacenavd`, SolidCraft reads `/dev/hidrawN`-directly, so the logged-in user needs access to the device. A udev rule that adds the `uaccess`-tag does that, for example-`/etc/udev/rules.d/70-3d-mouse.rules` for USB devices with 3Dconnexion's vendor id, and for its-Bluetooth ones (where `idVendor` isn't set, so the HID id is matched instead):--```-SUBSYSTEM=="hidraw", ATTRS{idVendor}=="256f", TAG+="uaccess"-SUBSYSTEM=="hidraw", KERNELS=="0005:256F:*", TAG+="uaccess"-```--Older SpaceNavigators use Logitech's vendor id `046d`, so add a rule with their product id (see-`lsusb`) instead of matching every Logitech device. A homemade device needs a rule with its own-vendor and product id. Reload with `sudo udevadm control --reload && sudo udevadm trigger`, then-replug the device. The Flatpak sandbox does not expose hidraw devices, so the 3D mouse only works-with native builds there for now.--SolidCraft finds the axes from the device's report descriptor, so it doesn't matter how a device-lays them out: translation and rotation in separate reports (3Dconnexion's wired devices), all six-in one (its wireless ones and most homemade devices), after the buttons, or narrower than 16 bits.-Each axis is scaled from the range the descriptor declares.--On macOS SolidCraft talks to the 3Dconnexion driver (3DxWare) when it is installed, through the-driver's client API (`crates/threedx-client`; the framework is loaded at run time, never bundled).-The driver keeps the device to itself, and sends it only to a program it can identify: SolidCraft-as an `.app` (the packaged app). Without the driver, or with its helper not running, SolidCraft reads the device through IOKit like on Windows.--SolidCraft does not follow 3DxWare's profile on macOS. Its default is 3DxWare's object mode.--In the browser: `cd apps/solidcraft-web && trunk build --release --public-url ./` (WebGPU, or-WebGL2 with `?webgl`; `?sample` opens the sample part).--Agents can control the document open in a browser tab through `window.solidcraft.execute(...)`-and `window.solidcraft.request(...)`; see the [browser command API](docs/browser-api.md).--## Scripts--A script is a JSON list of commands, the same ones the UI runs:--```json-{"commands": [- {"command": "sketch.create", "params": {"plane": "XY"}},- {"command": "sketch.rectangle.two_point", "params": {"p0": [0, 0], "p1": [40, 30]}},- {"command": "solid.extrude", "params": {"distance": 20}},- {"command": "solid.fillet", "params": {"edges": [[0, 0, 10]], "radius": 3}}-]}-```+More commands, the Windows cross-build and the browser build are in [docs/building.md](docs/building.md).## AI agents (MCP)-`solidcraft-cli mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server on-stdio. Headless it runs its own design session; with `--connect 127.0.0.1:PORT` it drives the app-started with `solidcraft --control PORT`, so you can watch the agent model. Tools:-`list_commands`, `execute`, `batch`, `inspect_design`, `measure`, `body_topology`,-`set_parameter`, `screenshot` (returns the image), `export`, `crash_reports`, `undo`, `redo`,-`new_design`, `open`, `save`. Tool calls reach files only in the open design's folder (when it lies inside your home-folder, never home itself or a hidden folder), SolidCraft's recovery folder and folders given with-`--allow-path DIR`. Claude Code: `claude mcp add solidcraft -- solidcraft-cli mcp`. Details, client-configuration and an example session: [docs/mcp.md](docs/mcp.md).+`solidcraft-cli mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server. Headless it+runs its own design session, or with `--connect` it drives the running app so you can watch.+Claude Code: `claude mcp add solidcraft -- solidcraft-cli mcp`. Tools, access rules and an+example session: [docs/mcp.md](docs/mcp.md).-## Architecture+## Scripts-<!-- ANCHOR: architecture -->-| Layer | Crates | Role |-|---|---|---|-| L0 | `geom` | vectors, planes, profiles, meshes and their measures |-| L1 | `sketch`, `kernel`, `render` | constraint solver and profiles; the B-rep kernel boundary (truck); view math and the headless scene description |-| L2 | `doc` | parameters, expressions, the feature timeline and its incremental evaluation |-| L3 | `io` | design files, STL/OBJ/STEP/3MF export, STEP and 3MF/STL/OBJ/glTF import features |-| L4 | `engine` | the session and the command registry (everything is a command) |-| L5 | `gpu`, `ui-egui`, `mcp` | compute-shader evaluation of display tessellation plans; the swappable desktop front end; the MCP server (headless or bridged to the app) |-| apps | `solidcraft`, `solidcraft-cli` | desktop app, headless CLI |-<!-- ANCHOR_END: architecture -->+A script is a JSON list of the same commands the UI runs, executed with `solidcraft-cli run`.+Format and example: [docs/scripts.md](docs/scripts.md). Pages can also be driven through the+[browser command API](docs/browser-api.md).## Contributing-SolidCraft uses a familiar parametric CAD workflow: constrained-sketches, solid features, an editable timeline, parameters and assemblies. See the-[roadmap](ROADMAP.md) for supported operations and current limitations.--See [CONTRIBUTING.md](CONTRIBUTING.md): how to build and test, the code map, the clean-room-and licence rules, and where help is wanted most.+Help is welcome. [CONTRIBUTING.md](CONTRIBUTING.md) covers how to build and test, the code map,+the clean-room and licence rules, and where help is wanted most. Open work is in+[GitHub issues](https://github.com/tangency-labs/solidcraft/issues); chat is on+[Discord](https://discord.gg/FtU4NQNVDH).## Sponsors@@ -337,3 +121,14 @@ SolidCraft is independent. Behaviour is designed from public documentation, geneconventions and user feedback. Reference tests use analytic values and open-source tools.SolidCraft is not affiliated with, sponsored by or endorsed by Autodesk. Autodesk andFusion are trademarks of Autodesk, Inc.++[badge-windows]: https://img.shields.io/badge/Windows-Download-0078D6?style=for-the-badge&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0yIDJoOS41djkuNUgyek0xMi41IDJIMjJ2OS41aC05LjV6TTIgMTIuNWg5LjVWMjJIMnpNMTIuNSAxMi41SDIyVjIyaC05LjV6Ii8%2BPC9zdmc%2B+[badge-macos]: https://img.shields.io/badge/macOS-Download-333333?style=for-the-badge&logo=apple&logoColor=white+[badge-linux]: https://img.shields.io/badge/Linux-AppImage-E95420?style=for-the-badge&logo=linux&logoColor=white+[badge-snap]: https://img.shields.io/badge/Snap-Snap_Store-82BEA0?style=for-the-badge&logo=snapcraft&logoColor=white+[badge-web]: https://img.shields.io/badge/Web-Try_in_browser-2EA44F?style=for-the-badge&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIyIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIvPjxwYXRoIGQ9Ik0yIDEyaDIwTTEyIDJhMTUgMTUgMCAwIDEgMCAyME0xMiAyYTE1IDE1IDAgMCAwIDAgMjAiLz48L3N2Zz4%3D+[windows-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x64.msi+[macos-dmg]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-macos-universal.dmg+[linux-appimage]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.AppImage+[snap-store]: https://snapcraft.io/solidcraft+[web-app]: https://solidcraft.io/appdiff --git a/docs/3d-mouse.md b/docs/3d-mouse.mdnew file mode 100644index 0000000000..383da9294d--- /dev/null+++ b/docs/3d-mouse.md@@ -0,0 +1,46 @@+# 3D mouse++On Windows, macOS and Linux, SolidCraft detects a connected 3D mouse through its HID multi-axis+controller interface: a 3Dconnexion SpaceNavigator or SpaceMouse, or a homemade device that+declares itself one. Move the cap to pan and zoom, and tilt or twist it to rotate the 3D view.+While editing a sketch, the cap pans and zooms without changing the sketch view. The Navigation+page in Preferences has an on/off switch, a speed control and, for each of the cap's six axes, an+invert switch and a speed for the 3D mouse. The web app reads+it too, through the browser; Firefox needs a 3DxWare setting first (see+[Getting started › 3D mouse in the browser](book/src/guide/getting-started.md#3d-mouse-in-the-browser)).++With 3DxWare on Windows, SolidCraft follows 3DxWare's profile for it when there is one, and+3DxWare's object mode (tilt to roll, twist to spin) until there is. The mouse-wheel turns that+3DxWare makes from the cap's motion are ignored, so the view doesn't zoom in steps as the cap tilts.++On Linux SolidCraft reads the 3D mouse through `spacenavd` when that daemon runs (its socket+`/var/run/spnav.sock`), so what you set in `spnavcfg` (swapped or inverted axes, sensitivity, dead+zones) applies as it does in other programs, and no udev rule is needed. With nothing set there,+the motion is the same as without the daemon. Without `spacenavd`, SolidCraft reads `/dev/hidrawN`+directly, so the logged-in user needs access to the device. A udev rule that adds the `uaccess`+tag does that, for example+`/etc/udev/rules.d/70-3d-mouse.rules` for USB devices with 3Dconnexion's vendor id, and for its+Bluetooth ones (where `idVendor` isn't set, so the HID id is matched instead):++```+SUBSYSTEM=="hidraw", ATTRS{idVendor}=="256f", TAG+="uaccess"+SUBSYSTEM=="hidraw", KERNELS=="0005:256F:*", TAG+="uaccess"+```++Older SpaceNavigators use Logitech's vendor id `046d`, so add a rule with their product id (see+`lsusb`) instead of matching every Logitech device. A homemade device needs a rule with its own+vendor and product id. Reload with `sudo udevadm control --reload && sudo udevadm trigger`, then+replug the device. The Flatpak sandbox does not expose hidraw devices, so the 3D mouse only works+with native builds there for now.++SolidCraft finds the axes from the device's report descriptor, so it doesn't matter how a device+lays them out: translation and rotation in separate reports (3Dconnexion's wired devices), all six+in one (its wireless ones and most homemade devices), after the buttons, or narrower than 16 bits.+Each axis is scaled from the range the descriptor declares.++On macOS SolidCraft talks to the 3Dconnexion driver (3DxWare) when it is installed, through the+driver's client API (`crates/threedx-client`; the framework is loaded at run time, never bundled).+The driver keeps the device to itself, and sends it only to a program it can identify: SolidCraft+as an `.app` (the packaged app). Without the driver, or with its helper not running, SolidCraft reads the device through IOKit like on Windows.++SolidCraft does not follow 3DxWare's profile on macOS. Its default is 3DxWare's object mode.diff --git a/docs/architecture.md b/docs/architecture.mdnew file mode 100644index 0000000000..d0e93cc623--- /dev/null+++ b/docs/architecture.md@@ -0,0 +1,13 @@+# Architecture++<!-- ANCHOR: architecture -->+| Layer | Crates | Role |+|---|---|---|+| L0 | `geom` | vectors, planes, profiles, meshes and their measures |+| L1 | `sketch`, `kernel`, `render` | constraint solver and profiles; the B-rep kernel boundary (truck); view math and the headless scene description |+| L2 | `doc` | parameters, expressions, the feature timeline and its incremental evaluation |+| L3 | `io` | design files, STL/OBJ/STEP/3MF export, STEP and 3MF/STL/OBJ/glTF import features |+| L4 | `engine` | the session and the command registry (everything is a command) |+| L5 | `gpu`, `ui-egui`, `mcp` | compute-shader evaluation of display tessellation plans; the swappable desktop front end; the MCP server (headless or bridged to the app) |+| apps | `solidcraft`, `solidcraft-cli` | desktop app, headless CLI |+<!-- ANCHOR_END: architecture -->diff --git a/docs/book/src/dev/architecture.md b/docs/book/src/dev/architecture.mdindex 61912142ac..72f03d2c6c 100644--- a/docs/book/src/dev/architecture.md+++ b/docs/book/src/dev/architecture.md@@ -3,7 +3,7 @@SolidCraft is a Cargo workspace in layers. A crate only depends on crates in lower layers, and`cargo xtask layers` fails the build otherwise.-{{#include ../../../../README.md:architecture}}+{{#include ../../../architecture.md:architecture}}The web app, `apps/solidcraft-web`, is the desktop front end compiled to wasm with[trunk](https://trunkrs.dev). `xtask` holds the repository's own tooling: `cargo xtask ci`,diff --git a/docs/building.md b/docs/building.mdnew file mode 100644index 0000000000..3548b5d9f8--- /dev/null+++ b/docs/building.md@@ -0,0 +1,28 @@+# Building and running++```sh+cargo run --release -p solidcraft -- --sample # desktop app with a sample part+cargo run --release -p solidcraft-cli -- commands # the command registry+cargo run --release -p solidcraft-cli -- run examples/bracket.json --out bracket.step+cargo run --release -p solidcraft-cli -- snapshot examples/bracket.json --out bracket.png+cargo run --release -p solidcraft-cli -- snapshot part.solidcraft --out preview.png --tool Pin --section z=12+cargo run --release -p solidcraft-cli -- render examples/render-studio.json --out product.png+cargo run --release -p solidcraft -- part.step # open a STEP file as a new design+cargo run --release -p solidcraft-cli -- eval part.step # measure an imported STEP file+cargo xtask ci # fmt, clippy, tests, icons, assets, layers, wasm+```++UI artwork changes follow the [icon specification](../assets/icons/ui/STYLE_GUIDE.md).+The [included review tool](../assets/icons/ui/README.md) discovers new icons and keeps+unaccepted artwork Open; run `cargo xtask icons` to check the collection.++Windows builds: `cargo xwin build --release --target x86_64-pc-windows-msvc -p solidcraft`.+++In the browser: `cd apps/solidcraft-web && trunk build --release --public-url ./` (WebGPU, or+WebGL2 with `?webgl`; `?sample` opens the sample part).++Agents can control the document open in a browser tab through `window.solidcraft.execute(...)`+and `window.solidcraft.request(...)`; see the [browser command API](browser-api.md).++See [CONTRIBUTING](../CONTRIBUTING.md) for the test and review workflow.diff --git a/docs/capabilities.md b/docs/capabilities.mdnew file mode 100644index 0000000000..00c98dc42e--- /dev/null+++ b/docs/capabilities.md@@ -0,0 +1,99 @@+# What works++The full feature summary, moved out of the README. The commands by area are in [features.md](features.md); status and plans are in [ROADMAP](../ROADMAP.md).++**Status: early but usable for simple parts.** 75 of 76 public reference parts+match their analytic or FreeCAD-computed volume, area, centre of mass and bounding box+([oracle.md](oracle.md)); the other is a tracked bug.+These checks do not establish complete geometric or workflow equivalence. The commands SolidCraft has+are listed by area in [features.md](features.md); status and plans are in [ROADMAP.md](../ROADMAP.md).+Open work and known bugs are in [GitHub issues](https://github.com/tangency-labs/solidcraft/issues),+and help is welcome: see [CONTRIBUTING.md](../CONTRIBUTING.md).+++- **Current-view DXF export** from File → Export Current View as DXF, with hidden edges+ omitted or dashed, shown body placements and the current camera. See [view DXF](view-dxf.md).++- **Sketches** on origin planes, offset planes or planar faces: lines, rectangles, circles,+ arcs, polygons, slots, ellipses, fit/control splines, conics and text; construction geometry,+ projection, trimming, fillets and chamfers, including corners at the origin.+ New face attachments retain supported construction identities and chosen occurrences;+ missing sources expose an explicit plane repair workflow. See [face attachments](face-attachments.md).+ Explicitly closed fit splines and closed associative offsets use periodic C2 interpolation.+ Supported convex line-and-arc offsets retain their identity when an inset consumes corner+ arcs, and linked extrusions follow the current boundary. Breaking the association freezes+ the boundary and keeps existing extrusions usable.+ Curve drawing and picking adapt together to zoom and display scale, including small circles+ at Fit and sketches in placed components.+- **Constraints and dimensions** solved by our own solver. Points the constraints fix relative+ to known geometry are placed exactly by construction (loci intersections and rigid-cluster+ decomposition, after Owen 1991 and Fudos–Hoffmann 1997); Levenberg–Marquardt solves the rest,+ and the rank of its Jacobian gives the remaining degrees of freedom. Constraints: coincident,+ point on curve, horizontal/vertical, parallel, perpendicular, tangent, curvature (G2), equal,+ concentric, collinear, midpoint, symmetry, fix; linear, aligned, horizontal, vertical,+ point-to-line, radius, diameter, angle, arc sweep, arc length and slot length dimensions driven+ by parameters. Over-constraining edits are rejected; fully constrained geometry turns black.+ Dragging solves the sketch every frame and rebuilds the model once, when the drag ends.+ Select a line or its two endpoints, type its dimension and press Enter to commit one undo+ step; with Sketch Dimension it's D, click, type, Enter. Fit keeps sketch geometry clear of the palette and navigation controls.+- **Profiles** found automatically, including regions split by lines and holes inside outlines.+ Newly captured complete adaptive boundaries retain their outer and hole source identities+ when spline span counts change. Partial or ambiguous boundaries do not qualify.+- **Features** on a parametric timeline: extrude, revolve, sweep, loft, fillet/chamfer,+ shell, draft, holes, threads, patterns, mirror, split, combine, move and construction geometry.+ The timeline rebuilds incrementally; features can be edited, suppressed, renamed, reordered+ and deleted. Supported geometry and current limitations are described in [ROADMAP.md](../ROADMAP.md).+ New revolves preserve symmetric and two-sided angular placement across reversed axes;+ older designs retain their saved convention when reopened or edited.+- **Parameters and configurations** with unit-aware expressions (`2 * width + 5 mm`,+ `angle / 2`), ordered rules, feature suppression and per-row body materials/appearances.+- **Assemblies** with nested components and occurrences, joints, motion studies, contact sets,+ interference and material-aware mass properties. Recorded body transfers preserve modelling+ history and world placement; 3D sketch wires retain their coordinate frames through edits.+- **Sheet metal** with flanges, hems, fold/unfold/refold, material cutouts, flat patterns,+ retained shallow prismatic pockets, exact line/arc/circle DXF outlines and bend tables;+ plastic enclosure features and rules. Pocket depth and side survive unfold/refold and appear+ separately from through-hole outlines in the flat preview and DXF.+- **Files**: design containers (`.solidcraft`) with lossless binary mesh payloads;+ plain JSON remains supported for opening, Save As and export. Desktop Open can show a saved+ provisional picture from warm geometry caches while rebuilding before editing; caches never+ replace the parametric design. Export to STEP (AP242 with body names, colours and+ components as assemblies; revolved faces as native planes, cylinders, cones, spheres and tori),+ IGES 5.3 (manifold solid B-reps with names and colours), 3MF, STL (binary/ASCII) and OBJ, and+ assemblies with joints as URDF for robot simulators (urdf.md);+ 3MF, STL, OBJ and glTF 2.0 (`.glb`/`.gltf`, its node tree as components and its materials as+ appearances) import as mesh bodies (they render, measure, move and export; solid features+ need B-rep bodies). The `mesh.convert` command reconstructs supported closed constant-section parts+ as parametric solids with planar and circular cylindrical faces;+ STEP import (AP203/AP214/AP242 solids, assemblies, units, names, colours) and IGES import+ (manifold solid B-reps, or trimmed and bounded surfaces sewn into solids) as a base feature+ that later features build on — open a `.step`/`.stp`/`.igs`/`.iges` file, insert one into a+ design, or drop it on the window ([docs/step-import.md](step-import.md)); FreeCAD+ `.FCStd` and Rhino `.3dm` solids import the same way through+ [cadmpeg](https://github.com/cadmpeg/cadmpeg) in the desktop app and CLI.+- **Render:** opaque surfaces can use metal fraction, roughness and dielectric IOR in the+ integrated product viewport and CPU preview PNGs. Existing simple colors remain supported.+ Fixed direct lighting is a preview; HDRI, refraction and texture maps are not implemented.+ See [opaque surfaces](render-opaque-pbr.md).+- **Display meshes** from our own tessellation planner: each face becomes a plan of (u, v)+ points and triangles that shares its edge nodes with its neighbours, so the mesh is watertight.+ Facets follow the chord tolerance, the facet angle and a longest side, with cells at most 2:1+ along straight directions. Box-bounded and four-cornered faces mesh as structured grids.+ Trimmed faces are cut into four-sided patches: squares around holes, butterflies in round+ faces, motorcycle traces from concave corners (after Lyon et al. 2019). Each patch then meshes+ as a Coons grid. Intersection edges are evaluated by Newton on both surfaces. A compute shader+ evaluates the plans for the whole scene in one dispatch, with a CPU fallback when the GPU+ can't build it. Planning and evaluating the 78 reference bodies takes about 65 ms, 50–65×+ faster than the previous mesher.+- **Desktop app** (egui + wgpu): toolbar with workspace tabs, browser, timeline, 3D viewport with+ axis view and navigation bar, sketch tools, feature dialogs, command palette, and a JSON-lines+ control channel so agents and tests can drive it.+ Feature errors and Help can open an editable **Create Issue** draft with relevant context+ and an optional reviewed screenshot; opening GitHub does not submit the report.+- **Headless CLI** `solidcraft-cli`: run command scripts, measure (volume, area, centre of mass,+ face/edge/vertex counts), export, render PNG snapshots and replay reference recipes.+ A snapshot can draw a body see-through and another solid in a colour of its own, and cut+ the model at a plane, so a picture shows the body a cut would remove inside the material+ it meets.+- **MCP server** `solidcraft-cli mcp`: AI agents model, measure and look at parts headless or+ in the running app (see below).diff --git a/docs/downloads.md b/docs/downloads.mdnew file mode 100644index 0000000000..c784b6cbe2--- /dev/null+++ b/docs/downloads.md@@ -0,0 +1,44 @@+# Downloads++Every platform and package. The links point at the latest release.++- **Windows:** download and run the [installer][windows-msi].+ Also for [ARM64][windows-arm64-msi] and [32-bit][windows-x86-msi] PCs, or as a+ [portable zip][windows-portable] that runs without installing.+ With [WinGet](https://learn.microsoft.com/windows/package-manager/winget/):+ `winget install bherbruck.SolidCraft`.+- **macOS:** open the [disk image][macos-dmg] and drag SolidCraft into Applications+ (Apple silicon and Intel).+- **Linux:** download the [AppImage][linux-appimage], allow it to run as a program and open it.+ Or install the [.deb][linux-deb] (Ubuntu, Debian, Mint) or [.rpm][linux-rpm] (Fedora,+ openSUSE), or use [Flatpak](https://docs.solidcraft.io/guide/getting-started.html#linux-flatpak).+ With Snap: `sudo snap install solidcraft` ([Snap Store][snap-store], or the [.snap file][linux-snap]).+ For ARM64: [AppImage][linux-arm64-appimage], [.deb][linux-arm64-deb], [.rpm][linux-arm64-rpm].+- **Web:** [try it in your browser][web-app], no install.+++The downloads aren't signed yet. On Windows, if SmartScreen warns you, choose **More info**, then+**Run anyway**. On macOS, the first time, right-click SolidCraft in Applications and choose **Open**.++**On SolidCraft 0.11 to 0.14?** Its **Update now** can't install 0.15.0 or later, because the+releases moved to a new address. Download the new version once from the links above; after that,+updating from inside SolidCraft works again ([details](https://docs.solidcraft.io/guide/updates.html#updating-from-011-to-014)).++Older versions, checksums and other formats are on the [releases page](https://github.com/tangency-labs/solidcraft/releases).+Install details, upgrading from earlier builds and building from source are in++[Getting started](https://docs.solidcraft.io/guide/getting-started.html).+[windows-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x64.msi+[windows-arm64-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-arm64.msi+[windows-x86-msi]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x86.msi+[windows-portable]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-windows-x64-portable.zip+[macos-dmg]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-macos-universal.dmg+[linux-appimage]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.AppImage+[linux-deb]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.deb+[linux-rpm]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.rpm+[linux-arm64-appimage]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-aarch64.AppImage+[linux-arm64-deb]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-aarch64.deb+[linux-arm64-rpm]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-aarch64.rpm+[linux-snap]: https://github.com/tangency-labs/solidcraft/releases/latest/download/solidcraft-linux-x86_64.snap+[snap-store]: https://snapcraft.io/solidcraft+[web-app]: https://solidcraft.io/appdiff --git a/docs/scripts.md b/docs/scripts.mdnew file mode 100644index 0000000000..fdaa8105a3--- /dev/null+++ b/docs/scripts.md@@ -0,0 +1,15 @@+# Scripts+++A script is a JSON list of commands, the same ones the UI runs:++```json+{"commands": [+ {"command": "sketch.create", "params": {"plane": "XY"}},+ {"command": "sketch.rectangle.two_point", "params": {"p0": [0, 0], "p1": [40, 30]}},+ {"command": "solid.extrude", "params": {"distance": 20}},+ {"command": "solid.fillet", "params": {"edges": [[0, 0, 10]], "radius": 3}}+]}+```++Run one with `solidcraft-cli run script.json --out part.step`; see [building](building.md) and the [command list](features.md).diff --git a/docs/showcase.md b/docs/showcase.mdnew file mode 100644index 0000000000..95907585ad--- /dev/null+++ b/docs/showcase.md@@ -0,0 +1,9 @@+# Built with SolidCraft++<a href="https://github.com/0xlillith/solidcraft-rover"><img src="screenshots/rover-build.gif" alt="SELENE, a scientific rover by 0xlillith, assembling itself as the timeline plays through its 3,323 steps in SolidCraft: tub, wheels, electronics, suspension, sampling arm, solar wings, dish and camera turret" loading="lazy"></a>++*SELENE, a scientific rover built entirely through SolidCraft's MCP server by+[@0xlillith](https://github.com/0xlillith/solidcraft-rover): 3,323 editable timeline steps that+rebuild with no errors, replayed here at 2× speed.+[Full video](https://github.com/tangency-labs/solidcraft/raw/refs/heads/main/screenshots/rover-build.mp4)+· [download the editable model](https://github.com/0xlillith/solidcraft-rover/releases/tag/v1.0.0).*