minor refactoring

* rename data-images
* move figures
* docs preview
* update config

.travis.yml

@@ -91,10 +91,10 @@ script:
   # sample run
   - mkdir results && touch configs/sample_config.yaml
   - python bm_experiments/bm_comp_perform.py -o ./results -n 1
-  - python birl/bm_template.py -t ./data_images/pairs-imgs-lnds_mix.csv -o ./results --visual --unique -cfg configs/sample_config.yaml
-  - rm ./data_images/*_/*/*_HE.csv  # remove target landmarks from histol. tissue
-  - python birl/bm_template.py -n anhir -t ./data_images/pairs-imgs-lnds_histol.csv -d ./data_images -o ./results --preprocessing matching-rgb gray -cfg configs/sample_config.yaml
-  - python bm_experiments/evaluate_experiment.py -d ./data_images -e ./results/BmTemplate_anhir --visual
+  - python birl/bm_template.py -t ./data-images/pairs-imgs-lnds_mix.csv -o ./results --visual --unique -cfg configs/sample_config.yaml
+  - rm ./data-images/*_/*/*_HE.csv  # remove target landmarks from histol. tissue
+  - python birl/bm_template.py -n anhir -t ./data-images/pairs-imgs-lnds_histol.csv -d ./data-images -o ./results --preprocessing matching-rgb gray -cfg configs/sample_config.yaml
+  - python bm_experiments/evaluate_experiment.py -d ./data-images -e ./results/BmTemplate_anhir --visual
 
 after_success:
   - coverage report

MANIFEST.in

@@ -11,7 +11,7 @@ include *.md
 include LICENSE
 
 # Include the visualisations
-recursive-include figures *.jpg
+recursive-include assets *.jpg
 
 # Include the util scripts and experiments
 recursive-include bm_dataset *.py
@@ -27,7 +27,7 @@ recursive-exclude notebooks *.ipynb *.txt
 exclude notebooks
 
 # Include the data files
-recursive-include data_images *
+recursive-include data-images *
 
 # Include the method config files
 recursive-include configs *

README.md

