TLIB documentation
 

tlHist2D Class Reference

List of all members.

Detailed Description

2D Histogram implementation and tools.

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

Public Member Functions

 tlHist2D ()
 tlHist2D (int length)
 tlHist2D (int xlength, int ylength, int xoffset=0, int yoffset=0)
virtual ~tlHist2D ()
int save (char *filename)
int load (char *filename)
int init (int length)
int init (int xlength, int ylength, int xoffset=0, int yoffset=0)
int clear ()
int update ()
int updateRank ()
int setXChannel (int channel)
int setYChannel (int channel)
int getVal (int x, int y)
int getXRank (int index)
int getYRank (int index)
int getMaxVal ()
int getMinVal ()
int getXOffset ()
int getXLength ()
int getXMaxIndex ()
int getXMinIndex ()
int getYOffset ()
int getYLength ()
int getYMaxIndex ()
int getYMinIndex ()
int setVal (int x, int y, tlHistData val)
int incVal (int x, int y)
int decVal (int x, int y)
int normalize (int max=100)
int integrate (int sum=100)
float compare (tlHist2D *hist)
int build (tlPixel *xdata, tlPixel *ydata, int len)
int build (tlPixel *xdata, tlPixel *ydata, int len, int xlength, int ylength, int xoffset=0, int yoffset=0)
int build (tlPixel *src, int width, int height, int pixelWidth, tlPixel *mask, int xchannel, int ychannel, tlRect *rect)
int build (tlHRPixel *xdata, tlHRPixel *ydata, int len)
int build (tlHRPixel *xdata, tlHRPixel *ydata, int len, int xlength, int ylength, int xoffset=0, int yoffset=0)
int getXHist (tlHist *hist)
int getYHist (tlHist *hist)
tlHist * getXHist ()
tlHist * getYHist ()
int toImage (tlImage *image)
tlImage * toImage ()

Public Attributes

int xChannel
int yChannel
tlHistData ** data
tlHistData * xRank
tlHistData * yRank

Constructor & Destructor Documentation

tlHist2D::tlHist2D (  ) 

Constructor, creates an empty histogram.

Note:
See error management for details.

tlHist2D::tlHist2D ( int  length  ) 

Constructor, create a square 2D histogram with a given number of bins.

Parameters:
length number of values in histogram on each axis
Note:
See error management for details.

tlHist2D::tlHist2D ( int  xlength,
int  ylength,
int  xoffset = 0,
int  yoffset = 0 
)

Create a 2D histogram with a given number of bins, where the first element of each dimension starts at a given offset.

For example, to create a histogram with both axis ranging between 10 and 30, call tlHist(20,20,10,10).

Parameters:
xlength number of values in histogram on the X axis
xoffset first index of the histogram on the X axis
ylength number of values in histogram on the Y axis
yoffset first index of the histogram on the Y axis
Note:
See error management for details.

tlHist2D::~tlHist2D (  )  [virtual]

Destructor.

Note:
See error management for details.

Member Function Documentation

int tlHist2D::save ( char *  filename  ) 

Save a 2D histogram to a file.

Parameters:
filename file name
Returns:
0 on success, -1 otherwise.
See error management for details.

int tlHist2D::load ( char *  filename  ) 

Read a 2D histogram from a file.

Parameters:
filename file name
Returns:
0 on success, -1 otherwise.
See error management for details.

int tlHist2D::init ( int  length  ) 

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

Parameters:
length number of values in histogram on each axis
Returns:
0 on success, -1 otherwise.
See error management for details.

int tlHist2D::init ( int  xlength,
int  ylength,
int  xoffset = 0,
int  yoffset = 0 
)

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

Parameters:
xlength number of values in histogram on the X axis
xoffset first index of the histogram on the X axis
ylength number of values in histogram on the Y axis
yoffset first index of the histogram on the Y axis
Returns:
0 on success, -1 otherwise.
See error management for details.

int tlHist2D::clear (  ) 

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

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

int tlHist2D::update (  ) 

Force recomputation of all internal data such as minima, maxima. It is only necessary to call this routine if the histogram values have been change manually (i.e. directly in the tlHist2D::data field). Calls to setVal(), incVal() and decVal() update this information automatically.

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

int tlHist2D::updateRank (  ) 

