pix4.c File Reference

#include <string.h>
#include <math.h>
#include "allheaders.h"

Go to the source code of this file.

Functions
NUMA *	pixGetGrayHistogram (PIX *pixs, l_int32 factor)
NUMA *	pixGetGrayHistogramMasked (PIX *pixs, PIX *pixm, l_int32 x, l_int32 y, l_int32 factor)
NUMA *	pixGetGrayHistogramInRect (PIX *pixs, BOX *box, l_int32 factor)
NUMAA *	pixGetGrayHistogramTiled (PIX *pixs, l_int32 factor, l_int32 nx, l_int32 ny)
l_ok	pixGetColorHistogram (PIX *pixs, l_int32 factor, NUMA **pnar, NUMA **pnag, NUMA **pnab)
l_ok	pixGetColorHistogramMasked (PIX *pixs, PIX *pixm, l_int32 x, l_int32 y, l_int32 factor, NUMA **pnar, NUMA **pnag, NUMA **pnab)
NUMA *	pixGetCmapHistogram (PIX *pixs, l_int32 factor)
NUMA *	pixGetCmapHistogramMasked (PIX *pixs, PIX *pixm, l_int32 x, l_int32 y, l_int32 factor)
NUMA *	pixGetCmapHistogramInRect (PIX *pixs, BOX *box, l_int32 factor)
l_int32	pixCountRGBColors (PIX *pixs)
L_AMAP *	pixGetColorAmapHistogram (PIX *pixs, l_int32 factor)
l_int32	amapGetCountForColor (L_AMAP *amap, l_uint32 val)
l_ok	pixGetRankValue (PIX *pixs, l_int32 factor, l_float32 rank, l_uint32 *pvalue)
l_ok	pixGetRankValueMaskedRGB (PIX *pixs, PIX *pixm, l_int32 x, l_int32 y, l_int32 factor, l_float32 rank, l_float32 *prval, l_float32 *pgval, l_float32 *pbval)
l_ok	pixGetRankValueMasked (PIX *pixs, PIX *pixm, l_int32 x, l_int32 y, l_int32 factor, l_float32 rank, l_float32 *pval, NUMA **pna)
l_ok	pixGetPixelAverage (PIX *pixs, PIX *pixm, l_int32 x, l_int32 y, l_int32 factor, l_uint32 *pval)
l_ok	pixGetPixelStats (PIX *pixs, l_int32 factor, l_int32 type, l_uint32 *pvalue)
l_ok	pixGetAverageMaskedRGB (PIX *pixs, PIX *pixm, l_int32 x, l_int32 y, l_int32 factor, l_int32 type, l_float32 *prval, l_float32 *pgval, l_float32 *pbval)
l_ok	pixGetAverageMasked (PIX *pixs, PIX *pixm, l_int32 x, l_int32 y, l_int32 factor, l_int32 type, l_float32 *pval)
l_ok	pixGetAverageTiledRGB (PIX *pixs, l_int32 sx, l_int32 sy, l_int32 type, PIX **ppixr, PIX **ppixg, PIX **ppixb)
PIX *	pixGetAverageTiled (PIX *pixs, l_int32 sx, l_int32 sy, l_int32 type)
l_int32	pixRowStats (PIX *pixs, BOX *box, NUMA **pnamean, NUMA **pnamedian, NUMA **pnamode, NUMA **pnamodecount, NUMA **pnavar, NUMA **pnarootvar)
l_int32	pixColumnStats (PIX *pixs, BOX *box, NUMA **pnamean, NUMA **pnamedian, NUMA **pnamode, NUMA **pnamodecount, NUMA **pnavar, NUMA **pnarootvar)
l_ok	pixGetRangeValues (PIX *pixs, l_int32 factor, l_int32 color, l_int32 *pminval, l_int32 *pmaxval)
l_ok	pixGetExtremeValue (PIX *pixs, l_int32 factor, l_int32 type, l_int32 *prval, l_int32 *pgval, l_int32 *pbval, l_int32 *pgrayval)
l_ok	pixGetMaxValueInRect (PIX *pixs, BOX *box, l_uint32 *pmaxval, l_int32 *pxmax, l_int32 *pymax)
l_ok	pixGetBinnedComponentRange (PIX *pixs, l_int32 nbins, l_int32 factor, l_int32 color, l_int32 *pminval, l_int32 *pmaxval, l_uint32 **pcarray, l_int32 fontsize)
l_ok	pixGetRankColorArray (PIX *pixs, l_int32 nbins, l_int32 type, l_int32 factor, l_uint32 **pcarray, l_int32 debugflag, l_int32 fontsize)
l_ok	pixGetBinnedColor (PIX *pixs, PIX *pixg, l_int32 factor, l_int32 nbins, NUMA *nalut, l_uint32 **pcarray, l_int32 debugflag)
PIX *	pixDisplayColorArray (l_uint32 *carray, l_int32 ncolors, l_int32 side, l_int32 ncols, l_int32 fontsize)
PIX *	pixRankBinByStrip (PIX *pixs, l_int32 direction, l_int32 size, l_int32 nbins, l_int32 type)
PIX *	pixaGetAlignedStats (PIXA *pixa, l_int32 type, l_int32 nbins, l_int32 thresh)
l_ok	pixaExtractColumnFromEachPix (PIXA *pixa, l_int32 col, PIX *pixd)
l_ok	pixGetRowStats (PIX *pixs, l_int32 type, l_int32 nbins, l_int32 thresh, l_float32 *colvect)
l_ok	pixGetColumnStats (PIX *pixs, l_int32 type, l_int32 nbins, l_int32 thresh, l_float32 *rowvect)
l_ok	pixSetPixelColumn (PIX *pix, l_int32 col, l_float32 *colvect)
l_ok	pixThresholdForFgBg (PIX *pixs, l_int32 factor, l_int32 thresh, l_int32 *pfgval, l_int32 *pbgval)
l_ok	pixSplitDistributionFgBg (PIX *pixs, l_float32 scorefract, l_int32 factor, l_int32 *pthresh, l_int32 *pfgval, l_int32 *pbgval, PIX **ppixdb)

