Yet Another Connected Components Labeling Benchmark

release license contributors

OS Build Compiler OpenCV CMake GPU Travis CI GitHub Actions
Ubuntu
16.04.6 LTS		 x64 gcc 5.4.0 3.1.0 3.13 None Build Status N/A
MacOS
(Darwin 17.7.0)		 x64 AppleClang 10
(Xcode-10.1)		 3.1.0 3.13 None Build Status N/A
Ubuntu
18.04.6 LTS		 x64 gcc 7 4.1.2 3.13.5 None N/A Action Status

Please include the following references when citing the YACCLAB project/dataset:

YACCLAB is an open source C++ project that enables researchers to test CCL algorithms under extremely variable points of view, running and testing algorithms on a collection of datasets described below. The benchmark performs the following tests which will be described later in this readme: correctness, average run-time (average), average run-time with steps (average_ws), density, size, granularity and memory accesses (memory). Notice that 8-connectivity is always used in the project.

Requirements

To correctly install and run YACCLAB following packages, libraries and utility are needed: - CMake 3.8.2 or higher (https://cmake.org), - OpenCV 3.0 or higher (http://opencv.org), - 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) 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)

Cmake

How to include a YACCLAB algorithm into your own project?

If your project requires a Connected Components Labeling algorithm and you are not interested in the whole YACCLAB benchmark you can use the connectedComponent function of the OpenCV library which implements the BBDT and SAUF algorithms since version 3.2.

Anyway, when the connectedComponents function is called, lot of additional code will be executed together with the core function. If your project requires the best performance you can include an algorithm implemented in YACCLAB adding the following files to your project:

  1. labeling_algorithms.h and labeling_algorithms.cc which define the base class from which every algorithm derives from.
  2. label_solver.h and label_solver.cc which cointain the implementation of labels solving algorithms.
  3. memory_tester.h and performance_evaluator.h just to make things work without changing the code.
  4. headers and sources files of the required algorithm/s. The association between algorithms and headers/sources files is reported in the table below.
Algorithm Name Authors Year Acronym Required Files Templated on Labels Solver
CPU - L. Di Stefano,
A. Bulgarelli [3]		 1999 DiStefano labeling_distefano_1999.h NO
Contour Tracing F. Chang,
C.J. Chen,
C.J. Lu [1]		 1999 CT labeling_fchang_2003.h NO
Run-Based Two-Scan L. He,
Y. Chao,
K. Suzuki [7]		 2008 RBTS labeling_he_2008.h YES
Scan Array-based with Union Find K. Wu,
E. Otoo,
K. Suzuki [6]		 2009 SAUF labeling_wu_2009.h, labeling_wu_2009_tree.inc YES
Stripe-Based Labeling Algorithm H.L. Zhao,
Y.B. Fan,
T.X. Zhang,
H.S. Sang [8]		 2010 SBLA labeling_zhao_2010.h NO
Block-Based with Decision Tree C. Grana,
D. Borghesani,
R. Cucchiara [4]		 2010 BBDT labeling_grana_2010.h, labeling_grana_2010_tree.inc YES
Configuration Transition Based L. He,
X. Zhao,
Y. Chao,
K. Suzuki [7]		 2014 CTB labeling_he_2014.h, labeling_he_2014_graph.inc YES
Block-Based with Binary Decision Trees W.Y. Chang,
C.C. Chiu,
J.H. Yang [2]		 2015 CCIT labeling_wychang_2015.h, labeling_wychang_2015_tree.inc, labeling_wychang_2015_tree_0.inc YES
Light Speed Labeling L. Cabaret,
L. Lacassagne,
D. Etiemble [5]		 2016 LSL_STD I
LSL_STDZ II
LSL_RLE III		 labeling_lacassagne_2016.h, labeling_lacassagne_2016_code.inc YES IV
Pixel Prediction C.Grana,
L. Baraldi,
F. Bolelli [9]		 2016 PRED labeling_grana_2016.h, labeling_grana_2016_forest.inc, labeling_grana_2016_forest_0.inc YES
Directed Rooted Acyclic Graph F. Bolelli,
L. Baraldi,
M. Cancilla,
C. Grana [23]		 2018 DRAG labeling_bolelli_2018.h, labeling_grana_2018_drag.inc YES
Spaghetti Labeling F. Bolelli,
S. Allegretti,
L. Baraldi,
C. Grana [13]		 2019 Spaghetti labeling_bolelli_2019.h, labeling_bolelli_2019_forest.inc, labeling_bolelli_2019_forest_firstline.inc, labeling_bolelli_2019_forest_lastline.inc, labeling_bolelli_2019_forest_singleline.inc YES
Null Labeling F. Bolelli,
M. Cancilla,
L. Baraldi,
C. Grana [13]		 - NULL V labeling_null.h NO
GPU Union Find V. Oliveira,
R. Lotufo [18]		 2010 UF labeling_CUDA_UF.cu NO
Optimized
Label Equivalence		 O. Kalentev,
A. Rai,
S. Kemnitz,
R. Schneider [19]		 2011 OLE labeling_CUDA_OLE.cu NO
Block Equivalence S. Zavalishin,
I. Safonov,
Y. Bekhtin,
I. Kurilin [20]		 2016 BE labeling_CUDA_BE.cu NO
Distanceless
Label Propagation		 L. Cabaret,
L. Lacassagne,
D. Etiemble [21]		 2017 DLP labeling_CUDA_DLP.cu NO
CUDA SAUF S. Allegretti,
F. Bolelli,
M. Cancilla,
C. Grana [29]		 - C-SAUF labeling_CUDA_SAUF.cu,
labeling_wu_2009_tree.inc		 NO
CUDA BBDT S. Allegretti,
F. Bolelli,
M. Cancilla,
C. Grana [29]		 - C-BBDT labeling_CUDA_BBDT.cu, labeling_grana_2010_tree.inc NO
CUDA DRAG S. Allegretti,
F. Bolelli,
M. Cancilla,
C. Grana [29]		 - C-DRAG labeling_CUDA_DRAG.cu NO
Block-based Union Find S. Allegretti,
F. Bolelli,
C. Grana [24]		 2019 BUF labeling_CUDA_BUF.cu NO
Block-based Komura Equivalence S. Allegretti,
F. Bolelli,
C. Grana [24]		 2019 BKE labeling_CUDA_BKE.cu NO

(I) standard version
(II) with zero-offset optimization
(III) with RLE compression
(IV) only on TTA and UF
(V) it only copies the pixels from the input image to the output one simply defining a lower bound limit for the execution time of CCL algorithms on a given machine and dataset.

Example of Algorithm Usage Outside the Benchmark

#include "labels_solver.h"
#include "labeling_algorithms.h"
#include "labeling_grana_2010.h" // To include the algorithm code (BBDT in this example)

#include <opencv2/opencv.hpp>

using namespace cv;

int main()
{
    BBDT<UFPC> BBDT_UFPC; // To create an object of the desired algorithm (BBDT in this example)
                          // templated on the labels solving strategy. See the README for the
                          // complete list of the available labels solvers, available algorithms
                          // (N.B. non all the algorithms are templated on the solver) and their
                          // acronyms.

    BBDT_UFPC.img_ = imread("test_image.png", IMREAD_GRAYSCALE); // To load into the CCL object
                                                                 // the BINARY image to be labeled

    threshold(BBDT_UFPC.img_, BBDT_UFPC.img_, 100, 1, THRESH_BINARY); // Just to be sure that the
                                                                      // loaded image is binary

    BBDT_UFPC.PerformLabeling(); // To perform Connected Components Labeling!

    Mat1i output = BBDT_UFPC.img_labels_; // To get the output labeled image  
    unsigned n_labels = BBDT_UFPC.n_labels_; // To get the number of labels found in the input img

    return EXIT_SUCCESS;
}

Configuration File

A YAML configuration file placed in the installation folder lets you specify which kinds of tests should be performed, on which datasets and on which algorithms. Four categories of algorithms are supported: 2D CPU, 2D GPU, 3D CPU and 3D GPU. For each of them, the configuration parameters are reported below.