Kinematics

Kinematics is a JSON-driven CLI app for planar mechanism simulation and animation built around the Python mechanism library.

Instead of writing a new throwaway Python script every time you want to explore a linkage, cam, gear train, slider mechanism, or multiloop assembly, you define the mechanism in an input JSON file and run the app from the command line.

Kinematics interprets the JSON, solves the mechanism, and generates the outputs you actually want:

• mechanism animations
• summary JSON files
• run manifest JSON files
• plots for supported mechanism families
• optional snapshots and exported artifacts

The result is a practical workflow for mechanism exploration that is far more reusable than one-off scripts.

---

Why this app exists

The upstream mechanism library is powerful, but the normal workflow often looks like this:

1. write a custom Python script
2. define joints and vectors manually in code
3. build loop equations by hand
4. run the script
5. repeat the whole process for the next mechanism

That works, but it becomes tedious fast.

Kinematics wraps that workflow in a CLI and a JSON-based input format so that you can focus on defining the mechanism, not rebuilding the same script structure over and over again.

The big idea is simple:

Describe the mechanism in JSON. Let the app do the rest.

---

What this app can already do

This project has already been used to simulate and animate mechanisms such as:

• four-bar linkages
• five-bar linkages
• crank-slider mechanisms
• offset crank-slider mechanisms
• gear-coupled linkage mechanisms
• cam and follower mechanisms
  • roller follower
  • flat follower
• Watt-style six-bar mechanisms
• generic multiloop mechanisms
• engine-style multiloop mechanisms
• quick-return starter configurations

This is not just a single-demo repo. It is already a practical mechanism playground.

---

Project structure

Typical project layout:

kinematics/
    mechanism/
        appearance.json
        __init__.py
        _player.py
        cams.py
        dataframe.py
        gears.py
        mechanism.py
        vectors.py
    in/
    out/
    apis.py
    app.py
    cli.py
    core.py
    io.py
    utils.py
    RUNS_CLI.md

Commands are typically run from the project root with:

python -m cli run --infile in/fourbar.json --pretty

---

The workflow

The Kinematics workflow is intentionally simple:

1. Create a JSON file in in/
2. Define the mechanism in that JSON
3. Run the CLI
4. Inspect the outputs in out/

That is it.

No bespoke sandbox script required for every new idea.

---

Example: defining a four-bar mechanism in JSON

Here is a real example input file:

{
  "topology": "fourbar",
  "title": "Four Bar Linkage Test",
  "angle_unit": "rad",
  "origin": "O",
  "joints": ["O", "A", "B", "C", "D"],
  "joint_settings": {
    "B": {"follow": true},
    "D": {"follow": true}
  },
  "vectors": [
    {"name": "a", "tail": "O", "head": "A", "r": 5},
    {"name": "b", "tail": "O", "head": "C", "r": 8, "theta": 0, "style": "ground"},
    {"name": "c", "tail": "A", "head": "B", "r": 8},
    {"name": "d", "tail": "C", "head": "B", "r": 9},
    {"name": "e", "tail": "A", "head": "D", "r": 4},
    {"name": "f", "tail": "O", "head": "D", "show": false}
  ],
  "input": {
    "pos": {
      "mode": "linspace",
      "start": 0,
      "stop": 18.8495559215,
      "count": 300
    }
  },
  "guess": {
    "pos": [0.8726646259971648, 2.0943951023931953, 5.0, 0.8726646259971648],
    "pos_angle_unit": "rad"
  },
  "coupler_point": {
    "offset_deg": 30
  },
  "animation": {},
  "output": {
    "dir": "out/fourbar",
    "save_animation": true,
    "animation_file": "mechanism.gif"
  }
}

Then run:

python -m cli run   --infile in/fourbar.json   --pretty   --progress

That one JSON file is enough to define:

• the topology
• the joints
• the vectors
• the grounded member
• the driver sweep
• the initial guess
• the coupler point settings
• the output directory
• the animation export

That is the whole point of the app.

---

