# Cam & Encoder Designer

Design **radial (disk) cams**, **barrel (cylindrical) cams**, and **optical
encoder discs** (incremental & absolute) — with live SVAJ analysis, design-rule
checks, manufacturing exports (CSV/DXF), and one-click **solid model
generation in FreeCAD**.

Python 3 + tkinter + matplotlib. No cloud, no license keys. MIT.

![Radial cam tab — profile, pressure angle, displacement and animation](docs/ui_radial.png)

## Highlights

- **Motion program editor** — compose the 360° cycle from Dwell / Rise /
  Return segments using 8 standard motion laws (cycloidal, simple harmonic,
  modified trapezoidal, modified sine, 3-4-5 & 4-5-6-7 polynomials,
  parabolic, uniform). Peak-acceleration coefficients validated against
  Rothbart's *Cam Design Handbook*. One-click example programs.
- **SVAJ diagrams** — displacement, velocity, acceleration and jerk vs cam
  angle, scaled to real units (mm/s…) by the cam speed.
- **Radial cams** — profile synthesis by inversion for translating roller
  (offset, CW/CCW) or flat-faced followers, with a live **animation** of the
  rotating cam driving its follower.
- **Barrel cams** — unwrapped groove development, groove-edge geometry, and
  a 3D preview.
- **Encoder discs** — incremental (PPR, duty, index/Z track, quadrature
  readout info) and absolute (1–12 bit **Gray** or binary code tracks).
- **Design-rule checks** — pressure angle vs the 30° guideline, undercutting
  (radius of curvature vs roller), flat-follower cusp condition, encoder
  window manufacturability. Every warning links to a fix in the built-in guide.
- **Built-in user guide** — press **F1** (or any ❓ Help button): seven
  chapters explain every option, every motion law, and every warning.
  Hover any field for a tooltip.
- **Exports** — CSV motion tables, DXF R12 (cam profile, groove development,
  encoder mask for laser cutting), and FreeCAD solids via the bundled
  workbench.

## Screenshots

| SVAJ diagrams | Barrel cam development |
| --- | --- |
| ![SVAJ diagrams tab](docs/ui_svaj.png) | ![Barrel cam tab](docs/ui_barrel.png) |

| Encoder designer | Built-in user guide |
| --- | --- |
| ![Encoder tab](docs/ui_encoder.png) | ![Help window](docs/ui_help.png) |

Generated solids in FreeCAD:

| Radial + barrel cams | Absolute encoder (8-bit Gray) | Incremental encoder |
| --- | --- | --- |
| ![Cams in FreeCAD](docs/freecad_cams.png) | ![Absolute encoder disc](docs/freecad_encoder.png) | ![Incremental encoder disc](docs/freecad_encoder_incremental.png) |

## Installation

Requires Python 3.10+ (tkinter included in the standard Windows/macOS
installers; on Linux install `python3-tk`).

```bat
git clone https://github.com/Sweetkubuni/cam-encoder-designer.git
cd cam-encoder-designer
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\python cam_designer.py
```

On Windows you can afterwards start it by double-clicking `run.bat`.

## Using the designer

1. **Define the motion** (left panel): add Rise / Dwell / Return segments —
   durations must total 360° and rises must cancel returns. Pick an entry
   from the *Example* drop-down to start from a known-good program.
   Double-click a segment to edit it; the editor describes each motion law.
2. **Check the SVAJ tab** — smooth curves mean smooth running. Set the cam
   speed (rpm) to read peaks in real units.
3. **Enter the cam geometry** — base circle, roller radius, offset and
   follower type for the radial cam; cylinder and roller radius for the
   barrel cam. The **Results** panel shows peak values; the status bar turns
   green (✓ OK) or red (⚠ warnings).
4. **Animate** — on the Radial cam tab, drag the slider or press ▶ Play.
5. **Export** — File menu for CSV/DXF, or **Send to FreeCAD ⚙** for solids.

The **Encoder tab** is a self-contained designer: choose Incremental or
Absolute, set the disc geometry, then export a DXF cutting mask or send the
disc + shaft to FreeCAD.

Stuck? **F1** opens the user guide; the *Warnings explained* chapter lists
every warning with its remedy.

## FreeCAD integration

The bundled workbench (`freecad-workbench/CamDesigner`, tested with
FreeCAD 1.0) turns designs into solids: an extruded radial cam with shaft
bore, a barrel cam with the roller-swept groove cut into the cylinder, and
encoder discs with windows cut through, assembled on a shaft.

1. Run `install_workbench.bat` (copies the workbench to
   `%APPDATA%\FreeCAD\Mod`), restart FreeCAD.
2. With FreeCAD running, click **Send to FreeCAD** in the designer — models
   appear immediately. Without FreeCAD running, the design is saved as JSON
   under `exports\` and can be loaded later via the workbench command
   **Import cam design…**, which also exposes thickness, bore, outer radius
   and groove depth.

### Automation / MCP

The workbench auto-starts a localhost XML-RPC bridge (`127.0.0.1:9875`).
`freecad_mcp_server.py` exposes it as MCP tools — `freecad_ping`,
`generate_cams`, `freecad_exec`, `freecad_objects`, `freecad_screenshot` —
so an AI assistant such as Claude Code can generate and inspect models.
Example MCP configuration:

```json
{
  "mcpServers": {
    "freecad-cam": {
      "type": "stdio",
      "command": "<repo>/.venv/Scripts/python.exe",
      "args": ["<repo>/freecad_mcp_server.py"]
    }
  }
}
```

> **Security note:** the bridge executes Python sent from localhost. It binds
> 127.0.0.1 only; don't run it where other local users shouldn't have that
> access.

## Exports reference

| Export | Where | Contents |
| --- | --- | --- |
| Motion table (CSV) | File menu | θ, s, v, a, j (per rad) + profile coords + pressure angle |
| Radial profile (DXF) | File menu | closed profile + pitch curve (layers `CAM_PROFILE`, `PITCH_CURVE`) |
| Barrel development (DXF) | File menu | groove edges + centreline, unrolled flat |
| Disc mask (DXF) | Encoder tab / File menu | outline, bore, windows (`OUTLINE`, `BORE`, `WINDOWS`) |
| Solids | Send to FreeCAD | Part features in the active FreeCAD document |

## Project layout

```
cam_designer.py                  the designer app (single file)
freecad_mcp_server.py            MCP server bridging Claude <-> FreeCAD
freecad-workbench/CamDesigner/   FreeCAD workbench (builder, bridge, GUI commands)
install_workbench.bat            copies the workbench into FreeCAD's Mod folder
docs/                            README images + generate_images.py
requirements.txt, run.bat
```

## Conventions

Millimetres and degrees throughout. Internally velocity/acceleration/jerk
are per radian of cam rotation (`v = ds/dθ`); plots and readouts also show
time-based values at the entered rpm. Encoder discs: dark = opaque,
white = transparent window; angles CCW from +x; the LSB track is outermost.

## References

- [mechref.org — Cam design](https://www.mechref.org/md/Cams/)
- METU OCW ME 301, ch. 8 (cam motion curves)
- Rothbart, *Cam Design Handbook*, McGraw-Hill 2004
- [Quantum Devices — Incremental encoder basics](https://www.quantumdev.com/resource-library/incremental-encoder-basics/)

## License

MIT — see [LICENSE](LICENSE).