Motion analysis: plots of a study's joint values and a point's path, and the parts that collide along it

- motion.plot: joint values and a point's path sampled as the study plays (closed loops
  following), with velocities and accelerations by finite differences, per step or per
  second with a duration.
- motion.interference: the pairs of parts that pass through each other along a study, with
  the first step, the step ranges, the depth and the shared volume; occurrences, against
  or contact sets choose the pairs; bounded samples and work.
- Motion Study dialog: a Study box opens a saved study; a chart of a joint value or a
  picked point with a cursor at the step shown (click to move there); Check collisions
  with the steps shaded on the chart. ui.start motion.study takes study.

docs/book/src/guide/assemblies.md

@@ -166,6 +166,36 @@ changed. A GIF keeps one palette for all its frames, so colours don't flicker, a
 what changed from one frame to the next. Frames are capped: at most 1000, and a GIF holds at most
 2^26 pixels of frames (about 160 frames of 800 × 500).
 
+**Motion analysis.** The **Motion Study** dialog's **Study** box opens a saved study to edit, and
+by its timeline the dialog charts what the study does.
+**Plot** picks a moving joint value (or **Picked point**, once a point is picked in the dialog's
+**Point** box) and whether to show its value, velocity or acceleration; the chart runs over the
+study's steps with a cursor at the step shown, and a click or a drag on it moves to that step.
+Values are in degrees and millimetres; rates are per step, or per second once **Duration** says
+how many seconds the whole study takes. A picked point charts its distance from where it
+starts, its speed and the size of its acceleration. **Check collisions** plays the study and
+lists the pairs of parts that pass through each other, with the steps where they do (a click on
+one shows the first of them); those steps are shaded on the chart. It checks the parts picked in
+**Components** (against the ones picked in **Against**, when there are any), else every
+component, or the pairs of the design's contact sets (a choice beside the button once it has any).
+
+`motion.plot {study, joints?, occurrence?, point?, samples?, duration?}` answers the same
+numbers: for each joint value its `value`, `velocity` and `acceleration` per sample (with their
+units), and for a point its `position`, `velocity` and `acceleration` vectors, `speed` and
+`acceleration_norm`. The study plays as `motion.play` places it (closed loops follow, contact sets
+stop it), each sample from the one before, on a copy: the design is not changed. Velocities and
+accelerations are finite differences between samples, central inside and one-sided at the ends,
+so they are as smooth as the samples are dense (up to 1000, one per step by default). Angles are
+unwrapped, so a joint that turns on past half a turn keeps counting.
+`motion.interference {study, occurrences?, against?, contact_sets?, samples?}` answers each
+colliding pair with its `first_step`, `last_step`, the `steps` ranges where they overlap, how
+deep (`depth_mm`, the deepest at `deepest_step`) and their shared `volume_mm3` there. It plays
+the study as `motion.play` does, but contact sets don't stop it, and parts are tested at the
+samples only: a part that passes right through another between two samples is missed. A check
+takes at most 256 bodies; on a large design, list the `occurrences` to check (an arm, with
+`against` the parts it must miss). When the work runs out it says `truncated` and the step it
+`checked_to`.
+
 **Insert Design** (`component.insert_design {path, translate?}`, on the **ASSEMBLE** panel and
 in the **File** menu) adds a component linked to another saved design, so each part can live in
 its own document. A STEP or mesh file picked there is inserted as **Insert STEP** or **Insert

docs/control-protocol.md

@@ -125,7 +125,7 @@ labels; `prefs:measure_axis_distances` identifies the checkbox.
 | `ui.set` | any `UiState` field (`tab`, `perspective`, `showGrid`, `dark`, …), and `hiddenBodies`, `hiddenOrigin`, `hiddenSketches`, `shownSketches`, `hiddenJoints` (whole lists; `browser.visibility` changes single items) | `dark: false` switches to the light theme |
 | `ui.view` | `view`: `front`, `back`, `top`, `bottom`, `left`, `right`, `iso`, `home`, `fit`; `animate` (bool, default false: snap) | |
 | `ui.camera` | `target?`: `[x, y, z]` (mm), `yaw?`, `pitch?`, `roll?` (radians), `distance?` (mm), `fov?`, `up?`; `fit?`: `true`, `false` or `[occurrence id or name…]` (`root`: the bodies outside every component) | the viewport's orbit camera: it looks at `target` from `distance` away; `yaw` 0 looks along +Y (from the front), `pitch` is the elevation (±π/2: straight down or up), `roll` turns the image. Fields given are set first (the others keep their values), then `fit` frames the listed occurrences (or everything), keeping the direction. The reply, passed back, sets the same view again, so a framing can be stored and replayed. `fov` and `up` follow the perspective setting (`ui.set`) and the up axis preference (`ui.prefs`) and can't change here; a refused field changes nothing |
-| `ui.start` | `command`, `params?` | like a toolbar click: starts the sketch tool or dialog for the command. `params` sets what the dialog opens on, and nothing runs until OK: `joint.drive` takes `joint` (id or name; without it, the joint picked in the browser, else the first joint that moves) and `values` (numbers in degrees or millimetres, or expressions). A command that takes no params is refused before it starts; a param the dialog doesn't take is refused and the dialog closes |
+| `ui.start` | `command`, `params?` | like a toolbar click: starts the sketch tool or dialog for the command. `params` sets what the dialog opens on, and nothing runs until OK: `joint.drive` takes `joint` (id or name; without it, the joint picked in the browser, else the first joint that moves) and `values` (numbers in degrees or millimetres, or expressions); `motion.study` takes `study` (id or name), which opens that study to edit and chart. A command that takes no params is refused before it starts; a param the dialog doesn't take is refused and the dialog closes |
 | `ui.click` | `x`, `y` (screen points), `button?`: left/right/middle, `shift?`, `ctrl?`, `double?` | real pointer input |
 | `ui.move` | `x`, `y`, `shift?`, `alt?`, `ctrl?`, `cmd?` | pointer movement without a button; modifiers apply until the next synthetic move/click; a move with omitted modifiers releases them. With `nav: "touchpad"`, Shift pans and Alt/Option orbits. |
 | `ui.drag` | `x0`, `y0`, `x1`, `y1`, `button?`, `shift?`, `ctrl?`, `steps?`, `hold?`, `hold_end?` | press, move, release; a left drag on the model is a box selection (left to right: window, right to left: crossing); with OpenSCAD navigation, plain left-drag on empty space orbits, Shift+left-drag box-selects, and drags starting on sketch geometry edit it; `hold` keeps the button down that many frames first (a right press-and-hold opens the marking menu, releasing over a direction picks it), `hold_end` that many frames at the end (a sketch drag shows its snap) |