Leptonica  1.82.0
Image processing and image analysis suite
pix4.c File Reference
#include <string.h>
#include <math.h>
#include "allheaders.h"

Go to the source code of this file.

Functions

NUMApixGetGrayHistogram (PIX *pixs, l_int32 factor)
 
NUMApixGetGrayHistogramMasked (PIX *pixs, PIX *pixm, l_int32 x, l_int32 y, l_int32 factor)
 
NUMApixGetGrayHistogramInRect (PIX *pixs, BOX *box, l_int32 factor)
 
NUMAApixGetGrayHistogramTiled (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)
 
NUMApixGetCmapHistogram (PIX *pixs, l_int32 factor)
 
NUMApixGetCmapHistogramMasked (PIX *pixs, PIX *pixm, l_int32 x, l_int32 y, l_int32 factor)
 
NUMApixGetCmapHistogramInRect (PIX *pixs, BOX *box, l_int32 factor)
 
l_ok pixCountRGBColorsByHash (PIX *pixs, l_int32 *pncolors)
 
l_ok pixCountRGBColors (PIX *pixs, l_int32 factor, l_int32 *pncolors)
 
L_AMAPpixGetColorAmapHistogram (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)
 
PIXpixGetAverageTiled (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 pixGetMaxColorIndex (PIX *pixs, l_int32 *pmaxindex)
 
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, PIXA *pixadb, l_int32 fontsize)
 
l_ok pixGetBinnedColor (PIX *pixs, PIX *pixg, l_int32 factor, l_int32 nbins, l_uint32 **pcarray, PIXA *pixadb)
 
PIXpixDisplayColorArray (l_uint32 *carray, l_int32 ncolors, l_int32 side, l_int32 ncols, l_int32 fontsize)
 
PIXpixRankBinByStrip (PIX *pixs, l_int32 direction, l_int32 size, l_int32 nbins, l_int32 type)
 
PIXpixaGetAlignedStats (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     pixCountRGBColorsByHash()
          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     pixGetMaxColorIndex()
          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]amapmap from pixel value to count
[in]valrgb or rgba pixel value
Returns
count, or -1 on error
Notes:
     (1) The ordered map is made by pixGetColorAmapHistogram().

Definition at line 967 of file pix4.c.

◆ pixaExtractColumnFromEachPix()

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

pixaExtractColumnFromEachPix()

Parameters
[in]pixaof identically sized, 8 bpp; not cmapped
[in]colcolumn index
[in]pixdpix into which each column is inserted
Returns
0 if OK, 1 on error

Definition at line 3107 of file pix4.c.

Referenced by pixaGetAlignedStats().

◆ pixaGetAlignedStats()

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

pixaGetAlignedStats()

Parameters
[in]pixaof identically sized, 8 bpp pix; not cmapped
[in]typeL_MEAN_ABSVAL, L_MEDIAN_VAL, L_MODE_VAL, L_MODE_COUNT
[in]nbinsof histogram for median and mode; ignored for mean
[in]threshon 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 3060 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]pixs8 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 1990 of file pix4.c.

◆ pixCountRGBColors()

l_ok pixCountRGBColors ( PIX pixs,
l_int32  factor,
l_int32 *  pncolors 
)

pixCountRGBColors()

Parameters
[in]pixsrgb or rgba
[in]factorsubsampling factor; integer >= 1
[out]pncolorsnumber of colors found
Returns
0 if OK, 1 on error
Notes:
     (1) If factor == 1, this gives the exact number of colors.
     (2) This is about 4x slower than pixCountRGBColorsByHash().

Definition at line 880 of file pix4.c.

◆ pixCountRGBColorsByHash()

l_ok pixCountRGBColorsByHash ( PIX pixs,
l_int32 *  pncolors 
)

pixCountRGBColorsByHash()

Parameters
[in]pixsrgb or rgba
[out]pncolorsnumber of colors found
Returns
0 if OK, 1 on error
Notes:
     (1) This is about 4x faster than pixCountRGBColors(),
         which uses an ordered map.