@@ -32,9 +32,9 @@ For evaluation, we have manually placed landmarks in each image pair. There are
 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](http://borda.github.com/dataset-histology-landmarks).
 
-![images-landmarks](docs/source/_figures/images-landmarks.jpg)
+![images-landmarks](assets/images-landmarks.jpg)
 
-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.
+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
@@ -61,7 +61,7 @@ The project contains the following folders:
 * `bm_dataset` - package handling dataset creation and servicing
 * `bm_experiments` - package with particular benchmark experiments
 * `configs` - configs for registration methods
-* `data_images` - folder with input sample data
+* `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
@@ -90,8 +90,8 @@ where the numbers match desired version
 
 ## Before benchmarks (pre-processing) 
 
-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`. 
+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`. 
 You can create your own costume cover table for a given dataset (folder with images and landmarks) by hand or use script `bm_dataset/create_registration_pairs.py` assuming the same folder structure `<dataset>/<image-set>/<scale>/<images-and-landmarks>` as for the [CIMA dataset](http://cmp.felk.cvut.cz/~borovji3/?page=dataset).
 
 ### Prepare synthetic data
@@ -102,8 +102,8 @@ The script will generate a set of geometrically deformed images mimicking differ
 
 ```bash
 python bm_dataset/create_real_synth_dataset.py \
-    -i ./data_images/images/Rat_Kidney_HE.jpg \
-    -l ./data_images/landmarks/Rat_Kidney_HE.csv \
+    -i ./data-images/images/Rat_Kidney_HE.jpg \
+    -l ./data-images/landmarks/Rat_Kidney_HE.csv \
     -o ./output/synth_dataset \
     -nb 5 --nb_workers 3 --visual
 ```
@@ -116,9 +116,9 @@ _(note A-B is the same as B-A)_
 
 ```bash
 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 \
+    -i ./data-images/synth_dataset/*.jpg \
+    -l ./data-images/synth_dataset/*.csv \
+    -csv ./data-images/cover_synth-dataset.csv \
     --mode each2all
 ```
 
@@ -127,15 +127,15 @@ python bm_dataset/generate_regist_pairs.py \
 We offer a script for scaling images in to particular scales for example
 ```bash
 python bm_dataset/rescale_tissue_images.py \
-    -i "./data_images/rat-kidney_/scale-5pc/*.jpg" \
+    -i "./data-images/rat-kidney_/scale-5pc/*.jpg" \
     -scales 10 -ext .png --nb_workers 2
 ```
 
 We introduce an option how to randomly take only a subset (use `nb_selected`) of annotated landmarks and also add some synthetic point (filling points up to `nb_total`) which are across set aligned using estimate affine transformation.
 
 ```bash
 python bm_dataset/rescale_tissue_landmarks.py \
-    -a ./data_images -d ./output \
+    -a ./data-images -d ./output \
     --nb_selected 0.5 --nb_total 200
 ``` 
 
@@ -150,7 +150,7 @@ Moreover we developed two additional script for converting large images, handlin
 
 Even though this framework is completely customizable we include several image registration methods commonly used in medical imaging.
 
-![visualise-regist-results](docs/source/_figures/registration_visual_landmarks.jpg)
+![visualise-regist-results](assets/registration_visual_landmarks.jpg)
 
 ### Install methods and run benchmarks
 
@@ -159,7 +159,7 @@ For each registration method, different experiments can be performed independent
 Sample execution of the "empty" benchmark template:
 ```bash
 python birl/bm_template.py \
-    -t ./data_images/pairs-imgs-lnds_mix.csv \
+    -t ./data-images/pairs-imgs-lnds_mix.csv \
     -o ./results \
     -cfg sample_config.yaml \
     --preprocessing matching-rgb gray \
@@ -168,8 +168,8 @@ python birl/bm_template.py \
 or with relative paths:
 ```bash
 python birl/bm_template.py \
-    -t ./data_images/pairs-imgs-lnds_histol.csv \
-    -d ./data_images \
+    -t ./data-images/pairs-imgs-lnds_histol.csv \
+    -d ./data-images \
     -o ./results \
     -cfg sample_config.yaml \
     --preprocessing gray matching-rgb
@@ -187,7 +187,7 @@ The general Image Registration benchmarks contain couple required and optional p
 * `--unique` each experiment has creation stamp included in its name (prevent overwriting experiments with the same method)
 * `--visual` generate a simple visualisation of particular image registrations
 
-![preprocessing-hist-matching](docs/source/_figures/Rat-Kidney_histogram-matching.jpg)
+![preprocessing-hist-matching](assets/Rat-Kidney_histogram-matching.jpg)
 
 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. 
@@ -204,8 +204,8 @@ For each benchmark experiment, the explanation about how to install and use a pa
 * **[bUnwarpJ](http://imagej.net/BUnwarpJ)** is the [ImageJ](https://imagej.nih.gov/ij/) plugin for elastic registration (optional usage of histogram matching and integration with [Feature Extraction](http://imagej.net/Feature_Extraction)).
     ```bash
     python bm_experiments/bm_bUnwarpJ.py \
-        -t ./data_images/pairs-imgs-lnds_histol.csv \
-        -d ./data_images \
+        -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 \
@@ -215,8 +215,8 @@ For each benchmark experiment, the explanation about how to install and use a pa
 * **[Register Virtual Stack Slices (RVSS)](https://imagej.net/Register_Virtual_Stack_Slices)** is the [ImageJ](https://imagej.nih.gov/ij/) plugin for affine/elastic registration of a sequence of images.
     ```bash
     python bm_experiments/bm_RVSS.py \
-        -t ./data_images/pairs-imgs-lnds_histol.csv \
-        -d ./data_images \
+        -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 \
@@ -225,8 +225,8 @@ For each benchmark experiment, the explanation about how to install and use a pa
 * **[elastix](http://elastix.isi.uu.nl/)** is image registration toolkit based on [ITK](http://www.itk.org/) and it consists of a collection of algorithms that are commonly used to solve (medical) image registration problems. For more details see [documentation](http://elastix.isi.uu.nl/download/elastix_manual_v4.8.pdf).
     ```bash
     python bm_experiments/bm_elastix.py \
-        -t ./data_images/pairs-imgs-lnds_histol.csv \
-        -d ./data_images \
+        -t ./data-images/pairs-imgs-lnds_histol.csv \
+        -d ./data-images \
         -o ./results \
         -elastix ~/Applications/elastix/bin \
         -cfg ./configs/elastix_affine.txt \
@@ -235,8 +235,8 @@ For each benchmark experiment, the explanation about how to install and use a pa
 * **[rNiftyReg](https://github.com/jonclayden/RNiftyReg)** is an R-native interface to the [NiftyReg image registration library](http://sourceforge.net/projects/niftyreg/) which contains programs to perform rigid, affine and non-linear registration of Nifty or analyse images. _NiftyReg supports max image size 2048._
     ```bash
     python bm_experiments/bm_rNiftyReg.py \
-        -t ./data_images/pairs-imgs-lnds_histol.csv \
-        -d ./data_images \
+        -t ./data-images/pairs-imgs-lnds_histol.csv \
+        -d ./data-images \
         -o ./results \
         -R Rscript \
         -script ./scripts/Rscript/RNiftyReg_linear.r \
@@ -245,17 +245,17 @@ For each benchmark experiment, the explanation about how to install and use a pa
 * **[Advanced Normalization Tools](http://stnava.github.io/ANTs/) (ANTs)** is a medical imaging framework containing state-of-the-art medical image registration and segmentation methods.
     ```bash
     python bm_experiments/bm_ANTs.py \
-        -t ./data_images/pairs-imgs-lnds_anhir.csv \
-        -d ./data_images \
+        -t ./data-images/pairs-imgs-lnds_anhir.csv \
+        -d ./data-images \
         -o ./results \
         -ANTs ~/Applications/antsbin/bin \
         -cfg ./configs/ANTs_SyN.txt
     ```
     For illustration see ANTsPy [registration tutorial](https://github.com/ANTsX/ANTsPy/blob/master/tutorials/10minTutorial.ipynb).
     ```bash
     python bm_experiments/bm_ANTsPy.py \
-        -t ./data_images/pairs-imgs-lnds_histol.csv \
-        -d ./data_images \
+        -t ./data-images/pairs-imgs-lnds_histol.csv \
+        -d ./data-images \
         -o ./results \
         -py python3 \
         -script ./scripts/Python/run_ANTsPy.py \
@@ -264,8 +264,8 @@ For each benchmark experiment, the explanation about how to install and use a pa
 * **[DROP](https://github.com/biomedia-mira/drop2)** is image registration and motion estimation based on Markov Random Fields.
     ```bash
     python bm_experiments/bm_DROP2.py \
-        -t ./data_images/pairs-imgs-lnds_histol.csv \
-        -d ./data_images \
+        -t ./data-images/pairs-imgs-lnds_histol.csv \
+        -d ./data-images \
         -o ./results \
         -DROP ~/Applications/DROP2/dropreg \
         -cfg ./configs/DROP2.txt \

appveyor.yml

@@ -79,7 +79,7 @@ test_script:
   - tox -v --sitepackages --parallel auto
   - mkdir results && touch configs/sample_config.yaml
   - python bm_experiments/bm_comp_perform.py -o ./results -n 1
-  - python birl/bm_template.py -n anhir -t ./data_images/pairs-imgs-lnds_mix.csv -o ./results --preprocessing matching-rgb gray --unique --visual -cfg configs/sample_config.yaml
+  - python birl/bm_template.py -n anhir -t ./data-images/pairs-imgs-lnds_mix.csv -o ./results --preprocessing matching-rgb gray --unique --visual -cfg configs/sample_config.yaml
 
 on_success:
   - coverage report

birl/benchmark.py

@@ -8,7 +8,7 @@
 
     mkdir ./results
     python benchmarks/bm_registration.py \
-        -t data_images/pairs-imgs-lnds_histol.csv -d ./data_images \
+        -t data-images/pairs-imgs-lnds_histol.csv -d ./data-images \
         -o ./results --unique
 
 Copyright (C) 2016-2019 Jiri Borovec <[email protected]>
@@ -77,7 +77,7 @@ class ImRegBenchmark(Experiment):
     >>> # Running in single thread:
     >>> 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')
+    >>> 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': 1,
@@ -92,7 +92,7 @@ class ImRegBenchmark(Experiment):
     >>> # Running in multiple parallel threads:
     >>> 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')
+    >>> 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,
@@ -938,7 +938,7 @@ def filter_paired_landmarks(item, path_dataset, path_reference, col_source, col_
     :param str col_target: column name of landmarks to be compared
     :return tuple(float,ndarray,ndarray): match ratio, filtered ref and move landmarks
 
-    >>> p_data = update_path('data_images')
+    >>> p_data = update_path('data-images')
     >>> p_csv = os.path.join(p_data, 'pairs-imgs-lnds_histol.csv')
     >>> df = pd.read_csv(p_csv)
     >>> ratio, lnds_ref, lnds_move = filter_paired_landmarks(dict(df.iloc[0]), p_data, p_data,

birl/bm_template.py

@@ -11,8 +11,8 @@
     mkdir ./results
     touch sample-config.yaml
     python birl/bm_template.py \
-        -t ./data_images/pairs-imgs-lnds_histol.csv \
-        -d ./data_images \
+        -t ./data-images/pairs-imgs-lnds_histol.csv \
+        -d ./data-images \
         -o ./results \
         --visual --unique \
         -cfg ./sample-config.yaml
@@ -57,7 +57,7 @@ class BmTemplate(ImRegBenchmark):
     >>> # Running in single thread:
     >>> 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')
+    >>> path_csv = os.path.join(update_path('data-images'), 'pairs-imgs-lnds_mix.csv')
     >>> open('sample_config.yaml', 'w').close()
     >>> BmTemplate.main({
     ...       'path_table': path_csv,
@@ -75,7 +75,7 @@ class BmTemplate(ImRegBenchmark):
     >>> # Running in multiple parallel threads:
     >>> 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')
+    >>> 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,

birl/utilities/data_io.py

@@ -365,7 +365,7 @@ def convert_image_to_nifti(path_image, path_out_dir=None):
     :param str path_out_dir: path to output folder
     :return str: resulted image
 
-    >>> path_img = os.path.join(update_path('data_images'), 'images',
+    >>> path_img = os.path.join(update_path('data-images'), 'images',
     ...                         'artificial_moving-affine.jpg')
     >>> path_img2 = convert_image_to_nifti(path_img, '.')
     >>> path_img2  # doctest: +ELLIPSIS
@@ -513,7 +513,7 @@ def convert_image_from_mhd(path_image, path_out_dir=None, img_ext='.png', scalin
         resulting image will be larger by this factor
     :return str: path to exported image
 
-    >>> path_img = os.path.join(update_path('data_images'), 'images',
+    >>> path_img = os.path.join(update_path('data-images'), 'images',
     ...                         'artificial_reference.jpg')
     >>> path_img = convert_image_to_mhd(path_img, scaling=1.5)
     >>> convert_image_from_mhd(path_img, scaling=1.5)  # doctest: +ELLIPSIS
@@ -549,7 +549,7 @@ def convert_image_to_mhd(path_image, path_out_dir=None, to_gray=True, overwrite=
         resulting image will be smaller by this factor
     :return str: path to exported image
 
-    >>> path_img = os.path.join(update_path('data_images'), 'images',
+    >>> path_img = os.path.join(update_path('data-images'), 'images',
     ...                         'artificial_moving-affine.jpg')
     >>> convert_image_to_mhd(path_img, scaling=2)  # doctest: +ELLIPSIS
     '...artificial_moving-affine.mhd'

birl/utilities/dataset.py

@@ -591,7 +591,7 @@ def list_sub_folders(path_folder, name='*'):
     :return list(str): folders
 
     >>> from birl.utilities.data_io import update_path
-    >>> paths = list_sub_folders(update_path('data_images'))
+    >>> paths = list_sub_folders(update_path('data-images'))
     >>> list(map(os.path.basename, paths))  # doctest: +ELLIPSIS
     ['images', 'landmarks', 'lesions_', 'rat-kidney_'...]
     """
@@ -792,7 +792,7 @@ def image_histogram_matching(source, reference, use_color='hsv', norm_img_size=4
     :return ndarray: transformed image
 
     >>> from birl.utilities.data_io import update_path, load_image
-    >>> path_imgs = os.path.join(update_path('data_images'), 'rat-kidney_', 'scale-5pc')
+    >>> path_imgs = os.path.join(update_path('data-images'), 'rat-kidney_', 'scale-5pc')
     >>> img1 = load_image(os.path.join(path_imgs, 'Rat-Kidney_HE.jpg'))
     >>> img2 = load_image(os.path.join(path_imgs, 'Rat-Kidney_PanCytokeratin.jpg'))
     >>> image_histogram_matching(img1, img2).shape == img1.shape

bm_ANHIR/evaluate_submission.py

@@ -22,9 +22,9 @@
 
     python evaluate_submission.py \
         -e ./results/BmUnwarpJ \
-        -t ./data_images/pairs-imgs-lnds_histol.csv \
-        -d ./data_images \
-        -r ./data_images \
+        -t ./data-images/pairs-imgs-lnds_histol.csv \
+        -d ./data-images \
+        -r ./data-images \
         -p ./bm_experiments/computer-performances_cmpgrid-71.json \
         -o ./output \
         --min_landmarks 0.20

bm_dataset/create_real_synth_dataset.py

@@ -6,8 +6,8 @@
 Sample run::
 
     python create_real_synth_dataset.py \
-        -i ../data_images/images/Rat-Kidney_HE.jpg \
-        -l ../data_images/landmarks/Rat-Kidney_HE.csv \
+        -i ../data-images/images/Rat-Kidney_HE.jpg \
+        -l ../data-images/landmarks/Rat-Kidney_HE.csv \
         -o ../output/synth_dataset  --visual
 
 Copyright (C) 2016-2019 Jiri Borovec <[email protected]>

bm_dataset/rescale_tissue_landmarks.py

@@ -9,7 +9,7 @@
 
 Sample usage::
 
-    python rescale_tissue_landmarks.py -a data_images -d results
+    python rescale_tissue_landmarks.py -a data-images -d results
 
     python bm_dataset/rescale_tissue_landmarks.py \
         -a /datagrid/Medical/dataset_ANHIR/landmarks_all \

bm_experiments/bm_ANTs.py

@@ -61,8 +61,8 @@
 Run the basic ANT registration with original parameters::
 
     python bm_experiments/bm_ANTs.py \
-        -t ./data_images/pairs-imgs-lnds_anhir.csv \
-        -d ./data_images \
+        -t ./data-images/pairs-imgs-lnds_anhir.csv \
+        -d ./data-images \
         -o ./results \
         --path_ANTs ~/Applications/antsbin/bin \
         --path_config ./configs/ANTs_SyN.txt
@@ -99,7 +99,7 @@ class BmANTs(ImRegBenchmark):
     >>> from birl.utilities.data_io import create_folder, update_path
     >>> path_out = create_folder('temp_results')
     >>> fn_path_conf = lambda n: os.path.join(update_path('configs'), n)
-    >>> path_csv = os.path.join(update_path('data_images'), 'pairs-imgs-lnds_mix.csv')
+    >>> 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,