Image Component Library (ICL)
Public Member Functions | Public Attributes | Friends | List of all members
icl::cv::ImageRegion Struct Reference

ImageRegion Structure providing region feature information. More...

#include <ImageRegion.h>

Public Member Functions

template<class T >
void calculateBoundaryIntern (const core::Img< T > &image) const
 internal utility function More...
 
void calculateThinnedBoundaryIntern () const
 another utility function More...
 
utils::Point getUpperLeftPixel () const
 utility function that returns the upper left pixel of the region More...
 
 ImageRegion (ImageRegionData *data=0)
 Null-construktor. More...
 
 operator bool () const
 returns whether this image region is not null More...
 
ImageRegionDatadata ()
 returns the internal data (do not use!) More...
 
const ImageRegionDatadata () const
 returns the internal data (do not use!) (const) More...
 
void sample (core::ImgBase *image, int color)
 samples the region into a given image More...
 
void sample (core::ImgBase *image, const std::vector< int > &channelColors)
 samples the region into a given image More...
 
int getSize () const
 returns the pixel count of the Region More...
 
int getVal () const
 returns the pixel value of the region More...
 
int getID () const
 returns a unique region ID More...
 
utils::Point32f getCOG () const
 returns the region's center of gravity More...
 
const std::vector< LineSegment > & getLineSegments () const
 retuns the internal list of line segments More...
 
const utils::RectgetBoundingBox () const
 returns the region's bounding box More...
 
const RegionPCAInfogetPCAInfo () const
 returns information about the regions spacial PCA More...
 
const std::vector< utils::Point > & getBoundary (bool thinned=true) const
 returns all boundary pixels of this region More...
 
int getBoundaryPointCount (bool thinned) const
 returns the size of boundary pixel array of the ImageRegion More...
 
float getBoundaryLength () const
 returns the estimated length of the boundary More...
 
const std::vector< utils::Point32f > & getBoundaryCorners () const
 Approximate the region boundary by polygon structure. More...
 
float getFormFactor () const
 returns the Form-Factor of the Region (Boundary¬≤/4PI*utils::Size) More...
 
const std::vector< utils::Point > & getPixels () const
 returns a list of all pixels, of this regions More...
 
void drawTo (const core::ImgBase *image, icl64f val) const
 sets all pixel positions in given image to val in channel 0 of image More...
 
void drawToColor (const core::ImgBase *image, const icl64f *color) const
 highlights the region in the image using the given color More...
 
const std::vector< ImageRegion > & getSubRegions (bool directOnly=true) const throw (utils::ICLException)
 returns a list of all fully contained image regions More...
 
const ImageRegiongetParentRegion () const throw (utils::ICLException)
 returns the parent regions (which might be NULL) More...
 
const std::vector< ImageRegion > & getParentTree () const throw (utils::ICLException)
 returns the parent region and the parent's parent and so on More...
 
const std::vector< ImageRegion > & getNeighbours () const throw (utils::ICLException)
 returns a list of all adjacent regions More...
 
bool isBorderRegion () const throw (utils::ICLException)
 returns whether this ImageRegion is adjacent to the image border More...
 
bool contains (const utils::Point &p) const
 returns whether a given pixel position is part of the image region More...
 
void showTree () const
 shows the region tree and neighbours (for debugging) More...
 
void setMetaData (const utils::Any &any) const
 associates meta data with this region (also const) More...
 
const utils::AnygetMetaData () const
 returns the meta data associated with this region More...
 

Public Attributes

