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

The dataset of stained histological tissues is composed by image pairs of related sections (mainly, consecutive cuts). Each image in the pair is coloured with a different stain. The registration of those images is a challenging task due to both artifacts and deformations acquired during sample preparation and apparece 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 reference and sensed image and their related landmarks (see ./data_images/pairs-imgs-lnds_mix.csv).

The project contains the following folders:

• benchmarks - package with benchmark & template and general useful utils
  • utilities - useful tools and functions
• bm_dataset - package handling dataset creation and servicing
• bm_experiments - package with particular benchmark experiments
• data_images - folder with input sample data
  • images - sample image pairs (reference and sensed one)
  • landmarks - related landmarks to images in previous folder
  • lesions_ - samples of histology tissue with annotation
  • rat-kidney_ - samples of histology tissue with annotation
• configs - configs for registration methods
• macros_ij - macros for ImageJ

In the data_images folder we provide some sample images with landmarks for registration. These sample registration pairs are saved in data_images/pairs-imgs-lnds_mix.csv.

There is a script to generate synthetic data. Just set an initial image and their corresponding landmarks. The script will generate a set of geometrically deformed images mimicking different stains and compute the new related landmarks.

python bm_dataset/create_real_synth_dataset.py \
    -i ./data_images/images/Rat_Kidney_HE.jpg \
    -l ./data_images/landmarks/Rat_Kidney_HE.csv \
    -o ./output/synth_dataset \
    -nb 5 --nb_jobs 3 --visual

When the synthetic datasets have been created, the cover csv file which contains the registration pairs (Reference and Moving image (landmarks)) is generated. Two modes are created: "first2all" for registering the first image to all others and "each2all" for registering each image to all other. (note A-B is the same as B-A)

python bm_dataset/generate_regist_pairs.py \
    -i ./data_images/synth_dataset/*.jpg \
    -l ./data_images/synth_dataset/*.csv \
    -csv ./data_images/cover_synth-dataset.csv \
    --mode each2all

• bUnwarpJ is the ImageJ plugin for elastic registration (optional integration with Feature Extraction).
• ...

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.

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:

mkdir results
python benchmark/bm_template.py \
    -c ./data_images/pairs-imgs-lnds_mix.csv \
    -o ./results \
    --an_executable none \
    --unique --visual

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 generate simple report exported in JSON file on given output path.

[TODO]

The project is using the standard BSD license.

For complete references see bibtex.

1. 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). Athens.

Configure local environment

Create your own local environment, for more information see the User Guide, and install dependencies requirements.txt contains list of packages and can be installed as

@duda:~$ cd BIRL 
@duda:~/BIRL$ virtualenv env
@duda:~/BIRL$ source env/bin/activate  
(env)@duda:~/BIRL$ pip install -r requirements.txt  
(env)@duda:~/BIRL$ python ...

and in the end terminating...

(env)@duda:~$ deactivate

Running docString tests - documentation and samples of doc string on pymotw and python/docs

Listing dataset in command line

find . | sed -e "s/[^-][^\/]*\// |/g" -e "s/|\([^ ]\)/|-\1/" >> dataset.txt