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.
This commit is contained in:
@@ -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 |
|
||||
@@ -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"}}
|
||||
]}
|
||||
@@ -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"}}
|
||||
]}
|
||||
@@ -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"}}
|
||||
]}
|
||||
@@ -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"}}
|
||||
]}
|
||||
@@ -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"}}
|
||||
]}
|
||||
@@ -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"}}
|
||||
]}
|
||||
@@ -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"}}
|
||||
]}
|
||||
@@ -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)
|
||||
|
||||
@@ -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`.
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user