Leptonica  1.83.1
Image processing and image analysis suite
colorcontent.c File Reference
#include "allheaders.h"

Go to the source code of this file.

Functions

l_ok pixColorContent (PIX *pixs, l_int32 rref, l_int32 gref, l_int32 bref, l_int32 mingray, PIX **ppixr, PIX **ppixg, PIX **ppixb)
 
PIXpixColorMagnitude (PIX *pixs, l_int32 rref, l_int32 gref, l_int32 bref, l_int32 type)
 
l_ok pixColorFraction (PIX *pixs, l_int32 darkthresh, l_int32 lightthresh, l_int32 diffthresh, l_int32 factor, l_float32 *ppixfract, l_float32 *pcolorfract)
 
PIXpixColorShiftWhitePoint (PIX *pixs, l_int32 rref, l_int32 gref, l_int32 bref)
 
PIXpixMaskOverColorPixels (PIX *pixs, l_int32 threshdiff, l_int32 mindist)
 
PIXpixMaskOverGrayPixels (PIX *pixs, l_int32 maxlimit, l_int32 satlimit)
 
PIXpixMaskOverColorRange (PIX *pixs, l_int32 rmin, l_int32 rmax, l_int32 gmin, l_int32 gmax, l_int32 bmin, l_int32 bmax)
 
l_ok pixFindColorRegions (PIX *pixs, PIX *pixm, l_int32 factor, l_int32 lightthresh, l_int32 darkthresh, l_int32 mindiff, l_int32 colordiff, l_float32 edgefract, l_float32 *pcolorfract, PIX **pcolormask1, PIX **pcolormask2, PIXA *pixadb)
 
l_ok pixNumSignificantGrayColors (PIX *pixs, l_int32 darkthresh, l_int32 lightthresh, l_float32 minfract, l_int32 factor, l_int32 *pncolors)
 
l_ok pixColorsForQuantization (PIX *pixs, l_int32 thresh, l_int32 *pncolors, l_int32 *piscolor, l_int32 debug)
 
l_ok pixNumColors (PIX *pixs, l_int32 factor, l_int32 *pncolors)
 
PIXpixConvertRGBToCmapLossless (PIX *pixs)
 
l_ok pixGetMostPopulatedColors (PIX *pixs, l_int32 sigbits, l_int32 factor, l_int32 ncolors, l_uint32 **parray, PIXCMAP **pcmap)
 
PIXpixSimpleColorQuantize (PIX *pixs, l_int32 sigbits, l_int32 factor, l_int32 ncolors)
 
NUMApixGetRGBHistogram (PIX *pixs, l_int32 sigbits, l_int32 factor)
 
l_ok makeRGBIndexTables (l_uint32 **prtab, l_uint32 **pgtab, l_uint32 **pbtab, l_int32 sigbits)
 
l_ok getRGBFromIndex (l_uint32 index, l_int32 sigbits, l_int32 *prval, l_int32 *pgval, l_int32 *pbval)
 
l_ok pixHasHighlightRed (PIX *pixs, l_int32 factor, l_float32 minfract, l_float32 fthresh, l_int32 *phasred, l_float32 *pratio, PIX **ppixdb)
 

