coordination-oru 0.6.1

Python port of coordination_oru: a multi-robot trajectory-envelope coordinator.

coordination-oru (Python)

A Python port of coordination_oru, the trajectory-envelope multi-robot coordinator from Pecora et al., A loosely-coupled approach for multi-robot coordination, motion planning and control, ICAPS 2018.

Documentation: https://pycoordination.pages.dev/ — getting started, a theory→implementation walkthrough of the paper, guides, and API reference.

This port targets production use. The framework is loosely coupled: paths may be supplied externally by any planner, though a built-in Hybrid A* planner (Reeds-Shepp paths over ROS-style occupancy maps) and two viewers (browser, pyglet) are included. The ROS layer of the original is out of scope.

Why Python?

Java original	Python replacement	Notes
JTS (vividsolutions)	shapely 2.x (GEOS)	GEOS is a direct C++ port of JTS — same semantics.
JGraphT	networkx	Near 1:1 graph API.
meta-csp APSPSolver	numpy Floyd-Warshall	~20 lines.
meta-csp Allen / Bounds	thin custom layer	~50 lines, 13 relation types.
meta-csp TrajectoryEnvelope	custom port	dataclasses + shapely.
Java threads	asyncio Tasks + Queues	Cleaner cancellation and fan-in.
Swing/AWT	deferred (matplotlib/pygame)	Visualization is a future stage.

We port only the meta-csp surface that coordination_oru actually exercises at runtime: the STP solver, Allen relations, and the trajectory-envelope plumbing. The general meta-CSP search engine, Boolean CSP solver, and timeline planner are dropped.

Quick start

pip install coordination-oru
coordination-oru-demo

This installs from PyPI (web-viewer frontend prebuilt) and opens the interactive demo in your browser: three robots on an occupancy-grid map. Click a robot, then press-drag-release on the map to post a goal pose — the built-in Hybrid A* planner plans the path and the coordinator sequences any conflicts live. --headless runs a scripted corner-swap scenario instead (--pyglet for the desktop viewer, --help for all flags).

Install (development)

pip install -e .[dev]

Examples

Each example is a standalone script — run it directly with Python. By default it opens an animated pyglet viewer (the viewers ship with the package); pass --headless to run text-only with per-robot progress instead.

python examples/two_robots.py

Every example also accepts a viewer flag — no per-script setup needed:

python examples/two_robots.py --web-viewer   # browser-based viewer
python examples/two_robots.py --pyglet       # force the pyglet window
python examples/two_robots.py --headless     # force the text-only run

--web-viewer serves a Vite + React frontend on http://127.0.0.1:8723/ (--port to change, --no-browser to not auto-open) with live paths, swept envelopes, critical-section highlights, footprints, zoom/pan, and dark mode. PyPI wheels ship the frontend prebuilt; in a source checkout build it once with npm --prefix frontend install && npm --prefix frontend run build.

Script	Scenario
examples/two_robots.py	Two RK4 robots cross at the origin; one yields at the intersection.
examples/three_robots.py	Three RK4 robots through one intersection, deadlock-free.
examples/three_robots_oldpath.py	The original Java repo's debug1/2/3.path recorded paths.
examples/convoy.py	Convoy following: a yielder trails the leader inside a shared corridor.
examples/dynamic_missions.py	Hybrid A*-planned missions on the demo map. With --web-viewer it is interactive: click a robot, then press-drag-release to post a goal pose (as in the gif above).
examples/five_robots_sine.py	Five robots on interleaved sine/cosine waves whose crossings form a lattice of critical sections.

Run the tests

pytest

License

GNU General Public License v3.0 or later — see LICENSE. The original Java coordination_oru is GPL-3.0, so this port keeps the same licence.

Layout

coordination_oru/
├── *.py               # Coordinator, trackers, critical sections, dependencies,
│                      #   forward models, missions (Java-mirroring module names)
├── metacsp/
│   ├── temporal/      # Bounds, Allen relations, STP (Floyd-Warshall)
│   └── spatial/       # Pose, TrajectoryEnvelope, TrajectoryEnvelopeSolver
├── motionplanning/    # Hybrid A* + Reeds-Shepp, ROS-style occupancy maps
├── simulation2D/      # RK4-tracked simulated robots, simulation coordinator
├── viz/               # Web viewer (starlette + React) and pyglet viewer
├── data/              # Bundled demo .path files and maps (ship with the wheel)
└── util/              # Footprint helpers, path loaders, structlog setup
examples/              # Standalone runnable demos (python examples/<name>.py)
docs/                  # MkDocs documentation (https://pycoordination.pages.dev/)