Detailed Description

   This file has these operations:

     (1) Pixel histograms
     (2) Pixel row/column statistics
     (3) Foreground/background estimation

   Pixel histogram, rank val, averaging and min/max
          NUMA       *pixGetGrayHistogram()
          NUMA       *pixGetGrayHistogramMasked()
          NUMA       *pixGetGrayHistogramInRect()
          NUMAA      *pixGetGrayHistogramTiled()
          l_int32     pixGetColorHistogram()
          l_int32     pixGetColorHistogramMasked()
          NUMA       *pixGetCmapHistogram()
          NUMA       *pixGetCmapHistogramMasked()
          NUMA       *pixGetCmapHistogramInRect()
          l_int32     pixCountRGBColors()
          L_AMAP     *pixGetColorAmapHistogram()
          l_int32     amapGetCountForColor()
          l_int32     pixGetRankValue()
          l_int32     pixGetRankValueMaskedRGB()
          l_int32     pixGetRankValueMasked()
          l_int32     pixGetPixelAverage()
          l_int32     pixGetPixelStats()
          l_int32     pixGetAverageMaskedRGB()
          l_int32     pixGetAverageMasked()
          l_int32     pixGetAverageTiledRGB()
          PIX        *pixGetAverageTiled()
          NUMA       *pixRowStats()
          NUMA       *pixColumnStats()
          l_int32     pixGetRangeValues()
          l_int32     pixGetExtremeValue()
          l_int32     pixGetMaxValueInRect()
          l_int32     pixGetBinnedComponentRange()
          l_int32     pixGetRankColorArray()
          l_int32     pixGetBinnedColor()
          PIX        *pixDisplayColorArray()
          PIX        *pixRankBinByStrip()

   Pixelwise aligned statistics
          PIX        *pixaGetAlignedStats()
          l_int32     pixaExtractColumnFromEachPix()
          l_int32     pixGetRowStats()
          l_int32     pixGetColumnStats()
          l_int32     pixSetPixelColumn()

   Foreground/background estimation
          l_int32     pixThresholdForFgBg()
          l_int32     pixSplitDistributionFgBg()

Definition in file pix4.c.

Function Documentation

amapGetCountForColor()

l_int32 amapGetCountForColor	(	L_AMAP *	amap,
		l_uint32	val
	)

amapGetCountForColor()

Parameters

[in]	amap	map from pixel value to count
[in]	val	rgb or rgba pixel value

Returns

count, or -1 on error

Notes:
     (1) The ordered map is made by pixGetColorAmapHistogram().

Definition at line 910 of file pix4.c.

pixaExtractColumnFromEachPix()

l_ok pixaExtractColumnFromEachPix	(	PIXA *	pixa,
		l_int32	col,
		PIX *	pixd
	)

pixaExtractColumnFromEachPix()

Parameters

[in]	pixa	of identically sized, 8 bpp; not cmapped
[in]	col	column index
[in]	pixd	pix into which each column is inserted

Returns

0 if OK, 1 on error

Definition at line 2975 of file pix4.c.

Referenced by pixaGetAlignedStats().

pixaGetAlignedStats()

PIX* pixaGetAlignedStats	(	PIXA *	pixa,
		l_int32	type,
		l_int32	nbins,
		l_int32	thresh
	)

pixaGetAlignedStats()

Parameters

[in]	pixa	of identically sized, 8 bpp pix; not cmapped
[in]	type	L_MEAN_ABSVAL, L_MEDIAN_VAL, L_MODE_VAL, L_MODE_COUNT
[in]	nbins	of histogram for median and mode; ignored for mean
[in]	thresh	on histogram for mode val; ignored for all other types

Returns

pix with pixelwise aligned stats, or NULL on error.

Notes:
     (1) Each pixel in the returned pix represents an average
         (or median, or mode) over the corresponding pixels in each
         pix in the pixa.
     (2) The thresh parameter works with L_MODE_VAL only, and
         sets a minimum occupancy of the mode bin.
         If the occupancy of the mode bin is less than thresh, the
         mode value is returned as 0.  To always return the actual
         mode value, set thresh = 0.  See pixGetRowStats().

Definition at line 2928 of file pix4.c.

References L_MEAN_ABSVAL, L_MEDIAN_VAL, L_MODE_COUNT, L_MODE_VAL, pixaExtractColumnFromEachPix(), pixaGetCount(), pixaGetPixDimensions(), pixCreate(), pixDestroy(), pixGetRowStats(), and pixSetPixelColumn().

pixColumnStats()

l_int32 pixColumnStats	(	PIX *	pixs,
		BOX *	box,
		NUMA **	pnamean,
		NUMA **	pnamedian,
		NUMA **	pnamode,
		NUMA **	pnamodecount,
		NUMA **	pnavar,
		NUMA **	pnarootvar
	)

pixColumnStats()

Parameters

[in]	pixs	8 bpp; not cmapped
[in]	box	[optional] clipping box; can be null
[out]	pnamean	[optional] numa of mean values
[out]	pnamedian	[optional] numa of median values
[out]	pnamode	[optional] numa of mode intensity values
[out]	pnamodecount	[optional] numa of mode counts
[out]	pnavar	[optional] numa of variance
[out]	pnarootvar	[optional] numa of square root of variance

Returns

na numa of requested statistic for each column, or NULL on error

Notes:
     (1) This computes numas that represent row vectors of statistics,
         with each of its values derived from the corresponding col of a Pix.
     (2) Use NULL on input to prevent computation of any of the 5 numas.
     (3) Other functions that compute pixel column statistics are:
            pixCountPixelsByColumn()
            pixAverageByColumn()
            pixVarianceByColumn()
            pixGetColumnStats()

Definition at line 1916 of file pix4.c.

pixCountRGBColors()

l_int32 pixCountRGBColors

(

PIX *

pixs

)

