weigertlab · C-Achard · Jan 3, 2025 · Jan 3, 2025 · Jan 3, 2025 · Jan 8, 2025
diff --git a/.cursorrules b/.cursorrules
@@ -0,0 +1,15 @@
+You are an expert coder in Python that likes concise, elegant, and self-explanatory code.
+
+Here are some general rules:
+
+
+- Follow PEP 8 naming conventions:
+  - snake_case for functions and variables
+  - PascalCase for classes
+  - UPPER_CASE for constants
+- Write clear comments explaining the rationale behind a complex algorithms  but don't be overly verbose
+- Use google style docstrings
+- Use type hints to improve code readability and catch potential errors.
+- Use f-strings for string interpolation
+- Prefer pathlib over os.path
+- Prefer tuples over lists for immutable data
diff --git a/.gitignore b/.gitignore
@@ -177,3 +177,6 @@ cython_debug/
 #.idea/
 
 trackastra/_version.py
+
+CTC_DATA/*
+.vscode/settings.json
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -8,4 +8,4 @@ repos:
     rev: v0.4.6
     hooks:
     - id: ruff
-      args: [--fix, --unsafe-fixes, --preview, --verbose]
+      args: [--fix, --unsafe-fixes, --preview, --verbose, --exit-zero]
diff --git a/README.md b/README.md
@@ -22,27 +22,45 @@ This repository contains the Python implementation of Trackastra.
 
 Please first set up a Python environment (with Python version 3.10 or higher), preferably via [conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) or [mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html#mamba-install).
 
+### Simple installation
 Trackastra can then be installed from PyPI using `pip`:
 ```bash
 pip install trackastra
 ```
 
+### With ILP support
 For tracking with an integer linear program (ILP, which is optional)
 ```bash
 conda create --name trackastra python=3.10 --no-default-packages
 conda activate trackastra
 conda install -c conda-forge -c gurobi -c funkelab ilpy
 pip install "trackastra[ilp]"
 ```
+<details>
+<summary>📄 <h4>Development installation</h4></summary>
+
+```bash
+conda create --name trackastra python=3.10 --no-default-packages
+conda activate trackastra
+conda install -c conda-forge -c gurobi -c funkelab ilpy
+git clone https://github.com/weigertlab/trackastra.git
+pip install -e "./trackastra[ilp,dev]"
+```
 
-Notes:
+</details>
+<details>
+<summary>📄 <h4></b>Notes/Troubleshooting</h4></summary>
+
 - For the optional ILP linking, this will install [`motile`](https://funkelab.github.io/motile/index.html) and binaries for two discrete optimizers:
 
   1. The [Gurobi Optimizer](https://www.gurobi.com/). This is a commercial solver, which requires a valid license. Academic licenses are provided for free, see [here](https://www.gurobi.com/academia/academic-program-and-licenses/) for how to obtain one.
 
   2. The [SCIP Optimizer](https://www.scipopt.org/), a free and open source solver. If `motile` does not find a valid Gurobi license, it will fall back to using SCIP.
 - On MacOS, installing packages into the conda environment before installing `ilpy` can cause problems.
 - 2024-06-07: On Apple M3 chips, you might have to use the nightly build of `torch` and `torchvision`, or worst case build them yourself.
+
+</details>
+
 
 ## Usage
 
@@ -113,7 +131,54 @@ v.add_labels(masks_tracked)
 v.add_tracks(data=napari_tracks, graph=napari_tracks_graph)
 ```
 
-### Training a model on your own data
+<h3>
+  <!-- <img src="https://camo.githubusercontent.com/5d68a2c2564bc50ca534f939922482779202499b14901e0671d5362def6ff59f/68747470733a2f2f696d6167656a2e6e65742f6d656469612f69636f6e732f747261636b6d6174652e706e67" alt="icon" height="20" style="vertical-align: middle;"/> -->
+  <img src="https://fiji.sc/site/logo.png" alt="icon" height="20" style="vertical-align: middle;"/>
+  Fiji (via TrackMate)
+</h3>
+
+Trackastra is one of the available trackers in [TrackMate](https://imagej.net/plugins/trackmate/). For installation and usage instructions take a look at this [tutorial](
+https://imagej.net/plugins/trackmate/trackers/trackmate-trackastra).
+
+<h3>
+  <img src="docs/icons/docker-mark-blue.png" alt="icon" height="20" style="vertical-align: middle;"/>
+  Docker images
+</h3>
+
+Some of our models are available as docker images on [Docker Hub](https://hub.docker.com/r/bentaculum/trackastra-track/tags). Currently, we only provide CPU-based docker images.
+
+Track within a docker container with the following command, filling the `<VARIABLES>`:
+
+```bash
+docker run -it -v <LOCAL_DATA_DIR>:/data -v <LOCAL_RESULTS_DIR>:/results bentaculum/trackastra-track:<MODEL_TAG> --input_test /data/<DATASET_IN_CTC_FORMAT> --detection_folder <TRA/SEG/ETC>"
+```
+<details>
+<summary>📄 <i>Show example with Cell Tracking Challenge model:</i></summary>
+<br>
+
+```bash
+wget http://data.celltrackingchallenge.net/training-datasets/Fluo-N2DH-GOWT1.zip 
+chmod -R 775 Fluo-N2DH-GOWT1
+docker pull bentaculum/trackastra-track:model.ctc-linking.ilp 
+docker run -it -v ./:/data -v ./:/results bentaculum/trackastra-track:model.ctc-linking.ilp --input_test data/Fluo-N2DH-GOWT1/01 --detection_folder TRA
+```
+
+</details>
+
+<h3>
+  <img src="docs/icons/terminal-cli-fill.256x224.png" alt="icon" height="20" style="vertical-align: middle;"/>
+  Command Line Interface
+</h3>
+After [installation](#installation), simply run in your terminal 
+
+```bash
+trackastra track --help
+```
+
+to build a command for tracking directly from images and corresponding instance segmentation masks saved on disk as two series of TIF files.
+
+
+## Usage: Training a model on your own data
 
 To run an example
 - clone this repository and got into the scripts directory with `cd trackastra/scripts`.

diff --git a/scripts/TAP_aug_bacteria copy.yaml b/scripts/TAP_aug_bacteria copy.yaml
@@ -0,0 +1,97 @@
+# Forked from zih_bacteria.yaml
+name: vanvliet_dinov2_aug
+# model: /home/achard/trastra_v2/BEST_2025-06-04_13-23-38_vanvliet_sam21_aug
+epochs: 750
+warmup_epochs: 5
+window: 4
+attn_dist_mode: v1
+delta_cutoff: 1
+num_encoder_layers: 4
+num_decoder_layers: 4
+causal_norm: none
+d_model: 128
+dropout: 0.05
+pos_embed_per_dim: 32
+lr: 0.0001
+train_samples: 32000
+max_tokens: 2048
+batch_size: 64
+detection_folders:
+- TRA
+crop_size:
+- 320
+- 320
+attn_positional_bias: rope
+ndim: 2
+# Features config
+features: pretrained_feats_aug
+# features: pretrained_feats
+# features: wrfeat
+#### Additional parameters for pretrained_feats
+augment: 3
+pretrained_n_augs: 25
+# pretrained_feats_model: facebook/sam2.1-hiera-base-plus
+# pretrained_feats_model: facebookresearch/co-tracker
+# pretrained_feats_model: facebook/dinov2-base
+pretrained_feats_model: weigertlab/tarrow
+pretrained_model_path: /home/achard/tarrow_runs/vanvliet_backbone_unet_delta1-2
+# pretrained_feats_model: debug/encoded_labels
+reduced_pretrained_feat_dim: 128
+pretrained_feats_mode: mean_patches_exact
+# pretrained_feats_mode: nearest_patch
+pretrained_feats_additional_props: regionprops_small
+# feat_embed_per_dim: 8 # Reduce additional dimensions added to the features via positional embedding
+rotate_features: true
+# disable_xy_coords: true
+# disable_all_coords: True
+cachedir: /backup/achard/cache
+outdir: /home/achard/trastra_v2
+# weight_decay: 0.01
+#### Logger
+logger: wandb
+wandb_project: "trackastra_v2"
+# Paths config
+cache: true
+compress: true
+distributed: false
+###
+
+input_train:
+- /home/achard/CTC_DATA/vanvliet/cib/140409-03  #
+- /home/achard/CTC_DATA/vanvliet/cib/140415-08
+- /home/achard/CTC_DATA/vanvliet/recA/151027-05
+- /home/achard/CTC_DATA/vanvliet/recA/151027-06
+# - /home/achard/CTC_DATA/vanvliet/recA/151027-10  # Has an empty frame, annoying
+- /home/achard/CTC_DATA/vanvliet/recA/151028-01
+- /home/achard/CTC_DATA/vanvliet/recA/151029-05
+- /home/achard/CTC_DATA/vanvliet/recA/151029-11
+- /home/achard/CTC_DATA/vanvliet/rpsM/151029_E1-6
+- /home/achard/CTC_DATA/vanvliet/rpsM/151101_E2-1
+- /home/achard/CTC_DATA/vanvliet/rpsM/151101_E2-2
+- /home/achard/CTC_DATA/vanvliet/rpsM/151101_E3-11
+- /home/achard/CTC_DATA/vanvliet/rpsM/151101_E4-12
+- /home/achard/CTC_DATA/vanvliet/metA/150317-07
+- /home/achard/CTC_DATA/vanvliet/metA/150318-06
+- /home/achard/CTC_DATA/vanvliet/metA/150331-12
+- /home/achard/CTC_DATA/vanvliet/metA/151222-10
+- /home/achard/CTC_DATA/vanvliet/metA/151222-11
+- /home/achard/CTC_DATA/vanvliet/pheA/150324-03
+- /home/achard/CTC_DATA/vanvliet/pheA/150324-05
+- /home/achard/CTC_DATA/vanvliet/pheA/150325-04
+- /home/achard/CTC_DATA/vanvliet/pheA/160112-04
+- /home/achard/CTC_DATA/vanvliet/trpL/150303-01
+- /home/achard/CTC_DATA/vanvliet/trpL/150303-08
+
+input_val:
+- /home/achard/CTC_DATA/vanvliet/trpL/150428-08
+- /home/achard/CTC_DATA/vanvliet/trpL/151021-11
+
+input_test:
+# - data/CTC_DATA/vanvliet/cib/140408-01  # dense labels not precise
+- /home/achard/CTC_DATA/vanvliet/rpsM/151029_E1-1  # ok
+- /home/achard/CTC_DATA/vanvliet/rpsM/151029_E1-5  # ok
+- /home/achard/CTC_DATA/vanvliet/rpsM/151101_E3-12  # ok
+- /home/achard/CTC_DATA/vanvliet/trpL/150309-04  # ok
+# - data/CTC_DATA/vanvliet/trpL/150310-05  # was empty
+- /home/achard/CTC_DATA/vanvliet/trpL/150310-11  # not in delta test set. quite some global moving!
+- /home/achard/CTC_DATA/vanvliet/pheA/160112-06  # ok. tricky. not in delta test set.
diff --git a/scripts/cotrack3_aug_bacteria.yaml b/scripts/cotrack3_aug_bacteria.yaml
@@ -0,0 +1,96 @@
+# Forked from zih_bacteria.yaml
+name: vanvliet_cotracker3_aug
+# model: /home/achard/trastra_v2/BEST_2025-06-04_13-23-38_vanvliet_sam21_aug
+epochs: 750
+warmup_epochs: 5
+window: 4
+attn_dist_mode: v1
+delta_cutoff: 1
+num_encoder_layers: 4
+num_decoder_layers: 4
+causal_norm: none
+d_model: 128
+dropout: 0.05
+pos_embed_per_dim: 32
+lr: 0.0001
+train_samples: 320005
+max_tokens: 2048
+batch_size: 64
+detection_folders:
+- TRA
+crop_size:
+- 320
+- 320
+attn_positional_bias: rope
+ndim: 2
+# Features config
+features: pretrained_feats_aug
+# features: pretrained_feats
+# features: wrfeat
+#### Additional parameters for pretrained_feats
+augment: 3
+pretrained_n_augs: 25
+# pretrained_feats_model: facebook/sam2.1-hiera-base-plus
+pretrained_feats_model: facebookresearch/co-tracker
+# pretrained_feats_model: weigertlab/tarrow
+# pretrained_model_path: /home/achard/tarrow_runs/vanvliet_backbone_unet_delta1-2
+# pretrained_feats_model: debug/encoded_labels
+reduced_pretrained_feat_dim: 128
+pretrained_feats_mode: mean_patches_exact
+# pretrained_feats_mode: nearest_patch
+pretrained_feats_additional_props: regionprops_small
+# feat_embed_per_dim: 8 # Reduce additional dimensions added to the features via positional embedding
+rotate_features: true
+# disable_xy_coords: true
+# disable_all_coords: True
+cachedir: /home/achard/cache
+outdir: /home/achard/trastra_v2
+# weight_decay: 0.01
+#### Logger
+logger: wandb
+wandb_project: "trackastra_v2"
+# Paths config
+cache: true
+compress: true
+distributed: false
+###
+
+input_train:
+- /home/achard/CTC_DATA/vanvliet/cib/140409-03  #
+- /home/achard/CTC_DATA/vanvliet/cib/140415-08
+- /home/achard/CTC_DATA/vanvliet/recA/151027-05
+- /home/achard/CTC_DATA/vanvliet/recA/151027-06
+# - /home/achard/CTC_DATA/vanvliet/recA/151027-10  # Has an empty frame, annoying
+- /home/achard/CTC_DATA/vanvliet/recA/151028-01
+- /home/achard/CTC_DATA/vanvliet/recA/151029-05
+- /home/achard/CTC_DATA/vanvliet/recA/151029-11
+- /home/achard/CTC_DATA/vanvliet/rpsM/151029_E1-6
+- /home/achard/CTC_DATA/vanvliet/rpsM/151101_E2-1
+- /home/achard/CTC_DATA/vanvliet/rpsM/151101_E2-2
+- /home/achard/CTC_DATA/vanvliet/rpsM/151101_E3-11
+- /home/achard/CTC_DATA/vanvliet/rpsM/151101_E4-12
+- /home/achard/CTC_DATA/vanvliet/metA/150317-07
+- /home/achard/CTC_DATA/vanvliet/metA/150318-06
+- /home/achard/CTC_DATA/vanvliet/metA/150331-12
+- /home/achard/CTC_DATA/vanvliet/metA/151222-10
+- /home/achard/CTC_DATA/vanvliet/metA/151222-11
+- /home/achard/CTC_DATA/vanvliet/pheA/150324-03
+- /home/achard/CTC_DATA/vanvliet/pheA/150324-05
+- /home/achard/CTC_DATA/vanvliet/pheA/150325-04
+- /home/achard/CTC_DATA/vanvliet/pheA/160112-04
+- /home/achard/CTC_DATA/vanvliet/trpL/150303-01
+- /home/achard/CTC_DATA/vanvliet/trpL/150303-08
+
+input_val:
+- /home/achard/CTC_DATA/vanvliet/trpL/150428-08
+- /home/achard/CTC_DATA/vanvliet/trpL/151021-11
+
+input_test:
+# - data/CTC_DATA/vanvliet/cib/140408-01  # dense labels not precise
+- /home/achard/CTC_DATA/vanvliet/rpsM/151029_E1-1  # ok
+- /home/achard/CTC_DATA/vanvliet/rpsM/151029_E1-5  # ok
+- /home/achard/CTC_DATA/vanvliet/rpsM/151101_E3-12  # ok
+- /home/achard/CTC_DATA/vanvliet/trpL/150309-04  # ok
+# - data/CTC_DATA/vanvliet/trpL/150310-05  # was empty
+- /home/achard/CTC_DATA/vanvliet/trpL/150310-11  # not in delta test set. quite some global moving!
+- /home/achard/CTC_DATA/vanvliet/pheA/160112-06  # ok. tricky. not in delta test set.