ImageRegionDatam_data
 Internally handled data (not shallow copied, but simply linked to the real data that is managed by the RegionDetector. More...
 

Friends

class RegionDetector
 Allows the RegionDetector to access private functions/methods. More...
 

Detailed Description

ImageRegion Structure providing region feature information.

General Information

The Region class provides several region information:

Internal Information

Valid ImageRegion-instances are only created by a RegionDetector instance.

Deferred Calculation of Features

Almost all features are computed on demand only. This means, that e.g. the center of gravity is only calculated if the corresponding getter-function getCOG() is called. The results of all features are automatically stored internally. By this means, all features must only be computed once, even if the corresponding getter function is called several times.

Region Graph Information

Some ImageRegion features are only available if the parent RegionDetector was set up to compute so called region graph information. From this, an ImageRegion structure can compute the following features: neighbour regions sub regions surrounding regions (parent region and parent region tree)

If one of these functions is called in a case where no region graph information is available, an exception will be thrown.

Internal Processing

Most high level features, such as bounding boxes or PCA information, can be calculated efficiently on the underlying LineSegment structure. Only this list of boundary pixels are calculated on basis of the underlying image.

Child Configurables

To avoid deep copies of internal region data, the ImageRegion is a very simple wrapper of an underlying data structure called ImageRegionData. Even though a pointer to this structure can be obtained using the ImageRegion::data() function, is is strongly recommended to use the ImageRegions interface only. Access to the internal structure is only for debugging.

Constructor & Destructor Documentation

icl::cv::ImageRegion::ImageRegion ( ImageRegionData data = 0)
inline

Null-construktor.

Member Function Documentation

template<class T >
void icl::cv::ImageRegion::calculateBoundaryIntern ( const core::Img< T > &  image) const

internal utility function

void icl::cv::ImageRegion::calculateThinnedBoundaryIntern ( ) const

another utility function

bool icl::cv::ImageRegion::contains ( const utils::Point p) const

returns whether a given pixel position is part of the image region

ImageRegionData* icl::cv::ImageRegion::data ( )
inline

returns the internal data (do not use!)

const ImageRegionData* icl::cv::ImageRegion::data ( ) const
inline

returns the internal data (do not use!) (const)

void icl::cv::ImageRegion::drawTo ( const core::ImgBase image,
icl64f  val 
) const

sets all pixel positions in given image to val in channel 0 of image

void icl::cv::ImageRegion::drawToColor ( const core::ImgBase image,
const icl64f color 
) const

highlights the region in the image using the given color

please note, that color must contain at least one element for each channel in the given image

const std::vector<utils::Point>& icl::cv::ImageRegion::getBoundary ( bool  thinned = true) const

returns all boundary pixels of this region

const std::vector<utils::Point32f>& icl::cv::ImageRegion::getBoundaryCorners ( ) const

Approximate the region boundary by polygon structure.

See also
ICLCore :: CornerDetectorCSS for a detailed description of function argmuments NEW* parameters can now be adjusted by the configurable interface of the parent RegionDetector instance
float icl::cv::ImageRegion::getBoundaryLength ( ) const

returns the estimated length of the boundary

This methods gives a much better estimation of the boundary length than getBoundaryPointCount(). The change in the estimated length should be no larger than 5 to 10 % under rotation of the object.
Complexity: linear in boundary length.

int icl::cv::ImageRegion::getBoundaryPointCount ( bool  thinned) const

returns the size of boundary pixel array of the ImageRegion

const utils::Rect& icl::cv::ImageRegion::getBoundingBox ( ) const

returns the region's bounding box

utils::Point32f icl::cv::ImageRegion::getCOG ( ) const

returns the region's center of gravity

float icl::cv::ImageRegion::getFormFactor ( ) const

returns the Form-Factor of the Region (Boundary²/4PI*utils::Size)

Please note that the formfactor for smaller regions is always a bit higher as expected for an ideal regions. This problem occurs due to using a 4-neighbourhood for calculating the boundary length of an ImageRegion;

The form factor formula is designed in that way, that an ideal circly has a formfactor of 1 and all other – less round – regions have a higher form factor:

  • circle 1
  • square 4/PI
  • cuboid (W=2*H) = 4.5/PI
int icl::cv::ImageRegion::getID ( ) const

returns a unique region ID

const std::vector<LineSegment>& icl::cv::ImageRegion::getLineSegments ( ) const

retuns the internal list of line segments

const utils::Any& icl::cv::ImageRegion::getMetaData ( ) const

returns the meta data associated with this region

const std::vector<ImageRegion>& icl::cv::ImageRegion::getNeighbours ( ) const
throw (utils::ICLException
)

returns a list of all adjacent regions

This function is only provided if region graph information is available (see Region Graph Information)

const ImageRegion& icl::cv::ImageRegion::getParentRegion ( ) const
throw (utils::ICLException
)

returns the parent regions (which might be NULL)

This function is only provided if region graph information is available (see Region Graph Information)

const std::vector<ImageRegion>& icl::cv::ImageRegion::getParentTree ( ) const
throw (utils::ICLException
)

returns the parent region and the parent's parent and so on

If a parent is null, the list ends immediately. In particular, this list can be empty This function is only provided if region graph information is available (see Region Graph Information)

const RegionPCAInfo& icl::cv::ImageRegion::getPCAInfo ( ) const

returns information about the regions spacial PCA

const std::vector<utils::Point>& icl::cv::ImageRegion::getPixels ( ) const

returns a list of all pixels, of this regions

Most of the time, this is very unefficient. It is strongly recommended to use getLineSegments() instead

int icl::cv::ImageRegion::getSize ( ) const

returns the pixel count of the Region

const std::vector<ImageRegion>& icl::cv::ImageRegion::getSubRegions ( bool  directOnly = true) const
throw (utils::ICLException
)

returns a list of all fully contained image regions

This function is only provided if region graph information is available (see Region Graph Information)

What is a Sub Region?

ImageRegion A contains ImageRegion B if

  1. B is a directly adjacent of A (B is in A's neighbour-list)
  2. There is no path from B (from ImageRegion to adjacent ImageRegion) to a border-region that does not cross A
utils::Point icl::cv::ImageRegion::getUpperLeftPixel ( ) const

utility function that returns the upper left pixel of the region

int icl::cv::ImageRegion::getVal ( ) const

returns the pixel value of the region

bool icl::cv::ImageRegion::isBorderRegion ( ) const
throw (utils::ICLException
)

returns whether this ImageRegion is adjacent to the image border

icl::cv::ImageRegion::operator bool ( ) const
inline

returns whether this image region is not null

a parent region e.g. can be null

void icl::cv::ImageRegion::sample ( core::ImgBase image,
int  color 
)

samples the region into a given image

void icl::cv::ImageRegion::sample ( core::ImgBase image,
const std::vector< int > &  channelColors 
)

samples the region into a given image

void icl::cv::ImageRegion::setMetaData ( const utils::Any any) const

associates meta data with this region (also const)

Note, this method is explicitly const since an un-const version would make the users simply copy the region before setting the meta data value. As all other properties, also the meta data is stored in the internal ImageRegionData structure. Therefore, also the meta-data is hold in the internally managed and shallowly copied data structure.

void icl::cv::ImageRegion::showTree ( ) const

shows the region tree and neighbours (for debugging)

Friends And Related Function Documentation

friend class RegionDetector
friend

Allows the RegionDetector to access private functions/methods.

Member Data Documentation

ImageRegionData* icl::cv::ImageRegion::m_data

Internally handled data (not shallow copied, but simply linked to the real data that is managed by the RegionDetector.


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