cadSet/text-to-cad/models/robots/lyra/README.md

lyra — dexterous humanoid hand concept

An aesthetically refined five-digit robotic RIGHT hand for an advanced bipedal robot: slim pearl-composite shell tubes over an exposed graphite structural spine, machined-aluminum precision knuckle clevises with visible pivot pins and rim washers, tendon-driven architecture (dorsal tendon channel grooves fanning to each knuckle plus a five-dial tensioner row at the wrist), integrated tactile sensing (2x2 palm pad array, per-phalanx soft-touch strips, palmar fingertip caps, amber-ringed palm sensor), and a 6-bolt wrist flange. Graceful human-like proportions (~198 mm flange to middle fingertip), clean industrial design, no logos.

Degrees of freedom (16)

Group	Joints	DOF
Each finger (x4)	MCP, PIP, DIP flexion (about -X)	12
Thumb	CMC yaw (opposition swing about +Z), CMC flex, MP, IP (about -Y)	4

MCP abduction/spread is intentionally omitted (documented tendon-budget trade in lyra_parts/chain.py). Named poses are capsule-tuned to small positive clearances (lyra_parts/clearance.py): precision_pinch and ok_sign kiss the thumb-index pads at ~0.7-0.8 mm surface clearance, tripod_pinch chuck-grips a virtual ~12 mm object, and the fist thumb rests on the index middle phalanx — no pose or animation blend interpenetrates.

Files

• lyra.py — build123d generator (gen_step()); authoritative source. Joints are authored as cadpy.assembly.AssemblyHelper revolute frames driven by the baked relaxed pose. Also exposes gen_urdf() / gen_srdf() for the robot description.
• lyra_parts/ — part-builder package. chain.py is the shared kinematic chain/pose/limit spec (stdlib-only FK included) used by the CAD assembly, the URDF/SRDF generators, and the animation sidecar; lib.py holds the palette and the verified revolute_attach() joint math; palm.py / digits.py build the parts; description.py emits the URDF/SRDF XML; mass_props.py holds baked CAD volume/COM/inertia/bbox data; clearance.py is the stdlib capsule-collision self-check (run python -m lyra_parts.clearance from this directory after editing poses or animation key orders — it sweeps every named pose and every sidecar blend path).
• lyra.step — generated STEP assembly (derived artifact), baked in the relaxed pose. Occurrence refs #o1.1..#o1.17 follow the asm.add order in lyra.py (palm, then index/middle/ring/pinky proximal/middle/distal, then thumb base/metacarpal/proximal/distal).
• .lyra.step.js — CAD Viewer animation sidecar driving per-frame chain FK deltas against the baked pose. Animations: poseTour (a finger-ripple wave, then relaxed -> precision pinch -> OK sign -> point -> tripod pinch -> fist; key order chosen so every blend is collision-free), graspLoop (power grasp), pinchLoop (pinch with pad double-tap), rippleLoop (traveling finger curl wave with overlapping per-digit pulses), countLoop (count to five from a fist; the thumb lifts to a hover before any finger extends). Controls: phase, mode, pose (named SRDF pose hold), grip.
• lyra.urdf — generated URDF (derived artifact): a frame-only wrist_mount root plus 17 physical links and 16 revolute joints, per-link 3MF mesh visuals, bbox collisions, CAD-derived inertials at an assumed 0.62 kg total mass.
• lyra.srdf — generated MoveIt2 SRDF (derived artifact): per-digit joint groups, fingers/hand unions, a palm-mounted hand_eef end effector, disabled collisions, and hand group states (zero, relaxed, fist, precision_pinch, tripod_pinch, point, ok_sign).
• STEP/ — per-link wrapper sources (gen_step() per link) and their generated STEP parts; 3MF/ — per-link mm mesh sidecars referenced by the URDF.

Conventions

Units mm. RIGHT hand: the wrist-flange mount face center is the origin, +Z distal (fingers up), +Y palmar, +X radial (thumb side). Every link frame sits at its joint center with axes parallel to the palm at zero angles (URDF joints are pure translations). Positive joint angles flex/curl. Regenerate with the CAD skill: python scripts/step models/robots/lyra/lyra.py. Regenerate link meshes per link with the CAD skill, e.g. python scripts/step models/robots/lyra/STEP/<link>.py --3mf ../3MF/<link>.3mf. Regenerate the robot description with the URDF/SRDF skills: python scripts/urdf models/robots/lyra/lyra.py=models/robots/lyra/lyra.urdf and python scripts/srdf models/robots/lyra/lyra.py=models/robots/lyra/lyra.srdf.