Definition at line 844 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]carrayarray of colors: 0xrrggbb00
[in]ncolorssize of array
[in]sidesize of each color square; suggest 200
[in]ncolsnumber of columns in output color matrix
[in]fontsizeto label each square with text. Valid set is {4,6,8,10,12,14,16,18,20}. Suggest 6 for 200x200 square. Use 0 to disable.
Returns
pixd color array, or NULL on error
Notes:
     (1) This generates an array of labeled color squares from an
         array of color values.
     (2) To make a single color square, use pixMakeColorSquare().

Definition at line 2877 of file pix4.c.

References bmfCreate(), bmfDestroy(), extractRGBValues(), L_ADD_BELOW, L_INSERT, pixaAddPix(), pixaCreate(), pixAddBorder(), pixAddSingleTextblock(), pixaDestroy(), pixaDisplayTiledInColumns(), pixClone(), 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]pixs8 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,yUL corner of pixm relative to the UL corner of pixs; can be < 0
[in]factorsubsampling factor; >= 1
[in]typeL_MEAN_ABSVAL, L_ROOT_MEAN_SQUARE, L_STANDARD_DEVIATION, L_VARIANCE
[out]pvalmeasured 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 1526 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]pixs32 bpp, or colormapped
[in]pixm[optional] 1 bpp mask over which average is to be taken; use all pixels if null
[in]x,yUL corner of pixm relative to the UL corner of pixs; can be < 0
[in]factorsubsampling factor; >= 1
[in]typeL_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 1424 of file pix4.c.

◆ pixGetAverageTiled()

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

pixGetAverageTiled()

Parameters
[in]pixs8 bpp, or colormapped
[in]sx,sytile size; must be at least 2 x 2
[in]typeL_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 1727 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]pixs32 bpp, or colormapped
[in]sx,sytile size; must be at least 2 x 2
[in]typeL_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 1650 of file pix4.c.

◆ pixGetBinnedColor()

l_ok pixGetBinnedColor ( PIX pixs,
PIX pixg,
l_int32  factor,
l_int32  nbins,
l_uint32 **  pcarray,
PIXA pixadb 
)

pixGetBinnedColor()

Parameters
[in]pixs32 bpp
[in]pixg8 bpp grayscale version of pixs
[in]factorsampling factor along pixel counting direction
[in]nbinsnumber of bins based on grayscale value {1,...,100}
[out]pcarrayarray of average color values in each bin
[in]pixadb[optional] debug: caller passes this in. Use to display output color squares and plots of color components.
Returns
0 if OK; 1 on error
Notes:
     (1) This takes a color image, a grayscale version, and the number
         of requested bins.  The pixels are ordered by the corresponding
         gray value and an equal number of pixels are put in each bin.
         The average color for each bin is returned as an array
         of l_uint32 colors in our standard RGBA ordering.  We require
         at least 5 pixels in each bin.
     (2) This is used by pixGetRankColorArray(), which generates the
         grayscale image pixg from the color image pixs.
     (3) Arrays of float64 are used for intermediate storage, without
         loss of precision, of the sampled uint32 pixel values.

Definition at line 2705 of file pix4.c.

◆ 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]pixs32 bpp rgb
[in]nbinsnumber of equal population bins; must be > 1
[in]factorsubsampling factor; >= 1
[in]colorL_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 2501 of file pix4.c.

◆ pixGetCmapHistogram()

NUMA* pixGetCmapHistogram ( PIX pixs,
l_int32  factor 
)

pixGetCmapHistogram()

Parameters
[in]pixscolormapped: d = 2, 4 or 8
[in]factorsubsampling 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 633 of file pix4.c.

Referenced by pixGetCmapHistogramInRect(), and pixGetCmapHistogramMasked().

◆ pixGetCmapHistogramInRect()

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

pixGetCmapHistogramInRect()

