TLIB documentation
 

tlHist Class Reference

List of all members.


Detailed Description

Histogram implementation and tools.

tlHist provides a histogram class compatible with TLIB images and objects. It offers simple functions such as ranking, normalization and scaling, building from images and data manipulation.

Public Member Functions

 tlHist ()
 tlHist (int length, int offset=0)
virtual ~tlHist ()
int init (int length, int offset=0)
int clear ()
int update ()
int setChannel (int channel)
int getVal (int index)
int getRank (int index)
int getMean ()
float getStdDev ()
int getMaxVal ()
int getMinVal ()
int getMaxIndex ()
int getMinIndex ()
int getOffset ()
int getLength ()
int setVal (int index, int val)
int incVal (int index)
int decVal (int index)
int normalize (int max=100)
int integrate (int sum=100)
float compare (tlHist *hist)
int build (tlPixel *data, int len)
int build (tlPixel *data, int len, int length, int offset=0)
int build (tlPixel *src, int width, int height, int pixelWidth, tlPixel *mask, int channel, tlRect *rect)
int build (tlHRPixel *data, int len)
int build (tlHRPixel *data, int len, int length, int offset=0)
int build (tlHRPixel *src, int width, int height, int pixelWidth, tlPixel *mask, int channel, tlRect *rect)

Public Attributes

int channel
tlHistDatadata
tlHistDatarank


Constructor & Destructor Documentation

tlHist::tlHist (  ) 

Constructor, creates an empty histogram.

Note:
See error management for details.

References channel, data, rank, and TL_NO_ERROR.

tlHist::tlHist ( int  length,
int  offset = 0 
)

Constructor, create a histogram with a given length, where the first element starts at a given offset. For example, to create a histogram ranging between 10 and 30, call tlHist(20,10).

Parameters:
length number of values in histogram
offset first index of the histogram
Note:
See error management for details.

References TL_NO_ERROR.

tlHist::~tlHist (  )  [virtual]

Destructor.

Note:
See error management for details.

References TL_NO_ERROR.


Member Function Documentation

int tlHist::init ( int  length,
int  offset = 0 
)

Initialize an existing histogram object to a different size. Memory array is reallocated, every index is set to 0.

Parameters:
length number of values in histogram
offset first index of the histogram
Returns:
0 on success, -1 otherwise.
See error management for details.

Referenced by build(), tlHist2D::getXHist(), and tlHist2D::getYHist().

int tlHist::clear (  ) 

Clear an existing histogram object. That is, set all index to 0.

Returns:
0 on success, -1 otherwise.
See error management for details.

References data, rank, TL_ERRNO_MSG, TL_ERROR_NULL_POINTER, and update().

int tlHist::update (  ) 

Force recomputation of all internal data such as minima, maxima, and ranking information.

Returns:
0 on success, -1 otherwise.
See error management for details.

References data, and rank.

Referenced by build(), clear(), decVal(), tlHist2D::getXHist(), tlHist2D::getYHist(), incVal(), and setVal().

int tlHist::setChannel ( int  channel  ) 

Set color channel contained in the histogram. This is provided as as an reference tool and does not affect the content or the processing of the histogram.

Parameters:
channel the desired channel as described in tlVision.
Returns:
0 on success, -1 otherwise.
See error management for details.

int tlHist::getVal ( int  index  ) 

Get the value of a given histogram index.

Parameters:
index the index to poll
Returns:
The histogram value for the given element on success, -1 otherwise.
See error management for details.

References data, TL_ERRNO_MSG, and TL_ERROR_NULL_POINTER.

int tlHist::getRank ( int  index  ) 

Get the rank of a given histogram index. getRank(0) returns the index of the highest histogram value. getRank(length) returns the index of the smallest histogram value.

Parameters:
index the rank index to poll
Returns:
The index at the given rank on success, -1 otherwise.
See error management for details.

