Combine tutorial from I2K with quick start guide in docs

[cmalinmayor]

No description provided.

[AnniekStok]

Hi @cmalinmayor

I have created a markdown checklist file for testing different application features before we release new versions. There are probably still some things missing, so I copied it here below because I thought it might be easier to update. I have also updated the tutorial markdown file (shared with you via OneDrive).

Motile-Tracker Developer Checklist

February 2025 - Caroline Malin-Mayor - Anniek Stokkermans

Installation

MacOS & Linux

conda create -n motile-plugin python=3.10
conda activate motile-plugin
conda install -c conda-forge -c funkelab -c gurobi ilpy
pip install motile-tracker

Potential fix for Windows (if the above results in below error at ilpy import)

ImportError: DLL load failed while importing wrapper: The specified module could not be found.`

conda create -n motile_tracker -c funkelab -c gurobi -c conda-forge -c defaults python=3.10 gurobi=11.0.3 ilpy=0.4.0 libhwloc=2.11.1 pip=24.2
conda activate motile_tracker
pip install motile==0.3.0 motile-toolbox==0.4.0 motile-tracker==3.1.1

Potential fix for Ubuntu in case you get this error:

Could not load the Qt platform plugin "xcb" in "" even though it was found.
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

sudo apt-get install libxcb-xinerama0

• Successful installation on MacOS
• Successful installation on Ubuntu
• Successful installation on Windows

Downloading sample data

(On MacOS, data is saved to /Users/[USERNAME]/Library/Application Support/motile-tracker)

• Fluo-N2DL-Hela
• Embryo Membranes

Generating Tracks

• Run tracking with default parameters on Fluo-N2DL-Hela crop (labels)
• Run tracking with default parameters on Fluo-N2DL-Hela crop (centroid)
• Run tracking with default parameters on Fluo-N2DL-Hela crop (labels) with an alternative scaling (1, 2, 1)
• Click 'Back to editing' and run tracking with different parameters
• Clicking on different results in the Results List switches back to those tracking results.

Node selection

• Selecting a node by clicking on a label when the seg layer is active (label becomes less transparent)
• Selecting a node by clicking on a point when the points layer is active (point size increases, cyan outline)
• Selecting a node by clicking on a point in the tree view (point size increases, cyan outline)
• Selecting a node centers the viewer (and z dimension, if present) on that node (only when zoomed in.)
• Selecting a node centers the viewer on that node when the viewer dims are flipped
• Selecting multiple points by holding SHIFT in seg, points, and tree view
• Selecting multiple points by SHIFT + drag in the tree view
• Selecting multiple points by SHIFT + drag in the points layer with the 'Select points' tool active.
• Deselecting an active node by clicking on it
• [Dev] Deselecting active nodes by clicking on an empty region in the points or seg layer.

Tree view

Tree view data display options

• Tree view toggle display between all and lineage only mode by:
  • Pressing Q
  • Using the radio button in the menu
• Tree view toggle between standard view and area feature display by:
  • Pressing W
  • Using the radio button in the menu

Tree view canvas controls

• Pan by mouse drag
• Zoom by mouse wheel/track pad scroll
• Zoom horizontally by:
  • Drag horizontally when holding right mouse button
  • Hold x and mouse wheel/track pad scroll
• Zoom vertically by:
  • Drag vertically when holding right mouse button
  • Hold y and mouse wheel/track pad scroll
• Reset view by: right mouse click
• Flip the x and y tree view axes by:
  • Press f
  • The Flip button

Tree view navigation - must work in all 4 views (standard/area mode and lineage/all mode) and with flipped display

• When in standard or feature view and all mode, and time is displayed vertically:
  • Right/left arrow keys select the next viewed right/left node in that time point (if there is one, otherwise does nothing). Viewed means in standard view, the next right/left tree node, and in feature view, the next right/left feature value node.
  • Up/down arrow keys go to the next/previous node in the lineage (if there is one). At division, it just picks a child aribtrarily (the left, currently).
• When in standard or feature view and all mode, and time is displayed horizonally:
  • Up/down arrow keys select the next viewed right/left node in that time point (if there is one, otherwise does nothing). Viewed means in standard view, the next right/left tree node, and in feature view, the next right/left feature value node.
  • Right/left arrow keys go to the next/previous node in the lineage (if there is one). At division, it just picks a child aribtrarily (the bottom, currently).
• When in standard or feature view and lineage mode, and time is displayed vertically:
  • Right/left arrow keys select the next right/left node in that time point (if there is one, otherwise does nothing - you can't actually see if there is a next one in the view, you just have to toggle to all mode to tell). In standard view, this will pick the next right/left tree node, and in feature view, the next right/left feature value node.
  • Up/down arrow keys go to the next/previous node in the lineage (if there is one). At division, it just picks a child aribtrarily (the left, currently).
• When in standard or feature view and lineage mode, and time is displayed horizonally:
  • Up/down arrow keys select the next right/left node in that time point (if there is one, otherwise does nothing - you can't actually see if there is a next one in the view, you just have to toggle to all mode to tell). In standard view, this will pick the next right/left tree node, and in feature view, the next right/left feature value node.
  • Left/Right arrow keys go to the next/previous node in the lineage (if there is one). At division, it just picks a child aribtrarily (the bottom, currently).

Display

• Nodes, tracks, points, labels have matching colors
• Nodes have triangle/circle/cross symbol when dividing/linear/end point.
• Viewer toggle display by pressing Q

Seg layer

• Clicking Shuffle colors shuffles the display color for labels, points, and tree view
• Clicking on a label sets the corresponding label value and color in the menu.
• Using the pipet on a label sets the corresponding label value and color in the menu.
• Pressing M selects a new, unused label id.
• Using the eraser to remove part of a label updates its size and centroid
• Using the eraser to remove a label entirely also removes its node in points layer and tree view, creating a skip edge if it was connected to other nodes.
• Fill bucket tool is not allowed to completely replace a label, but it can replace a fragment of label (e.g. after you have split a label by erasing through it)
• paint tool is not allowed to completely replace a label, but it can replace a fragment of label (e.g. after you have split a label by erasing through it)
• The polygon tool is disabled
• Painting with a new label creates a new node
• The z step is not centered while painting or erasing.
• It is not allowed to include the time dimension in n edit dim
• Painting with a label that has already divided upstream will ask for confirmation to break the division event.

Points layer

• When the 'Add points' tool is active, clicking on the canvas adds an new node, but only when no seg is present.
• It is only allowed to move points with the 'Select points' tool if no seg is present.
• The 'point size' slider changes the point size.
• The 'x' button deletes selected points (select while in 'Select points' mode).
• [Dev]. Adding new points either continues existing tracks (last active one) or starts new tracks according to what is specified by the continue tracks / new tracks radio buttons.

Tracks layer

• Track colors match with the labels/points/tree view.

Editing actions

• Pressing D or Delete or the Delete button in the Edit Tracks menu deletes selected nodes and their segmentation, if present, and creates skip edges as appropriate.
• Selecting two connected nodes and pressing B | Break button breaks the connection into two separate tracks
• Selecting two non-horizontal nodes on separate tracks and pressing A | Add button creates a new (skip) connection and recolors tracks accordingly.
• Adding a new incoming connection to a node that already has an incoming connection asks for confirmation to remove the existing connection (merges not (yet) allowed).
• Creating a division by adding a second outgoing connection relabels the tracks and updates the symbols accordingly
• Creating a horizontal connection between two nodes is not allowed

Undo / Redo

• Undo Add edge
• Undo Break edge
• Undo Paint event
• Undo Fill bucket event
• Undo Delete
• Redo Add edge
• Redo Break edge
• Redo Paint event
• Redo Fill bucket event
• Redo Delete

Save and Export

• Save Motile Run
  • attrs.json
  • gaps.txt
  • solver_params.json
  • (seg.npy)
  • graph.json
• Load Motile Run
  • Points, Tracks, (seg), tree view are updated accordingly
  • Scaling is set correctly
• Export to csv (columns: t, (z), y, x, id, parent_id, track_id, area, lineage_id (dev), color (dev))
• Import external tracks
  • 2D & 3D without segmentation
  • with segmentation from tif
  • with segmentation from zarr
  • with segmentation and alternative scaling
  • with alternative column names
  • with a different seg_id than node id
  • with string ids instead of integers
  • with non-unique ids --> should fail
  • fails when seg_id does not match with segmentation file
  • if a seg is present, allows to measure area (recompute)
  • if a seg is present, allows to load area from a non-used column