Feature Request: Unified Global Coordinate System Across All Microscopes

[AdvancedImagingUTSW]

Feature Request: Unified Global Coordinate System Across All Navigate Microscopes

---

Problem / Motivation

Smart-acquisition routines assume every microscope shares the same axis conventions, but each rig currently has different stage polarities and camera orientations.

Symptoms

• Z-axis confusion: Positive Z moves toward the objective on some scopes and away on others.
• Camera inversions: Image X/Y directions vary between systems.
• Multi-scale mis-registration: Coordinate transforms aren’t consistent across resolutions.
• Crash risk: A user/workflow can drive the stage into an objective if driven the wrong direction.

A single, explicit coordinate system—plus per-microscope flip-flags—will eliminate hidden assumptions, simplify code, and make automated routines safe and portable.

---

Proposed Solution

1. Adopt an Absolute Stage-Space Convention

   Axis	+ Direction (physical)	Crash-Risk Notes
   Z	Toward detection objective	Always the “crash” direction
   Y	Toward illumination objective	­
   X	Away from optical-table front edge	­
   F	Same sense as +Z (focus motor)	­
   θ	Counter-clockwise (viewed from above)	­

For multi-view illumination systems, the primary microscope would define the coordinate system. Additional working definitions are needed for the upright ASLM and OPM rigs where the specimen moves obliquely relative to the classical axes.

2. Define Camera-Space Rules

   • +Y stage ⇒ image moves up (screen coordinates).
   • +X stage ⇒ image moves right.
   • Per-camera camera_flip_flags correct any mismatch.

3. Config-Level Mapping

   stage_flip_flags:
     flip_x: false
     flip_y: true
     flip_z: false
     flip_theta: true
   
   camera_flip_flags:
     flip_x: true
     flip_y: false
   

Provide GUI helper:

Create a popup window that allows someone to readily change the flip flags without having to reboot the software.

4. Stitching Workflows
   • Needs to be extensively tested with BigDataViewer to guarantee that we do not disrupt downstream workflows.

5. Safety & Regression Tests
   • Unit test: Simulate flip matrices; verify move_relative(+z) maps to a positive internal delta toward the crash direction.
   • Integration test: Jog +10 µm in each axis and assert expected image displacement on every microscope. This would also be a good way to calibrate the stages when they move in the lateral dimensions.

6. Documentation • Add “Coordinate System” page with diagrams, rationale (link to Slack discussion), and migration guide.

Priority: P0 – prerequisite for reliable multi-microscope smart routines