Image Component Library (ICL)
Public Member Functions | Private Member Functions | Private Attributes | List of all members
icl::cv::RegionDetector Class Reference

Complex utility class for detection of connected image components. More...

#include <RegionDetector.h>

Inheritance diagram for icl::cv::RegionDetector:
icl::utils::Uncopyable icl::utils::Configurable icl::utils::UncopiedInstance< icl::cv::RegionDetector >

Public Member Functions

 RegionDetector (bool createRegionGraph, const std::string &configurableID=Configurable::create_default_ID("region-detector-"))
 first constructor with given flag for creation of the region graph More...
 RegionDetector (int minSize=1, int maxSize=400000000, int minVal=0, int maxVal=255, bool createRegionGraph=false, const std::string &configurableID=Configurable::create_default_ID("region-detector-"))
 2nd constructor with given constraints and region-graph creation flag More...
virtual ~RegionDetector ()
 Destructor. More...
void setConstraints (int minSize, int maxSize, int minVal, int maxVal)
 set up new constraints More...
void setCreateGraph (bool on)
 set up the region-graph creation flag More...
void setCSSParams (float angle_thresh=162., float rc_coeff=1.5, float sigma=3., float curvature_cutoff=100., float straight_line_thresh=0.1)
 sets the internally used parameters for CSS-based corner detection More...
const std::vector< ImageRegion > & detect (const core::ImgBase *image)
 main apply function that is used to detect an images image-regions More...
const ImageRegion click (const utils::Point &pos)
 Utility function that returns the image regions that contains a given position (e.g. from mouse input) More...
const std::vector< ImageRegion > & getLastDetectedRegions ()
- Public Member Functions inherited from icl::utils::Configurable
virtual ~Configurable ()
 virtual destructor More...
 Configurable (const Configurable &other)
 Copy constructor. More...
Configurableoperator= (const Configurable &other)
 Assignment operator. More...
void setConfigurableID (const std::string &ID) throw (ICLException)
 sets the ID of this configurable More...
const std::string & getConfigurableID () const
 returns the configurables static ID More...
bool isOrderedFlagSet () const
 returns whether the ordered flag is set More...
void deactivateProperty (const std::string &pattern)
 adds an additional deativation pattern More...
void deleteDeactivationPattern (const std::string &pattern)
 removed a formerly added deactivation pattern More...
std::vector< std::string > getPropertyListWithoutDeactivated () const
 this returns a filtered list of properties (using all filters added by deactivateProperty) More...
virtual void adaptProperty (const std::string &name, const std::string &newType, const std::string &newInfo, const std::string &newToolTip) throw (ICLException)
 this function can be used to adapt a specific property afterwards More...
void registerCallback (const Callback &cb)
 add a callback for changed properties More...
void removedCallback (const Callback &cb)
 removes a callback that was registered before More...
void syncChangesTo (Configurable *others, int num=1)
 this can be used to let this instance also apply property changes to others More...
virtual void setPropertyValue (const std::string &propertyName, const Any &value) throw (ICLException)
 sets a property value More...
virtual std::vector< std::string > getPropertyList () const
 returns a list of All properties, that can be set using setProperty More...
virtual bool supportsProperty (const std::string &propertyName) const
 base implementation for property check (seaches in the property list) More...
virtual void saveProperties (const std::string &filename, const std::vector< std::string > &propertiesToSkip=EMPTY_VEC) const
 writes all available properties into a file More...
virtual void loadProperties (const std::string &filename, const std::vector< std::string > &propertiesToSkip=EMPTY_VEC)
 reads a camera config file from disc More...
virtual std::string getPropertyType (const std::string &propertyName) const
 get type of property More...
virtual std::string getPropertyInfo (const std::string &propertyName) const
 get information of a properties valid values More...
virtual Any getPropertyValue (const std::string &propertyName) const
 returns the current value of a property or a parameter More...
virtual std::string getPropertyToolTip (const std::string &propertyName) const
 returns the tooltip description for a given property More...
virtual int getPropertyVolatileness (const std::string &propertyName) const
 Returns whether this property may be changed internally. More...

Private Member Functions

void useImage (const core::ImgBase *image) throw (utils::ICLException)
 Internally used utility function that extracts the input images ROI if necessary. More...
void analyseRegions ()
 creates region-parts More...
void joinRegions ()
 combines ImageRegionParts More...
void linkRegions ()
 detects region neighbours More...
void setUpBorders ()
 detects border regions More...
void filterRegions ()
 filters regions by given size and value constraints More...

Private Attributes

Data * m_data
 internal data structure More...

Additional Inherited Members

- Public Types inherited from icl::utils::Configurable
typedef Function< void, const Property & > Callback
 Function type for changed properties. More...
- Static Public Member Functions inherited from icl::utils::Configurable
static std::string create_default_ID (const std::string &prefix)
 this function can be used in subclasses to create a default ID More...
static Configurableget (const std::string &id)
 returns configurable by given ID More...
static void register_configurable_type (const std::string &classname, Function< Configurable * > creator) throw (ICLException)
 registers a configurable type More...
