YACCLAB
YACCLAB: Yet Another Connected Components Labeling Benchmark
Install / Use
/learn @prittt/YACCLABREADME
Yet Another Connected Components Labeling Benchmark
- <p align="justify"> Allegretti, Stefano; Bolelli, Federico; Grana, Costantino "Optimized Block-Based Algorithms to Label Connected Components on GPUs." IEEE Transactions on Parallel and Distributed Systems, 2019. <a title="BibTex" href="https://federicobolelli.it/pub_files/2019tpds.html">BibTex</a>. <a title="Download" href="https://federicobolelli.it/pub_files/2019tpds.pdf">PDF</a>.</p>
- <p align="justify"> Bolelli, Federico; Cancilla, Michele; Baraldi, Lorenzo; Grana, Costantino "Towards Reliable Experiments on the Performance of Connected Components Labeling Algorithms" Journal of Real-Time Image Processing, 2018. <a title="BibTex" href="https://federicobolelli.it/pub_files/2018jrtip.html">BibTex</a>. <a title="Download" href="https://federicobolelli.it/pub_files/2018jrtip.pdf">PDF</a>.</p>
- <p align="justify"> Grana, Costantino; Bolelli, Federico; Baraldi, Lorenzo; Vezzani, Roberto "YACCLAB - Yet Another Connected Components Labeling Benchmark" Proceedings of the 23rd International Conference on Pattern Recognition, Cancun, Mexico, 4-8 Dec 2016. <a title="BibTex" href="https://federicobolelli.it/pub_files/2016icpr.html">BibTex</a>. <a title="Download" href="https://federicobolelli.it/pub_files/2016icpr.pdf">PDF</a>.</p>
Notice that 8-connectivity is always used in the project.
</p>Reproducible Research
<p align="justify">This project follows the Reproducible Research paradigms and received the <a href="https://github.com/RLPR">Reproducible Label in Pattern Recognition (RLPR)</a>.</p><img style="float: right;" src="/doc/EPDT/RRLPR.png">Requirements
<p align="justify"> To correctly install and run YACCLAB following packages, libraries and utilities are needed:- CMake 3.18 or higher (https://cmake.org);
- OpenCV 3.0 or higher (http://opencv.org), required packages are
core,imgcodecs,imgproc; - Gnuplot (http://www.gnuplot.info/);
- One of your favourite IDE/compiler with C++14 support.
GPU algorithms also require:
- CUDA Toolkit 9.2 or higher (https://developer.nvidia.com/cuda-toolkit) and OpenCV
cudafeatures2dpackage (as of OpenCV 4.5.3, package dependencies entail that required packages for CUDA algorithms arecore,cudafeatures2d,cudaarithm,cudafilters,cudaimgproc,cudawarping,cudev,features2d,imgcodecs,imgproc).
Notes for gnuplot:
- on Windows system: be sure add gnuplot to system path if you want YACCLAB automatically generates charts.
- on MacOS system: 'pdf terminal' seems to be not available due to old version of cairo, 'postscript' is used instead.
Installation (refer to the image below)
- <p align="justify">Clone the GitHub repository (HTTPS clone URL: https://github.com/prittt/YACCLAB.git) or simply download the full master branch zip file and extract it (e.g YACCLAB folder).</p>
- <p align="justify">Install software in YACCLAB/bin subfolder (suggested) or wherever you want using CMake (point 2 of the example image). Note that CMake should automatically find the OpenCV path whether correctly installed on your OS (3), download the YACCLAB Dataset (be sure to check the box if you want to download it (4a) and (4b) or to select the correct path if the dataset is already on your file system (7)), and create a C++ project for the selected IDE/compiler (9-10). Moreover, if you want to test 3D or GPU algorithms tick the corresponding boxes (5) and (6). </p>
- <p align="justify">Set the <a href="#conf">configuration file (config.yaml)</a> placed in the installation folder (bin in this example) in order to select desired tests.</p>
- <p align="justify">Open the project, compile and run it: the work is done!</p>
CMake Configuration Variables
| Name | Meaning | Default |
| ------------------------------------ |-----------------------------| --------|
| YACCLAB_DOWNLOAD_DATASET | whether to automatically download the 2D YACCLAB dataset or not | OFF |
| YACCLAB_DOWNLOAD_DATASET_3D | whether to automatically download the 3D YACCLAB dataset or not | OFF |
| YACCLAB_ENABLE_3D | enable/disable the support for 3D algorithms | OFF |
| YACCLAB_ENABLE_CUDA | enable/disable CUDA support | OFF |
| YACCLAB_ENABLE_EPDT_19C | enable/disable the EPDT_19C 3D algorithm which is based on a heuristic decision tree generated from a 3D mask with 19 conditions (may noticeably increase compilation time), it has no effect when YACCLAB_ENABLE_3D is OFF | OFF |
| YACCLAB_ENABLE_EPDT_22C | enable/disable the EPDT_22C 3D algorithm which is based on a heuristic decision tree generated from a 3D mask with 22 conditions (may noticeably increase compilation time), it has no effect when YACCLAB_ENABLE_3D is OFF | OFF |
| YACCLAB_ENABLE_EPDT_26C | enable/disable the EPDT_26C 3D algorithm which is based on a heuristic decision tree generated from a 3D mask with 26 conditions (may noticeably increase compilation time), it has no effect when YACCLAB_ENABLE_3D is OFF | OFF |
| YACCLAB_FORCE_CONFIG_GENERATION | whether to force the generation of the default configuration file (config.yaml) or not. When this flag is turned OFF any existing configuration file will not be overwritten | OFF |
| YACCLAB_INPUT_DATASET_PATH | path to the input dataset folder, where to find test datasets | ${CMAKE_INSTALL_PREFIX}/input |
| YACCLAB_OUTPUT_RESULTS_PATH | path to the output folder, where to save output results | ${CMAKE_INSTALL_PREFIX}/output |
| OpenCV_DIR | OpenCV installation path | - |