pixCountRGBColors()

Parameters

[in]

pixs

rgb or rgba

Returns

ncolors, or -1 on error

Definition at line 831 of file pix4.c.

pixDisplayColorArray()

PIX* pixDisplayColorArray	(	l_uint32 *	carray,
		l_int32	ncolors,
		l_int32	side,
		l_int32	ncols,
		l_int32	fontsize
	)

pixDisplayColorArray()

Parameters

[in]	carray	array of colors: 0xrrggbb00
[in]	ncolors	size of array
[in]	side	size of each color square; suggest 200
[in]	ncols	number of columns in output color matrix
[in]	fontsize	to label each square with text. Valid set is {4,6,8,10,12,14,16,18,20}. Use 0 to disable.

Returns

pixd color array, or NULL on error

Definition at line 2759 of file pix4.c.

References bmfCreate(), bmfDestroy(), extractRGBValues(), L_ADD_BELOW, pixaCreate(), pixaDestroy(), pixaDisplay(), pixCreate(), pixDestroy(), and pixSetAllArbitrary().

pixGetAverageMasked()

l_ok pixGetAverageMasked	(	PIX *	pixs,
		PIX *	pixm,
		l_int32	x,
		l_int32	y,
		l_int32	factor,
		l_int32	type,
		l_float32 *	pval
	)

pixGetAverageMasked()

Parameters

[in]	pixs	8 or 16 bpp, or colormapped
[in]	pixm	[optional] 1 bpp mask over which average is to be taken; use all pixels if null
[in]	x,y	UL corner of pixm relative to the UL corner of pixs; can be < 0
[in]	factor	subsampling factor; >= 1
[in]	type	L_MEAN_ABSVAL, L_ROOT_MEAN_SQUARE, L_STANDARD_DEVIATION, L_VARIANCE
[out]	pval	measured value of given 'type'

Returns

0 if OK, 1 on error

Notes:
     (1) Use L_MEAN_ABSVAL to get the average value of pixels in pixs
         that are under the fg of the optional mask.  If the mask
         is null, it finds the average of the pixels in pixs.
     (2) Likewise, use L_ROOT_MEAN_SQUARE to get the rms value of
         pixels in pixs, either masked or not; L_STANDARD_DEVIATION
         to get the standard deviation from the mean of the pixels;
         L_VARIANCE to get the average squared difference from the
         expected value.  The variance is the square of the stdev.
         For the standard deviation, we use
             sqrt([([x] - x)]^2) = sqrt([x^2] - [x]^2)
     (3) Set the subsampling factor > 1 to reduce the amount of
         computation.
     (4) Clipping of pixm (if it exists) to pixs is done in the inner loop.
     (5) Input x,y are ignored unless pixm exists.
     (6) A better name for this would be: pixGetPixelStatsGray()

Definition at line 1457 of file pix4.c.

Referenced by pixThresholdForFgBg().

pixGetAverageMaskedRGB()

l_ok pixGetAverageMaskedRGB	(	PIX *	pixs,
		PIX *	pixm,
		l_int32	x,
		l_int32	y,
		l_int32	factor,
		l_int32	type,
		l_float32 *	prval,
		l_float32 *	pgval,
		l_float32 *	pbval
	)

pixGetAverageMaskedRGB()

Parameters

[in]	pixs	32 bpp, or colormapped
[in]	pixm	[optional] 1 bpp mask over which average is to be taken; use all pixels if null
[in]	x,y	UL corner of pixm relative to the UL corner of pixs; can be < 0
[in]	factor	subsampling factor; >= 1
[in]	type	L_MEAN_ABSVAL, L_ROOT_MEAN_SQUARE, L_STANDARD_DEVIATION, L_VARIANCE
[out]	prval	[optional] measured red value of given 'type'
[out]	pgval	[optional] measured green value of given 'type'
[out]	pbval	[optional] measured blue value of given 'type'

Returns

0 if OK, 1 on error

Notes:
     (1) For usage, see pixGetAverageMasked().
     (2) If there is a colormap, it is removed before the 8 bpp
         component images are extracted.
     (3) A better name for this would be: pixGetPixelStatsRGB()

Definition at line 1361 of file pix4.c.

pixGetAverageTiled()

PIX* pixGetAverageTiled	(	PIX *	pixs,
		l_int32	sx,
		l_int32	sy,
		l_int32	type
	)

pixGetAverageTiled()

Parameters

[in]	pixs	8 bpp, or colormapped
[in]	sx,sy	tile size; must be at least 2 x 2
[in]	type	L_MEAN_ABSVAL, L_ROOT_MEAN_SQUARE, L_STANDARD_DEVIATION

Returns

pixd average values in each tile, or NULL on error

Notes:
     (1) Only computes for tiles that are entirely contained in pixs.
     (2) Use L_MEAN_ABSVAL to get the average abs value within the tile;
         L_ROOT_MEAN_SQUARE to get the rms value within each tile;
         L_STANDARD_DEVIATION to get the standard dev. from the average
         within each tile.
     (3) If colormapped, converts to 8 bpp gray.

Definition at line 1653 of file pix4.c.

References pixGetDimensions().

pixGetAverageTiledRGB()

l_ok pixGetAverageTiledRGB	(	PIX *	pixs,
		l_int32	sx,
		l_int32	sy,
		l_int32	type,
		PIX **	ppixr,
		PIX **	ppixg,
		PIX **	ppixb
	)

pixGetAverageTiledRGB()

Parameters

[in]	pixs	32 bpp, or colormapped
[in]	sx,sy	tile size; must be at least 2 x 2
[in]	type	L_MEAN_ABSVAL, L_ROOT_MEAN_SQUARE, L_STANDARD_DEVIATION
[out]	ppixr	[optional] tiled 'average' of red component
[out]	ppixg	[optional] tiled 'average' of green component
[out]	ppixb	[optional] tiled 'average' of blue component

Returns

0 if OK, 1 on error

