Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Docs: a beginner's page for equation curves, with pictures and examples (#9282)

Ahmad Khan71bb4f7c98e1
diff --git a/attribution/pending/docs-equation-curves.md b/attribution/pending/docs-equation-curves.md
new file mode 100644
index 0000000000..8f494f0583
--- /dev/null
+++ b/attribution/pending/docs-equation-curves.md
@@ -0,0 +1,7 @@
+| docs/book/src/generated/equation-circle.png | SolidCraft contributors | rendered by `cargo xtask book` (`solidcraft-cli snapshot docs/book/scripts/equation-circle.json`; gitignored) | MIT OR Apache-2.0 |
+| docs/book/src/generated/equation-flower.png | SolidCraft contributors | rendered by `cargo xtask book` (`solidcraft-cli snapshot docs/book/scripts/equation-flower.json`; gitignored) | MIT OR Apache-2.0 |
+| docs/book/src/generated/equation-involute.png | SolidCraft contributors | rendered by `cargo xtask book` (`solidcraft-cli snapshot docs/book/scripts/equation-involute.json`; gitignored) | MIT OR Apache-2.0 |
+| docs/book/src/generated/equation-line.png | SolidCraft contributors | rendered by `cargo xtask book` (`solidcraft-cli snapshot docs/book/scripts/equation-line.json`; gitignored) | MIT OR Apache-2.0 |
+| docs/book/src/generated/equation-parabola.png | SolidCraft contributors | rendered by `cargo xtask book` (`solidcraft-cli snapshot docs/book/scripts/equation-parabola.json`; gitignored) | MIT OR Apache-2.0 |
+| docs/book/src/generated/equation-spiral.png | SolidCraft contributors | rendered by `cargo xtask book` (`solidcraft-cli snapshot docs/book/scripts/equation-spiral.json`; gitignored) | MIT OR Apache-2.0 |
+| docs/book/src/generated/equation-wave.png | SolidCraft contributors | rendered by `cargo xtask book` (`solidcraft-cli snapshot docs/book/scripts/equation-wave.json`; gitignored) | MIT OR Apache-2.0 |
diff --git a/docs/book/scripts/equation-circle.json b/docs/book/scripts/equation-circle.json
new file mode 100644
index 0000000000..40e5e06b05
--- /dev/null
+++ b/docs/book/scripts/equation-circle.json
@@ -0,0 +1,6 @@
+{"commands": [
+ {"command": "sketch.create", "params": {"plane": "XY", "name": "Circle"}},
+ {"command": "sketch.equation_curve", "params": {"x": "20 * cos(t)", "y": "20 * sin(t)", "start": 0, "end": "2 * pi"}},
+ {"command": "sketch.finish", "params": {}},
+ {"command": "view.apply", "params": {"view": "top"}}
+]}
diff --git a/docs/book/scripts/equation-flower.json b/docs/book/scripts/equation-flower.json
new file mode 100644
index 0000000000..3a2cda5acf
--- /dev/null
+++ b/docs/book/scripts/equation-flower.json
@@ -0,0 +1,6 @@
+{"commands": [
+ {"command": "sketch.create", "params": {"plane": "XY", "name": "Flower"}},
+ {"command": "sketch.equation_curve", "params": {"x": "(20 + 4 * cos(6 * t)) * cos(t)", "y": "(20 + 4 * cos(6 * t)) * sin(t)", "start": 0, "end": "2 * pi"}},
+ {"command": "sketch.finish", "params": {}},
+ {"command": "solid.extrude", "params": {"sketch": "Flower", "distance": 6, "body_name": "Flower"}}
+]}
diff --git a/docs/book/scripts/equation-involute.json b/docs/book/scripts/equation-involute.json
new file mode 100644
index 0000000000..4e867fdb71
--- /dev/null
+++ b/docs/book/scripts/equation-involute.json
@@ -0,0 +1,8 @@
+{"commands": [
+ {"command": "parameters.add", "params": {"name": "r", "expression": "20 mm"}},
+ {"command": "sketch.create", "params": {"plane": "XY", "name": "Involute"}},
+ {"command": "sketch.equation_curve", "params": {"x": "r * (cos(t) + t * sin(t))", "y": "r * (sin(t) - t * cos(t))", "start": 0, "end": 1.5}},
+ {"command": "sketch.circle.center", "params": {"center": [0, 0], "diameter": 40}},
+ {"command": "sketch.finish", "params": {}},
+ {"command": "view.apply", "params": {"view": "top"}}
+]}
diff --git a/docs/book/scripts/equation-line.json b/docs/book/scripts/equation-line.json
new file mode 100644
index 0000000000..ff1aefe92f
--- /dev/null
+++ b/docs/book/scripts/equation-line.json
@@ -0,0 +1,6 @@
+{"commands": [
+ {"command": "sketch.create", "params": {"plane": "XY", "name": "Line"}},
+ {"command": "sketch.equation_curve", "params": {"explicit": true, "y": "x / 2", "start": 0, "end": 40}},
+ {"command": "sketch.finish", "params": {}},
+ {"command": "view.apply", "params": {"view": "top"}}
+]}
diff --git a/docs/book/scripts/equation-parabola.json b/docs/book/scripts/equation-parabola.json
new file mode 100644
index 0000000000..fd14cf23b8
--- /dev/null
+++ b/docs/book/scripts/equation-parabola.json
@@ -0,0 +1,6 @@
+{"commands": [
+ {"command": "sketch.create", "params": {"plane": "XY", "name": "Parabola"}},
+ {"command": "sketch.equation_curve", "params": {"explicit": true, "y": "x * x / 20", "start": -30, "end": 30}},
+ {"command": "sketch.finish", "params": {}},
+ {"command": "view.apply", "params": {"view": "top"}}
+]}
diff --git a/docs/book/scripts/equation-spiral.json b/docs/book/scripts/equation-spiral.json
new file mode 100644
index 0000000000..80ca0e9587
--- /dev/null
+++ b/docs/book/scripts/equation-spiral.json
@@ -0,0 +1,6 @@
+{"commands": [
+ {"command": "sketch.create", "params": {"plane": "XY", "name": "Spiral"}},
+ {"command": "sketch.equation_curve", "params": {"x": "2 * t * cos(t)", "y": "2 * t * sin(t)", "start": 0, "end": "4 * pi"}},
+ {"command": "sketch.finish", "params": {}},
+ {"command": "view.apply", "params": {"view": "top"}}
+]}
diff --git a/docs/book/scripts/equation-wave.json b/docs/book/scripts/equation-wave.json
new file mode 100644
index 0000000000..8e862639b3
--- /dev/null
+++ b/docs/book/scripts/equation-wave.json
@@ -0,0 +1,6 @@
+{"commands": [
+ {"command": "sketch.create", "params": {"plane": "XY", "name": "Wave"}},
+ {"command": "sketch.equation_curve", "params": {"explicit": true, "y": "8 * sin(x / 5)", "start": 0, "end": "20 * pi"}},
+ {"command": "sketch.finish", "params": {}},
+ {"command": "view.apply", "params": {"view": "top"}}
+]}
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
index 6c309d6357..de0960efcd 100644
--- a/docs/book/src/SUMMARY.md
+++ b/docs/book/src/SUMMARY.md
@@ -7,6 +7,7 @@
- [Getting started](guide/getting-started.md)
- [A tour of the window](guide/ui-tour.md)
- [Sketching and constraints](guide/sketching.md)
+ - [Equation curves](guide/equation-curves.md)
- [Solid features](guide/features.md)
- [Parameters and expressions](guide/parameters.md)
- [Components and joints](guide/assemblies.md)
diff --git a/docs/book/src/guide/equation-curves.md b/docs/book/src/guide/equation-curves.md
new file mode 100644
index 0000000000..f49cf8a161
--- /dev/null
+++ b/docs/book/src/guide/equation-curves.md
@@ -0,0 +1,123 @@
+# Equation curves
+
+An equation curve is a curve you **describe with a rule** instead of drawing it with clicks.
+You type the rule, and SolidCraft draws the curve that follows it, exactly, every time.
+
+It is the way to get shapes that are hard to draw by hand: a smooth wave, a parabola, a spiral,
+or the curved side of a gear tooth.
+
+## Your first curve: a straight ramp
+
+1. Start a sketch: **SOLID › CREATE › Create Sketch**, then click a plane.
+2. Click **SKETCH › CREATE › Equation Curve**. A window opens with a wave already filled in.
+3. Set **Form** to **Explicit**. Now there is one rule to fill in, **y(x)**: *how high is the curve
+ at each x?*
+4. Type `x / 2` in **y(x)**, `0` in **Start** and `40` in **End**.
+5. Click **OK**.
+
+![The curve y = x / 2 from x = 0 to x = 40: a straight ramp](../generated/equation-line.png)
+
+The rule says: *the height is half of how far along you are*. At x = 10 the curve is 5 high, at
+x = 40 it is 20 high. **Start** and **End** say where along x the curve begins and stops.
+
+## Explicit: one rule for the height
+
+With **Explicit**, you write the height `y` using `x`. Try these (same steps, other rules):
+
+| Rule in **y(x)** | Start | End | What you get |
+|---|---|---|---|
+| `x / 2` | `0` | `40` | a straight ramp (above) |
+| `x * x / 20` | `-30` | `30` | a parabola, the shape of a thrown ball's path |
+| `8 * sin(x / 5)` | `0` | `20 * pi` | a smooth wave |
+
+![The parabola y = x * x / 20 from x = -30 to x = 30](../generated/equation-parabola.png)
+
+![The wave y = 8 * sin(x / 5): two smooth waves along x](../generated/equation-wave.png)
+
+In the wave, `8` is how tall each bump is and `5` stretches it sideways: try `x / 10` and the
+waves get twice as long.
+
+## Parametric: a rule for x and a rule for y
+
+Some curves go back on themselves, like a circle: for one x there are two heights. For those,
+set **Form** to **Parametric** and give **two** rules, **x(t)** and **y(t)**.
+
+Think of `t` as **a clock**. It starts at **Start** and ticks up to **End**. At every moment the
+two rules say where the pen is: across (`x`) and up (`y`). The curve is the path the pen draws
+while the clock runs.
+
+| Rule in **x(t)** | Rule in **y(t)** | Start | End | What you get |
+|---|---|---|---|---|
+| `20 * cos(t)` | `20 * sin(t)` | `0` | `2 * pi` | a circle of radius 20 |
+| `2 * t * cos(t)` | `2 * t * sin(t)` | `0` | `4 * pi` | a spiral, two turns |
+
+![A circle of radius 20 drawn from x = 20 cos(t), y = 20 sin(t)](../generated/equation-circle.png)
+
+For the circle, `cos` and `sin` walk the pen around, and `20` is how far from the middle it
+stays. `2 * pi` is one full turn, so the circle closes. In the spiral, the distance from the
+middle (`2 * t`) grows while the clock runs, so the pen moves outwards as it goes round.
+
+![A spiral of two turns drawn from x = 2 t cos(t), y = 2 t sin(t)](../generated/equation-spiral.png)
+
+## Angles are in radians
+
+`sin`, `cos` and `tan` count angles in **radians**, not degrees: a full turn is `2 * pi`
+(about 6.28), half a turn is `pi`. You can also write an angle with its unit for **Start** and
+**End**, such as `360 deg`.
+
+A number without a unit is in your design's unit (millimetres unless you changed it).
+
+## Using parameters: a gear tooth
+
+Rules can use the design's [parameters](parameters.md). Here a parameter `r` (20 mm) is the size
+of a base circle, and the curve is the *involute* of that circle: the path the end of a string
+makes as you unwind it from the circle. The sides of most gear teeth have this shape.
+
+| Rule in **x(t)** | Rule in **y(t)** | Start | End |
+|---|---|---|---|
+| `r * (cos(t) + t * sin(t))` | `r * (sin(t) - t * cos(t))` | `0` | `1.5` |
+
+![The involute of a 20 mm base circle, starting on the circle and curving away from it](../generated/equation-involute.png)
+
+Change `r` in the Parameters dialog and the curve redraws itself to match: the rule is kept, not
+just the shape.
+
+## From curve to part
+
+An equation curve is an ordinary sketch curve, so you can build with it:
+
+- A curve that **ends where it starts** closes by itself, smoothly. Extrude it and you get a
+ solid. This flower uses a radius that goes in and out six times as the clock goes round once:
+
+ | Rule in **x(t)** | Rule in **y(t)** | Start | End |
+ |---|---|---|---|
+ | `(20 + 4 * cos(6 * t)) * cos(t)` | `(20 + 4 * cos(6 * t)) * sin(t)` | `0` | `2 * pi` |
+
+ ![The flower curve extruded 6 mm into a solid](../generated/equation-flower.png)
+
+- An **open** curve can be closed with lines: draw lines from its two ends, then extrude the
+ shape. For example, close a wave with three lines down to the x axis to get a wavy strip.
+- It can be the **path** of a sweep.
+
+## Changing a curve
+
+Right-click the curve and choose **Edit Equation Curve**. The same window opens with the rules
+in it; change them and click **OK**.
+
+## When something goes wrong
+
+- **The curve is tiny or huge.** Check the numbers in the rule and the Start/End range: `sin`
+ never goes past 1, so `sin(x)` alone is at most 1 mm high. Multiply it (`8 * sin(x)`).
+- **The wave has too few bumps, or far too many.** Remember radians: `sin(x)` repeats every
+ `2 * pi` (6.28) along x, not every 360.
+- **The circle has a gap.** End must be a whole turn: `2 * pi`, or `360 deg`.
+- **A rule is rejected.** Use `*` for multiply (`2 * t`, not `2t`), and close every bracket.
+
+## For scripts and agents
+
+The commands are `sketch.equation_curve` and `sketch.equation_curve.edit` (see the
+[command reference](../reference/commands.md)). The curve is a fit point spline through points
+worked out from the rules, as many as keep it within the **Tolerance** (0.01 mm unless you set
+another), up to 500. Its points are fixed, so other curves can start at its ends. When a parameter
+a rule uses changes, the points follow. The pictures on this page come from the scripts in
+`docs/book/scripts/equation-*.json`.
diff --git a/docs/book/src/guide/sketching.md b/docs/book/src/guide/sketching.md
index 1418976dfe..b01ea3543f 100644
--- a/docs/book/src/guide/sketching.md
+++ b/docs/book/src/guide/sketching.md
@@ -227,16 +227,10 @@ it smoothly. Right-click finishes an ordinary natural fit. Offset accepts both e
handles and dense fitted curves; the second click sets the side and distance from the curve.
**Equation Curve** draws a curve from formulas instead of clicks: x(t) and y(t) over a range of
-t, or y = f(x) over a range of x. The formulas use the expression language and the design's
-parameters, so `x = r * (cos(t) + t * sin(t))`, `y = r * (sin(t) - t * cos(t))` with t from 0 to
-1 is the involute of a base circle of radius `r`. The variable is a plain number: `sin(t)` takes
-it in radians, and a result without a unit is in the design's unit. The curve is a fit point
-spline through points worked out from the formulas, as many as keep it within the tolerance
-(0.01 mm unless you set another), up to 500; a curve that ends where it starts closes smoothly.
-Its points are fixed, so other curves can start at its ends and close a profile for Extrude or
-Revolve, and it can be a sweep path. When a parameter it uses changes, the points follow.
-Right-click the curve and choose **Edit Equation Curve** to change the formulas
-(`sketch.equation_curve` and `sketch.equation_curve.edit` from scripts and agents).
+t, or y = f(x) over a range of x, using the design's parameters. [Equation curves](equation-curves.md)
+walks through it step by step, with pictures and examples (a line, a parabola, a wave, a circle,
+a spiral, a gear tooth's involute). Right-click the curve and choose **Edit Equation Curve** to
+change the formulas (`sketch.equation_curve` and `sketch.equation_curve.edit` from scripts and agents).
While drawing in a planar sketch, **Construction** (X) changes the line type without
ending the tool or losing picked points and inline values. The preview and hover feedback