Detailed Description


     Build an image of the color content, on a per-pixel basis,
     as a measure of the amount of divergence of each color
     component (R,G,B) from gray.
        l_int32    pixColorContent()

     Find the 'amount' of color in an image, on a per-pixel basis,
     as a measure of the difference of the pixel color from gray.
        PIX       *pixColorMagnitude()

     Find the fraction of pixels with "color" that are not close to black
        l_int32    pixColorFraction()

     Do a linear TRC to map colors so that the three input reference
     values go to white.  These three numbers are typically the median
     or average background values.
        PIX       *pixColorShiftWhitePoint()

     Generate a mask over pixels that have sufficient color and
     are not too close to gray pixels.
        PIX       *pixMaskOverColorPixels()

     Generate a mask over dark pixels with little color
        PIX       *pixMaskOverGrayPixels()

     Generate mask over pixels within a prescribed cube in RGB space
        PIX       *pixMaskOverColorRange()

     Determine if there are significant color regions that are
     not background in a page image
        l_int32    pixFindColorRegions()

     Find the number of perceptually significant gray intensities
     in a grayscale image.
        l_int32    pixNumSignificantGrayColors()

     Identify images where color quantization will cause posterization
     due to the existence of many colors in low-gradient regions.
        l_int32    pixColorsForQuantization()

     Find the number of unique colors in an image
        l_int32    pixNumColors()

     Lossless conversion of RGB image to colormapped
        PIX       *pixConvertRGBToCmapLossless()

     Find the most "populated" colors in the image (and quantize)
        l_int32    pixGetMostPopulatedColors()
        PIX       *pixSimpleColorQuantize()

     Construct a color histogram based on rgb indices
        NUMA      *pixGetRGBHistogram()
        l_int32    makeRGBIndexTables()
        l_int32    getRGBFromIndex()

     Identify images that have highlight (red) color
        l_int32    pixHasHighlightRed()

 Color is tricky.  If we consider gray (r = g = b) to have no color
 content, how should we define the color content in each component
 of an arbitrary pixel, as well as the overall color magnitude?

 I can think of three ways to define the color content in each component:

 (1) Linear.  For each component, take the difference from the average
     of all three.
 (2) Linear.  For each component, take the difference from the average
     of the other two.
 (3) Nonlinear.  For each component, take the minimum of the differences
     from the other two.

 How might one choose from among these?  Consider two different situations:
 (a) r = g = 0, b = 255            {255}   /255/   <255>
 (b) r = 0, g = 127, b = 255       {191}   /128/   <255>
 How much g is in each of these?  The three methods above give:
 (a)  1: 85   2: 127   3: 0        [85]
 (b)  1: 0    2: 0     3: 127      [0]
 How much b is in each of these?
 (a)  1: 170  2: 255   3: 255      [255]
 (b)  1: 127  2: 191   3: 127      [191]
 The number I'd "like" to give is in [].  (Please don't ask why, it's
 just a feeling.

 So my preferences seem to be somewhere between (1) and (2).
 (3) is just too "decisive!"  Let's pick (2).

 We also allow compensation for white imbalance.  For each
 component, we do a linear TRC (gamma = 1.0), where the black
 point remains at 0 and the white point is given by the input
 parameter.  This is equivalent to doing a global remapping,
 as with pixGlobalNormRGB(), followed by color content (or magnitude)
 computation, but without the overhead of first creating the
 white point normalized image.

 Another useful property is the overall color magnitude in the pixel.
 For this there are again several choices, such as:
     (a) rms deviation from the mean
     (b) the average L1 deviation from the mean
     (c) the maximum (over components) of one of the color
         content measures given above.

 For now, we will consider three of the methods in (c):
   L_INTERMED_DIFF
       Define the color magnitude as the intermediate value of the
       three differences between the three components.
       For (a) and (b) above, this value is in /../.
    L_AVE_MAX_DIFF_2
       Define the color magnitude as the maximum over components
       of the difference between the component value and the
       average of the other two.  It is easy to show that
       this is equivalent to selecting the two component values
       that are closest to each other, averaging them, and
       using the distance from that average to the third component.
       For (a) and (b) above, this value is in {..}.
   L_MAX_DIFF
       Define the color magnitude as the maximum value of the
       three differences between the three components.
       For (a) and (b) above, this value is in <..>.

Definition in file colorcontent.c.

Function Documentation

◆ getRGBFromIndex()

l_ok getRGBFromIndex ( l_uint32  index,
l_int32  sigbits,
l_int32 *  prval,
l_int32 *  pgval,
l_int32 *  pbval 
)

getRGBFromIndex()

Parameters
[in]indexrgbindex
[in]sigbits2-6, significant bits retained in the quantizer for each component of the input image
[out]prval,pgval,pbvalrgb values
Returns
0 if OK, 1 on error
Notes:
     (1) The index is expressed in bits, based on the the
         sigbits of the r, g and b components, as
            r7 r6 ... g7 g6 ... b7 b6 ...
     (2) The computed rgb values are in the center of the quantized cube.
         The extra bit that is OR'd accomplishes this.

Definition at line 1881 of file colorcontent.c.

◆ makeRGBIndexTables()

l_ok makeRGBIndexTables ( l_uint32 **  prtab,
l_uint32 **  pgtab,
l_uint32 **  pbtab,
l_int32  sigbits 
)

makeRGBIndexTables()

