Registration & Reference Processing — Command Line Guide

This document describes the three main CLI tools used in the registration workflow:

1. assembled_reg.py — full sample-to-reference registration
2. downsample_ref.py — preprocessing of reference images
3. separate_ref.py — splitting reference label masks

Before running any command:

• Navigate to the regtry folder.

• Make sure the virtual environment is activated (you should see (venv) in your terminal prompt). if not, activate it with:

  ../nnUNet/venv/Scripts/Activate.ps1
  

---

1. Registration Pipeline — assembled_reg.py

Runs the complete registration workflow, including preprocessing, ANTs/CMTK registration, and label assignment.

Usage

python assembled_reg.py <sample_LIF> <reference_folder> <output_folder> <label_csv> [--cmtk] [--output-metric]

Arguments

• sample_LIF Path to the .lif file containing the sample stack.

• reference_folder Folder containing the processed reference dataset (e.g., reference2010 or reference2018).

• output_folder Output location where all registration results will be written.

• label_csv CSV file storing label definitions; generated automatically if it does not exist.

• --cmtk (optional) Use CMTK instead of ANTs for optic lobe registration.

• --output-metric (optional) Export similarity/metric scores to a CSV.

Example

python assembled_reg.py E:/Gabriela/lifFiles/sample.lif ./reference2010 ./reference ../outputs ./reference/labels.csv --cmtk --output-metric

---

2. Reference Downsampling — downsample_ref.py

Prepares the reference images by downsampling them to the required voxel size and spacing.

Usage

python downsample_ref.py <ref_folder> [--format <ext>] [--spacing <x,y,z>]

Arguments

• ref_folder Directory containing the reference image files.

• --format, -f (optional) File format of the images (default: tif). Must be either nrrd or tif.

• --spacing, -s (optional but required for tif) Comma-separated spacing values (e.g., 0.62,0.62,0.62). Required when --format is tif, since TIFF images do not contain spacing metadata. Ignored when format is nrrd.

Examples

NRRD input (spacing taken from file):

python downsample_ref.py "./reference" --format nrrd

TIFF input (spacing must be provided):

python downsample_ref.py "./reference" --format tif --spacing "0.62,0.62,0.62"

---

3. Reference Label Separation — separate_ref.py

Splits a whole-brain reference label mask into left optic lobe (OLL) and right optic lobe (OLR) labels using user-provided ID lists. Optionally applies the same split to an intensity image.

Usage

python separate_ref.py <label_path> <OLL_label_ids> <OLR_label_ids> [--intensityImg_path <path>]

Arguments

• label_path Path to the whole reference label image (e.g., label_whole_01.nrrd).

• OLL_label_ids Comma-separated list of label IDs belonging to the left optic lobe.

• OLR_label_ids Comma-separated list of label IDs belonging to the right optic lobe.

• --intensityImg_path (optional) Path to the intensity image to be split in the same way.

Example (PowerShell)

python separate_ref.py `
  "./reference/label_whole_01.nrrd" `
  "2,3,17,19" `
  "28,29,41,43" `
  --intensityImg_path "./reference/ref_whole_01.nrrd"