Notes:
     (1) For usage, see pixGetAverageTiled().
     (2) If there is a colormap, it is removed before the 8 bpp
         component images are extracted.

Definition at line 1576 of file pix4.c.

pixGetBinnedColor()

l_ok pixGetBinnedColor	(	PIX *	pixs,
		PIX *	pixg,
		l_int32	factor,
		l_int32	nbins,
		NUMA *	nalut,
		l_uint32 **	pcarray,
		l_int32	debugflag
	)

pixGetBinnedColor()

Parameters

[in]	pixs	32 bpp
[in]	pixg	8 bpp grayscale version of pixs
[in]	factor	sampling factor along pixel counting direction
[in]	nbins	number of intensity bins
[in]	nalut	LUT for mapping from intensity to bin number
[out]	pcarray	array of average color values in each bin
[in]	debugflag	1 to display output debug plots of color components; 2 to write them as png to file

Returns

0 if OK; 1 on error

Notes:
     (1) This takes a color image, a grayscale (intensity) version,
         a LUT from intensity to bin number, and the number of bins.
         It computes the average color for pixels whose intensity
         is in each bin.  This is returned as an array of l_uint32
         colors in our standard RGBA ordering.
     (2) This function generates equal width intensity bins and
         finds the average color in each bin.  Compare this with
         pixGetRankColorArray(), which rank orders the pixels
         by the value of the selected component in each pixel,
         sets up bins with equal population (not intensity width!),
         and gets the average color in each bin.

Definition at line 2629 of file pix4.c.

References pixGetData(), and pixGetDimensions().

pixGetBinnedComponentRange()

l_ok pixGetBinnedComponentRange	(	PIX *	pixs,
		l_int32	nbins,
		l_int32	factor,
		l_int32	color,
		l_int32 *	pminval,
		l_int32 *	pmaxval,
		l_uint32 **	pcarray,
		l_int32	fontsize
	)

pixGetBinnedComponentRange()

Parameters

[in]	pixs	32 bpp rgb
[in]	nbins	number of equal population bins; must be > 1
[in]	factor	subsampling factor; >= 1
[in]	color	L_SELECT_RED, L_SELECT_GREEN or L_SELECT_BLUE
[out]	pminval	[optional] minimum value of component
[out]	pmaxval	[optional] maximum value of component
[out]	pcarray	[optional] color array of bins
[in]	fontsize	[optional] 0 for no debug; for debug, valid set is {4,6,8,10,12,14,16,18,20}.

Returns

0 if OK, 1 on error

Notes:
     (1) This returns the min and max average values of the
         selected color component in the set of rank bins,
         where the ranking is done using the specified component.

Definition at line 2367 of file pix4.c.

pixGetCmapHistogram()

NUMA* pixGetCmapHistogram	(	PIX *	pixs,
		l_int32	factor
	)

pixGetCmapHistogram()

Parameters

[in]	pixs	colormapped: d = 2, 4 or 8
[in]	factor	subsampling factor; integer >= 1

Returns

na histogram of cmap indices, or NULL on error

Notes:
     (1) This generates a histogram of colormap pixel indices,
         and is of size 2^d.
     (2) Set the subsampling factor > 1 to reduce the amount of computation.

Definition at line 627 of file pix4.c.

Referenced by pixGetCmapHistogramInRect(), and pixGetCmapHistogramMasked().

pixGetCmapHistogramInRect()

NUMA* pixGetCmapHistogramInRect	(	PIX *	pixs,
		BOX *	box,
		l_int32	factor
	)

pixGetCmapHistogramInRect()

Parameters

[in]	pixs	colormapped: d = 2, 4 or 8
[in]	box	[optional] over which histogram is to be computed; use full image if NULL
[in]	factor	subsampling factor; integer >= 1

Returns

na histogram, or NULL on error

Notes:
     (1) This generates a histogram of colormap pixel indices,
         and is of size 2^d.
     (2) Set the subsampling factor > 1 to reduce the amount of computation.
     (3) Clipping to the box is done in the inner loop.

Definition at line 772 of file pix4.c.

References pixGetCmapHistogram().

pixGetCmapHistogramMasked()

NUMA* pixGetCmapHistogramMasked	(	PIX *	pixs,
		PIX *	pixm,
		l_int32	x,
		l_int32	y,
		l_int32	factor
	)

pixGetCmapHistogramMasked()

Parameters

[in]	pixs	colormapped: d = 2, 4 or 8
[in]	pixm	[optional] 1 bpp mask over which histogram is to be computed; use all pixels if null
[in]	x,y	UL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null
[in]	factor	subsampling factor; integer >= 1

Returns

na histogram, or NULL on error

Notes:
     (1) This generates a histogram of colormap pixel indices,
         and is of size 2^d.
     (2) Set the subsampling factor > 1 to reduce the amount of computation.
     (3) Clipping of pixm to pixs is done in the inner loop.

Definition at line 692 of file pix4.c.

References pixGetCmapHistogram().

pixGetColorAmapHistogram()

L_AMAP* pixGetColorAmapHistogram	(	PIX *	pixs,
		l_int32	factor
	)

pixGetColorAmapHistogram()

Parameters

[in]	pixs	rgb or rgba
[in]	factor	subsampling factor; integer >= 1

Returns

amap, or NULL on error

Notes:
     (1) This generates an ordered map from pixel value to histogram count.
     (2) Use amapGetCountForColor() to use the map to look up a count.

Definition at line 861 of file pix4.c.

pixGetColorHistogram()

l_ok pixGetColorHistogram	(	PIX *	pixs,
		l_int32	factor,
		NUMA **	pnar,
		NUMA **	pnag,
		NUMA **	pnab
	)

pixGetColorHistogram()

Parameters

[in]	pixs	rgb or colormapped
[in]	factor	subsampling factor; integer >= 1
[out]	pnar	red histogram
[out]	pnag	green histogram
[out]	pnab	blue histogram

Returns

0 if OK, 1 on error