Parameters
[out]prtab,pgtab,pbtab256-entry rgb index tables
[in]sigbits2-6, significant bits retained in the quantizer for each component of the input image
Returns
0 if OK, 1 on error
Notes:
     (1) These tables are used to map from rgb sample values to
         an rgb index, using
            rgbindex = rtab[rval] | gtab[gval] | btab[bval]
         where, e.g., if sigbits = 3, the index is a 9 bit integer:
            r7 r6 r5 g7 g6 g5 b7 b6 b5

Definition at line 1789 of file colorcontent.c.

◆ pixColorContent()

l_ok pixColorContent ( PIX pixs,
l_int32  rref,
l_int32  gref,
l_int32  bref,
l_int32  mingray,
PIX **  ppixr,
PIX **  ppixg,
PIX **  ppixb 
)

pixColorContent()

Parameters
[in]pixs32 bpp rgb or 8 bpp colormapped
[in]rrefreference value for red component
[in]grefreference value for green component
[in]brefreference value for blue component
[in]mingraymin gray value for which color is measured
[out]ppixr[optional] 8 bpp red 'content'
[out]ppixg[optional] 8 bpp green 'content'
[out]ppixb[optional] 8 bpp blue 'content'
Returns
0 if OK, 1 on error
Notes:
     (1) This returns the color content in each component, which is
         a measure of the deviation from gray, and is defined
         as the difference between the component and the average of
         the other two components.  See the discussion at the
         top of this file.
     (2) The three numbers (rref, gref and bref) can be thought
         of in two ways:
           (a) as the values in the image corresponding to white,
               to compensate for an unbalanced color white point.
           (b) the median or mean values of the background color of
               a scan.
         The gamma TRC transformation is used to modify all colors so that
         these reference values become white.
         These three numbers must either be all 0 or all non-zero.
         To skip the TRC transform, set them all to 0.
     (3) If the maximum component after white point correction,
         max(r,g,b), is less than mingray, all color components
         for that pixel are set to zero.
         Use mingray = 0 to turn off this filtering of dark pixels.
     (4) Therefore, use 0 for all four input parameters if the color
         magnitude is to be calculated without either white balance
         correction or dark filtering.

Definition at line 202 of file colorcontent.c.

References pixColorShiftWhitePoint(), pixCreate(), pixGetData(), and pixGetDimensions().

◆ pixColorFraction()

l_ok pixColorFraction ( PIX pixs,
l_int32  darkthresh,
l_int32  lightthresh,
l_int32  diffthresh,
l_int32  factor,
l_float32 *  ppixfract,
l_float32 *  pcolorfract 
)

pixColorFraction()

Parameters
[in]pixs32 bpp rgb
[in]darkthreshthreshold near black; if the largest (lightest) component is below this, the pixel is not considered in the statistics; typ. 20
[in]lightthreshthreshold near white; if the smallest (darkest) component is above this, the pixel is not considered in the statistics; typ. 244
[in]diffthreshthresh for the maximum difference between component values; below this the pixel is not considered to have sufficient color
[in]factorsubsampling factor
[out]ppixfractfraction of pixels in intermediate brightness range that were considered for color content
[out]pcolorfractfraction of pixels that meet the criterion for sufficient color; 0.0 on error
Returns
0 if OK, 1 on error
Notes:
     (1) This function is asking the question: to what extent does the
         image appear to have color?   The amount of color a pixel
         appears to have depends on both the deviation of the
         individual components from their average and on the average
         intensity itself.  For example, the color will be much more
         obvious with a small deviation from white than the same
         deviation from black.
     (2) Any pixel that meets these three tests is considered a
         colorful pixel:
           (a) the lightest component must equal or exceed darkthresh
           (b) the darkest component must not exceed lightthresh
           (c) the max difference between components must equal or
               exceed diffthresh.
     (3) The dark pixels are removed from consideration because
         they don't appear to have color.
     (4) The very lightest pixels are removed because if an image
         has a lot of "white", the color fraction will be artificially
         low, even if all the other pixels are colorful.
     (5) If pixfract is very small, there are few pixels that are neither
         black nor white.  If colorfract is very small, the pixels
         that are neither black nor white have very little color
         content.  The product 'pixfract * colorfract' gives the
         fraction of pixels with significant color content.
     (6) One use of this function is as a preprocessing step for median
         cut quantization (colorquant2.c), which does a very poor job
         splitting the color space into rectangular volume elements when
         all the pixels are near the diagonal of the color cube.  For
         octree quantization of an image with only gray values, the
         2^(level) octcubes on the diagonal are the only ones
         that can be occupied.