Compute ranking information. Depending on the size of the histogram, this operation can be very time consuming !

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

int tlHist2D::setXChannel ( int  channel  ) 

Set color channel contained in the histogram X axis. This is provided as as an reference 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 tlHist2D::setYChannel ( int  channel  ) 

Set color channel contained in the histogram Y axis. This is provided as as an reference 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 tlHist2D::getVal ( int  x,
int  y 
)

Get the value of a given histogram index.

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

int tlHist2D::getXRank ( int  index  ) 

Get the X axis index of a histogram value at a given rank. getRank(0) returns the X index of the highest histogram value. getRank(xLength) returns the X index of the smallest histogram value.

Parameters:
index the X rank index to poll
Returns:
The index at the given rank on success, -1 otherwise.
See error management for details.
Note:
The rank information must be computed by calling updateRank() first.

int tlHist2D::getYRank ( int  index  ) 

Get the Y axis index of a histogram value at a given rank. getRank(0) returns the Y index of the highest histogram value. getRank(xLength) returns the Y index of the smallest histogram value.

Parameters:
index the Y rank index to poll
Returns:
The index at the given rank on success, -1 otherwise. See error management for details.
Note:
The rank information must be computed by calling updateRank() first.

int tlHist2D::getMaxVal (  )  [inline]

Return the highest value in the histogram.

Returns:
The highest value in the histogram.

int tlHist2D::getMinVal (  )  [inline]

Return the lowest value in the histogram.

Returns:
The lowest value in the histogram.

int tlHist2D::getXOffset (  )  [inline]

Return the offset of the first histogram index on the X axis.

Returns:
The offset of the first histogram value on the X axis.

int tlHist2D::getXLength (  )  [inline]

Return the length of the histogram on the X axis.

Returns:
The length of the histogram on the X axis.

int tlHist2D::getXMaxIndex (  )  [inline]

Return the X index of the highest value in the histogram.

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

int tlHist2D::getXMinIndex (  )  [inline]

Return the X index of the lowest value in the histogram.

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

int tlHist2D::getYOffset (  )  [inline]

Return the offset of the first histogram index on the Y axis.

Returns:
The offset of the first histogram value on the Y axis.

int tlHist2D::getYLength (  )  [inline]

Return the length of the histogram on the Y axis.

Returns:
The length of the histogram on the Y axis.

int tlHist2D::getYMaxIndex (  )  [inline]

Return the Y index of the highest value in the histogram.

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

int tlHist2D::getYMinIndex (  )  [inline]

Return the Y index of the lowest value in the histogram.

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

int tlHist2D::setVal ( int  x,
int  y,
tlHistData  val 
)

Set the value of a given histogram index.

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

int tlHist2D::incVal ( int  x,
int  y 
)

Increment the value of a given histogram index.

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

int tlHist2D::decVal ( int  x,
int  y 
)

Decrement the value of a given histogram index

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

int tlHist2D::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.

int tlHist2D::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.

float tlHist2D::compare ( tlHist2D *  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).
Return -1 if argument histogram is empty.
Note:
Both histogram must have the same dimension.

int tlHist2D::build ( tlPixel *  xdata,
tlPixel *  ydata,
int  len 
)

Build a 2D histogram from two tlPixel array.

Parameters:
xdata data set (first dimension)
ydata data set (second dimension)
len data sets 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 each dimension, which are then set automatically. See build(tlPixel *xdata, tlPixel *ydata, int len, int xlength, int ylength, int xoffset, int yoffset) to manually set the offset.
See also:
build(tlPixel *xdata, tlPixel *ydata, int len, int xlength, int ylength, int xoffset, int yoffset) build (tlPixel *src, int width, int height, int pixelWidth, tlPixel *mask, int xchannel, int ychannel, tlRect *rect)

int tlHist2D::build ( tlPixel *  xdata,
tlPixel *  ydata,
int  len,
int  xlength,
int  ylength,
int  xoffset = 0,
int  yoffset = 0 
)

Build a histogram from two tlPixel array.

