Production Use

Quick Start

cd topos
source .venv/bin/activate
python -m topos.main

1. Power all 3 anchors (USB-C power or charger)
2. Connect 1 anchor via USB to the Mac (or all via WiFi)
3. Turn on performer tags
4. Open http://localhost:7070
5. Verify: header shows 3/3 anchors · N tags

Available Outputs

Protocol	Port	Use Case
PSN	UDP multicast 236.10.10.10:56565	Soma, Augment3d (PSN v2.03, left-handed: X=right, Y=up, Z=depth)
OSC	UDP 127.0.0.1:8000	QLab, reactive audio
ADM-OSC	UDP 127.0.0.1:9000	Immersive audio
WebSocket	ws://localhost:7070/ws/trackers	Dashboard, custom apps, relay

Toggle outputs on/off from the outputs section in the right panel.

Persistence

Topos automatically saves to data/state.json:

• Performer names
• Anchor positions (calibration)
• Terrain measurements
• Output toggle states

To start fresh:

python -m topos.main --clean

Presets

Save and restore named configurations (per venue):

1. In the right panel, section presets
2. Enter a name (e.g. “douze-dix-huit”), click save
3. To restore: click the preset name (confirms before applying)
4. To delete: click ×

Presets store: performer names, anchor positions, terrain measurements, zone, output toggles.

Coordinate System

Topos uses configurable coordinate presets. Default is Capture (aligned with Capture Sweden):

Axis	Direction	Stage reference
+X	Stage right	Cour
+Y	Up	Height
+Z	Downstage	Face

Configure in config/topos.yaml:

calibration:
  coordinate_system: "capture"   # or "stage_left" for legacy

PSN output automatically converts to the PSN v2.03 coordinate system.

2D / 3D Trilateration

Toggle between 2D (floor tracking, Z=0) and 3D (full Z-axis) in the dashboard. 3D requires anchors at different heights for good vertical resolution.

Art-Net Fixture Tracking

Topos computes pan/tilt angles for moving head fixtures and sends DMX via Art-Net:

1. Add a fixture in the right panel (name, universe, DMX address, position)
2. Load a GDTF/XML profile for pan/tilt channel mapping and ranges
3. Assign a tracker to the fixture — it follows that performer
4. Per-fixture flags: swap pan/tilt, invert pan, invert tilt

Art-Net is sent to the configured host (typically the ONYX console IP or broadcast 2.255.255.255).

Fixture Auto-Calibration

Multi-fixture wizard — calibrate several projos in one pass with a single tag on stage. The fixture position is measured by the operator (±10-20 cm is enough); the solver determines the rest heading and the DMX→angle mappings.

1. Mesure la position physique de chaque projo (ruban, plan accroche, télémètre…). Saisis les valeurs (x, y, z) dans le formulaire Fixtures (X=cour-jardin, Y=hauteur, Z=face-lointain en convention Capture).
2. In Fixtures mode, click the calibration lumière CTA.
3. Step 1 — projos : check the fixtures to calibrate. Each row shows the current position. If a fixture is still at the default (0, 0, 3), it is flagged « ⚠ position non mesurée » and the wizard refuses to continue — clic « éditer pos » pour corriger inline.
4. Step 2 — acquisition : pick the reference tag, place it at a position on stage, aim every selected projo at it (via ONYX or any console). Click valider ce tag pour les fixtures sélectionnées — Topos samples the tag position once over 3 s and records one point per fixture, reading each one’s pan/tilt either from the Art-Net snoop on UDP 6454 or from the manual inputs (fallback when no console signal is visible).
5. Move the tag to a new position, repeat. Minimum 3 positions for a good fit; 4-5 is better. Try to stay in the same quadrant of the Onyx position-grid for all captures so the console doesn’t unwind pan the long way around between points.
6. Step 3 — résultat : per-fixture orientation, pan/tilt ranges, and residual error in degrees, with per-point error breakdown. A point that the operator drove in « mode B » (pan+180° / tilt mirrored) is detected as an outlier and excluded from the fit; the wizard flags it with a red warning so you can recapture if needed.

Tracking Cues

Save and recall fixture→tracker assignments per scene:

1. Set up fixtures tracking the right performers
2. In the tracking cues section, enter a cue name → save
3. To recall: click the cue name or send OSC /topos/cue/recall "cue_name"

Cues store which fixture follows which tracker. Useful for scene changes.

OSC Control Input

Topos listens for OSC commands on port 7080 (configurable):

Address	Argument	Action
/topos/cue/recall	string name	Recall a tracking cue
/topos/cue/recall	int index	Recall cue by index
/topos/output/artnet	0 or 1	Toggle Art-Net output
/topos/output/psn	0 or 1	Toggle PSN output
/topos/output/osc	0 or 1	Toggle OSC output

Enable in config/topos.yaml:

osc_control:
  enabled: true
  port: 7080

Ghost Mode

When a tag loses signal, the dashboard holds its last known position in amber. The ghost timeout is adjustable per performer (30s to 30min) in the tracker panel.

Canvas Navigation

• Scroll wheel: zoom in/out (cursor-centered)
• Click + drag: pan the view
• Double-click: fit all tracked objects (anchors + performers + origin)

The calibration zone is shown as a dashed border at any zoom level. The origin (0,0) is marked with a crosshair. Grid scale labels show metres.

Relay Mode

Run a slave Topos on a remote machine to re-publish PSN/OSC locally:

# On the remote machine (e.g. Soma's Mac):
python -m topos.main --relay ws://10.12.18.112:7070/ws/trackers

The slave connects to the master’s WebSocket, receives tracker positions, and re-emits them via PSN multicast on localhost. Useful when multicast doesn’t cross network boundaries.