SpiderCam

A from-scratch Python implementation of a SpiderCam / cable-driven parallel robot (CDPR) "computations" project. It ships a normal kinematics + statics core first, then layers on advanced physics, an AI director, and a WebGPU digital twin.

Features

This is a rebuild that adds advanced capabilities on top of a clean core:

1. AI directing & cinematography — aesthetic framing (rule of thirds, headroom, lead room), RL trajectory prediction for fast subjects, prompt-to-trajectory via LLMs, and emotion/action-driven subject tracking.
2. Advanced physics & kinematics — Irvine catenary sag + elasticity compensation, optimal (QP) tension distribution, and Singer–Seering input shaping for anti-sway / vibration damping.
3. Digital twin & visual simulation — a Three.js + WebGPU real-time twin, synthetic training-data export, and AR overlay hooks.
4. Modern architecture & interaction — modular-monolith services behind clean seams (gRPC/WebSocket-ready bus), a hardware abstraction layer, and dynamic collision avoidance. A spatial/gesture input path drives the camera.

Adopted conventions (not invented): the YAML rig schema and frame/platform split follow oKermorgant's ROS CDPR; the kinematics math and naming (structure_matrix, force_distribution, pose) follow cdpyr (Philipp Tempel, TU Delft); the hardware-facing API follows SpiderRobot (EMS-TU-Ilmenau); the analysis-vs-simulation split follows CASPR.

Quick start

uv sync --extra dev          # or: pip install -e ".[dev]"
pytest                       # run the test suite
python examples/01_ik_fk.py  # load a rig and solve IK / FK

Load a robot and solve inverse kinematics:

from spidercam import load_robot, Pose

robot = load_robot("configs/default_robot.yaml")
pose = Pose.from_xyz_rpy([0.0, 0.0, 2.0], [0.0, 0.0, 0.0])
# ... see spidercam.kinematics.inverse / forward

Project layout

src/spidercam/      computations, AI director, twin, control, HAL, bus
configs/            YAML rig definitions
examples/           numbered, runnable demos (one per feature)
tests/              pytest regression tests
web/                three.js + WebGPU viewer for the digital twin

Status

Phased build. See the module docstrings and the per-phase examples in examples/ for what currently runs. Heavier AI/RL dependencies are optional extras (pip install spidercam[ai]) so the core stays light.

License

MIT.