static std::vector< std::string > get_registered_configurables ()
 returns a list of all registered configurable classnames More...
static Configurablecreate_configurable (const std::string &classname) throw (ICLException)
 creates a configurable by given name More...
- Static Public Attributes inherited from icl::utils::Configurable
static const std::vector< std::string > EMPTY_VEC
 used as shortcut – just an empty vector of std::strings More...
- Protected Member Functions inherited from icl::utils::Uncopyable
 Uncopyable ()
 Empty base constructor. More...
- Protected Member Functions inherited from icl::utils::Configurable
void addProperty (const std::string &name, const std::string &type, const std::string &info, const Any &value=Any(), const int volatileness=0, const std::string &tooltip=std::string()) throw (ICLException)
 This can be used by derived classes to store supported properties in the internal list. More...
void addChildConfigurable (Configurable *configurable, const std::string &childPrefix="")
 This adds another configurable as child. More...
void removeChildConfigurable (Configurable *configurable)
 removes the given child configurable More...
Propertyprop (const std::string &propertyName) throw (ICLException)
 this CAN be used e.g. to store a property value in internal property-list More...
const Propertyprop (const std::string &propertyName) const throw (ICLException)
 this CAN be used e.g. to store a property value in internal property-list More...
 Configurable (const std::string &ID="", bool ordered=true) throw (ICLException)
 create this configurable with given ID More...
void call_callbacks (const std::string &propertyName, const Configurable *caller) const
 calls all registered callbacks More...
- Protected Attributes inherited from icl::utils::Configurable
std::vector< Callbackcallbacks
 internally managed list of callbacks More...

Detailed Description

Complex utility class for detection of connected image components.

The RegionDetector extracts all connected components from a given input image

Pixel Neighbourhood

Currently, only a 4-Neighbourhood for pixels is supported. This means, that Image-Regions have to be adjacent either horizontally or vertically. Pixels with an identical value, that are only connected diagonally are not connected.

Supported Image Depths

As internally, adjacent pixels are compared using the default '==' processing of float- or double-images is currently not supported. Furthermore, it is also very uncommon to search for connected components on floating-point images.

Multi-Channel Images

In short: multi-channel images are not supported at all. Strictly speaking only the channel with index 0 is used, all other remain untouched.


ROI support is provided by the internally used instance of class RunLengthEncoder. The RunLengthEncoder has only a very small overhead for ROI-images. If an image with set ROI is passed to the RegionDetectors detect- function, only the images ROI is process internally. All other pixels will not be processed at all. In this case, regions, that are adjacent to the image ROI are set to be border-regions and image regions that intersect the ROI are cut at the ROI-boundaries. In other words, the detection behaves as if the image-ROI is extracted before the detection step.

Image Ownership

The RegionDetector instance does not take ownership of the given input image. However, the input image needs to remain unchanged as long as the result of the RegionDetector::detect-function is used. Currently, only the ImageRegions's ImageRegion::getBoundary() and variants of this method actually demand the image to be unchanged, however, future implementations of other feature functions of ImageRegion do not guarantee this.

The ImageRegion Structure

The ImageRegion structure that is returned by the RegionDetector::detect-function Is a utility wrapper around it's data structure that is called ImageRegionData. Please do not use ImageRegionData directly, but only by using the ImageRegion interface. ImageRegions can easily be copied (just a single pointer copy) – the internal data is always managed by the parent RegionDetector instance.

Detection Constraints

There are two direct constraints, that can be defined for filtering the set of all image regions:

Note: Internally, all regions are always detected and automatically filtered afterwards. By this means, RegionDetector::detect only returns regions, that match the given size and value constraints but also all neighbours and sub-regions of these are also available even if they do not match the filter criterion.

Region Graph Information

RegionDetector provides the functionality to perform a simple connected component analysis as well as to compute higher level information about the region structure. In particular, it can be set up to create a so called region graph. Which defines basically, which regions are adjacent. This information can then be used to compute a region hierarchy that defines which regions do contain which other regions. The most expensive step is to define the region neighbours of each region. Therefore, the creation of this additinal information has to be activated explicitly. If the RegionDetector was not set up to create the region graph (either via a constructor argument or using the function RegionDetector::setCreateGraph(bool)), this information is not available, and the following region-information are not available: region neighbours sub-regions parent regions

The Segmentation Algorithm

We use a custom designed and highly optimized algorithm for connected component analysis. In a first step: The image is run-length encoded. All further steps are performed on the resulting LineSegment representation.

The Algorithm is split into 6 parts:

  1. run length encoding
  2. region analysis (create region-parts)
  3. region joining (collect sup-parts of top-level parts in order to obtain regions)
  4. region linking (only if a region graph is created) set up region neighbours
  5. setting up border regions (only if a region graph is created)
  6. region filtering (filter regions by using given size and value constraint)
  7. further processing on individual regions

Run Length Encoding

