Napari-Travali

⚠️ 🚧 👷 Still work in progress, early-alpha! There can be any changes in API. ⚠️ 🚧 👷

Napari TRAck VALIdator ... a software for manual track / segmentation validation

Features

Enables manual validation and editing of cell tracking results.

Switching tracks
Redrawing segmentation
Daughter cell selection / drawing
Annotating track ends

Installation

Currently at this early stage, you can install Napari Travali only from GitHub

$ pip install git+https://github.com/yfukai/napari-travali

Usage

How to run

python -m napari_travali /path/to/zarr
# python -m napari_travali /path/to/zarr --presist # for a small-scale dataset

Input data specification

Currently we accept segmented / tracked data in the following format.

file format : zarr (hopefully HDF5 in future)
contents :
- Dataset named image ... 5-dim dataset with dimensional order TCZYX
- Group named labels
  - Dataset (default name original or original.travali, let name: (dataset_name)) ... 4-dim dataset with dimensional order TZYX
    - attr named target_Ts ... target time frame indices for manual track validation (masks in the other frames are ignored)
- Group named df_tracks
  - Dataset name: (dataset_name) ... 2-dim dataset with columns (frame, label, track_id, bbox_y0, bbox_y1, bbox_x0, bbox_x1)
    - attr named finalized_track_ids ... (optional) list of finalized segment ids
    - attr named candidate_track_ids ... (optional) list of candidate segment ids
- Group named df_divisions
  - Dataset name: (dataset_name) ... 2-dim dataset with columns (parent_track_id, frame_child1, label_child1, frame_child2, label_child2)

Label loading logic

When reading file, original.travali is read if exits. If not, original is read.
When writing file,
- If the read dataset is suffixed with .travali, the same name is used.
- If the read dataset is not suffixed with .travali, (original name).travali is used.

Please see the Command-line Reference for details.

Modes and editing commands

Common operations
- Typing Shift + Left ... move to the previous timeframe in target_Ts
- Typing Shift + Right ... move to the next timeframe in target_Ts
- Typing Control + Shift + Alt + s ... save the manual validation result
All label
- Clicking a label ... select the label and to Label selected
Label selected
- Typing Escape ... cancel editing and to All label
- Typing Enter ... finalize editing and to All label
- Typing r ... Redrawing the segmentation. Transition to Label redraw
- Typing s ... Switching the segmented area. Transition to Label switch
- Typing d ... Modifying the daughter areas. Transition to Daughter switch or Daughter draw (asks before transition)
- Typing t ... Marking termination
Label redraw
- Typing Escape ... cancel redraw and make transition to Label selected
- Typing Enter ... finalize redraw and make transition to Label selected
Label switch
- Typing Escape ... cancel switch and make transition to Label selected
- Clicking a label ... select the label to switch and make transition to Label selected
Daughter switch
- Typing Escape ... cancel choosing daughters and make transition to Label selected
- Clicking a label ... select the label as a daughter and make transition to either of Daughter switch or Daughter draw (asks before transition) or Label selected (if you already selected two daughters)
Daughter draw
- Typing Escape ... cancel choosing daughters and to Label selected
- Typing Enter ... finalize drawing a daughter and make transition to either of Daughter switch or Daughter draw (asks before transition) or Label selected (if you already selected two daughters)

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, Napari Travali is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template.