References data, rank, TL_ERRNO_MSG, and TL_ERROR_NULL_POINTER.

int tlHist::getMean (  )  [inline]

Return the mean of the data in the histogram.

Returns:
The mean of the data in the histogram.

int tlHist::getStdDev (  )  [inline]

Return the standard deviation of the data in the histogram.

Returns:
The standard deviation of the data in the histogram.

int tlHist::getMaxVal (  )  [inline]

Return the highest value in the histogram.

Returns:
The highest value in the histogram.

int tlHist::getMinVal (  )  [inline]

Return the lowest value in the histogram.

Returns:
The lowest value in the histogram.

int tlHist::getMaxIndex (  )  [inline]

Return the index of the highest value in the histogram.

Returns:
The index of the highest value in the histogram.

int tlHist::getMinIndex (  )  [inline]

Return the index of the lowest value in the histogram.

Returns:
The index of the lowest value in the histogram.

int tlHist::getOffset (  )  [inline]

Return the offset of the first histogram index.

Returns:
The offset of the first histogram value.

int tlHist::getLength (  )  [inline]

Return the length of the histogram.

Returns:
The length of the histogram.

Referenced by compare().

int tlHist::setVal ( int  index,
int  val 
)

Set the value of a given histogram index.

Parameters:
index the index to set
val the new value of the index
Returns:
0 on success, -1 otherwise.
See error management for details.

References data, TL_ERRNO_MSG, TL_ERROR_NULL_POINTER, and update().

int tlHist::incVal ( int  index  ) 

Increment the value of a given histogram index.

Parameters:
index the index to increment
Returns:
0 on success, -1 otherwise.
See error management for details.

References data, TL_ERRNO_MSG, TL_ERROR_NULL_POINTER, and update().

int tlHist::decVal ( int  index  ) 

Decrement the value of a given histogram index

Parameters:
index the index to decrement
Returns:
0 on success, -1 otherwise.
See error management for details.

References data, TL_ERRNO_MSG, TL_ERROR_NULL_POINTER, and update().

int tlHist::normalize ( int  newMax = 100  ) 

Scale all histogram values proportionally so that the greatest value matches a desired value. The default (newMax=100) sets all index to their weight in the histogram in [%].

Parameters:
newMax the desired greatest value
Returns:
0 on success, -1 otherwise.
See error management for details.

References data.

Referenced by integrate().

int tlHist::integrate ( int  sum = 100  ) 

Scale all histogram values proportionally so that the sum of all values matches a desired value (as closely as possible).

Parameters:
sum the desired sum value
Returns:
0 on success, -1 otherwise.
See error management for details.

References data, and normalize().

float tlHist::compare ( tlHist hist  ) 

Compare the histogram with another histogram.

Parameters:
hist the histogram to compare with
Returns:
A value representing the similitude of the histograms [0;1]
(1 meaning similar, 0 meaning radically different).
Returns -1 if the argument histogram is empty.
Note:
Both histogram must be of the same length.

References data, getLength(), TL_ERRNO_MSG, TL_ERROR, and TL_MIN.

int tlHist::build ( tlPixel src,
int  len 
)

Build a histogram from a tlPixel array.

Parameters:
src pixel data set to build upon
len pixel data set length
Returns:
0 on success, -1 otherwise.
See error management for details.
Remarks:
This routine first goes through the data array once to determine the length and offset of the data, which are then set automatically. See build(tlPixel *src, int len, int length, int offset) to manually set the offset.
See also:
build(tlPixel *src, int len, int length, int offset) build(tlPixel *src, int width, int height, int pixelWidth, tlPixel *mask, int channel, tlRect *rect)

Referenced by build(), and tlPixelArray::buildHist().

int tlHist::build ( tlPixel src,
int  len,
int  length,
int  offset = 0 
)

Build a histogram from a tlPixel array.

