# What Types of Kinematics Does cadgen Support? A Complete Guide to Motion Modeling

> Explore cadgen kinematics: mates, couplings, and poses. This guide explains motion modeling in STEP files using JSON side-car files for comprehensive CAD control.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: deep-dive
- Published: 2026-09-11

---

**The cadgen library supports three distinct kinematics categories—mates, couplings, and poses—defined in a JSON side-car file that accompanies your STEP file.**

The earthtojake/text-to-cad repository provides a powerful CAD generation toolkit where motion modeling is handled through a structured kinematics side-car. Understanding what types of kinematics cadgen supports is essential for creating articulated models with realistic mechanical behavior. The system enforces a strict schema through the `KINEMATICS_KEYS` constant, ensuring every motion definition falls into one of three validated categories.

## Understanding the Kinematics Side-Car Architecture

Cadgen models motion through a **kinematics side-car**, a JSON file placed alongside your STEP file that defines how parts move and interact. The side-car's `kinematics` object is validated against the `KINEMATICS_KEYS` constant defined in [`packages/cadgen/src/cadgen/kinematics.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/kinematics.py) at line 60. According to the repository's documentation in [`skills/cad/references/kinematics.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/references/kinematics.md), this validation ensures the dictionary contains only the three permitted top-level keys: `mates`, `couplings`, and `poses`.

## The Three Types of Kinematics in cadgen

The cadgen library categorizes all motion modeling into three specific types, each serving a distinct mechanical purpose in your CAD assemblies.

### Mates: Defining Movable Connections

**Mates** represent typed joints that define movable connections between parts, such as revolute or prismatic joints. These entries specify axes of rotation, translation limits, and joint types that constrain how components move relative to one another. In the source code, mates are defined as an array of objects containing properties like `name`, `type`, `axis`, and `limits`.

### Couplings: Coordinating Motion Between Joints

**Couplings** establish relationships that synchronize the motion of different mates, enabling coordinated mechanical movement. These definitions link source and target joints through ratios or functional relationships, ensuring that manipulating one joint automatically drives another according to specified mechanical rules.

### Poses: Configuring Absolute Positions

**Poses** provide fixed or configurable position and orientation states for parts or entire assemblies. Unlike mates which define relative motion constraints, poses specify absolute configuration states—such as "default" or "open" positions—by assigning specific values to joint variables.

## Implementing Kinematics in Your CAD Models

To apply these kinematics types in practice, you define a `KINEMATICS` dictionary in your model's Python file and attach it via the `@step` decorator. Concrete usage appears in model source files such as [`models/hypercar/src/hypercar.py`](https://github.com/earthtojake/text-to-cad/blob/main/models/hypercar/src/hypercar.py), which demonstrates real-world application of the kinematics system.

Define the kinematics structure:

```python
KINEMATICS = {
    "mates": [
        {"name": "joint1", "type": "revolute", "axis": [0, 0, 1], "limits": [0, 180]},
        {"name": "joint2", "type": "prismatic", "axis": [1, 0, 0], "limits": [0, 10]},
    ],
    "couplings": [
        {"source": "joint1", "target": "joint2", "ratio": 1.0}
    ],
    "poses": {
        "default": {"joint1": 0, "joint2": 0},
        "open": {"joint1": 90, "joint2": 5}
    }
}

```

Attach to your model using the decorator:

```python
@step(out="../STEP/example.step", kinematics=KINEMATICS)
def build():
    pass

```

For command-line workflows, pass kinematics via the `--kinematics` flag:

```bash
cadgen snapshot models/example.step tmp/out.png --kinematics '{"mates":[...],"couplings":[...],"poses":{...}}'

```

Alternatively, reference an external JSON file:

```bash
cadgen snapshot models/example.step tmp/out.png --kinematics path/to/kinematics.json

```

## Summary

- Cadgen supports exactly three kinematics types: **mates** for joint definitions, **couplings** for motion synchronization, and **poses** for configuration states.
- The `KINEMATICS_KEYS` constant in [`packages/cadgen/src/cadgen/kinematics.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/kinematics.py) enforces this schema at line 60.
- Kinematics are defined via JSON side-cars that accompany STEP files, either embedded in Python source or passed via CLI arguments.
- The `@step` decorator connects kinematics definitions to model generation functions.

## Frequently Asked Questions

### What file format does cadgen use for kinematics definitions?

Cadgen uses JSON format for kinematics side-car files placed alongside STEP models. You can embed these definitions directly in Python dictionaries using the `KINEMATICS` constant or save them as separate `.json` files referenced via the `--kinematics` CLI flag.

### How does cadgen validate kinematics definitions?

According to the source code in [`packages/cadgen/src/cadgen/kinematics.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/kinematics.py), cadgen validates kinematics using the `KINEMATICS_KEYS` constant which restricts the top-level dictionary to only three allowed keys: `mates`, `couplings`, and `poses`. The validator rejects any kinematics objects containing additional or missing required entries.

### Can I define custom kinematics types beyond mates, couplings, and poses?

No, the current implementation restricts kinematics to the three standard types enforced by `KINEMATICS_KEYS`. Attempting to add custom top-level keys to the kinematics dictionary will fail validation. However, within the `mates` array, you can specify various joint types such as revolute or prismatic to model diverse mechanical behaviors.

### What is the difference between mates and poses in cadgen?

**Mates** define the mechanical constraints and degrees of freedom between parts—essentially how components can move relative to each other—while **poses** define specific instantiations of those degrees of freedom. Think of mates as the joint definitions and poses as snapshots of joint values that place the assembly in specific configurations like "open" or "closed."