orientation and channel preview

[akhanf]

Summary

Add an optional QC step to SPIMpack that helps users visually validate image orientation and channel labels before finalizing dataset packaging.

The idea is to load a low-resolution version of each dataset for a set of candidate orientation strings, generate browser-viewable previews, and let the user confirm which orientation produces anatomically correct labels/views. This same workflow could also support visual confirmation or editing of channel labels.

Motivation

SPIM datasets may require manual verification of:

• orientation strings
• anatomical direction labels
• channel naming / assignment

A lightweight visual QC step would reduce metadata mistakes before packaging into BIDS.

Since ZarrNii.from_file(..., level=5, orientation=...) can load low-resolution data and img.to_nifti() can easily export to NIfTI, this seems feasible without needing full-resolution data in memory.

Proposed approach

Implement an optional QC/orientation preview command in SPIMpack.

High-level flow:

1. For a dataset, read a low-resolution image with one or more candidate orientation strings, e.g.:
   • ZarrNii.from_file("....ims", level=5, orientation="RPI")
2. Export the low-resolution oriented image to NIfTI via img.to_nifti()
3. Open a lightweight web-based viewer for interactive orthoview inspection
4. Let the user:
   • compare candidate orientations
   • confirm which orientation is correct
   • visually inspect channels
   • confirm or edit channel labels
5. Save the accepted orientation/channel metadata for downstream packaging

Viewer idea

A lightweight browser-based viewer such as Niivue seems like a good fit here, since:

• the QC data can be exported to NIfTI
• orthoview inspection is the main use case
• it avoids requiring a heavy desktop GUI

A minimal implementation could also begin with a simple local web app that loads generated low-res NIfTI files and allows selection between candidate orientations and channels.

Suggested scope for v1

• Add a CLI subcommand such as:
  -spimpack qc preview <dataset>
• Support a user-provided or default list of candidate orientations
• Generate low-resolution oriented previews only
• Convert previews to NIfTI
• Launch a small local web UI for review
• Record the user’s selected orientation and confirmed/edited channel labels

Nice-to-have follow-ups

• Side-by-side comparison of two candidate orientations
• Saved screenshots / provenance artifacts
• Heuristics to rank likely orientations
• Batch QC across multiple datasets
• Snapshot-only/headless mode for CI or remote review

Open questions

• What should the CLI/API look like?
• Should v1 support a fixed shortlist of candidate orientations or arbitrary user input?
• Where should accepted QC decisions be stored?
• Should channel review be in scope for the initial implementation, or should orientation QC land first?

Acceptance criteria

• User can run an optional QC command on a dataset
• SPIMpack loads a low-resolution preview for one or more candidate orientations
• Preview data can be inspected in a lightweight browser-based viewer
• User can select/confirm the correct orientation
• User can inspect and confirm/edit channel labels
• The selected metadata is persisted for later packaging steps