In Progress: STAR Collision Detection on iSWAP, Channels, and 96 Channel in 3D Visualizer

[stefangolas]

STAR: Collision Detection on iSWAP, Channels, and 96 Channel

The iSWAP's plate and lid moves are planned from where resources actually are (iswap_transport.py), and every plan is judged for what it would hit before anything runs (iswap_collisions.py). A command results in swept paths for every component that moves - not just the one planned for: the iSWAP's parts and what it holds, the X-arm's body, and everything mounted on it that the plan does not drive (the channels, the 96-head), which ride the carriage the plan moves. A gripper swinging under lowered channels is caught the same way a plate carried into a rack is. The same judgement covers the pipette and head commands themselves (star_collisions.py): a channel's or the head's move in Y and Z is swept against what stands around the arm and against the other riders, so an iSWAP left out - or anything else in the way - is caught as geometry, not only by the discrete gates. And with a viewer's opt-in flag on, the same checks become a gate on the driver: a command that would hit something never reaches the device.

Layering (separation of concerns)

• pylabrobot/resources/collision.py - generic, machine-agnostic: box semantics over the resource tree (solid / frame / enclosure, by how a resource holds its children), convex pieces, swept segments, GJK distance, a bounding-volume broadphase. Declared hulls (.collision.json per model) refine a resource's pieces where shipped; without one, a resource is its box. Groups may ride a shared moving frame - the engine composes the frame against what stands still and eliminates it exactly between groups on the same frame, so relative checks of parts that share a drive stay tight. A reported sweep is then walked finely (about 1 mm / 1° steps, capped), so what it reports carries the plan time of first contact (Collision.when) and the pose the group stood in then (Collision.at); where a group is at a plan time is one definition, Group.pose_at.

• hamilton/star/driver/features/star_collisions.py - what the arm's checks share: the kept scene of what stands still, the exemptions policy, and the groups of everything mounted on the X-arm; and the pipette and head command checks built on them. Channels commanded by the same amount move as one rigid row and are let off each other; otherwise the command is what moves the riders relative to each other, so they are judged against each other.

• hamilton/star/driver/features/iswap_transport.py / iswap_collisions.py - the iSWAP's own kinematics and judgement, beside iswap.py, building on star_collisions.py. The planner plans; the collision module judges; the sweep is uniform and the pairwise policy is explicit: parts of one machine are let off each other, as is anything mounted together on the carriage, and what a plan means to touch (what is picked up, what it stands on, what it is put down on) is never reported.

The raise gate (opt-in)

Viewer3D(..., raise_on_collision=True) is the switch, and attach_viewer_collisions(driver, viewer, transport) (in motion.py, beside attach_viewer_motion) is the wiring: STARDriver.send_command hands every non-read command to the driver's collision_listener before it is sent (before locks; reads exempt). The listener decodes the channels' C0 JY/C0 JZ (tenths), a channel's P<n> ZA (drive increments), and the head's YA/ZA; runs the checks of star_collisions.py; and on a hit draws via viewer.show_collisions(...) and raises CollisionError(origin, collisions), where the origin names the command - "channel 0's Z move (P1 ZA)". A command that would hit something never reaches the device. With the flag off, the listener is a no-op and behaviour is exactly as before; R0 commands are never judged.

The iSWAP's plans are judged where they are made: the transport draws (collision_reporter slot) what a refused plan would hit, before its existing iSWAPCollisionError.

The viewer broadcasts what a gate caught as a collisions event ({"event": "collisions", ...}, one entry per collided-with resource with its group and index); the page draws red transparent boxes over those resources at the first-contact instant (static/collisions.js). The README's message table says so.

Files this PR adds, and what each is for