Definition at line 490 of file colorcontent.c.

◆ pixColorMagnitude()

PIX* pixColorMagnitude ( PIX pixs,
l_int32  rref,
l_int32  gref,
l_int32  bref,
l_int32  type 
)

pixColorMagnitude()

Parameters
[in]pixs32 bpp rgb or 8 bpp colormapped
[in]rrefreference value for red component
[in]grefreference value for green component
[in]brefreference value for blue component
[in]typechooses the method for calculating the color magnitude: L_INTERMED_DIFF, L_AVE_MAX_DIFF_2, L_MAX_DIFF
Returns
pixd 8 bpp, amount of color in each source pixel, or NULL on error
Notes:
     (1) For an RGB image, a gray pixel is one where all three components
         are equal.  We define the amount of color in an RGB pixel as
         a function depending on the absolute value of the differences
         between the three color components.  Consider the two largest
         of these differences.  The pixel component in common to these
         two differences is the color farthest from the other two.
         The color magnitude in an RGB pixel can be taken as one
         of these three definitions:
           (a) The minimum value of these two differences.  This is
               the intermediate value of the three distances between
               component values.
           (b) The average of these two differences.  This is the
               average distance from the two components that are
               nearest to each other to the third component.
           (c) The maximum difference between component values.
     (2) As an example, suppose that R and G are the closest in
         magnitude.  Then the color is determined as either:
           (a) The minimum distance of B from these two:
                  min(|B - R|, |B - G|).
           (b) The average distance of B from these two:
                  (|B - R| + |B - G|) / 2
           (c) The maximum distance of B from these two:
                  max(|B - R|, |B - G|)
     (3) This example can be visualized graphically.  Put the R,G and B
         component values on a line; e.g.,
               G...R...........B
           (a) B - R
           (b) B - (R + G) / 2
           (c) B - G
     (4) The three methods for choosing the color magnitude from
         the components are selected with these flags:
           (a) L_INTERMED_DIFF
           (b) L_AVE_MAX_DIFF_2
           (c) L_MAX_DIFF
     (5) The three numbers (rref, gref and bref) can be thought
         of in two ways:
           (a) as the values in the image corresponding to white,
               to compensate for an unbalanced color white point.
           (b) the median or mean values of the background color of
               a scan.
         The gamma TRC transformation is used to modify all colors so that
         these reference values become white.
         These three numbers must either be all 0 or all non-zero.
         To skip the TRC transform, set them all to 0.

Definition at line 360 of file colorcontent.c.

References L_AVE_MAX_DIFF_2, L_INTERMED_DIFF, L_MAX_DIFF, pixColorShiftWhitePoint(), pixCreate(), pixGetData(), and pixGetDimensions().

◆ pixColorsForQuantization()

l_ok pixColorsForQuantization ( PIX pixs,
l_int32  thresh,
l_int32 *  pncolors,
l_int32 *  piscolor,
l_int32  debug 
)

pixColorsForQuantization()