Notes:
     (1) This generates a set of three 256 entry histograms,
         one for each color component (r,g,b).
     (2) Set the subsampling factor > 1 to reduce the amount of computation.

Definition at line 410 of file pix4.c.

References pixGetDimensions().

Referenced by pixGetColorHistogramMasked().

pixGetColorHistogramMasked()

l_ok pixGetColorHistogramMasked	(	PIX *	pixs,
		PIX *	pixm,
		l_int32	x,
		l_int32	y,
		l_int32	factor,
		NUMA **	pnar,
		NUMA **	pnag,
		NUMA **	pnab
	)

pixGetColorHistogramMasked()

Parameters

[in]	pixs	32 bpp rgb, or colormapped
[in]	pixm	[optional] 1 bpp mask over which histogram is to be computed; use all pixels if null
[in]	x,y	UL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null
[in]	factor	subsampling factor; integer >= 1
[out]	pnar	red histogram
[out]	pnag	green histogram
[out]	pnab	blue histogram

Returns

0 if OK, 1 on error

Notes:
     (1) This generates a set of three 256 entry histograms,
     (2) Set the subsampling factor > 1 to reduce the amount of computation.
     (3) Clipping of pixm (if it exists) to pixs is done in the inner loop.
     (4) Input x,y are ignored unless pixm exists.

Definition at line 512 of file pix4.c.

References pixGetColorHistogram(), and pixGetDimensions().

pixGetColumnStats()

l_ok pixGetColumnStats	(	PIX *	pixs,
		l_int32	type,
		l_int32	nbins,
		l_int32	thresh,
		l_float32 *	rowvect
	)

pixGetColumnStats()

Parameters

[in]	pixs	8 bpp; not cmapped
[in]	type	L_MEAN_ABSVAL, L_MEDIAN_VAL, L_MODE_VAL, L_MODE_COUNT
[in]	nbins	of histogram for median and mode; ignored for mean
[in]	thresh	on histogram for mode val; ignored for all other types
[in]	rowvect	vector of results gathered down the columns of pixs

Returns

0 if OK, 1 on error

Notes:
     (1) This computes a row vector of statistics using each
         column of a Pix.  The result is put in rowvect.
     (2) The thresh parameter works with L_MODE_VAL only, and
         sets a minimum occupancy of the mode bin.
         If the occupancy of the mode bin is less than thresh, the
         mode value is returned as 0.  To always return the actual
         mode value, set thresh = 0.
     (3) What is the meaning of this thresh parameter?
         For each column, the total count in the histogram is h, the
         image height.  So thresh, relative to h, gives a measure
         of the ratio of the bin width to the width of the distribution.
         The larger thresh, the narrower the distribution must be
         for the mode value to be returned (instead of returning 0).

Definition at line 3172 of file pix4.c.

pixGetExtremeValue()

l_ok pixGetExtremeValue	(	PIX *	pixs,
		l_int32	factor,
		l_int32	type,
		l_int32 *	prval,
		l_int32 *	pgval,
		l_int32 *	pbval,
		l_int32 *	pgrayval
	)

pixGetExtremeValue()

Parameters

[in]	pixs	8 bpp grayscale, 32 bpp rgb, or colormapped
[in]	factor	subsampling factor; >= 1; ignored if colormapped
[in]	type	L_SELECT_MIN or L_SELECT_MAX
[out]	prval	[optional] red component
[out]	pgval	[optional] green component
[out]	pbval	[optional] blue component
[out]	pgrayval	[optional] min or max gray value

Returns

0 if OK, 1 on error

Notes:
     (1) If pixs is grayscale, the result is returned in &grayval.
         Otherwise, if there is a colormap or d == 32,
         each requested color component is returned.  At least
         one color component (address) must be input.

Definition at line 2141 of file pix4.c.

References L_SELECT_MAX, and L_SELECT_MIN.

Referenced by bilateralCreate().

pixGetGrayHistogram()

NUMA* pixGetGrayHistogram	(	PIX *	pixs,
		l_int32	factor
	)

pixGetGrayHistogram()

Parameters

[in]	pixs	1, 2, 4, 8, 16 bpp; can be colormapped
[in]	factor	subsampling factor; integer >= 1

Returns

na histogram, or NULL on error

Notes:
     (1) If pixs has a colormap, it is converted to 8 bpp gray.
         If you want a histogram of the colormap indices, use
         pixGetCmapHistogram().
     (2) If pixs does not have a colormap, the output histogram is
         of size 2^d, where d is the depth of pixs.
     (3) Set the subsampling factor > 1 to reduce the amount of computation.

Definition at line 109 of file pix4.c.

Referenced by pixCompareTilesByHisto(), pixGetGrayHistogramInRect(), pixGetGrayHistogramMasked(), pixGetGrayHistogramTiled(), and pixSplitDistributionFgBg().

pixGetGrayHistogramInRect()

NUMA* pixGetGrayHistogramInRect	(	PIX *	pixs,
		BOX *	box,
		l_int32	factor
	)

pixGetGrayHistogramInRect()

Parameters

[in]	pixs	8 bpp, or colormapped
[in]	box	[optional] over which histogram is to be computed; use full image if NULL
[in]	factor	subsampling factor; integer >= 1

Returns

na histogram, or NULL on error

Notes:
     (1) If pixs is cmapped, it is converted to 8 bpp gray.
         If you want a histogram of the colormap indices, use
         pixGetCmapHistogramInRect().
     (2) This always returns a 256-value histogram of pixel values.
     (3) Set the subsampling factor > 1 to reduce the amount of computation.

Definition at line 285 of file pix4.c.

References pixGetGrayHistogram().

pixGetGrayHistogramMasked()

NUMA* pixGetGrayHistogramMasked	(	PIX *	pixs,
		PIX *	pixm,
		l_int32	x,
		l_int32	y,
		l_int32	factor
	)

pixGetGrayHistogramMasked()

Parameters

