MĒCHANĒ (μηχανή) — Mathematical Mechanism Designer

A self-hosted web workbench for designing, simulating, validating and exporting mechanical mechanisms from their mathematics: involute, cycloidal and noncircular gears, planetary sets, cycloidal speed reducers, linkages, Geneva drives and cams — with inverse design (gear-ratio search, four-bar path synthesis, cams from drawn motion, variable-ratio gears from a drawn ratio) and 3D-print-oriented export.

Planetary gear set (sun 18, planets 18, ring 54, ring held: 4 : 1). Open it directly with /?preset=planetary.

Mathematical correctness comes before visual plausibility. Every mechanism is built from one shared model, solved by one planar kinematic solver, checked on its actual geometry, and reported honestly when it does not work.

Quick start

docker compose up --build

Open http://localhost:8000. A Classical Spur Pair is loaded and animating.

Options (environment variables for docker compose):

Variable	Default	Meaning
MECHANE_PORT	8000	host port
MECHANE_BIND	127.0.0.1	host interface (0.0.0.0 exposes it — there is no authentication)
MECHANE_BASE_PATH	/	serve under a path prefix behind a reverse proxy, e.g. /mechane
MECHANE_WORKERS	2	server worker processes
MECHANE_PUBLIC_URL, MECHANE_SMTP_*	—	accounts: public URL for confirmation links; mail relay (without it, links go to the log) — see docs/deployment.md
MECHANE_GIT_COMMIT	unknown	recorded in provenance records (MECHANE_GIT_COMMIT=$(git rev-parse --short HEAD) docker compose up --build)

Accounts, projects and printer profiles persist in the mechane-data volume (/data). Production (k3s + Argo CD, https://works.baumann.gr/mechane/) is built by the Forgejo workflow in .forgejo/workflows/ and deployed from the GitOps repository websites-config/mechane — see docs/deployment.md. No cloud services are used. See docs/deployment.md.

What is implemented

Area	Status
Shared model: parts, joints (revolute, prismatic, pin-in-slot, distance, fixed), couplings (linear, functional), drivers, assemblies, manufacturing definitions	✔
Planar kinematic solver: Newton–Raphson on F(q,u)=0, predictor–corrector continuation, DOF/redundancy from Jacobian rank, singularity, unreachable and discontinuity detection	✔
Involute spur gears by simulated rack generation (exact involute, trochoidal root fillet, undercut, profile shift, backlash by tooth thinning)	✔
External pairs: spur, helical (true involute helicoid), herringbone (with optional relief gap)	✔
Internal pairs, rack & pinion, planetary sets (any fixed member, Willis checked), compound trains	✔
Cycloidal (epi/hypocycloid) gear pairs	✔
Cycloidal speed reducer: exact envelope profile (any tooth-count difference), eccentric input, output-pin coupling by distance joints, single or dual disc, bearing seats, adaptive clearance/backlash validation, assembly guide	✔
Noncircular gears: elliptical, multi-lobed, Fourier, synthesised from a drawn ratio g(φ) — teeth generated by the same rack rolling on the pitch curves	✔
Four-bar (Grashof, both branches, coupler curves, transmission angle), slider-crank, Scotch yoke, Peaucellier–Lipkin, Jansen leg	✔
Geneva mechanism (n slots, locking disc, clearance)	✔
Disc cams (knife-edge/roller, offset) from motion laws or a drawn curve, verified on the generated polygon	✔
Tooth-contact validation (overlap and measured backlash at many positions), collision sweep sampled across the whole motion cycle (≤ 120 frames)	✔
Inverse design: exact/approximate gear-ratio search, four-bar path synthesis (SciPy), cam and noncircular synthesis	✔
Export: binary STL, 3MF, OBJ, SVG, DXF (R12), project JSON, provenance Markdown, ZIP package with build-plate layout; all STLs re-imported and refused unless watertight with one body per part and matching volume/extent; DXF read back; 3MF/OBJ written from the same validated solids (not re-imported)	✔
Optional ground plate: outline from the swept footprint, axle holes at every ground pivot (sized from bores, own fit), mounting holes clear of moving parts	✔
Accounts as in MATHĒMA: email-confirmed registration, signed-cookie sessions, per-account projects and printer profiles; rest of the app usable without login	✔
31 presets (30 available, 1 planned), seeded random mutation gallery, versioned projects with migration, undo/redo	✔
STEP export, pantograph (2-DOF), spatial mechanisms, dynamics/strength	✘ not implemented

Development

python3 -m venv .venv && .venv/bin/pip install -r backend/requirements-dev.txt
cd backend && ../.venv/bin/python -m pytest          # ~240 tests
cd frontend && npm install && npm test && npm run build
# run: backend on :8000 serving the built frontend
cd backend && MECHANE_STATIC_DIR=../frontend/dist ../.venv/bin/python -m mechane
# or frontend dev server with API proxy: cd frontend && npm run dev

Docker test stages: docker build --target test . (backend) and docker build --target frontend-test ..

Documentation

• User guide
• Architecture · Adding a mechanism family
• Mathematics overview · Gears · Cycloidal reducer · Linkages · Cams
• Kinematics & solver · Inverse design
• Manufacturing & export · Deployment

Honest limitations

• Kinematics are planar. Helical teeth are exact helicoids in geometry, but their axial effects (thrust, overlap contact) are not simulated.
• Verification is geometric/kinematic: no loads, stresses, friction, wear or print-accuracy guarantees. Fits and compensation are starting values.
• Collision checks sample the cycle (120 frames; tooth meshes 10–48 positions per period). Very thin transient interferences between samples can be missed.
• Meshes are exact prisms of exact polygons (polyline-discretised curves); no B-rep/STEP output.