In a first preprocessing step, the input image is run length encoded. Each image line is then no longer represented as a set of width pixel values but as a sequence of so called LineSegments each defined by pixel value, x,y, and xend. For this step a RunLengthEncoder instances is used. Note, that run length encoding is highly optimized in case of using icl8u-images. Here, the most essential step (search for the first pixel value that is different from the current one) is accelerated by checking 4 next pixels at once.

Region Analysis

In this processing step, each 2 successive image lines (represented as sequences of LineSegments) are processed. Internally, we used a utility structure called WorkingLineSegment for run length encoding. This utility class can also hold additinal information which is a pointer to an ImageRegionPart in this step. If two line segments A and B with identical values are adjacent (using 4-neighbourhood), they are both added to A's ImageRegionPart and B's ImageRegionPart is set to A's ImageRegionPart. Occasionally, A and B are already set up with an ImageRegionPart. In this case, B's ImageRegionPart is added to A's ImageRegionPart and B's ImageRegionPart is set to be no longer on top level. Only top level ImageRegionParts are transformed to complete image regions in the next step.
After this step, we have a set of ImageRegionParts. Some of this parts are still top level, others are not and need to be added to their top-most ImageRegionPart.

Region Joining

Here, a ImageRegion (stricly speaking ImageRegionData-structure) is created from each top level ImageRegionParts T. During the creation process, all WorkingLineSegments of T and all contained ImageRegionParts are collected recursively. Furthermore, the internally used WorkingLineSegments do no longer need information about their parent ImageRegionPart. Therefore, their data pointer is set to their parent ImageRegionData structure.
After this step, we already have a set of all image regions.

Region Linking

If a region graph needs to be created, this step is used to detect which regions are adjacent. Again, we use the internal WorkingLineSegment representation. For each pair adjacent WorkingLineSegments A and B (4-neighbourhood) A's linked ImageRegionData is set to be a neighbour of B's ImageRegionData and vice versa. After this step, each ImageRegionData contains a set of all of it's adjacent ImageRegionData structures.

Setting up Border Regions

For the computation of region containment, regions that are adjacent to the image borders are special as these regions are not contained by other regions. Here, we again use the internal WorkingLineSegment representation to set up the isBorder-flag of all ImageRegionData structures that touch the image border to true.

Filtering Regions

Lastly, all ImageRegionData structures are filtered w.r.t. the given size and value constraints.

Constructor & Destructor Documentation

icl::cv::RegionDetector::RegionDetector ( bool  createRegionGraph,
const std::string &  configurableID = Configurable::create_default_ID("region-detector-") 

first constructor with given flag for creation of the region graph

Note: at default, the region graph is not created

icl::cv::RegionDetector::RegionDetector ( int  minSize = 1,
int  maxSize = 400000000,
int  minVal = 0,
int  maxVal = 255,
bool  createRegionGraph = false,
const std::string &  configurableID = Configurable::create_default_ID("region-detector-") 

2nd constructor with given constraints and region-graph creation flag

virtual icl::cv::RegionDetector::~RegionDetector ( )


Member Function Documentation

void icl::cv::RegionDetector::analyseRegions ( )

creates region-parts

see Region Analysis

const ImageRegion icl::cv::RegionDetector::click ( const utils::Point pos)

Utility function that returns the image regions that contains a given position (e.g. from mouse input)

click always refers to the last detect call. If no region contains the given point (e.g. because it is outside the image rectangle), a null-region is returned.

const std::vector<ImageRegion>& icl::cv::RegionDetector::detect ( const core::ImgBase image)

main apply function that is used to detect an images image-regions

As explained in Supported Image Depths, this function is only valid for icl8u, icl16s and icl32s images

void icl::cv::RegionDetector::filterRegions ( )

filters regions by given size and value constraints

see Filtering Regions

const std::vector<ImageRegion>& icl::cv::RegionDetector::getLastDetectedRegions ( )
void icl::cv::RegionDetector::joinRegions ( )

combines ImageRegionParts

see Region Joining

void icl::cv::RegionDetector::linkRegions ( )

detects region neighbours

see Region Linking

void icl::cv::RegionDetector::setConstraints ( int  minSize,
int  maxSize,
int  minVal,
int  maxVal 

set up new constraints

void icl::cv::RegionDetector::setCreateGraph ( bool  on)

set up the region-graph creation flag

void icl::cv::RegionDetector::setCSSParams ( float  angle_thresh = 162.,
float  rc_coeff = 1.5,
float  sigma = 3.,
float  curvature_cutoff = 100.,
float  straight_line_thresh = 0.1 

sets the internally used parameters for CSS-based corner detection

The internal corner detector is used if ImageRegion::getBoundaryCorners is called on detected regions. Note, this can also be adjusted by the Configurable interface

void icl::cv::RegionDetector::setUpBorders ( )

detects border regions

see Setting up Border Regions

void icl::cv::RegionDetector::useImage ( const core::ImgBase image)
throw (utils::ICLException

Internally used utility function that extracts the input images ROI if necessary.

Member Data Documentation

Data* icl::cv::RegionDetector::m_data

internal data structure

internal data pointer

The documentation for this class was generated from the following file: