Drosophila Brain Aligner and Color-Depth MIP Pipeline

This repository contains a Fiji/ImageJ and CMTK pipeline for automatically registering multichannel Drosophila brain 3D confocal data to the JRC2018 unisex template and creating color-depth maximum-intensity projections (color-depth MIP, or CDM) from the aligned channels.

The pipeline was developed by Hideo Otsuna at HHMI Janelia Research Campus.

What the pipeline does

For each input brain volume, the pipeline:

1. Opens the microscopy volume and separates its channels.
2. Selects or estimates the structural reference channel.
3. Normalizes orientation, voxel size, brightness, and brain position in Fiji.
4. Performs affine registration followed by non-rigid registration with CMTK.
5. Applies the resulting transformation to every image channel.
6. Reformats the data into JRC2018 unisex 20x_HR space.
7. Calculates a zero-normalized cross-correlation alignment score. And export .mov.
8. Creates a color-depth MIP for each aligned channel. Color represents position along the Z axis, making neurite depth visible in a single 2D image. Also, it can submit to NeuronBridge for searching neurons.

Repository contents

• 20xBrain_Align_CMTK.sh — main pipeline driver.
• 20x_40x_Brain_Global_Aligner_Pipeline.ijm — Fiji preprocessing and orientation macro.
• TempCrop_after_affine.ijm — crops the template after affine alignment.
• 12bit_Conversion.ijm — normalizes the reference channel to 12-bit range.
• Score_Generator_Cluster.ijm — calculates alignment quality scores.
• Color_Depth_MIP_batch_0404_2019_For_Pipeline.ijm — generates color-depth MIPs.
• nrrd_compression.ijm — rewrites NRRD images with compression.
• Plugins_Color_MIP/ — compiled Fiji plugins, masks, and the color-depth LUT.
• Java_Files/ — Java source files for the custom plugin JARs where source is available.
• Template/ — core JRC2018 unisex registration templates and color-MIP masks.

Requirements

• macOS or Linux with Bash. The checked-in configuration currently selects the macOS branch.
• Fiji/ImageJ with Bio-Formats.
• CMTK, including registration, warp, and reformatx.
• The custom plugins in Plugins_Color_MIP/. Copy this folder into Fiji.app/plugins/
• JRC2018 unisex template volumes and the preprocessing/color-MIP masks referenced by the macros. The four core files used by the main alignment and color-MIP stages are included in Template/.
• Enough memory and disk space for multiple uncompressed or compressed 3D NRRD volumes.

The main 20x workflow expects these JRC2018 files in the configured template directory:

• JRC2018_UNISEX_20x_onemicron.nrrd
• JRC2018_UNISEX_20x_HR.nrrd
• MAX_JRC2018_UNISEX_20x_HR_2DMASK.tif
• JRC2018_UNISEX_20x_HR_3DMASK.nrrd

JRC2018_UNISEX_20x_HR.nrrd is tracked with Git LFS because it exceeds GitHub’s regular per-file size limit. Install Git LFS before adding or cloning this template.

The preprocessing macro also refers to JFRC2010 helper projections and masks, including JFRC2010_60pxMedP.tif, Lateral_JFRC2010_5time_smallerMIP.tif, JFRC2010_50pxSlice.tif, JFRC2010_ShapeMatchingMask.tif, and the selected average, median, or maximum projection image.

Installation and configuration

1. Clone this repository.

   git clone <repository-url>
   cd Brain-aligner-CDM-cleater-pipeline

2. Copy the JAR and class files from Plugins_Color_MIP/ into the Fiji plugins/ directory.

3. Copy Plugins_Color_MIP/PsychedelicRainBow2.lut into the Fiji luts/ directory.

4. Restart Fiji and confirm that the custom commands used by the macros are available. These include A4095 normalizer, Alignment ScoresSD, DSLT, DSLT3D LINE2, Gamma samewindow noswing, MIP right color, Nrrd Writer, and quit plugin.

5. Edit the local configuration block near the beginning of 20xBrain_Align_CMTK.sh:

   CMTK=/path/to/cmtk/bin
   FIJI=/path/to/Fiji/ImageJ-executable
   MACRO_DIR=/path/to/Brain-aligner-CDM-cleater-pipeline
   TempDir=/path/to/JRC2018/templates-and-masks

   The checked-in file contains paths from the original development workstation. They must be changed before running on another computer. The script currently sets test=1, which selects the macOS configuration block; set it appropriately if adapting the Linux configuration.

6. Make the driver executable if necessary:

   chmod +x 20xBrain_Align_CMTK.sh

Running the complete pipeline

./20xBrain_Align_CMTK.sh \
  /path/to/input_brain.tif \
  8 \
  0.46 \
  1.0 \
  false \
  Signal_amount \
  Max \
  ""

Arguments are positional:

Position	Argument	Description
1	Input image	Full path to the microscopy volume.
2	CPU threads	Number of threads used by CMTK and compatible Fiji plugins.
3	XY voxel size	Pixel width/height in micrometers.
4	Z voxel size	Slice spacing in micrometers.
5	Force voxel size	true to use the supplied voxel sizes; false to prefer metadata when available.
6	Reference channel	Signal_amount, ch1, ch2, ch3, or ch4.
7	Comparison method	Max or Median for preprocessing/reference comparison.
8	Extra template	Optional additional reformatted output: 63x, 40x, 0.38, or an empty string.

The preprocessing macro contains readers for common Fiji/Bio-Formats inputs, including TIFF, LSM, CZI, OIF, LIF, NRRD, H5J, V3DPBD, AM, and MHA. Actual support depends on the readers installed in Fiji.

Important input-path behavior

Use an input filename and directory path without spaces. The current shell script attempts to rename an input containing a space by moving the original file. To protect source data, use a copy of the input when testing the pipeline.

Outputs

In the current macOS configuration, the script creates a working directory beside the input image using the input filename without its extension. Important outputs include:

• <sample>_01.nrrd, <sample>_02.nrrd, etc. — preprocessed channels.
• affine.xform — CMTK affine transformation.
• warp.xform — CMTK non-rigid transformation.
• <sample>_U_20x_HR_01.nrrd, etc. — channels reformatted into JRC2018 unisex high-resolution space.
• *_Score.property and score logs — registration quality results.
• preprocessing logs, metadata, and diagnostic images.

Color-depth MIPs are written to an MIP/ directory beside the sample working directory. Depending on the input and channel configuration, output images may be PNG or TIFF.

Existing intermediate files are generally detected and reused, allowing an interrupted job to resume. Review the log before assuming a resumed run completed every stage successfully.

Running only color-depth MIP generation

The MIP macro accepts a comma-separated argument string containing the input directory, input filename, output directory, and template/mask directory. Directory arguments must end with / because the macro concatenates paths directly.

/path/to/Fiji/ImageJ-executable --headless \
  -macro Color_Depth_MIP_batch_0404_2019_For_Pipeline.ijm \
  "/path/to/aligned/,sample_U_20x_HR_01.nrrd,/path/to/MIP/,/path/to/templates/"

The default MIP settings perform automatic brightness normalization, signal/background processing, depth coloring with PsychedelicRainBow2, and addition of a slice-depth color scale. Settings such as thresholds, LUT, output format, and processed slice range are defined near the top of the macro.

Notes and limitations

• This is research software and should be validated on representative data before batch processing.
• The main driver is currently configured for the JRC2018 unisex template (gender=u) and a 20x workflow.
• Several paths and environment choices are configured directly in the shell script rather than through a separate configuration file.
• Alignment quality depends on correct voxel calibration, orientation, reference-channel selection, signal quality, and availability of the matching template/mask files.
• The repository contains compiled plugins for reproducibility. Java sources are provided in Java_Files/ where available.

License

This project is distributed under the GNU General Public License v3.0. See LICENSE for the full text.