Parameters
[in]pixs8 bpp gray or 32 bpp rgb; with or without colormap
[in]threshbinary threshold on edge gradient; 0 for default
[out]pncolorsthe number of colors found
[out]piscolor[optional] 1 if significant color is found; 0 otherwise. If pixs is 8 bpp, and does not have a colormap with color entries, this is 0
[in]debug1 to output masked image that is tested for colors; 0 otherwise
Returns
0 if OK, 1 on error.
Notes:
     (1) This function finds a measure of the number of colors that are
         found in low-gradient regions of an image.  By its
         magnitude relative to some threshold (not specified in
         this function), it gives a good indication of whether
         quantization will generate posterization.   This number
         is larger for images with regions of slowly varying
         intensity (if 8 bpp) or color (if rgb). Such images, if
         quantized, may require dithering to avoid posterization,
         and lossless compression is then expected to be poor.
     (2) If pixs has a colormap, the number of colors returned is
         the number in the colormap.
     (3) It is recommended that document images be reduced to a width
         of 800 pixels before applying this function.  Then it can
         be expected that color detection will be fairly accurate
         and the number of colors will reflect both the content and
         the type of compression to be used.  For less than 15 colors,
         there is unlikely to be a halftone image, and lossless
         quantization should give both a good visual result and
         better compression.
     (4) When using the default threshold on the gradient (15),
         images (both gray and rgb) where ncolors is greater than
         about 15 will compress poorly with either lossless
         compression or dithered quantization, and they may be
         posterized with non-dithered quantization.
     (5) For grayscale images, or images without significant color,
         this returns the number of significant gray levels in
         the low-gradient regions.  The actual number of gray levels
         can be large due to jpeg compression noise in the background.
     (6) Similarly, for color images, the actual number of different
         (r,g,b) colors in the low-gradient regions (rather than the
         number of occupied level 4 octcubes) can be quite large, e.g.,
         due to jpeg compression noise, even for regions that appear
         to be of a single color.  By quantizing to level 4 octcubes,
         most of these superfluous colors are removed from the counting.
     (7) The image is tested for color.  If there is very little color,
         it is thresholded to gray and the number of gray levels in
         the low gradient regions is found.  If the image has color,
         the number of occupied level 4 octcubes is found.
     (8) The number of colors in the low-gradient regions increases
         monotonically with the threshold thresh on the edge gradient.
     (9) Background: grayscale and color quantization is often useful
         to achieve highly compressed images with little visible
         distortion.  However, gray or color washes (regions of
         low gradient) can defeat this approach to high compression.
         How can one determine if an image is expected to compress
         well using gray or color quantization?  We use the fact that
           * gray washes, when quantized with less than 50 intensities,
             have posterization (visible boundaries between regions
             of uniform 'color') and poor lossless compression
           * color washes, when quantized with level 4 octcubes,
             typically result in both posterization and the occupancy
             of many level 4 octcubes.
         Images can have colors either intrinsically or as jpeg
         compression artifacts.  This function reduces but does not
         completely eliminate measurement of jpeg quantization noise
         in the white background of grayscale or color images.

Definition at line 1268 of file colorcontent.c.

◆ pixColorShiftWhitePoint()

PIX* pixColorShiftWhitePoint ( PIX pixs,
l_int32  rref,
l_int32  gref,
l_int32  bref 
)

pixColorShiftWhitePoint()

Parameters
[in]pixs32 bpp rgb or 8 bpp colormapped
[in]rrefreference value for red component
[in]grefreference value for green component
[in]brefreference value for blue component
Returns
pix2 32 bpp if OK, NULL on error
Notes:
     (1) This returns a pix where the colors are linearly mapped to
         so that the components go to 255 at the input reference values.
     (2) These three numbers (rref, gref and bref) can be thought
         of in two ways:
           (a) as the values in the image corresponding to white,
               to compensate for an unbalanced color white point.
           (b) the median or mean values of the background color of
               an image.
         A linear (gamma = 1) TRC transformation is used.
     (3) Any existing colormap is removed and a 32 bpp rgb pix is returned.
     (4) No transformation is applied if any of the three numbers are <= 0.
         If any are < 0, or if some but not all are 0, a warning is given.

Definition at line 577 of file colorcontent.c.

Referenced by pixColorContent(), and pixColorMagnitude().

◆ pixConvertRGBToCmapLossless()

PIX* pixConvertRGBToCmapLossless ( PIX pixs)

pixConvertRGBToCmapLossless()

Parameters
[in]pixs32 bpp RGB
Returns
pixd if num colors <= 256; null otherwise or on error
Notes:
     (1) If there are not more than 256 colors, this losslessly
         converts and RGB image to a colormapped one, with the
         smallest pixel depth required to hold all the colors.

Definition at line 1509 of file colorcontent.c.

◆ pixFindColorRegions()

l_ok pixFindColorRegions ( PIX pixs,
PIX pixm,
l_int32  factor,
l_int32  lightthresh,
l_int32  darkthresh,
l_int32  mindiff,
l_int32  colordiff,
l_float32  edgefract,
l_float32 *  pcolorfract,
PIX **  pcolormask1,
PIX **  pcolormask2,
PIXA pixadb 
)

pixFindColorRegions()

