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

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 at line 60. According to the repository's documentation in 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, which demonstrates real-world application of the kinematics system.

Define the kinematics structure:

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:

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

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

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

Alternatively, reference an external JSON file:

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 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, 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."

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}