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

As the data we use a dataset of stain histological tissues image pairs of related (mainly consecutive cuts) sections where each of them in the pair is colour different stain. The apprentice difference and deformations during sensing makes the image registration challenging task.

For evaluation we have set of manually placed landmarks in each image pair at least 40 uniformly spread over the tissue (we do not put any landmarks in backround). For more information about annotation creation and handling handling landmarks we refer special repository - Dataset: histology landmarks.

The dataset is defined by CSV file containing paths to reference and sensed image and their related landmarks (see ./data_images/pairs-imgs-lnds_mix.csv).

The project contains also a few folders and its brief description is:

• benchmarks - package with benchmark & template and general useful utils
  • utilities - useful tools and functions
• bm_dataset - package with 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 mainly for ImageJ
• scripts - useful scripts handling some staff around the benchmark itself

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

There is an option to generate synthetic data, such that you set an initial image and landmarks and the script generates set of geometrical deformed images with also change color space and related computed new landmarks.

python scripts/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 you have generated the synthetic datasets we generate the cover csv file which contains the registration pairs such as Reference and Moving image (landmarks). We generate then in two modes "first-all" for registering the first one to all others and "all-all" for registering each image to all other. (note A-B is the same as B-A so it is the just once)

python scripts/generate_registration_pairs.py \
    -i ./data_images/synth_dataset/*.jpg \
    -l ./data_images/synth_dataset/*.csv \
    -csv ./data_images/cover_synth-dataset.csv \
    --mode all-all

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

• ...

The description how to install and use particular registration methods is described in the documentation (top in each file) for each benchmark experiments.

Experiments on each registration methods can be performed independently with respect to selected parameters and the given set of chosen image pairs.

Sample execution of the "empty" benchmark template

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

[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 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