[in]	pixs	8 bpp, or colormapped
[in]	pixm	[optional] 1 bpp mask over which histogram is to be computed; use all pixels if null
[in]	x,y	UL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null
[in]	factor	subsampling factor; integer >= 1

Returns

na histogram, or NULL on error

Notes:
     (1) If pixs is cmapped, it is converted to 8 bpp gray.
         If you want a histogram of the colormap indices, use
         pixGetCmapHistogramMasked().
     (2) This always returns a 256-value histogram of pixel values.
     (3) Set the subsampling factor > 1 to reduce the amount of computation.
     (4) Clipping of pixm (if it exists) to pixs is done in the inner loop.
     (5) Input x,y are ignored unless pixm exists.

Definition at line 205 of file pix4.c.

References pixGetGrayHistogram().

pixGetGrayHistogramTiled()

NUMAA* pixGetGrayHistogramTiled	(	PIX *	pixs,
		l_int32	factor,
		l_int32	nx,
		l_int32	ny
	)

pixGetGrayHistogramTiled()

Parameters

[in]	pixs	any depth, colormap OK
[in]	factor	subsampling factor; integer >= 1
[in]	nx,ny	tiling; >= 1; typically small

Returns

naa set of histograms, or NULL on error

Notes:
     (1) If pixs is cmapped, it is converted to 8 bpp gray.
     (2) This returns a set of 256-value histograms of pixel values.
     (3) Set the subsampling factor > 1 to reduce the amount of computation.

Definition at line 353 of file pix4.c.

References L_CLONE, L_INSERT, numaaAddNuma(), numaaCreate(), pixaDestroy(), pixaGetPix(), pixaSplitPix(), pixConvertTo8(), pixDestroy(), and pixGetGrayHistogram().

pixGetMaxValueInRect()

l_ok pixGetMaxValueInRect	(	PIX *	pixs,
		BOX *	box,
		l_uint32 *	pmaxval,
		l_int32 *	pxmax,
		l_int32 *	pymax
	)

pixGetMaxValueInRect()

Parameters

[in]	pixs	8, 16 or 32 bpp grayscale; no color space components
[in]	box	[optional] region; set box = NULL to use entire pixs
[out]	pmaxval	[optional] max value in region
[out]	pxmax	[optional] x location of max value
[out]	pymax	[optional] y location of max value

Returns

0 if OK, 1 on error

Notes:
     (1) This can be used to find the maximum and its location
         in a 2-dimensional histogram, where the x and y directions
         represent two color components (e.g., saturation and hue).
     (2) Note that here a 32 bpp pixs has pixel values that are simply
         numbers.  They are not 8 bpp components in a colorspace.

Definition at line 2278 of file pix4.c.

pixGetPixelAverage()

l_ok pixGetPixelAverage	(	PIX *	pixs,
		PIX *	pixm,
		l_int32	x,
		l_int32	y,
		l_int32	factor,
		l_uint32 *	pval
	)

pixGetPixelAverage()

Parameters

[in]	pixs	8 or 32 bpp, or colormapped
[in]	pixm	[optional] 1 bpp mask over which average is to be taken; use all pixels if null
[in]	x,y	UL corner of pixm relative to the UL corner of pixs; can be < 0
[in]	factor	subsampling factor; >= 1
[out]	pval	average pixel value

Returns

0 if OK, 1 on error

Notes:
     (1) For rgb pix, this is a more direct computation of the
         average value of the pixels in pixs that are under the
         mask pixm. It is faster than pixGetPixelStats(), which
         calls pixGetAverageMaskedRGB() and has the overhead of
         generating a temporary pix of each of the three components;
         this can take most of the time if factor > 1.
     (2) If pixm is null, this gives the average value of all
         pixels in pixs.  The returned value is an integer.
     (3) For color pixs, the returned pixel value is in the standard
         uint32 RGBA packing.
     (4) Clipping of pixm (if it exists) to pixs is done in the inner loop.
     (5) Input x,y are ignored if pixm does not exist.

Definition at line 1176 of file pix4.c.

pixGetPixelStats()

l_ok pixGetPixelStats	(	PIX *	pixs,
		l_int32	factor,
		l_int32	type,
		l_uint32 *	pvalue
	)

pixGetPixelStats()

Parameters

[in]	pixs	8 bpp, 32 bpp or colormapped
[in]	factor	subsampling factor; integer >= 1
[in]	type	L_MEAN_ABSVAL, L_ROOT_MEAN_SQUARE, L_STANDARD_DEVIATION, L_VARIANCE
[out]	pvalue	pixel value corresponding to input type

Returns

0 if OK, 1 on error

Notes:
     (1) Simple function to get one of four statistical values of an image.
     (2) It does not take a mask: it uses the entire image.
     (3) To get the average pixel value of an RGB image, suggest using
         pixGetPixelAverage(), which is considerably faster.

Definition at line 1294 of file pix4.c.

pixGetRangeValues()

l_ok pixGetRangeValues	(	PIX *	pixs,
		l_int32	factor,
		l_int32	color,
		l_int32 *	pminval,
		l_int32 *	pmaxval
	)

pixGetRangeValues()

Parameters

[in]	pixs	8 bpp grayscale, 32 bpp rgb, or colormapped
[in]	factor	subsampling factor; >= 1; ignored if colormapped
[in]	color	L_SELECT_RED, L_SELECT_GREEN or L_SELECT_BLUE
[out]	pminval	[optional] minimum value of component
[out]	pmaxval	[optional] maximum value of component

Returns

0 if OK, 1 on error

Notes:
     (1) If pixs is 8 bpp grayscale, the color selection type is ignored.

Definition at line 2063 of file pix4.c.

pixGetRankColorArray()

l_ok pixGetRankColorArray	(	PIX *	pixs,
		l_int32	nbins,
		l_int32	type,
		l_int32	factor,
		l_uint32 **	pcarray,
		l_int32	debugflag,
		l_int32	fontsize
	)

pixGetRankColorArray()

Parameters

