Overview

The DiatomTrack software comprises three steps: 

1) Image segmentation, 
2) Cell tracking, and 
3) Manual editing.



Starting a new analysis

1) Segmentation
Upon launch, a configuration window appears to specify 
- the paths for the segmentation: input/raw images, model states, and output/saving, 
- name of the experiment or project,
- limit the number of frames to be segmented here, and
- if you only want to segment and save the results for later (box).
(Note: By default, the frames are segmented in batches of 4, so that segmentation will choose the next higher multiple.)

2) Tracking
Next, you  software will prompt you for tracker parameters (default values are already optimized for the given experimental data). 
The segmentation begins immediately with a progress bar displayed. Extracted objects are processed and followed by frame-to-frame tracking. 
Finally, the editor opens automatically.

3) Editing
See below.

Resuming an analysis

If segmentation was skipped:
Provide the path to pre-segmented data. You may redefine the project name or frame limit. Processing resumes at 2) Tracking.

If opening prior results:
Choose one of two formats
- a combined .tvf-file which is a modified AVI containing tracking data in the metadata. (This is slower to load but preserves all data in a single file.)
- a combination of a video and CSV file.
Processing resumes at 3) Editing.



The editor

The editor is organized in three columns. On the left, you find the video and below the playback and overlay options. The center column shows the lineage trees. The buttons on the right enable manipulation of the tracking data.


Left column: video, playback and overlay options

Navigation
Zoom: Drag with left mouse button; reset view with single left-click.
Cell Selection: Double-right-click a cell to select it.

Overlay controls (below video; toggle visual aids)
Position trace: Shows a trace cells' last locations.
Lineage highlighting:  Isolates overlays for selected lineage only.
Frustule age indicator: Marks the longer sides of the cells (denoting thecae's age if known).
Cell age indicator: Marks cells position in the lineage by color (distinction by knowledge of cell 'age' and/or theca age).


Center column: Lineage management

Lineage tree panel: Hierarchical list of all cell lineages, sorted by tree ID.
Options:
- Expand/collapse the layout.
- Highlight the cells corresponding to a clicked line. 
- Filter displayed trees by zoom. 
- Filter displayed trees by frame. (Current or entered frame.) 
- Synchronize with highlighted lineage in overlay. Can also be toggled by double clicking.

Frame list (adjacent to lineages):
Shows the frames where the highlighted tracklet appears. Double-click to jump to frame.

Removed tracklets list (smallest panel):
Lists IDs of deleted tracklets. 


Right column: Tracking data tools

Flip frustule age at selected frame 
Reverses assignment of theca age at the selected (or current) frame (red = younger; blue = older).

Flip cell age on level
Reverses age assignment of the sibling cells (red = younger; blue = older).

Flip selected cell's age
Toggles through all given age options for selected cell. (Necessary if tracklets are cut and reassigned.)

Split tracklet at selected frame
Splits tracklet at the selected (or current) frame and creates new tracklet for subsequent frames.

Merge tracklets
Toggles frame list to selection mode. Select two tracklets. Merge upon a second click on the button and toggle back to frame list. Right-click to deselect tracklets.

Move tracklets
Toggles frame list to selection mode. Chose tracklets. Second click to select new parent tracklet. Third click to apply. Right-click to deselect.

Swap tracklets at current frame
Toggles frame list to selection mode. Swap identity of the selected tracklets at current image upon second click.Right-click to deselect.

Remove tracklet
Removes all data of selected tracklet, moves ID to the removed tracklet list and removes from overlay. 

Restore tracklet
Recovers tracklet from the removed tracklet list.

Remove/Restore short tracklets
Applies action to all tracklets appearing once.



Saving & Exiting

Click Save & Exit to open the save dialog.

Specify
- output directory and filename,
- whether to save unmodified raw data alongside edited results,
- whether to generate edit statistics.

DiatomTrack saves all data and closes automatically upon completion.



Output

The extracted data is saved as CSV from pandas. The file contains these columns:
f - frame index
row - row index	
tree - lineage tree ID
id - cell ID
start - first frame of cell ID
parent - cell's parent ID (-1 = no parent)
division - frame of division (-1 = no division)
age - 'age' of the cell (0 = unknown, 1 = older, 2 = younger)
side - tracked rotation for theca age
frame - frame
x - x-location
y - y-location
width - width of bounding box
height - height of bounding box
rotation - rotation of bounding box
area - area of segmentation
show - deletion marker (0 = deleted)
move_distance - distance moved since last detection
norm_distance - distance moved since last detection normalized by number of frames