borda/birl repository overview

⁠BIRL: Benchmark on Image Registration methods with Landmark validation

This project/framework is the key component of Automatic Non-rigid Histological Image Registration (ANHIR)⁠ challenge hosted at ISBI 2019⁠ conference. The related discussion is hosted on forum.image.sc⁠.

The project contains a set of sample images with related landmark annotations and experimental evaluation of state-of-the-art image registration methods.

The initial dataset of stained histological tissues⁠ is composed by image pairs of related sections (mainly, consecutive cuts). Each image in the pair is colored with a different stain. The registration of those images is a challenging task due to both artefacts and deformations acquired during sample preparation and appearance differences due to staining. For evaluation, we have manually placed landmarks in each image pair. There are at least 40 uniformly spread over the tissue. We do not put any landmarks in the background. For more information about annotation creation and landmarks handling, we refer to the special repository - Dataset: histology landmarks⁠.

The dataset is defined by a CSV file containing paths to target and sensed image and their related landmarks (see ./data-images/pairs-imgs-lnds_mix.csv). With the change of the cover table, the benchmarks can be used for any other image dataset.

⁠Features

List of the main/key features of this package:

• automatic execution of image registration of a sequence of image pairs
• integrated evaluation of registration performances using Target Registration Error (TRE)
• integrated visualization of performed registration
• running several image registration experiment in parallel
• resuming unfinished sequence of registration benchmark
• handling around dataset and creating own experiments
• using basic image pre-processing - normalizing
• rerun evaluation and visualisation for finished experiments

⁠Experiments with included methods

Even though this framework is completely customizable we include several image registration methods commonly used in medical imaging.

⁠Install methods and run benchmarks

For each registration method, different experiments can be performed independently using different values of the parameters or image pairs sets.

Sample execution of the "empty" benchmark template:

python birl/bm_template.py \
    -t ./data-images/pairs-imgs-lnds_mix.csv \
    -o ./results \
    -cfg sample_config.yaml \
    --preprocessing matching-rgb gray \
    --unique --visual

or with relative paths:

python birl/bm_template.py \
    -t ./data-images/pairs-imgs-lnds_histol.csv \
    -d ./data-images \
    -o ./results \
    -cfg sample_config.yaml \
    --preprocessing gray matching-rgb

The general Image Registration benchmarks contain couple required and optional parameters that are shared among 'all' methods/benchmarks. The brief description is the following...

Required parameters:

• -t/--path_table path to the cover table describing image/landmarks registration pairs
• -d/--path_dataset path to the dataset folder with images and landmarks
• -o/--path_out output path for saving results

Optional parameters:

• --preprocessing offer some image pre-processing before image registration starts, the order defines the order of performed operations; the options are matching-<color-space> (where <color-space> is for example rgb or hsv) equalize source to target image and gray converting both images to gray-scale
• --unique each experiment has creation stamp included in its name (prevent overwriting experiments with the same method)
• --visual generate a simple visualization of particular image registrations

Measure your computer performance using average execution time on several simple image registrations. The registration consists of loading images, denoising, feature detection, transform estimation, and image warping.

python bm_experiments/bm_comp_perform.py -o ./results

This script generates simple report exported in JSON file on a given output path.

⁠Prepared experimental docker image

Used prepared docker image from Docker Hub

docker run --rm -it borda/birl:SOTA-py3.7 bash

You can build it on your own, note it takes lots of time, be prepared.

git clone <git-repository>
docker image build \
    -t birl:py3.6 \
    -f bm_experiments/Dockerfile \
    --build-arg PYTHON_VERSION=3.6 \
    .

To run your docker use

docker image list
docker run --rm -it birl:py3.6 bash

⁠Included registration methods

For each benchmark experiment, the explanation about how to install and use a particular registration method is given in the documentation. Brief text at the top of each file.

