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

#include <RegionDetector.h>

Inheritance diagram for 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...

Configurable &	operator= (const Configurable &other)
	Assignment operator. More...

void	setConfigurableID (const std::string &ID)
	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)
	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)
	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)
	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 Configurable *	get (const std::string &id)
	returns configurable by given ID More...

static void	register_configurable_type (const std::string &classname, Function< Configurable * > creator)
	registers a configurable type More...

static std::vector< std::string >	get_registered_configurables ()
	returns a list of all registered configurable classnames More...

static Configurable *	create_configurable (const std::string &classname)
	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())
	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...

Property &	prop (const std::string &propertyName)
	this CAN be used e.g. to store a property value in internal property-list More...

const Property &	prop (const std::string &propertyName) const
	this CAN be used e.g. to store a property value in internal property-list More...

	Configurable (const std::string &ID="", bool ordered=true)
	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< Callback >	callbacks
	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

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:

size (minSize,maxSize) defines an interval for the pixel-count of valid regions.
value (minValue,maxValue) defines and interval for the pixel-value of valid 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:

run length encoding
region analysis (create region-parts)
region joining (collect sup-parts of top-level parts in order to obtain regions)
region linking (only if a region graph is created) set up region neighbours
setting up border regions (only if a region graph is created)
region filtering (filter regions by using given size and value constraint)
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

◆ RegionDetector() [1/2]

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

◆ RegionDetector() [2/2]

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

◆ ~RegionDetector()

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

virtual

Destructor.

Member Function Documentation

◆ analyseRegions()

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

private

creates region-parts

see Region Analysis

◆ click()

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.

◆ detect()

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

◆ filterRegions()

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

private

filters regions by given size and value constraints

see Filtering Regions

◆ getLastDetectedRegions()

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

◆ joinRegions()

void icl::cv::RegionDetector::joinRegions ( )

private

combines ImageRegionParts

see Region Joining

◆ linkRegions()

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

private

detects region neighbours

see Region Linking

◆ setConstraints()

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

set up new constraints

◆ setCreateGraph()

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

set up the region-graph creation flag

◆ setCSSParams()

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

◆ setUpBorders()

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

private

detects border regions

see Setting up Border Regions

◆ useImage()

void icl::cv::RegionDetector::useImage ( const core::ImgBase * image )

private

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

Member Data Documentation

◆ m_data

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

private

internal data structure

internal data pointer

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

/Users/alneuman/vm/icl/ICLCV/src/ICLCV/RegionDetector.h

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Pixel Neighbourhood

Supported Image Depths

Multi-Channel Images

ROI-Support

Image Ownership

The ImageRegion Structure

Detection Constraints

Region Graph Information

The Segmentation Algorithm

Run Length Encoding

Region Analysis

Region Joining

Region Linking

Setting up Border Regions

Filtering Regions

Constructor & Destructor Documentation

◆ RegionDetector() [1/2]

◆ RegionDetector() [2/2]

◆ ~RegionDetector()

Member Function Documentation

◆ analyseRegions()

◆ click()

◆ detect()

◆ filterRegions()

◆ getLastDetectedRegions()

◆ joinRegions()

◆ linkRegions()

◆ setConstraints()

◆ setCreateGraph()

◆ setCSSParams()

◆ setUpBorders()

◆ useImage()

Member Data Documentation

◆ m_data