Brain registration and atlas processing using BrainGlobe and Imaris

This repository contains a pipeline for registering Imaris .ims brain images to a BrainGlobe atlas, processing the resulting masks and uploading them to Imaris as surfaces. The pipeline is divided into 3 main parts, that can be used separately:

1. Raw .ims data downscaling (ImageJ macro: 00a_rescaleMacroBatch.ijm/00b_rescaleMacro.ijm), followed by brain atlas registration in BrainGlobe (not automated)
2. Processing of the brain region mask (Python script: 01_mask_processing_pipeline.py) - adjusting the level of details, discarding small disconnected components and converting the mask from 32-bit to 16-bit image.
3. Importing the mask to Imaris (built-in Imaris function) followed by importing corresponding brain region and IDs (custom Imaris XTension: XT_ImportBrainRegionIdentificators.m).

---

Requirements

• ImageJ / Fiji (Schindelin et al., 2012) - for part 1
• Miniconda - for part 1 and 2
• Python 3.12 - for part 1 and 2
• BrainGlobe (Claudi et al., 2021; Tyson et al., 2022) - for part 1 and 2
• Imaris (with XTension support) - for part 3

---

Installation

1. Set up the Python BrainGlobe environment (required for registration and subsequent mask processing)

conda create -n brainglobe_env python=3.12
conda activate brainglobe_env
pip install brainglobe

For more detailed description, follow information on the BrainGlobe webpage: https://brainglobe.info/documentation/index.html

2. Install the provided Imaris XTension (required for import of brain region names and IDs to Imaris)

Copy the XT_ImportBrainRegionIdentificators.py to your Imaris XTensions folder, such as:

C:\Users\<YourUsername>\Documents\Imaris\XTensions

(Path to Imaris extension folder can be set in Imaris Preferences.)

Restart Imaris.

---

1. Rescaling and registration

Rescaling (ImageJ / Fiji)

Detailed Documentation

Rescaling is included for easier handling of large datasets. (such as in case of lightsheet data)

1. Open the macro script in Fiji. If you want to process more files at once, open the batch script option (00a_rescaleMacro.ijm), otherwise, use the second option that will process a single image (00b_rescaleMacro.ijm)
2. In the macro, adjust parameters if needed.
3. Run the macro.

Registration (manually in Napari + BrainGlobe)

1. Open Napari and drag the .tiff image (use 'napari builtins' reader, if asked).
2. Download the atlas if needed via brainrender → Manage atlas versions
3. Open brainreg plugin
4. Configure:
   • Atlas: perens_lsmf_mouse_20um suitable for lightsheet data, or other selected
   • Orientation: Use Check Orientation tool (docs)
   • Region: Full brain or left/right hemisphere
   • Voxel size: ~20 µm (check in Fiji: Image → Properties)
   • Save original orientation: Check this option
   • Output directory: Set accordingly
   • Keep other settings default unless optimizing
5. Click Run
6. If registration misaligned, try changing Smoothing sigma to 0, and optimize other parameters

2. Mask processing (Python script)

Detailed Documentation

The processing adjusts the level of detail, discards small regions and converts the mask to 16-bit, which is needed for loading to Imaris.

1. Open 01_mask_processing_pipeline.py in any text or code editor.
2. If needed, adjust parameters, such as the list of regions to flatten.
3. Run the script. 

You can run the script from the Anaconda Prompt as follows:

• Open the Anaconda Prompt.

• Activate the BrainGlobe environment:

  conda activate brainglobe_env

• Navigate to the folder containing the script:

  cd path/to/your/script

• Run the script:

  python mask_processing_pipeline.py

4. When prompted, select the original mask path.

. The script will output the processed mask (adjusted_mask.tiff) in the same folder.

3. Brain region import to Imaris (Custom Imaris XTension)

Detailed Documentation

IMPORTANT: If you want to directly import masks from BrainGlobe to Imaris without using the script from part 2, make sure to convert the mask to 16-bit before using hte Import Segmentation/Label function. If you attempt importing a 32-bit mask, Imaris seems to get stuck.

1. Open original .ims file

2. Go to:

   Import → Import Segmentation/Label
   

   and select the adjusted mask → This creates new surfaces

   IMPORTANT: The mask cannot be 32-bit, otherwise the loading gets stuck.

3. Select the surfaces object, in XTension tab → Run Brain region identificators import

4. When prompted, provide:

   • adjusted_mask.tif (the adjusted mask that was loaded in the previous step)
   • used_region_ids.csv (a CSV file with two columns: region_id for the numeric region identifiers and region_name for the corresponding anatomical names)

5. Wait for label import to finish (may take a few minutes)

Alternative import to Imaris

In case of big datasets, the import of identifiers can get stuck. In that case, you can use a workaround. Instead of opening the original .ims file, you can use the downsampled .tiff file directly:

1. Open the downsampled .tiff file in Imaris.
   • It will be automatically converted to .ims format.
2. Use the same mask import procedure as described above:

   Import → Import Segmentation/Label
   

   • This creates new surfaces.
3. Run the Brain region identificators import XTension on the surfaces.
4. When prompted, provide:
   • adjusted_mask.tif
   • used_region_ids.csv
5. Once the labels are imported, export the scene via:

   File → Export Scene
   

6. Open the original .ims file.
7. Import the previously exported scene using:

   File → Import Scene → Add to existing objects
   

8. Important: Before importing, make sure the voxel origin of the image (minimum µm) is set to 0 in all dimensions. Otherwise, the imported surfaces may be shifted.

This approach is useful if you want to work with a smaller image first and transfer results back to the full-resolution dataset.

---

Author & Citation

Iva Švecová, Institute of Experimental Medicine (iva.svecova@iem.cas.cz)

If you use this code, please cite the repository using the following DOI:

---