From 71bb4f7c98e1137dc9e46abbcdb9a69d884403a0 Mon Sep 17 00:00:00 2001 From: Ahmad Khan Date: Fri, 30 Oct 2026 07:54:27 +0000 Subject: [PATCH] Docs: a beginner's page for equation curves, with pictures and examples (#9282) A new user guide page, Equation curves, under Sketching: the first curve step by step, Explicit and Parametric explained with tables of rules to type (a line, a parabola, a wave, a circle, a spiral), radians, parameters with the involute of a base circle, building a part (a closed flower curve extruded), editing, and common mistakes. The technical details stay in a short section for scripts and agents. Seven pictures, rendered by `cargo xtask book` from new scripts in docs/book/scripts/equation-*.json (gitignored output, attributed in attribution/pending/docs-equation-curves.md). The Sketching page keeps a short summary and links to the new page. --- attribution/pending/docs-equation-curves.md | 7 ++ docs/book/scripts/equation-circle.json | 6 + docs/book/scripts/equation-flower.json | 6 + docs/book/scripts/equation-involute.json | 8 ++ docs/book/scripts/equation-line.json | 6 + docs/book/scripts/equation-parabola.json | 6 + docs/book/scripts/equation-spiral.json | 6 + docs/book/scripts/equation-wave.json | 6 + docs/book/src/SUMMARY.md | 1 + docs/book/src/guide/equation-curves.md | 123 ++++++++++++++++++++ docs/book/src/guide/sketching.md | 14 +-- 11 files changed, 179 insertions(+), 10 deletions(-) create mode 100644 attribution/pending/docs-equation-curves.md create mode 100644 docs/book/scripts/equation-circle.json create mode 100644 docs/book/scripts/equation-flower.json create mode 100644 docs/book/scripts/equation-involute.json create mode 100644 docs/book/scripts/equation-line.json create mode 100644 docs/book/scripts/equation-parabola.json create mode 100644 docs/book/scripts/equation-spiral.json create mode 100644 docs/book/scripts/equation-wave.json create mode 100644 docs/book/src/guide/equation-curves.md diff --git a/attribution/pending/docs-equation-curves.md b/attribution/pending/docs-equation-curves.md new file mode 100644 index 000000000..8f494f058 --- /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 000000000..40e5e06b0 --- /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 000000000..3a2cda5ac --- /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 000000000..4e867fdb7 --- /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 000000000..ff1aefe92 --- /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 000000000..fd14cf23b --- /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 000000000..80ca0e958 --- /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 000000000..8e862639b --- /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 6c309d635..de0960efc 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 000000000..f49cf8a16 --- /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 1418976df..b01ea3543 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