Parameters
[in]pixscolormapped: d = 2, 4 or 8
[in]box[optional] over which histogram is to be computed; use full image if NULL
[in]factorsubsampling 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 778 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]pixscolormapped: 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,yUL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null
[in]factorsubsampling 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 698 of file pix4.c.

References pixGetCmapHistogram().

◆ pixGetColorAmapHistogram()

L_AMAP* pixGetColorAmapHistogram ( PIX pixs,
l_int32  factor 
)

pixGetColorAmapHistogram()

Parameters
[in]pixsrgb or rgba
[in]factorsubsampling 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 916 of file pix4.c.

◆ pixGetColorHistogram()

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

pixGetColorHistogram()

Parameters
[in]pixsrgb or colormapped
[in]factorsubsampling factor; integer >= 1
[out]pnarred histogram
[out]pnaggreen histogram
[out]pnabblue 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 416 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]pixs32 bpp rgb, or colormapped
[in]pixm[optional] 1 bpp mask over which histogram is to be computed; use all pixels if null
[in]x,yUL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null
[in]factorsubsampling factor; integer >= 1
[out]pnarred histogram
[out]pnaggreen histogram
[out]pnabblue 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 518 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]pixs8 bpp; not cmapped
[in]typeL_MEAN_ABSVAL, L_MEDIAN_VAL, L_MODE_VAL, L_MODE_COUNT
[in]nbinsof histogram for median and mode; ignored for mean
[in]threshon histogram for mode val; ignored for all other types
[in]rowvectvector 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 3304 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]pixs8 bpp grayscale, 32 bpp rgb, or colormapped
[in]factorsubsampling factor; >= 1; ignored if colormapped
[in]typeL_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 2215 of file pix4.c.

References L_SELECT_MAX, and L_SELECT_MIN.

Referenced by bilateralCreate(), and pixMultiplyGray().

◆ pixGetGrayHistogram()

NUMA* pixGetGrayHistogram ( PIX pixs,
l_int32  factor 
)

pixGetGrayHistogram()

Parameters
[in]pixs1, 2, 4, 8, 16 bpp; can be colormapped
[in]factorsubsampling 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 115 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]pixs8 bpp, or colormapped
[in]box[optional] over which histogram is to be computed; use full image if NULL
[in]factorsubsampling 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 291 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]pixs8 bpp, or colormapped
[in]pixm[optional] 1 bpp mask over which histogram is to be computed; use all pixels if null
[in]x,yUL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null
[in]factorsubsampling 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 211 of file pix4.c.

References pixGetGrayHistogram().

◆ pixGetGrayHistogramTiled()

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

pixGetGrayHistogramTiled()

Parameters
[in]pixsany depth, colormap OK
[in]factorsubsampling factor; integer >= 1
[in]nx,nytiling; >= 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 359 of file pix4.c.

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

◆ pixGetMaxColorIndex()

l_ok pixGetMaxColorIndex ( PIX pixs,
l_int32 *  pmaxindex 
)

pixGetMaxColorIndex()

Parameters
[in]pixs1, 2, 4 or 8 bpp colormapped
[out]pmaxindexmax colormap index value
Returns
0 if OK, 1 on error

Definition at line 2427 of file pix4.c.

References pixGetDimensions().

◆ pixGetMaxValueInRect()

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

pixGetMaxValueInRect()

Parameters
[in]pixs8, 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 2352 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]pixs8 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,yUL corner of pixm relative to the UL corner of pixs; can be < 0
[in]factorsubsampling factor; >= 1
[out]pvalaverage 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.
     (6) For general averaging of 1, 2, 4 or 8 bpp grayscale, use
         pixAverageInRect().

Definition at line 1239 of file pix4.c.

◆ pixGetPixelStats()

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

pixGetPixelStats()

Parameters
[in]pixs8 bpp, 32 bpp or colormapped
[in]factorsubsampling factor; integer >= 1
[in]typeL_MEAN_ABSVAL, L_ROOT_MEAN_SQUARE, L_STANDARD_DEVIATION, L_VARIANCE
[out]pvaluepixel 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 1357 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]pixs8 bpp grayscale, 32 bpp rgb, or colormapped
[in]factorsubsampling factor; >= 1; ignored if colormapped
[in]colorL_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 2137 of file pix4.c.

