khanlab / khanlab/SPIMpack

orientation and channel preview

Open
#2 0 comments 1 reaction 2 assignees Claimed by @akhanf View on GitHub
Dominant language
Python
Stars
1
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## 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 `
- 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

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.