[in]	pixs	32 bpp or cmapped
[in]	nbins	number of equal population bins; must be > 1
[in]	type	color selection flag
[in]	factor	subsampling factor; integer >= 1
[out]	pcarray	array of colors, ranked by intensity
[in]	debugflag	1 to display color squares and plots of color components; 2 to write them as png to file
[in]	fontsize	[optional] 0 for no debug; for debug, valid set is {4,6,8,10,12,14,16,18,20}. Ignored if debugflag == 0. fontsize == 6 is typical.

Returns

0 if OK, 1 on error

Notes:
     (1) The color selection flag is one of: L_SELECT_RED, L_SELECT_GREEN,
         L_SELECT_BLUE, L_SELECT_MIN, L_SELECT_MAX, L_SELECT_AVERAGE,
         L_SELECT_HUE, L_SELECT_SATURATION.
     (2) Then it finds the histogram of the selected color type in each
         RGB pixel.  For each of the nbins sets of pixels,
         ordered by this color type value, find the average RGB color,
         and return this as a "rank color" array.  The output array
         has nbins colors.
     (3) Set the subsampling factor > 1 to reduce the amount of
         computation.  Typically you want at least 10,000 pixels
         for reasonable statistics.
     (4) The rank color as a function of rank can then be found from
            rankint = (l_int32)(rank * (nbins - 1) + 0.5);
            extractRGBValues(array[rankint], &rval, &gval, &bval);
         where the rank is in [0.0 ... 1.0].
         This function is meant to be simple and approximate.
     (5) Compare this with pixGetBinnedColor(), which generates equal
         width intensity bins and finds the average color in each bin.

Definition at line 2467 of file pix4.c.

pixGetRankValue()

l_ok pixGetRankValue	(	PIX *	pixs,
		l_int32	factor,
		l_float32	rank,
		l_uint32 *	pvalue
	)

pixGetRankValue()

Parameters

[in]	pixs	8 bpp, 32 bpp or colormapped
[in]	factor	subsampling factor; integer >= 1
[in]	rank	between 0.0 and 1.0; 1.0 is brightest, 0.0 is darkest
[out]	pvalue	pixel value corresponding to input rank

Returns

0 if OK, 1 on error

Notes:
     (1) Simple function to get rank values of an image.
         For a color image, the median value (rank = 0.5) can be
         used to linearly remap the colors based on the median
         of a target image, using pixLinearMapToTargetColor().

Definition at line 945 of file pix4.c.

pixGetRankValueMasked()

l_ok pixGetRankValueMasked	(	PIX *	pixs,
		PIX *	pixm,
		l_int32	x,
		l_int32	y,
		l_int32	factor,
		l_float32	rank,
		l_float32 *	pval,
		NUMA **	pna
	)

pixGetRankValueMasked()

Parameters

[in]	pixs	8 bpp, or colormapped
[in]	pixm	[optional] 1 bpp mask, over which the rank val is to be taken; use all pixels if null
[in]	x,y	UL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null
[in]	factor	subsampling factor; integer >= 1
[in]	rank	between 0.0 and 1.0; 1.0 is brightest, 0.0 is darkest
[out]	pval	pixel value corresponding to input rank
[out]	pna	[optional] of histogram

Returns

0 if OK, 1 on error

Notes:
     (1) Computes the rank value of pixels in pixs that are under
         the fg of the optional mask.  If the mask is null, it
         computes the average of the pixels in pixs.
     (2) Set the subsampling factor > 1 to reduce the amount of
         computation.
     (3) Clipping of pixm (if it exists) to pixs is done in the inner loop.
     (4) Input x,y are ignored unless pixm exists.
     (5) The rank must be in [0.0 ... 1.0], where the brightest pixel
         has rank 1.0.  For the median pixel value, use 0.5.
     (6) The histogram can optionally be returned, so that other rank
         values can be extracted without recomputing the histogram.
         In that case, just use
             numaHistogramGetValFromRank(na, rank, &val);
         on the returned Numa for additional rank values.

Definition at line 1107 of file pix4.c.

pixGetRankValueMaskedRGB()

l_ok pixGetRankValueMaskedRGB	(	PIX *	pixs,
		PIX *	pixm,
		l_int32	x,
		l_int32	y,
		l_int32	factor,
		l_float32	rank,
		l_float32 *	prval,
		l_float32 *	pgval,
		l_float32 *	pbval
	)

pixGetRankValueMaskedRGB()

Parameters

[in]	pixs	32 bpp
[in]	pixm	[optional] 1 bpp mask over which rank val is to be taken; use all pixels if null
[in]	x,y	UL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null
[in]	factor	subsampling factor; integer >= 1
[in]	rank	between 0.0 and 1.0; 1.0 is brightest, 0.0 is darkest
[out]	prval	[optional] red component val for input rank
[out]	pgval	[optional] green component val for input rank
[out]	pbval	[optional] blue component val for input rank

Returns

0 if OK, 1 on error

Notes:
     (1) Computes the rank component values of pixels in pixs that
         are under the fg of the optional mask.  If the mask is null, it
         computes the average of the pixels in pixs.
     (2) Set the subsampling factor > 1 to reduce the amount of
         computation.
     (4) Input x,y are ignored unless pixm exists.
     (5) The rank must be in [0.0 ... 1.0], where the brightest pixel
         has rank 1.0.  For the median pixel value, use 0.5.

Definition at line 1015 of file pix4.c.

pixGetRowStats()

l_ok pixGetRowStats	(	PIX *	pixs,
		l_int32	type,
		l_int32	nbins,
		l_int32	thresh,
		l_float32 *	colvect
	)

pixGetRowStats()

Parameters

[in]	pixs	8 bpp; not cmapped
[in]	type	L_MEAN_ABSVAL, L_MEDIAN_VAL, L_MODE_VAL, L_MODE_COUNT
[in]	nbins	of histogram for median and mode; ignored for mean
[in]	thresh	on histogram for mode; ignored for mean and median
[in]	colvect	vector of results gathered across the rows of pixs

Returns

0 if OK, 1 on error