◆ pixGetRankColorArray()

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

pixGetRankColorArray()

Parameters
[in]pixs32 bpp or cmapped
[in]nbinsnumber of equal population bins; must be > 1
[in]typecolor selection flag
[in]factorsubsampling factor; integer >= 1
[out]pcarrayarray of colors, ranked by intensity
[in]pixadb[optional] debug: caller passes this in. Use to display color squares and to capture plots of color components
[in]fontsize[optional] debug: only used if pixadb exists. Valid set is {4,6,8,10,12,14,16,18,20}. 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) The pixels are ordered by the value of the selected color
         value, and an equal number are placed in nbins.  The average
         color in each bin is returned in a color array with 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.  Must be at least 10 samples/bin.
     (4) A crude "rank color" as a function of rank can 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].

Definition at line 2600 of file pix4.c.

◆ pixGetRankValue()

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

pixGetRankValue()

Parameters
[in]pixs8 bpp, 32 bpp or colormapped
[in]factorsubsampling factor; integer >= 1
[in]rankbetween 0.0 and 1.0; 1.0 is brightest, 0.0 is darkest
[out]pvaluepixel value corresponding to input rank
Returns
0 if OK, 1 on error
Notes:
     (1) Simple function to get a rank value (color) 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().
     (2) For RGB, this treats each color component independently.
         It calls pixGetGrayHistogramMasked() on each component, and
         uses the returned gray histogram to get the rank value.
         It then combines the 3 rank values into a color pixel.

Definition at line 1006 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]pixs8 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,yUL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null
[in]factorsubsampling factor; integer >= 1
[in]rankbetween 0.0 and 1.0; 1.0 is brightest, 0.0 is darkest
[out]pvalpixel 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 1168 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]pixs32 bpp
[in]pixm[optional] 1 bpp mask over which rank val is to be taken; use all pixels if null
[in]x,yUL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null
[in]factorsubsampling factor; integer >= 1
[in]rankbetween 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 1076 of file pix4.c.

Referenced by evalColorfillData().

◆ pixGetRowStats()

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

pixGetRowStats()

Parameters
[in]pixs8 bpp; not cmapped
[in]typeL_MEAN_ABSVAL, L_MEDIAN_VAL, L_MODE_VAL, L_MODE_COUNT
[in]nbinsof histogram for median and mode; ignored for mean
[in]threshon histogram for mode; ignored for mean and median
[in]colvectvector 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 3182 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]pixs32 bpp or cmapped
[in]directionL_SCAN_HORIZONTAL or L_SCAN_VERTICAL
[in]sizeof strips in scan direction
[in]nbinsnumber of equal population bins; must be > 1
[in]typecolor selection flag
Returns
pixd result, or NULL on error
Notes:
     (1) This generates a pix of height nbins, where each column
         represents a horizontal or vertical strip of the input image.
         If direction == L_SCAN_HORIZONTAL, the input image is
         tiled into vertical strips of width size, where size is
         chosen as 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,
         L_SELECT_HUE, L_SELECT_SATURATION.
         It determines how the rank ordering is done.
     (4) Typical input values might be size = 5, nbins = 10.

Definition at line 2953 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]pixs8 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 1830 of file pix4.c.

◆ pixSetPixelColumn()

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

pixSetPixelColumn()

Parameters
[in]pix8 bpp; not cmapped
[in]colcolumn index
[in]colvectvector of floats
Returns
0 if OK, 1 on error

Definition at line 3405 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]pixsany depth; cmapped ok
[in]scorefractfraction of the max score, used to determine the range over which the histogram min is searched
[in]factorsubsampling 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 3504 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]pixsany depth; cmapped ok
[in]factorsubsampling factor; integer >= 1
[in]threshthreshold 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 3445 of file pix4.c.

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