# Mechanisms

Mechanisms are assemblies whose parts move: linkages that close a loop, gears and belts that couple joints, screws that turn into a slide, and motion studies that play the motion and check it for collisions. Read [Assemblies](assemblies.md) first: everything here is built from its joints.

## Closed loops

A joint between two components the joints already place closes a loop (a four-bar linkage, a slider-crank) and is solved, not only checked: the loop's other axes follow.

- Mark the axis that drives the loop `"driven": true` (`{"rotation":{"position":"30 deg","driven":true}}`); `inspect_assembly` shows the values of the axes it moves with `solvedByLoop`.
- A loop that cannot close at that position is a `JOINT_CONFLICT` on its closing joint: check the link lengths, or the driven position against the loop's range.
- Ball, planar and pin-slot joints are the usual way to leave a loop the freedom it needs (a pin in a slot, a rod end).

## Rigid groups

`group.create` makes components move as one, each where it is now relative to the first, without picking faces: `{"type":"group.create","id":"$g","components":[<component>,<component>]}`. A component is in one group at most. Use it for a weldment or parts that are bolted together and never move apart.

## Relations

Relations couple two joints' axes: drive the first, the second follows, and the second's limits stop the first.

| Type         | Ratio                                                                      |
| ------------ | -------------------------------------------------------------------------- |
| `gear`       | Turns of b per turn of a; b turns the other way.                           |
| `belt`       | Turns of b per turn of a, the same way.                                    |
| `rackPinion` | How far b slides per turn of a, a length: `"pi * 10 mm"` for a Ø10 pinion. |
| `screw`      | How far b slides per turn of a: the screw's lead.                          |

```json
{
  "type": "relation.create",
  "id": "$feed",
  "relation": {
    "type": "screw",
    "a": { "joint": "<lead screw's revolute joint>", "axis": "rotation" },
    "b": { "joint": "<carriage's slider joint>", "axis": "translation" },
    "ratio": "2 mm"
  }
}
```

Side b's own position is where it is while a is at zero. `"reversed": true` turns the direction around.

## Motion studies

A motion study is keyframes of joint values over time. Axes move in straight lines between keyframes and hold outside them; playing a study changes nothing in the assembly.

```json plan:spin-study
{
  "summary": "A study that turns the shaft once in 4 s",
  "steps": [
    {
      "label": "Full turn",
      "commands": [
        {
          "type": "study.create",
          "id": "$spin",
          "study": {
            "name": "Full turn",
            "duration": 4,
            "keyframes": [
              {
                "time": 0,
                "values": [
                  {
                    "joint": "<Shaft on plate.$turn>",
                    "axis": "rotation",
                    "value": "0 deg"
                  }
                ]
              },
              {
                "time": 4,
                "values": [
                  {
                    "joint": "<Shaft on plate.$turn>",
                    "axis": "rotation",
                    "value": "360 deg"
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}
```

Then `check_motion` with the study's id runs it and lists every pair of components that collide, from when to when and how much. It checks every degree or half millimeter of the fastest axis, an axis that turns a lead screw (side a of a screw relation) by half a millimeter of the travel it makes (a 30-turn Tr12x3 screw is 180 poses), or as many `samples` as you ask between `from` and `to` (seconds). A study's `"sampling": "fine"` (`study.update`) checks the screw by the degree too, for a handwheel or a cam on it that could hit something within a turn; when its time runs out it answers `complete: false` with `checkedTo`, so check the rest with `from` or fewer samples. Check the ends of travel and the poses the user cares about with `check_interference` and `positions` too.

The user plays studies and exports them as a video or a GIF.

## Exploded views

An exploded view moves components apart in steps, along an axis of the assembly or a joint's axis, to show how it goes together; showing it changes nothing:

```json
{
  "type": "exploded.create",
  "id": "$x",
  "view": {
    "name": "Service view",
    "trails": true,
    "steps": [
      {
        "components": ["<cover>"],
        "direction": { "axis": "z" },
        "distance": "30 mm"
      },
      {
        "components": ["<shaft>"],
        "direction": { "joint": "<shaft's joint>" },
        "flip": false,
        "distance": "40 mm"
      }
    ]
  }
}
```

## Commands

`group.create`, `group.update`, `group.delete`, `relation.create`, `relation.update`, `relation.delete`, `study.create`, `study.update`, `study.delete`, `exploded.create`, `exploded.update`, `exploded.delete`. Read them with `describe_commands`.