• bUnwarpJ⁠ is the ImageJ⁠ plugin for elastic registration (optional usage of histogram matching and integration with Feature Extraction⁠).

  python bm_experiments/bm_bUnwarpJ.py \
      -t ./data-images/pairs-imgs-lnds_histol.csv \
      -d ./data-images \
      -o ./results \
      -Fiji ~/Applications/Fiji.app/ImageJ-linux64 \
      -cfg ./configs/ImageJ_bUnwarpJ_histol.yaml \
      --preprocessing matching-rgb \
      --visual --unique
  

  Copy
• Register Virtual Stack Slices (RVSS)⁠ is the ImageJ⁠ plugin for affine/elastic registration of a sequence of images.

  python bm_experiments/bm_RVSS.py \
      -t ./data-images/pairs-imgs-lnds_histol.csv \
      -d ./data-images \
      -o ./results \
      -Fiji ~/Applications/Fiji.app/ImageJ-linux64 \
      -cfg ./configs/ImageJ_RVSS_histol.yaml \
      --visual --unique
  

  Copy
• elastix⁠ is image registration toolkit based on ITK⁠ and it consists of a collection of algorithms that are commonly used to solve (medical) image registration problems. For more details see documentation⁠.

  python bm_experiments/bm_elastix.py \
      -t ./data-images/pairs-imgs-lnds_histol.csv \
      -d ./data-images \
      -o ./results \
      -elastix ~/Applications/elastix/bin \
      -cfg ./configs/elastix_affine.txt \
      --visual --unique
  

  Copy
• rNiftyReg⁠ is an R-native interface to the NiftyReg image registration library⁠ which contains programs to perform rigid, affine and non-linear registration of Nifty or analyse images. NiftyReg supports max image size 2048.

  python bm_experiments/bm_rNiftyReg.py \
      -t ./data-images/pairs-imgs-lnds_histol.csv \
      -d ./data-images \
      -o ./results \
      -R Rscript \
      -script ./scripts/Rscript/RNiftyReg_linear.r \
      --visual --unique
  

  Copy
• Advanced Normalization Tools⁠ (ANTs) is a medical imaging framework containing state-of-the-art medical image registration and segmentation methods.

  python bm_experiments/bm_ANTs.py \
      -t ./data-images/pairs-imgs-lnds_anhir.csv \
      -d ./data-images \
      -o ./results \
      -ANTs ~/Applications/antsbin/bin \
      -cfg ./configs/ANTs_SyN.txt
  

  Copy
  For illustration see ANTsPy registration tutorial⁠.

  python bm_experiments/bm_ANTsPy.py \
      -t ./data-images/pairs-imgs-lnds_histol.csv \
      -d ./data-images \
      -o ./results \
      -py python3 \
      -script ./scripts/Python/run_ANTsPy.py \
      --visual --unique
  

  Copy
• DROP⁠ is image registration and motion estimation based on Markov Random Fields.

  python bm_experiments/bm_DROP2.py \
      -t ./data-images/pairs-imgs-lnds_histol.csv \
      -d ./data-images \
      -o ./results \
      -DROP ~/Applications/DROP2/dropreg \
      -cfg ./configs/DROP2.txt \
      --visual --unique
  

  Copy
• ...

Some more image registration methods integrated in ImageJ are listed in Registration⁠.

⁠References

For complete references see bibtex⁠.

1. Borovec, J. (2019). BIRL: Benchmark on Image Registration methods with Landmark validation⁠. arXiv preprint arXiv:1912.13452⁠.
2. Borovec, J., Kybic, J., et al. (2020). ANHIR: Automatic Non-rigid Histological Image Registration Challenge⁠. In IEEE Transaction on Medical Imaging (TMI). DOI: 10.1109/TMI.2020.2986331⁠.
3. Borovec, J., Munoz-Barrutia, A., & Kybic, J. (2018). Benchmarking of image registration methods for differently stained histological slides⁠. In IEEE International Conference on Image Processing (ICIP) (pp. 3368–3372), Athens. DOI: 10.1109/ICIP.2018.8451040⁠