3D Histology Reconstruction

This repository hosts the code for 3D histology reconstruction using a probabilistic model of spatial deformation that yields reconstructions for multiple histological stains that are jointly smooth, robust to outliers and follow the reference shape.

The framework is used for accurate 3D reconstruction of two stains (Nissl and parvalbumin) from the Allen human brain atlas (/scripts). Two different base registration algorithms are used: learning-based (RegNet) using PyTorch and a more standard approach using NiftyReg package.

Requirements:

Python
The code run on python v3.6.9 and several external libraries listed under requirements.txt

Gurobi package
Gurobi optimizer is used to solve the linear program. You can download it from here and create an academic free license from here

NiftyReg package
Needed to run the algorithm using NiftyReg as base registration algorithm. http://cmictig.cs.ucl.ac.uk/wiki/index.php/NiftyReg_documentation

MATLAB
Needed to download data from the Allen repository.

Run the code

• Set-up configuration files

  • setup.py: original absolute paths are specified here. Please, update this according to your setting.
  • config_dev.py: experiment parameters are specified here, specially regarding neural network training (loss, network, etc...)
  • config_data.py: data parameters are specified here. You may not want to modify this file

• Download data from the Allen repository
  From /database/preprocessing, run the download_allen.m script to download all sections and generate the corresponding masks. The initial linear alignment between the histology stack and the MR volume would be also downloaded from our public data repository (XXXX). Finally, you'll also find the MNI template (T2 contrast) and the correspondig segmentation for mapping the reconstructions to the MNI space.

• Create dataset
  From /database/preprocessing, run the generate_initial_images.py file in order to set the database properly to be used in the code (naming convention, ordering, etc...). The slice_info_* .csv files are used to map images from the Allen repository to the database convention used in this project.

• Generate images
  From /scripts, run the generate_slices.py file to generate the images that will be used in the project, at the appropriate resolution and shape.

• Train the registration networks
  Under /networks, there are several script to train and test intra and intermodality registration networks. You can run any of these from the command line with the appropriate parameters and configuration (config_dev.py)

• Build the graph and run the algorithm
  Under /algorithm there are the scripts to build the graph ( initialize_graph_X.py ) and run the algorithm (algorithm_X.py ) for RegNet and NR registration algorithms.

• Group blocks
  Run the group_blocks.py file under /scripts/visualization. This wil group the *.tree images in a single file. You need to specify which reconstruction you want to group.

• Deform colored images
  Use the deform_images.py file under /scripts/visualization to deform the original colored images from each contrast and create a *.tree file for each.

• Equalize and resample
  Use the eq_and_resample.py file under /scripts/visualization for simple equalization of histology sections and resampling along the stack directon at the desired resolution.

Code updates

26 March 2021:

• Initial commit

Citation

[1] Robust joint registration of multiple stains and MRI for multimodal 3D histology reconstruction: Application to the Allen human brain atlas. Adrià Casamitjana, Marco Lorenzi, Sebastiano Ferraris, Loïc Peter, Marc Modat, Allison Stevens, Bruce Fischld, Tom Vercauteren, Juan Eugenio Iglesias. Medical image analysis 75 (2022): 102265.

References

[1] Model-based refinement of nonlinear registrations in 3D histology reconstruction Juan Eugenio Iglesias, Marco Lorenzi, Sebastiano Ferraris, Loïc Peter, Marc Modat, Allison Stevens, Bruce Fischl, and Tom Vercauteren MICCAI 2018

[2] VoxelMorph: A Learning Framework for Deformable Medical Image Registration Guha Balakrishnan, Amy Zhao, Mert R. Sabuncu, John Guttag, Adrian V. Dalca TMI 2019