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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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 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 |++++++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 |++++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.++++## 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` |++++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` |++ ++- 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.mdindex 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 ehandles 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 withoutending the tool or losing picked points and inline values. The preview and hover feedback