Parameters:
xdata data set (first dimension)
ydata data set (second dimension)
len data sets length
xlength number of values in histogram on the X axis
xoffset first index of the histogram on the X axis
ylength number of values in histogram on the Y axis
yoffset first index of the histogram on the Y axis
Returns:
0 on success, -1 otherwise.
See error management for details.
Remarks:
See build(tlPixel *xdata, tlPixel *ydata, int len) to set the offset and length parameters automatically.
See also:
build(tlPixel *xdata, tlPixel *ydata, int len) build (tlPixel *src, int width, int height, int pixelWidth, tlPixel *mask, int xchannel, int ychannel, tlRect *rect)

int tlHist2D::build ( tlPixel *  src,
int  width,
int  height,
int  pixelWidth,
tlPixel *  mask,
int  xchannel,
int  ychannel,
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
xchannel the channel to consider (first dimension)
ychannel the channel to consider (second dimension)
rect the portion of the image to consider
Returns:
0 on success, -1 otherwise.
See error management for details.

int tlHist2D::build ( tlHRPixel *  xdata,
tlHRPixel *  ydata,
int  len 
)

Build a 2D histogram from two high-resolution pixel arrays.

Parameters:
xdata data set (first dimension)
ydata data set (second dimension)
len data sets 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 each dimension, which are then set automatically. See build(tlPixel *xdata, tlPixel *ydata, int len, int xlength, int ylength, int xoffset, int yoffset) to manually set the offset.
See also:
build(tlHRPixel *xdata, tlHRPixel *ydata, int len, int xlength, int ylength, int xoffset, int yoffset)

int tlHist2D::build ( tlHRPixel *  xdata,
tlHRPixel *  ydata,
int  len,
int  xlength,
int  ylength,
int  xoffset = 0,
int  yoffset = 0 
)

Build a histogram from two high-resolution pixel arrays.

Parameters:
xdata data set (first dimension)
ydata data set (second dimension)
len data sets length
xlength number of values in histogram on the X axis
xoffset first index of the histogram on the X axis
ylength number of values in histogram on the Y axis
yoffset first index of the histogram on the Y axis
Returns:
0 on success, -1 otherwise.
See error management for details.
Remarks:
See build(tlPixel *xdata, tlPixel *ydata, int len) to set the offset and length parameters automatically.
See also:
build(tlPixel *xdata, tlPixel *ydata, int len) build (tlPixel *src, int width, int height, int pixelWidth, tlPixel *mask, int xchannel, int ychannel, tlRect *rect)

int tlHist2D::getXHist ( tlHist *  hist  ) 

Project the histogram on the X axis and build the resulting unidimensional histogram.

Parameters:
hist [out] the resulting projected histogram
Returns:
0 on success, -1 otherwise.
See error management for details.

int tlHist2D::getYHist ( tlHist *  hist  ) 

Project the histogram on the Y axis and build the resulting unidimensional histogram.

Parameters:
hist [out] the resulting projected histogram
Returns:
0 on success, -1 otherwise.
See error management for details.

tlHist * tlHist2D::getXHist (  ) 

Project the histogram on the X axis and build the resulting unidimensional histogram.

Returns:
A pointer to the resulting projected histogram.
Note:
It is the responsability of the programmer to delete the tlHist object after use.

tlHist * tlHist2D::getYHist (  ) 

Project the histogram on the Y axis and build the resulting unidimensional histogram.

Returns:
A pointer to the resulting projected histogram.
Note:
It is the responsability of the programmer to delete the tlHist object after use.

int tlHist2D::toImage ( tlImage *  image  ) 

Converts the 2D histogram into a gray scale tlImage.

Parameters:
image [out] resulting image
Returns:
0 on success, -1 otherwise.
See error management for details.

tlImage * tlHist2D::toImage (  ) 

Converts the 2D histogram into a gray scale tlImage.

Returns:
A pointer to the resulting tlImage object.
Note:
It is the responsability of the programmer to delete the tlImage object after use.

Member Data Documentation

int tlHist2D::xChannel

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

int tlHist2D::yChannel

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

int ** tlHist2D::data

Contain the histogram data.

int * tlHist2D::xRank

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

int * tlHist2D::yRank

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

The documentation for this class was generated from the following files:
TLIB documentation - generated on 7 May 2008
Please address any questions to seb@tuyphon.com
(C) 2001-2008 - S. Grange
(C) 2001-2007 - VRAI Group, EPFL
All Rights Reserved.