Parameters
[in]pixs32 bpp rgb
[in]pixm[optional] 1 bpp mask image
[in]factorsubsample factor; integer >= 1
[in]lightthreshthreshold for component average in lightest of 10 buckets; typ. 210; -1 for default
[in]darkthreshthreshold to eliminate dark pixels (e.g., text) from consideration; typ. 70; -1 for default.
[in]mindiffminimum difference (b - r) and (g - r), used to find blue or green pixels; typ. 10; -1 for default
[in]colordiffminimum difference in (max - min) component to qualify as a color pixel; typ. 90; -1 for default
[in]edgefractfraction of image half-width and half-height for which color pixels are ignored; typ. 0.05.
[out]pcolorfractfraction of 'color' pixels found
[out]pcolormask1[optional] mask over background color, if any
[out]pcolormask2[optional] filtered mask over background color
[out]pixadb[optional] debug intermediate results
Returns
0 if OK, 1 on error
Notes:
     (1) This function tries to determine if there is a significant
         color or darker region on a scanned page image, where part
         of the image is background that is either white or reddish.
         This also allows extraction of regions of colored pixels that
         have a smaller red component than blue or green components.
     (2) If pixm exists, pixels under its fg are combined with
         dark pixels to make a mask of pixels not to be considered
         as color candidates.
     (3) There are four thresholds.
         * lightthresh: compute the average value of each rgb pixel,
           and make 10 buckets by value.  If the lightest bucket gray
           value is below lightthresh, the image is not considered
           to have a light bg, and this returns 0.0 for colorfract.
         * darkthresh: ignore pixels darker than this (typ. fg text).
           We make a 1 bpp mask of these pixels, and then dilate it to
           remove all vestiges of fg from their vicinity.
         * mindiff: consider pixels with either (b - r) or (g - r)
           being at least this value, as having color.
         * colordiff: consider pixels where the (max - min) difference
           of the pixel components exceeds this value, as having color.
     (4) All components of color pixels that are touching the image
         border are removed.  Additionally, all pixels within some
         normalized distance edgefract from the image border can
         be removed.  This insures that dark pixels near the edge
         of the image are not included.
     (5) This returns in pcolorfract the fraction of pixels that have
         color and are not in the set consisting of an OR between
         pixm and the dilated dark pixel mask.
     (6) No masks are returned unless light color pixels are found.
         If colorfract > 0.0 and pcolormask1 is defined, this returns
         a 1 bpp mask with fg pixels over the color background.
         This mask may have some holes in it.
     (7) If colorfract > 0.0 and pcolormask2 is defined, this returns
         a version of colormask1 where small holes have been filled.
     (8) To generate a boxa of rectangular regions from the overlap
         of components in the filtered mask:
               boxa1 = pixConnCompBB(colormask2, 8);
               boxa2 = boxaCombineOverlaps(boxa1, NULL);
         This is done here in debug mode.

Definition at line 933 of file colorcontent.c.

◆ pixGetMostPopulatedColors()

l_ok pixGetMostPopulatedColors ( PIX pixs,
l_int32  sigbits,
l_int32  factor,
l_int32  ncolors,
l_uint32 **  parray,
PIXCMAP **  pcmap 
)

pixGetMostPopulatedColors()

Parameters
[in]pixs32 bpp rgb
[in]sigbits2-6, significant bits retained in the quantizer for each component of the input image
[in]factorsubsampling factor; use 1 for no subsampling
[in]ncolorsthe number of most populated colors to select
[out]parray[optional] array of colors, each as 0xrrggbb00
[out]pcmap[optional] colormap of the colors
Returns
0 if OK, 1 on error
Notes:
     (1) This finds the ncolors most populated cubes in rgb colorspace,
         where the cube size depends on sigbits as
              cube side = (256 >> sigbits)
     (2) The rgb color components are found at the center of the cube.
     (3) The output array of colors can be displayed using
              pixDisplayColorArray(array, ncolors, ...);

Definition at line 1604 of file colorcontent.c.

◆ pixGetRGBHistogram()

NUMA* pixGetRGBHistogram ( PIX pixs,
l_int32  sigbits,
l_int32  factor 
)

pixGetRGBHistogram()

