Documentation site and CI workflows
An mdBook under docs/book: a user guide (getting started, UI tour, sketching, features, parameters, components and joints, sheet metal, plastic, files, shortcuts, MCP) and a developer guide (CONTRIBUTING, architecture, command engine, kernel boundary, persistent naming, test harnesses, and the existing docs/*.md pages). `cargo xtask book` generates the command reference from `solvecraft-cli commands` and renders the screenshots with `solvecraft-cli snapshot`, then runs mdbook. .github/workflows/pages.yml publishes the book at /solvecraft/ and the web app at /solvecraft/app/ (skipped while the repository is private). .github/workflows/ci.yml runs `cargo xtask ci` on pull requests. README and Help → Documentation link to the book. Fixes #28 Fixes #8 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
bherbruckandClaude Opus 5.5 committed
1 parent
2c3fec087e
commit
0d7e456bc1
35 files changed
+792
-5
No files matched your search
@@ -0,0 +1,22 @@
|
||||
# Components and joints
|
||||
|
||||
A design is a tree of **components**. **New Component** (`component.create`) adds one, and
|
||||
**Create Components from Bodies** (`component.from_bodies`) turns bodies into components. Each
|
||||
component has its own origin, bodies, sketches and timeline entries. The **active component**
|
||||
(the radio button in the browser) receives new sketches and features; the others are drawn
|
||||
faded.
|
||||
|
||||
A component is placed by its **occurrences**. Paste creates another instance of the same
|
||||
component, and **Paste New** creates an independent copy. Move an occurrence with the move
|
||||
triad, then **Capture Position** to keep it or **Revert** to put it back. SolveCraft asks before
|
||||
the next command if a move wasn't captured. **Ground** fixes an occurrence in place.
|
||||
|
||||
**Joints** (`joint.create`, J) connect two components by joint origins that snap to faces, edges,
|
||||
circles and vertices: rigid, revolute, slider, cylindrical, pin-slot, planar and ball, with
|
||||
offsets, flip and limits. **As-built Joint** keeps the current position, **Rigid Group** locks
|
||||
components together, **Drive Joints** moves a joint through its values, and **Motion Link**
|
||||
couples two joints. Contact sets stop motion where bodies would pass through each other,
|
||||
**Motion Study** keys joint values along a timeline, and **Interference** shows overlapping
|
||||
volumes in red.
|
||||
|
||||
STEP export writes the component tree as an assembly.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Solid features
|
||||
|
||||
Features live on the **timeline** and rebuild incrementally from the first one that changed.
|
||||
Each one can be edited (double-click), suppressed, renamed, reordered (if nothing it depends on
|
||||
moves after it), rolled back to, and deleted. Deleting asks first when other features depend on
|
||||
it.
|
||||
|
||||
| Panel | Features |
|
||||
|---|---|
|
||||
| Create | extrude (one side, two sides, symmetric, taper, start offset, to a distance or through all; new body, join, cut, intersect), revolve, sweep, loft, box, cylinder, sphere, torus, coil, pipe, rib, web, emboss, hole (simple, counterbore, countersink, tapped; on faces or at sketch points), thread, rectangular/circular/path patterns, mirror |
|
||||
| Modify | press pull, fillet, chamfer, shell, draft, scale, combine, split body, offset face, replace face, move/copy, align, remove |
|
||||
| Construct | offset plane, plane at angle |
|
||||
| Inspect | measure, section analysis, interference, curvature comb and map, zebra, draft, minimum radius, isocurves, centre of mass |
|
||||
|
||||
Fillets and chamfers handle straight edges between planar faces, whole smooth loops, runs of
|
||||
neighbouring edges with mitred or spherical corners, and closed chains of curved edges (a rolling
|
||||
ball). See the roadmap's known limitations for the rest.
|
||||
|
||||
Feature references to faces and edges are stored by name, so an upstream edit that moves geometry
|
||||
keeps them on the right face (see [Persistent naming](../dev/naming.md)). When a reference can't
|
||||
be found, the feature warns instead of silently picking another face.
|
||||
|
||||
Press **Delete** on anything selected (bodies, faces, sketches, features, planes, components,
|
||||
canvases). It runs as one undoable step and lists the features that would go with it or fail.
|
||||
@@ -0,0 +1,19 @@
|
||||
# Import and export
|
||||
|
||||
| Format | Read | Write |
|
||||
|---|---|---|
|
||||
| `.solvecraft` (JSON design, versioned) | yes | yes |
|
||||
| STEP (AP203, AP214, AP242) | solids, assemblies, units, names, colours | AP242 with names, colours and the component tree |
|
||||
| IGES 5.3 | manifold solids, or trimmed surfaces sewn into solids | manifold solids with names and colours |
|
||||
| 3MF, STL, OBJ | mesh bodies | yes |
|
||||
| DXF, SVG | into a sketch | sketches and flat patterns as DXF |
|
||||
| PNG, JPEG | canvases and decals | |
|
||||
|
||||
Opening a STEP or IGES file creates a design with the file's bodies as a base feature, and
|
||||
inserting one adds them to the current design. Later features build on them. Mesh bodies render,
|
||||
measure, move and export, but solid features need B-rep bodies.
|
||||
|
||||
Saves are atomic: a crash at any moment leaves either the old file or the new one, and the
|
||||
replaced version is kept as `<file>.bak`. Unsaved changes are autosaved to a recovery folder,
|
||||
and the next launch offers to recover them. Older design files are upgraded on open, and files
|
||||
from a newer version are refused with a message.
|
||||
@@ -0,0 +1,56 @@
|
||||
# Getting started
|
||||
|
||||
## Desktop
|
||||
|
||||
Download the latest build from the
|
||||
[releases page](https://github.com/bherbruck/solvecraft/releases), or build it yourself with
|
||||
stable Rust (1.90 or newer):
|
||||
|
||||
```sh
|
||||
git clone https://github.com/bherbruck/solvecraft && cd solvecraft
|
||||
cargo run --release -p solvecraft -- --sample # opens with a sample part
|
||||
```
|
||||
|
||||
`solvecraft part.step` opens a STEP, IGES, 3MF, STL or OBJ file as a new design, and
|
||||
`solvecraft design.solvecraft` opens a saved design. Windows builds cross-compile from Linux with
|
||||
`cargo xwin build --release --target x86_64-pc-windows-msvc -p solvecraft`.
|
||||
|
||||
## Web
|
||||
|
||||
The same app runs in the browser: [open SolveCraft on the web](../app/) (`?sample` opens the sample
|
||||
part, `?webgl` forces WebGL2 where WebGPU is missing). Designs are saved in the browser's private
|
||||
file storage, which needs HTTPS or localhost. To build it yourself:
|
||||
|
||||
```sh
|
||||
rustup target add wasm32-unknown-unknown
|
||||
cd apps/solvecraft-web && trunk serve --release
|
||||
```
|
||||
|
||||
## CLI
|
||||
|
||||
`solvecraft-cli` runs the same commands without a window:
|
||||
|
||||
```sh
|
||||
cargo run --release -p solvecraft-cli -- commands # every command, as JSON
|
||||
cargo run --release -p solvecraft-cli -- run examples/bracket.json --out bracket.step
|
||||
cargo run --release -p solvecraft-cli -- eval examples/bracket.json # volume, area, faces…
|
||||
cargo run --release -p solvecraft-cli -- snapshot examples/bracket.json --out bracket.png
|
||||
cargo run --release -p solvecraft-cli -- exec solid.box '{"length": 20, "width": 10, "height": 5}'
|
||||
```
|
||||
|
||||
A script is a list of commands:
|
||||
|
||||
```json
|
||||
{"commands": [
|
||||
{"command": "sketch.create", "params": {"plane": "XY"}},
|
||||
{"command": "sketch.rectangle.two_point", "params": {"p0": [0, 0], "p1": [40, 30]}},
|
||||
{"command": "sketch.finish", "params": {}},
|
||||
{"command": "solid.extrude", "params": {"distance": 20}},
|
||||
{"command": "solid.fillet", "params": {"edges": [[0, 0, 10]], "radius": 3}}
|
||||
]}
|
||||
```
|
||||
|
||||
|
||||
|
||||
Units are millimetres and degrees unless an expression says otherwise (`"1 in"`, `"30 deg"`),
|
||||
and Z is up.
|
||||
@@ -0,0 +1 @@
|
||||
{{#include ../../../mcp.md}}
|
||||
@@ -0,0 +1,21 @@
|
||||
# Parameters and expressions
|
||||
|
||||
Every dimension and feature input is a **model parameter** (`d1`, `d2`, …). **User parameters**
|
||||
are ones you add yourself, with a unit, an expression and an optional comment. Change them in
|
||||
**Change Parameters** (`parameters.change`). The timeline rebuilds from the first feature that
|
||||
uses them.
|
||||
|
||||
Expressions are unit-aware: `2 * width + 5 mm`, `angle / 2`, `sqrt(area)`, `1 in + 3 mm`, using
|
||||
`+ - * / ^`, parentheses, `sin cos tan asin acos atan atan2 sqrt abs min max floor ceil round mod
|
||||
trunc` and unit conversion. A length where an angle is expected (or the other way round) is an
|
||||
error, not a silent conversion. Cycles are reported with their path (`a → b → a`), renaming a
|
||||
parameter updates every expression, dimension and feature input that uses it, and a parameter
|
||||
in use can't be deleted (the error lists its users).
|
||||
|
||||
The design's units (Document Settings in the browser: mm, cm, m, in or ft) set how a bare number
|
||||
typed into a feature is read. In an inch design `2` means 2 in. Changing the units never moves
|
||||
existing geometry.
|
||||
|
||||
Parameters export to and import from CSV or JSON (`parameters.export`, `parameters.import`).
|
||||
**Configurations** (`config.*`) keep a table of rows, each with its own parameter values and
|
||||
suppressed features, switched with `config.activate`.
|
||||
@@ -0,0 +1,13 @@
|
||||
# Plastic parts
|
||||
|
||||
The PLASTIC tab has a small enclosure subset:
|
||||
|
||||
- **Boss** (`plastic.boss`): screw bosses with a hole, fillets and optional ribs.
|
||||
- **Lip / Groove** (`plastic.lip`): the mating lip and groove along a shell's opening.
|
||||
- **Snap Fit** (`plastic.snap_fit`): a cantilever snap hook and its catch.
|
||||
- **Rest** (`plastic.rest`): a pad for a part to rest on.
|
||||
- **Plastic Rules** (`plastic.manage_rules`, `plastic.assign_rule`): wall thickness, draft and
|
||||
clearance per material, used as the features' defaults.
|
||||
|
||||
Rib and web (on the SOLID tab) complete the set. These features are checked against
|
||||
hand-computed geometry rather than a Fusion oracle.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Sheet metal
|
||||
|
||||
The SHEET METAL tab builds parts from a sheet of constant thickness under a **sheet metal rule**
|
||||
(thickness, bend radius, K-factor), set in **Sheet Metal Rules** (`sheet.manage_rules`).
|
||||
|
||||
- **Flange** (`sheet.flange`): a base flange from a sketch profile, a contour flange from an open
|
||||
sketch, or an edge flange from a part edge.
|
||||
- **Hem** (`sheet.hem`) and **Fold** (`sheet.fold`) along a sketch line.
|
||||
- **Unfold / Refold** (`sheet.unfold`, `sheet.refold`) for working on the flat part.
|
||||
- **Convert** (`sheet.convert`) turns a solid of constant thickness into sheet metal.
|
||||
- **Create Flat Pattern** (`sheet.flat_pattern`) shows the flat part with its bend lines and a
|
||||
bend table, and exports it as DXF.
|
||||
|
||||
Bends follow the rule's K-factor, so flat lengths match what a press brake will make. The
|
||||
oracle checks these against parts built in Fusion.
|
||||
@@ -0,0 +1,29 @@
|
||||
# Keyboard shortcuts
|
||||
|
||||
Command shortcuts can be changed in File › Keyboard Shortcuts; these are the defaults.
|
||||
|
||||
| Key | Command | Key | Command |
|
||||
|---|---|---|---|
|
||||
| L | Line | E | Extrude |
|
||||
| R | Two-Point Rectangle | Q | Press Pull |
|
||||
| C | Center Diameter Circle | F | Fillet |
|
||||
| D | Sketch Dimension | H | Hole |
|
||||
| X | Construction | M | Move/Copy |
|
||||
| O | Offset | J | Joint |
|
||||
| T | Trim | I | Measure |
|
||||
| P | Project | A | Appearance |
|
||||
| Ctrl+Z | Undo | Ctrl+Y | Redo |
|
||||
| Ctrl+N | New Design | Ctrl+O | Open |
|
||||
| Ctrl+S | Save | Delete | Delete the selection |
|
||||
|
||||
Keys handled by the window itself:
|
||||
|
||||
| Key | Action |
|
||||
|---|---|
|
||||
| S | the S box: search every command at the cursor |
|
||||
| V | show or hide the selected bodies, sketches and planes |
|
||||
| F2 | rename the selected browser or timeline item |
|
||||
| F6 | fit the view to the model |
|
||||
| Esc | cancel the running command, or clear the selection |
|
||||
|
||||
Help › Keyboard Shortcuts in the app lists the current bindings, including any you changed.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Sketching and constraints
|
||||
|
||||
A sketch lies on a plane: an origin plane, a construction plane or a planar face. Start one with
|
||||
**Create Sketch** (`sketch.create`) and click a plane, or pick a face first. **Finish Sketch**
|
||||
returns to the model.
|
||||
|
||||
## Geometry
|
||||
|
||||
Lines and polylines (L), rectangles (two-point R, three-point, centre), circles (centre C,
|
||||
two-point, three-point, tangent), arcs (three-point, centre, tangent), polygons, slots, ellipses,
|
||||
fit-point and control-point splines, conics, points and text. **Construction** (X) turns curves
|
||||
into reference geometry that doesn't form profiles. Modify tools include trim (T), extend, break,
|
||||
fillet, chamfer, offset (O), mirror, patterns, move/copy and scale.
|
||||
|
||||
**Project** (P) and **Intersect** bring model edges into the sketch as linked geometry that
|
||||
follows later changes. Sketching on a face projects its edges automatically.
|
||||
|
||||
## Constraints and dimensions
|
||||
|
||||
The solver is SolveCraft's own (damped Gauss–Newton with degree-of-freedom analysis). Constraints:
|
||||
coincident, horizontal/vertical, parallel, perpendicular, tangent, equal, concentric, collinear,
|
||||
midpoint, symmetry, fix, curvature (G2) and polygon. **Sketch Dimension** (D) adds linear,
|
||||
aligned, horizontal, vertical, radius, diameter and angle dimensions. Each is a parameter
|
||||
(`d1`, `d2`, …), so it can hold an expression.
|
||||
|
||||
Under-constrained geometry is blue and fully constrained geometry turns dark, and the status
|
||||
shows the remaining degrees of freedom. A constraint or dimension that would over-constrain the
|
||||
sketch is refused rather than applied. Drag a point to move it; the solver keeps every
|
||||
constraint while you drag.
|
||||
|
||||
## Profiles
|
||||
|
||||
Closed loops become profiles automatically, including regions split by crossing lines and
|
||||
islands inside outlines. Extrude, revolve, sweep and loft pick profiles.
|
||||
@@ -0,0 +1,29 @@
|
||||
# A tour of the window
|
||||
|
||||
|
||||
|
||||
- **Title bar.** On Windows and Linux the application bar is the window's title bar: File, save,
|
||||
undo and redo, the start page, the theme, Help, and one tab per open design (each with its own
|
||||
undo history, selection and camera).
|
||||
- **Toolbar.** The workspace switcher (DESIGN) sits on the left. The tabs (SOLID, SURFACE,
|
||||
SHEET METAL, PLASTIC, UTILITIES, and SKETCH while you sketch) hold panels of commands. Click a
|
||||
panel's name for all its commands.
|
||||
- **Browser** (left). The design as a tree: document settings and units, named views, the
|
||||
origin, bodies, sketches, construction planes, canvases, joints and components. The eye shows or
|
||||
hides an item, a component's radio button makes it the active component, and right-clicking any
|
||||
row gives that item's menu. Rows drag into groups and other components.
|
||||
- **Viewport.** Click to select, Shift or Ctrl to add, drag for a window or crossing box. The
|
||||
wheel zooms at the cursor, the middle button pans and Shift+middle orbits (the mouse preset in
|
||||
Preferences switches to SolidWorks or Inventor style). The view cube and the navigation bar
|
||||
change the view. Right-click for the marking menu: eight commands around the cursor, plus a
|
||||
menu for whatever is under it.
|
||||
- **Dialogs** dock on the right with a live preview. Most features also show drag handles and a
|
||||
value box in the viewport.
|
||||
- **Timeline** (bottom). Every feature in order. Double-click to edit, drag the marker to roll
|
||||
back, and drag features to reorder them.
|
||||
- **S box.** Press S anywhere for a command search at the cursor. Pin the commands you use most
|
||||
to its top.
|
||||
|
||||
Preferences (File › Preferences) hold the theme, the units of new designs, the mouse preset, the
|
||||
visual style and autosave. Help › Keyboard Shortcuts lists every key, and File › Keyboard
|
||||
Shortcuts changes them.
|
||||
Reference in new issue
Block a user