File	Purpose
pylabrobot/resources/collision.py	The engine, machine-agnostic: box semantics over the resource tree (solid / frame / enclosure, by how a resource holds its children), convex pieces, swept segments over shared time, GJK distance, a bounding-volume broadphase, declared hulls per model, and the fine walk that reports where and when a meeting happened.
pylabrobot/resources/collision_tests.py	The engine's battery: solids, frames, sweeps, GJK, broadphase scale, two movers over shared time, the fine walk's instants and poses, and declared shapes.
pylabrobot/hamilton/star/driver/features/iswap_transport.py	The iSWAP's plate and lid moves planned from the resources: every reach ranked from the model, the primitive steps of a pick-up, put-down, lid lift and lid seat, and what is held handed to the gripper as the jaws close.
pylabrobot/hamilton/star/driver/features/iswap_transport_tests.py	The planner's battery: reaches and their ranking, refused plans before anything moves, the joints where they started.
pylabrobot/hamilton/star/driver/features/iswap_collisions.py	The iSWAP's judgement: a plan's sweeps as groups of everything that moves, judged before the first step, with the exemptions policy explicit - parts of one machine, riders of one carriage, and what the plan means to touch are never reported.
pylabrobot/hamilton/star/driver/features/iswap_collisions_tests.py	The judgement's battery, true positives included: lowered channels refuse a plan against their own group, and clearing the arm lets the same plan run.
pylabrobot/hamilton/star/driver/features/star_collisions.py	What the arm's checks share - the kept scene of what stands still, the exemptions, the groups of everything mounted on the X-arm - and the pipette and head command checks built on them.
pylabrobot/hamilton/star/driver/features/star_collisions_tests.py	The command checks' battery: a row of channels caught when lowered and clear when raised, channels judged against each other, the head at the tip racks, carried tips against a lidded plate's lid, and the gate refusing a butted carrier.
pylabrobot/visualizer3D/static/collisions.js	The page's side of the collisions event: red transparent boxes over the collided-with resources at the first-contact instant.
pylabrobot/visualizer3D/collision_demo.py	The demo: a tip carrier flush against the source carrier, a clean pick-up judged first, then an over-wide Open driven to the fine-walked meeting instant and frozen with the boxes drawn.
pylabrobot/visualizer3D/transport_demo.py	The iSWAP moving a lidded plate between sites and working its lid, planned from the resources and played on the page.
pylabrobot/hamilton/star/resource_model/*.collision.json (5)	Fitted hulls for the iSWAP's link, gripper body, fingers and pads, and the X-arm's dual rails - what the planner's own body is, beyond boxes.
pylabrobot/resources/hamilton/resource_model/hamilton_tip_carrier_L5.collision.json	The tip carrier's declared shape: 31 hulls, the five pockets hollow, so a seated rack never phantom-hits its own carrier.

Files this PR touches, and why

• hamilton/star/driver/master.py - send_command hands every non-read command to the driver's optional collision_listener before it is sent, before locks; reads exempt. Inert when unset.
• hamilton/star/driver/features/head.py - get_reference_point_location(): a reported head position converted back into a location, the inverse of the record method, for the head's own check.
• hamilton/star/motion.py - attach_viewer_collisions(driver, viewer, transport): the gate's wiring, beside attach_viewer_motion.
• visualizer3D/server.py - raise_on_collision, show_collisions(collisions, groups=None), and the collisions event broadcast.
• visualizer3D/static/transport.js - the collisions message dispatch.
• visualizer3D/static/app.js - what the page does with them: hand the boxes to collisions.js.
• visualizer3D/static/constants.js - the COLLISION box style.
• visualizer3D/README.md - the message table's collisions row.
• visualizer3D/server_tests.py - ShowCollisionsTests: the event's payload and who it reaches.
• visualizer3D/demo.py - the deck keeps a track of clearance, so the demo's grip envelope is chosen, not stumbled into; the mfx carrier, whose tall holders block the same way, is off the deck.
• visualizer3D/browser_tests.py - the page-settle checks what the scene names, not a deck's old size.

Demo

python -m pylabrobot.visualizer3D.collision_demo - the tip carrier stands flush against the source carrier, as a packed deck puts them. A clean long-way pick-up of source_1 is judged first (it passes); an Open to jaw_range[1] (133.7 mm) then meets the carrier's wall part way, and the run is driven to the fine-walked meeting instant and frozen there, with the boxes drawn on what would have been hit.

Behaviour changes

None on live firmware unless a viewer with raise_on_collision=True is attached - and none in the drive path when it is not. With the flag on, the gate stands between the driver and the device: a command that sweeps into something raises CollisionError and is not sent. The pipette and head checks remain available as a library for anything that wants to report without raising. Simulator only: the simulated iSWAP answers the force-window grip close (C0 GC) by stopping the jaws at the commanded width, so the model's grip is the planned grip. One change in the model's geometry: a lid seated on a plate (or any itemized resource) is now among the solid pieces - the engine looked only at what sat in the items, never at what sat on them.

Tests

• The engine's battery: solids and frames, swept hulls, GJK, broadphase scale (a sweep among 4,000+ pieces visits a handful), two movers over shared time; a lid seated on a plate is solid with it, above the plate's own box; and the fine walk: what it reports, the instant and pose it reports them at, and the guarded ends of a pairwise timeline.

• The planner: every reach ranked from the model, plans refused before anything moves, the joints where they started.

• The checker: the sweeps end where the model puts the parts; a second check builds no new scene, said in what it constructs rather than in seconds, which no two machines agree on; and true positives - channels lowered into the iSWAP's way refuse its plan (reported against the channels' own group), and clearing the arm lets the same plan run.

• The pipette and head checks: the row of channels moved across the deck is caught when lowered and clear when raised; a channel moved across its neighbours is caught pairwise; a head swept across the deck at working height runs into the tip racks and the tips standing in them, and the same move above them is clear; tips carried on a channel meet a lidded plate's lid where the command means to touch only the plate.

• The gate: a refused command is named by its origin and never sent; the flag off leaves the same commands untouched; and a tip carrier butted against the source carrier stops the grip, naming the carrier, with the joints and whatever is held left as they were.

• The declared shapes: a carrier whose model ships hulls is those hulls, and seated racks never phantom-hit their own carrier - the pockets are hollow and static-vs-static is never judged.

Notes

• Upstream ships no .collision.json hulls, so every resource is checked as its box (conservative, with touch-leniency for box-represented resources). The six sidecars shipped here (the iSWAP's link, gripper body, fingers and pads, the X-arm's dual rails, and the tip carrier - 31 hulls, the pockets hollow so a seated rack never hits its own carrier) were fitted offline from Hamilton's models; a hull conversion utility is not part of this PR.

• Runtime, measured on the demo deck (2,180 resources, gate on): a whole-plan iSWAP judge runs about 1.7-2.2 s - the fine walk, not the scene build, which is kept and amortized - and the per-command gate costs about 40-60 ms per channel or head command (0.7-1.0 s across the demo's 17 commands), all of it before the command is sent. The broadphase itself buys ~1,700x over naive all-to-all on a 4,000-piece deck (1 exact test instead of 4,097).

• Stacked on STAR: act firmware commands out in the viewer (motion playback) #1468 (shares the demo's motion-attachment API and the simulator's grip-close answer); retargets to main once that merges.