Parameters
[in]pixs32 bpp rgb
[in]sigbits2-6, significant bits retained in the quantizer for each component of the input image
[in]factorsubsampling factor; use 1 for no subsampling
Returns
numa histogram of colors, indexed by RGB components, or NULL on error
Notes:
     (1) This uses a simple, fast method of indexing into an rgb image.
     (2) The output is a 1D histogram of count vs. rgb-index, which
         uses red sigbits as the most significant and blue as the least.
     (3) This function produces the same result as pixMedianCutHisto().

Definition at line 1723 of file colorcontent.c.

◆ pixHasHighlightRed()

l_ok pixHasHighlightRed ( PIX pixs,
l_int32  factor,
l_float32  minfract,
l_float32  fthresh,
l_int32 *  phasred,
l_float32 *  pratio,
PIX **  ppixdb 
)

pixHasHighlightRed()

Parameters
[in]pixs32 bpp rgb
[in]factorsubsampling; an integer >= 1; use 1 for all pixels
[in]minfractthreshold fraction of all image pixels; must be > 0.0
[in]fthreshthreshold on a function of the components; typ. ~2.5
[out]phasred1 if red pixels are above threshold
[out]pratio[optional] normalized fraction of threshold red pixels that is actually observed
[out]ppixdb[optional] seed pixel mask
Returns
0 if OK, 1 on error
Notes:
     (1) Pixels are identified as red if they satisfy two conditions:
         (a) The components satisfy (R-B)/B > fthresh   (red or dark fg)
         (b) The red component satisfied R > 128  (red or light bg)
         Masks are generated for (a) and (b), and the intersection
         gives the pixels that are red but not either light bg or
         dark fg.
     (2) A typical value for minfract = 0.0001, which gives sensitivity
         to an image where a small fraction of the pixels are printed
         in red.
     (3) A typical value for fthresh = 2.5.  Higher values give less
         sensitivity to red, and fewer false positives.

Definition at line 1962 of file colorcontent.c.

◆ pixMaskOverColorPixels()

PIX* pixMaskOverColorPixels ( PIX pixs,
l_int32  threshdiff,
l_int32  mindist 
)

pixMaskOverColorPixels()

Parameters
[in]pixs32 bpp rgb or 8 bpp colormapped
[in]threshdiffthreshold for minimum of the max difference between components
[in]mindistmin allowed distance from nearest non-color pixel
Returns
pixd 1 bpp, mask over color pixels, or NULL on error
Notes:
     (1) The generated mask identifies each pixel as either color or
         non-color.  For a pixel to be color, it must satisfy two
         constraints:
           (a) The max difference between the r,g and b components must
               equal or exceed a threshold threshdiff.
           (b) It must be at least mindist (in an 8-connected way)
               from the nearest non-color pixel.
     (2) The distance constraint (b) is only applied if mindist > 1.
         For example, if mindist == 2, the color pixels identified
         by (a) are eroded by a 3x3 Sel.  In general, the Sel size
         for erosion is 2 * (mindist - 1) + 1.
         Why have this constraint?  In scanned images that are
         essentially gray, color artifacts are typically introduced
         in transition regions near sharp edges that go from dark
         to light, so this allows these transition regions to be removed.

Definition at line 680 of file colorcontent.c.

References pixGetDimensions().

◆ pixMaskOverColorRange()

PIX* pixMaskOverColorRange ( PIX pixs,
l_int32  rmin,
l_int32  rmax,
l_int32  gmin,
l_int32  gmax,
l_int32  bmin,
l_int32  bmax 
)

pixMaskOverColorRange()

Parameters
[in]pixs32 bpp rgb or 8 bpp colormapped
[in]rmin,rmaxmin and max allowed values for red component
[in]gmin,gmaxditto for green
[in]bmin,bmaxditto for blue
Returns
pixd 1 bpp, mask over color pixels, or NULL on error

Definition at line 816 of file colorcontent.c.

References pixGetDimensions().

◆ pixMaskOverGrayPixels()

PIX* pixMaskOverGrayPixels ( PIX pixs,
l_int32  maxlimit,
l_int32  satlimit 
)

pixMaskOverGrayPixels()

