Cycloidal Studio

Design, optimize, and export cycloidal-drive tooth profiles — right in your browser.

License: MIT No build step Deps: zero for the web tools

中文说明 → README.zh.md

Cycloidal drives (the reducers inside RV gearboxes and robot joints) live or die by their tooth-profile modification — a few microns of relief that decide backlash, stiffness, smoothness, and whether the thing even meshes after you account for machining tolerance. This project makes that design loop interactive: a zero-build web tool (ES modules, no bundler) with a built-in multi-objective optimizer, plus a Python pipeline that reproduces the literature benchmarks.

The web tool is pure HTML/JS/Canvas — no build, no dependencies, no server. Open the file, or deploy to GitHub Pages in two clicks.

Shape Designer

• Live demo: https://shkinsem.github.io/cycloidal-studio/ — no install, runs in the browser.
• Locally: clone the repo and open index.html in any modern browser.

Tune one tooth and watch the whole drive respond, live:

• Editable geometry & spec: pin-circle Rb, pin radius Rr, eccentricity E, lobe count N, rated torque.
• A manufacturing plan instead of abstract tolerances: pick how each part is made — disk profile (grinding / wire EDM / milling / printing), pins, pin holes, eccentric — and the tool converts each process into a ±μm error source (editable if you know your shop better). Eccentricity error is weighted by a finite-differenced gap sensitivity, not assumed 1:1.
• As-built prediction: a 400-sample Monte-Carlo over those error sources gives the backlash of the units you'd actually machine (typical–95th percentile) plus the jam risk — this number moves when you change the plan, unlike the zero-error ideal backlash.
• Error budget: each source's worst-case backlash contribution, ranked, with a "tighten this first" hint — so you know which drawing callout actually buys you arcminutes.
• Modification δ(θ) = offset + Σk ck·cos(kNθ) (4 harmonics) with drag sliders and presets.
• Goal-driven optimizer: a built-in NSGA-II (Web Worker, no Python) searches modifications for your geometry and plan, auto-loads the best design, and gives a verdict judged on as-built backlash: guaranteed at worst case, met at 95% yield, or unreachable — with a self-calibrated "shrink total error to ±X μm, start with Y" advisory.
• Animated mesh: the eccentric disk actually runs; loaded teeth glow.
• One-click SolidWorks export: copy the equation-driven X(t) / Y(t) (numbers baked in) or download a point-cloud CSV.
• EN / 中文 toggle throughout.

Everything the RV-reducer literature reports, from one model:

The web tool needs no Python. The optimizer/ pipeline exists to verify the physics against the literature and to produce reference fronts at higher resolution (its knee designs are the web tool's presets):

pip install -r requirements.txt
cd optimizer
python test_model.py # sanity checks (fast)
python benchmark.py # reproduce the literature trends (5/5)
python optimize.py # NSGA-II → results/pareto_front.csv (+ plot, SolidWorks export)
python model.py # analysis figures for one design → results/

optimize.py runs a real NSGA-II (via pygad, no exotic deps) over a 4-harmonic profile δ(θ)=offset+Σk ck·cos(kNθ), four objectives (backlash, stiffness, ripple, pressure angle) under hard constraints (robust margin ≥ 0.5′, manufacturable, removes material everywhere). A quick smoke run: QUICK=1 python optimize.py.

A literature review (see the notes in git history) found that "using a neural network to learn the optimal profile" is mostly a myth in this field: published ML is almost entirely surrogate models that just accelerate FEA inside a classical GA/NSGA-II. The design-freedom win comes from a richer geometric parameterization, not a neural net. This project takes exactly that route — richer harmonics + NSGA-II + manufacturing-error robustness — and benchmark.py reproduces the field's qualitative results 5/5:

1. Modification relieves peak pressure angle (unmodified ≈ 85° → ≈ 55°).
2. "Reverse-bow" modification beats a pure offset on stiffness and load sharing.
3. Loaded-tooth count rises with torque (elastic load spreading).
4. Backlash and tolerance margin trade off monotonically.
5. Machining error erodes margin — a nominal-optimal design can jam where a robust one holds.

Physics is quasi-static, rigid-disk, linearized contact — trends are faithful; absolute values are order-of-magnitude. For paper-grade absolute numbers the next step is loaded-tooth-contact / FEA.

The site is static, so deployment is trivial. Either way:

A. Automatic (included workflow). Push to main; the workflow in .github/workflows/pages.yml publishes the site. Enable it once: Settings → Pages → Build and deployment → Source: GitHub Actions.

B. Zero-config. Settings → Pages → Deploy from a branch → main / root.

Your site appears at https://<your-username>.github.io/<repo>/.

index.html # the tool: designer + live robust optimizer (open this)
pareto.html # legacy URL — redirects to index.html
optimizer/
 model.py # physics core: mesh, backlash, stiffness, ripple, margin (verified)
 objectives.py # K-harmonic profile + pressure angle / manufacturability / robustness
 optimize.py # NSGA-II multi-objective → Pareto front
 benchmark.py # reproduces the literature trends (5/5)
 test_model.py # unit checks
 results/ # pareto_front.csv (committed reference front; figures/txt are regenerable, gitignored)
assets/ # screenshot used in this README
cad/ # reference SolidWorks part
requirements.txt # numpy, matplotlib, pygad (only for the optimizer)

Issues and PRs welcome — this is meant to be hacked on. Good first directions: higher-fidelity loaded-tooth-contact physics, a spline/NURBS parameterization option, exporting to other CAD formats, or per-harmonic machining-error models beyond the uniform worst case.

MIT — see LICENSE. Built for the RoboMaster community and cycloidal-drive tinkerers.