Parameters:
src pixel data set to build upon
len pixel data set length
length number of values in histogram
offset first index of the histogram
Returns:
0 on success, -1 otherwise.
See error management for details.
Remarks:
See build(tlPixel *src, int len) to set the offset and length parameters automatically.
See also:
build(tlPixel *src, int len, int offset) build(tlPixel *src, int width, int height, int pixelWidth, tlPixel *mask, int channel, tlRect *rect)

References data, init(), TL_ERRNO_MSG, TL_ERROR_INDEX_OUT_OF_BOUNDS, and update().

int tlHist::build ( tlPixel src,
int  width,
int  height,
int  pixelWidth,
tlPixel mask,
int  channel,
tlRect rect 
)

Build a histogram from the given channel of a portion of a given pixel array.

Parameters:
src the pixel array
width image width
height image height
pixelWidth bytes per pixel
mask pixel mask
channel the channel to consider
rect the portion of the image to consider
Returns:
0 on success, -1 otherwise.
See error management for details.

References data, tlSize::height, init(), TL_ERRNO_MSG, TL_ERROR_NULL_POINTER, TL_MAX, TL_MAX_PIXEL_VAL, TL_MIN, TL_MIN_PIXEL_VAL, TL_PIXEL, update(), tlSize::width, tlLocation::x, and tlLocation::y.

int tlHist::build ( tlHRPixel *  src,
int  len 
)

Build a histogram from a high-resolution pixel array.

Parameters:
src pixel data set to build upon
len pixel data set length
Returns:
0 on success, -1 otherwise.
See error management for details.
Remarks:
This routine first goes through the data array once to determine the length and offset of the data, which are then set automatically. See build(tlPixel *src, int len, int length, int offset) to manually set the offset.
See also:
build(tlHRPixel *src, int len, int length, int offset) build(tlHRPixel *src, int width, int height, int pixelWidth, tlPixel *mask, int channel, tlRect *rect)

References build().

int tlHist::build ( tlHRPixel *  src,
int  len,
int  length,
int  offset = 0 
)

Build a histogram from a high-resolution pixel array.

Parameters:
src pixel data set to build upon
len pixel data set length
length number of values in histogram
offset first index of the histogram
Returns:
0 on success, -1 otherwise.
See error management for details.
Remarks:
See build(tlHRPixel *src, int len) to set the offset and length parameters automatically.
See also:
build(tlHRPixel *src, int len, int offset) build(tlHRPixel *src, int width, int height, int pixelWidth, tlPixel *mask, int channel, tlRect *rect)

References data, init(), TL_ERRNO_MSG, TL_ERROR_INDEX_OUT_OF_BOUNDS, and update().

int tlHist::build ( tlHRPixel *  src,
int  width,
int  height,
int  pixelWidth,
tlPixel mask,
int  channel,
tlRect rect 
)

Build a histogram from the given channel of a portion of a given high-resolution pixel array.

Parameters:
src the pixel array
width image width
height image height
pixelWidth bytes per pixel
mask pixel mask
channel the channel to consider
rect the portion of the image to consider
Returns:
0 on success, -1 otherwise.
See error management for details.

References data, tlSize::height, init(), TL_ERRNO_MSG, TL_ERROR_NULL_POINTER, TL_MAX, TL_MAX_PIXEL_VAL, TL_MIN, TL_MIN_PIXEL_VAL, TL_PIXEL, update(), tlSize::width, tlLocation::x, and tlLocation::y.


Member Data Documentation

Desribe the color channel the histogram was built from (R, G, B, etc.)

Referenced by tlHist().

int * tlHist::data

int * tlHist::rank

Contain the index of the histogram values sorted in reversed order. (rank[0] = index of the highest peak in the histogram)

Referenced by clear(), getRank(), tlHist(), and update().


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


TLIB documentation - generated on 12 May 2008
Please address any questions to seb@tuyphon.com
(C) 2001-2008 - S. Grange
(C) 2001-2007 - VRAI Group, EPFL
All Rights Reserved.