bm_experiments.bm_DROP module

Benchmark for DROP.

DROP is a approach for image registration and motion estimation based on Markov Random Fields.

See also

https://www.mrf-registration.net

Related Publication:

  1. Deformable Medical Image Registration: Setting the State of the Art with Discrete Methods

    Authors: Ben Glocker, Aristeidis Sotiras, Nikos Komodakis, Nikos Paragios Published in: Annual Review of Biomedical Engineering, Vol. 12, 2011, pp. 219-244

Installation for Linux

  1. Download executable according your operation system,

    https://www.mrf-registration.net/deformable/index.html

  2. Copy/extract executables and libraries to you favourite destination

  3. Install all missing libraries such as QT4 with OpenGL support

  4. Test calling the executable ./dropreg2d which should return something like:

    Usage: dropreg2d <source> <target> <result> <paramfile> [mask]

Usage

To see the explanation of particular parameters see the User Manual

http://www.mrf-registration.net/download/drop_user_guide_V1.05.pdf

Sample run:

mkdir ./results
python bm_experiments/bm_DROP.py         -t ./data-images/pairs-imgs-lnds_histol.csv         -d ./data-images         -o ./results         -DROP $HOME/Applications/DROP/dropreg2d         --path_config ./configs/DROP.txt         --visual --unique

Note

experiments was tested on Ubuntu (Linux) based OS system

Note

to check whether you have all needed libraries on Linux use ldd dropreg2d, see: https://askubuntu.com/a/709271/863070 AND set path to the libdroplib.so as export LD_LIBRARY_PATH=/lib:/usr/lib:/usr/local/lib, see: https://unix.stackexchange.com/a/67783 ; https://stackoverflow.com/a/49660575/4521646

Note

This method is not optimized nor suitable for large images, so all used images are first scaled to be 2000x2000 pixels and then the registration is performed. After registration is resulting image scaled back. The landmarks are scalded accordingly.

Glocker, Ben, et al. “Deformable medical image registration: setting the state of the art

with discrete methods.” Annual review of biomedical engineering 13 (2011): 219-244. https://pdfs.semanticscholar.org/0c5f/277d357e3667b18b5420fd660f221c935fcc.pdf

Copyright (C) 2017-2019 Jiri Borovec <jiri.borovec@fel.cvut.cz>

class bm_experiments.bm_DROP.BmDROP(params)[source]

Bases: birl.benchmark.ImRegBenchmark

Benchmark for DROP no run test while this method requires manual installation of DROP

For the app installation details, see module details.

Note

DROP requires gray scale images in MHD format where pixel values are in range (0, 255) of uint8.

Example

>>> from birl.utilities.data_io import create_folder, update_path
>>> path_out = create_folder('temp_results')
>>> path_csv = os.path.join(update_path('data-images'), 'pairs-imgs-lnds_mix.csv')
>>> params = {'path_table': path_csv,
...           'path_out': path_out,
...           'nb_workers': 2,
...           'unique': False,
...           'visual': True,
...           'exec_DROP': 'dropreg2d',
...           'path_config': os.path.join(update_path('configs'), 'DROP.txt')}
>>> benchmark = BmDROP(params)
>>> benchmark.run()  
>>> import shutil
>>> shutil.rmtree(path_out, ignore_errors=True)

initialise benchmark

Parameters

params (dict) – parameters

_clear_after_registration(item, patterns=('output*', '*.mhd', '*.raw'))[source]

clean unnecessarily files after the registration

Parameters

  • item (dict) – dictionary with registration information

  • patterns (list(str)) – string patterns of file names

Return dict

the same or updated registration info

_extract_warped_image_landmarks(item)[source]

get registration results - warped registered images and landmarks

Parameters

item (dict) – dictionary with registration params

Return dict

paths to warped images/landmarks

_generate_regist_command(item)[source]

generate the registration command

Parameters

item (dict) – dictionary with registration params

Return str|list(str)

the execution commands

_prepare()[source]

Prepare the experiment folder.

_prepare_img_registration(item)[source]

converting the input images to gra-scale and MHD format

Parameters

item (dict) – dictionary with registration params

Return dict

the same or updated registration info

static extend_parse(arg_parser)[source]

extent the basic arg parses by some extra required parameters

Return object

static extract_landmarks_shift_from_mhd(path_deform_x, path_deform_y, lnds)[source]

given pair of deformation fields and landmark positions get shift

Parameters

  • path_deform_x (str) – path to deformation field in X axis

  • path_deform_y (str) – path to deformation field in Y axis

  • lnds (ndarray) – landmarks

Return ndarray

shift for each landmarks

COL_TIME_CONVERT = 'conversion time [s]'[source]

time need for image conversion and optional scaling

MAX_IMAGE_DIAGONAL = 2828[source]

maximal image size (diagonal in pixels) recommended for DROP registration

REQUIRED_PARAMS = ['path_out', 'path_table', 'exec_DROP', 'path_config'][source]

required experiment parameters