Parameters
[in]pixs32 bpp rgb
[in]maxlimitonly consider pixels with max component <= maxlimit
[in]satlimitonly consider pixels with saturation <= satlimit
Returns
pixd (1 bpp), or NULL on error
Notes:
     (1) This generates a mask over rgb pixels that are gray (i.e.,
         have low saturation) and are not too bright.  For example, if
         we know that the gray pixels in pixs have saturation
         (max - min) less than 10, and brightness (max) less than 200,
            pixMaskOverGrayPixels(pixs, 220, 10)
         will generate a mask over the gray pixels.  Other pixels that
         are not too dark and have a relatively large saturation will
         be little affected.
     (2) The algorithm is related to pixDarkenGray().

Definition at line 760 of file colorcontent.c.

◆ pixNumColors()

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

pixNumColors()

Parameters
[in]pixs2, 4, 8, 32 bpp
[in]factorsubsampling factor; integer
[out]pncolorsthe number of colors found in the pix
Returns
0 if OK, 1 on error.
Notes:
     (1) This returns the number of colors found in the image,
         even if there is a colormap.  If factor == 1 and the
         number of colors differs from the number of entries
         in the colormap, a warning is issued.
     (2) Use factor == 1 to find the actual number of colors.
         Use factor > 1 to more efficiently find an approximate
         number of colors.
     (3) For d = 2, 4 or 8 bpp grayscale, this returns the number
         of colors found in the image in 'ncolors'.
     (4) For d = 32 bpp (rgb), if the number of colors is greater
         than 256, this uses a hash set with factor == 1.

Definition at line 1408 of file colorcontent.c.

References pixGetData(), and pixGetDimensions().

◆ pixNumSignificantGrayColors()

l_ok pixNumSignificantGrayColors ( PIX pixs,
l_int32  darkthresh,
l_int32  lightthresh,
l_float32  minfract,
l_int32  factor,
l_int32 *  pncolors 
)

pixNumSignificantGrayColors()

Parameters
[in]pixs8 bpp gray
[in]darkthreshdark threshold for minimum intensity to be considered; typ. 20
[in]lightthreshthreshold near white, for maximum intensity to be considered; typ. 236
[in]minfractminimum fraction of all pixels to include a level as significant; typ. 0.0001; should be < 0.001
[in]factorsubsample factor; integer >= 1
[out]pncolorsnumber of significant colors; 0 on error
Returns
0 if OK, 1 on error
Notes:
     (1) This function is asking the question: how many perceptually
         significant gray color levels is in this pix?
         A color level must meet 3 criteria to be significant:
           ~ it can't be too close to black
           ~ it can't be too close to white
           ~ it must have at least some minimum fractional population
     (2) Use -1 for default values for darkthresh, lightthresh and minfract.
     (3) Choose default of darkthresh = 20, because variations in very
         dark pixels are not visually significant.
     (4) Choose default of lightthresh = 236, because document images
         that have been jpeg'd typically have near-white pixels in the
         8x8 jpeg blocks, and these should not be counted.  It is desirable
         to obtain a clean image by quantizing this noise away.

Definition at line 1147 of file colorcontent.c.

◆ pixSimpleColorQuantize()

PIX* pixSimpleColorQuantize ( PIX pixs,
l_int32  sigbits,
l_int32  factor,
l_int32  ncolors 
)

pixSimpleColorQuantize()

Parameters
[in]pixs32 bpp rgb
[in]sigbits2-4, significant bits retained in the quantizer for each component of the input image
[in]factorsubsampling factor; use 1 for no subsampling
[in]ncolorsthe number of most populated colors to select
Returns
pixd 8 bpp cmapped or NULL on error
Notes:
     (1) If you want to do color quantization for real, use octcube
         or modified median cut.  This function shows that it is
         easy to make a simple quantizer based solely on the population
         in cells of a given size in rgb color space.
     (2) The ncolors most populated cells at the sigbits level form
         the colormap for quantizing, and this uses octcube indexing
         under the covers to assign each pixel to the nearest color.
     (3) sigbits is restricted to 2, 3 and 4.  At the low end, the
         color discrimination is very crude; at the upper end, a set of
         similar colors can dominate the result.  Interesting results
         are generally found for sigbits = 3 and ncolors ~ 20.
     (4) See also pixColorSegment() for a method of quantizing the
         colors to generate regions of similar color.
     (5) See also pixConvertRGBToCmapLossless() to losslessly convert
         an RGB image with not more than 256 colors.

Definition at line 1679 of file colorcontent.c.