Why JSON is the right abstraction

The app is designed around the idea that mechanism definition should be data, not throwaway code.

With JSON, you can:

• keep mechanism inputs version-controlled
• compare two mechanisms easily
• reuse a solved input later
• build a growing in/ library of validated examples
• automate runs from the CLI
• avoid copying and editing ad hoc Python scripts

Instead of asking:

“Which script do I need to write for this mechanism?”

you ask:

“How do I describe this mechanism in JSON?”

That is a much better long-term workflow.

---

Supported topology styles

Current examples and runners cover a broad set of mechanism styles:

Linkages

• fourbar
• fivebar
• crank_slider
• offset_crank_slider

Gears

• gear_pair

Cams

• cam
  • roller follower
  • flat follower
  • multiple motion kinds supported through the cam runner

Multiloop and advanced cases

• sixbar
• watt_sixbar
• stephenson_sixbar
• engine-style multiloop mechanisms
• starter quick-return style configurations

The generic multiloop support is especially important because it pushes the app beyond canned textbook demos.

---

Outputs

Depending on topology and configuration, a run can generate:

• animated GIFs
• MP4 videos when FFmpeg is installed
• summary.json
• run_manifest.json
• mechanism snapshots
• cam profile plots
• displacement plots
• SVAJ plots
• follower plots
• optional geometry exports

Typical output folders look like this:

out/
    cam_flat_follower/
    cam_mechanism/
    cam_mechanism_multi/
    crank_slider/
    crunode_coupler/
    engine/
    fivebar/
    fourbar/
    quick_return/
    watt_sixbar_fullrev/

---

Typical CLI usage

Run a case:

python -m cli run --infile in/fourbar.json --pretty

Show progress for longer solves or animation exports:

python -m cli run --infile in/fourbar.json --pretty --progress

Skip animation if you only want summary outputs:

python -m cli run --infile in/fourbar.json --pretty --skip-animation

Choose the project root explicitly if needed:

python -m cli run --infile in/fourbar.json --root . --pretty

---

MP4 export note

GIF export works out of the box in many environments.

For MP4 export, install FFmpeg on your system so matplotlib can use a video writer backend.

On macOS with Homebrew:

brew install ffmpeg

Then verify:

ffmpeg -version

---

Example mechanism ideas already tested

The app has already been pushed through a practical set of examples, including:

• a standard four-bar with coupler trace
• a five-bar linkage
• a crank-slider mechanism
• a gear-based four-bar representation
• roller-follower cam examples
• flat-follower cam examples
• multi-motion cam runs
• Watt-style six-bar linkage
• engine-style multiloop example
• quick-return starter configuration

That matters because it shows the architecture is not just theoretical. It is already doing real work.

---

Architecture philosophy

Kinematics does not replace the upstream mechanism library.
It wraps it.

The wrapper layer is what makes the project useful in day-to-day exploration:

• cli.py gives a consistent command-line interface
• core.py orchestrates runs
• app.py provides the app entry layer
• apis.py contains the topology runners and solving logic
• io.py handles file I/O
• utils.py holds reusable helpers

This keeps the original library intact while adding a much better user workflow on top.

---

What makes this repo interesting

A lot of engineering repos stop at “here is a script.”

This repo is more useful than that.

It is trying to become a reusable kinematics tool where:

• the input is declarative
• the run path is standardized
• the outputs are reproducible
• the mechanism definition lives in JSON instead of scattered scripts

That makes it easier to scale from one mechanism to many.

---

Current status

This project is already functional and useful, but still evolving.

Areas that can continue improving:

• schema consistency across all topology families
• more polished validation and error reporting
• richer quick-return and sliding-joint support
• broader example coverage
• cleaner documentation of JSON schemas
• GUI development on top of the CLI core
• additional export options

The important part is that the core idea already works.

---

In one sentence

Kinematics turns planar mechanism simulation into a JSON-first workflow, so you can define a mechanism once, run it from the CLI, and get the animation and outputs you need without writing a throwaway Python script every time.