Notes:
     (1) This computes a column vector of statistics using each
         row of a Pix.  The result is put in colvect.
     (2) The thresh parameter works with L_MODE_VAL only, and
         sets a minimum occupancy of the mode bin.
         If the occupancy of the mode bin is less than thresh, the
         mode value is returned as 0.  To always return the actual
         mode value, set thresh = 0.
     (3) What is the meaning of this thresh parameter?
         For each row, the total count in the histogram is w, the
         image width.  So thresh, relative to w, gives a measure
         of the ratio of the bin width to the width of the distribution.
         The larger thresh, the narrower the distribution must be
         for the mode value to be returned (instead of returning 0).
     (4) If the Pix consists of a set of corresponding columns,
         one for each Pix in a Pixa, the width of the Pix is the
         number of Pix in the Pixa and the column vector can
         be stored as a column in a Pix of the same size as
         each Pix in the Pixa.

Definition at line 3050 of file pix4.c.

Referenced by pixaGetAlignedStats().

pixRankBinByStrip()

PIX* pixRankBinByStrip	(	PIX *	pixs,
		l_int32	direction,
		l_int32	size,
		l_int32	nbins,
		l_int32	type
	)

pixRankBinByStrip()

Parameters

[in]	pixs	32 bpp or cmapped
[in]	direction	L_SCAN_HORIZONTAL or L_SCAN_VERTICAL
[in]	size	of strips in scan direction
[in]	nbins	number of equal population bins; must be > 1
[in]	type	color selection flag

Returns

pixd result, or NULL on error

Notes:
     (1) This generates a pix where each column represents a strip of
         the input image.  If direction == L_SCAN_HORIZONTAL, the
         input impage is tiled into vertical strips of width size,
         where size is a compromise between getting better spatial
         columnwise resolution (small size) and getting better
         columnwise statistical information (larger size).  Likewise
         with rows of the image if direction == L_SCAN_VERTICAL.
     (2) For L_HORIZONTAL_SCAN, the output pix contains rank binned
         median colors in each column that correspond to a vertical
         strip of width size in the input image.
     (3) The color selection flag is one of: L_SELECT_RED, L_SELECT_GREEN,
         L_SELECT_BLUE, L_SELECT_MIN, L_SELECT_MAX, L_SELECT_AVERAGE.
         It determines how the rank ordering is done.
     (4) Typical input values might be size = 5, nbins = 10.

Definition at line 2831 of file pix4.c.

pixRowStats()

l_int32 pixRowStats	(	PIX *	pixs,
		BOX *	box,
		NUMA **	pnamean,
		NUMA **	pnamedian,
		NUMA **	pnamode,
		NUMA **	pnamodecount,
		NUMA **	pnavar,
		NUMA **	pnarootvar
	)

pixRowStats()

Parameters

[in]	pixs	8 bpp; not cmapped
[in]	box	[optional] clipping box; can be null
[out]	pnamean	[optional] numa of mean values
[out]	pnamedian	[optional] numa of median values
[out]	pnamode	[optional] numa of mode intensity values
[out]	pnamodecount	[optional] numa of mode counts
[out]	pnavar	[optional] numa of variance
[out]	pnarootvar	[optional] numa of square root of variance

Returns

na numa of requested statistic for each row, or NULL on error

Notes:
     (1) This computes numas that represent column vectors of statistics,
         with each of its values derived from the corresponding row of a Pix.
     (2) Use NULL on input to prevent computation of any of the 5 numas.
     (3) Other functions that compute pixel row statistics are:
            pixCountPixelsByRow()
            pixAverageByRow()
            pixVarianceByRow()
            pixGetRowStats()

Definition at line 1756 of file pix4.c.

pixSetPixelColumn()

l_ok pixSetPixelColumn	(	PIX *	pix,
		l_int32	col,
		l_float32 *	colvect
	)

pixSetPixelColumn()

Parameters

[in]	pix	8 bpp; not cmapped
[in]	col	column index
[in]	colvect	vector of floats

Returns

0 if OK, 1 on error

Definition at line 3273 of file pix4.c.

Referenced by pixaGetAlignedStats().

pixSplitDistributionFgBg()

l_ok pixSplitDistributionFgBg	(	PIX *	pixs,
		l_float32	scorefract,
		l_int32	factor,
		l_int32 *	pthresh,
		l_int32 *	pfgval,
		l_int32 *	pbgval,
		PIX **	ppixdb
	)

pixSplitDistributionFgBg()

Parameters

[in]	pixs	any depth; cmapped ok
[in]	scorefract	fraction of the max score, used to determine the range over which the histogram min is searched
[in]	factor	subsampling factor; integer >= 1
[out]	pthresh	[optional] best threshold for separating
[out]	pfgval	[optional] average foreground value
[out]	pbgval	[optional] average background value
[out]	ppixdb	[optional] plot of distribution and split point

Returns

0 if OK, 1 on error

Notes:
     (1) See numaSplitDistribution() for details on the underlying
         method of choosing a threshold.

Definition at line 3372 of file pix4.c.

References gplotCreate(), lept_mkdir(), numaDestroy(), numaSplitDistribution(), pixConvertTo8BySampling(), and pixGetGrayHistogram().

pixThresholdForFgBg()

l_ok pixThresholdForFgBg	(	PIX *	pixs,
		l_int32	factor,
		l_int32	thresh,
		l_int32 *	pfgval,
		l_int32 *	pbgval
	)

pixThresholdForFgBg()

Parameters

[in]	pixs	any depth; cmapped ok
[in]	factor	subsampling factor; integer >= 1
[in]	thresh	threshold for generating foreground mask
[out]	pfgval	[optional] average foreground value
[out]	pbgval	[optional] average background value

Returns

0 if OK, 1 on error

Definition at line 3313 of file pix4.c.

References L_MEAN_ABSVAL, pixConvertTo8BySampling(), pixDestroy(), pixGetAverageMasked(), pixInvert(), and pixThresholdToBinary().