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

Go to the source code of this file.

Functions

PIXpixColorGrayRegions (PIX *pixs, BOXA *boxa, l_int32 type, l_int32 thresh, l_int32 rval, l_int32 gval, l_int32 bval)
 
l_ok pixColorGray (PIX *pixs, BOX *box, l_int32 type, l_int32 thresh, l_int32 rval, l_int32 gval, l_int32 bval)
 
PIXpixColorGrayMasked (PIX *pixs, PIX *pixm, l_int32 type, l_int32 thresh, l_int32 rval, l_int32 gval, l_int32 bval)
 
PIXpixSnapColor (PIX *pixd, PIX *pixs, l_uint32 srcval, l_uint32 dstval, l_int32 diff)
 
PIXpixSnapColorCmap (PIX *pixd, PIX *pixs, l_uint32 srcval, l_uint32 dstval, l_int32 diff)
 
PIXpixLinearMapToTargetColor (PIX *pixd, PIX *pixs, l_uint32 srcval, l_uint32 dstval)
 
l_ok pixelLinearMapToTargetColor (l_uint32 scolor, l_uint32 srcmap, l_uint32 dstmap, l_uint32 *pdcolor)
 
PIXpixShiftByComponent (PIX *pixd, PIX *pixs, l_uint32 srcval, l_uint32 dstval)
 
l_ok pixelShiftByComponent (l_int32 rval, l_int32 gval, l_int32 bval, l_uint32 srcval, l_uint32 dstval, l_uint32 *ppixel)
 
l_ok pixelFractionalShift (l_int32 rval, l_int32 gval, l_int32 bval, l_float32 fract, l_uint32 *ppixel)
 
PIXpixMapWithInvariantHue (PIX *pixd, PIX *pixs, l_uint32 srcval, l_float32 fract)
 

Detailed Description


     Coloring "gray" pixels
          PIX             *pixColorGrayRegions()
          l_int32          pixColorGray()
          PIX             *pixColorGrayMasked()

     Adjusting one or more colors to a target color
          PIX             *pixSnapColor()
          PIX             *pixSnapColorCmap()

     Piecewise linear color mapping based on a source/target pair
          PIX             *pixLinearMapToTargetColor()
          l_int32          pixelLinearMapToTargetColor()

     Fractional shift of RGB towards black or white
          PIX             *pixShiftByComponent()
          l_int32          pixelShiftByComponent()
          l_int32          pixelFractionalShift()
          PIX             *pixShiftWithInvariantHue()

 There are quite a few "coloring" functions in leptonica.
 You can find them in these files:
      coloring.c
      paintcmap.c
      pix2.c
      blend.c
      enhance.c

 They fall into the following categories:

 (1) Moving either the light or dark pixels toward a
     specified color. (pixColorGray, pixColorGrayMasked)
 (2) Forcing all pixels whose color is within some delta of a
     specified color to move to that color. (pixSnapColor)
 (3) Doing a piecewise linear color shift specified by a source
     and a target color.  Each component shifts independently.
     (pixLinearMapToTargetColor, pixMapWithInvariantHue).
 (4) Shifting all colors by a given fraction of their distance
     from 0 (if shifting down) or from 255 (if shifting up).
     This is useful for colorizing either the background or
     the foreground of a grayscale image. (pixShiftByComponent)
 (5) Shifting all colors by a component-dependent fraction of
     their distance from 0 (if shifting down) or from 255 (if
     shifting up).  This is useful for modifying the color to
     compensate for color shifts in acquisition or printing.
     (enhance.c: pixColorShiftRGB, pixMosaicColorShiftRGB).
 (6) Repainting selected pixels. (paintcmap.c: pixSetSelectMaskedCmap)
 (7) Blending a fraction of a specific color with the existing RGB
     color.  (pix2.c: pixBlendInRect())
 (8) Changing selected colors in a colormap.
     (paintcmap.c: pixSetSelectCmap, pixSetSelectMaskedCmap)
 (9) Shifting all the pixels towards black or white depending on
     the gray value of a second image.  (blend.c: pixFadeWithGray)
 (10) Changing the hue, saturation or brightness, by changing one of
     these parameters in HSV color space by a fraction of the distance
     toward its end-point, but leaving the other two parameters
     invariant.  For example, you can change the brightness by moving
     each pixel's v-parameter a specified fraction of the distance
     toward 0 (darkening) or toward 255 (brightening), without altering
     the hue or saturation.  (enhance.c: pixModifySaturation,
     pixModifyHue, pixModifyBrightness)

Definition in file coloring.c.

Function Documentation

◆ pixColorGray()

l_ok pixColorGray ( PIX pixs,
BOX box,
l_int32  type,
l_int32  thresh,
l_int32  rval,
l_int32  gval,
l_int32  bval 
)

pixColorGray()

Parameters
[in]pixs8 bpp gray, rgb or colormapped image
[in]box[optional] region in which to apply color; can be NULL
[in]typeL_PAINT_LIGHT, L_PAINT_DARK
[in]threshaverage value below/above which pixel is unchanged
[in]rval,gval,bvalnew color to paint
Returns
0 if OK; 1 on error
Notes:
     (1) This is an in-place operation; pixs is modified.
         If pixs is colormapped, the operation will add colors to the
         colormap.  Otherwise, pixs will be converted to 32 bpp rgb if
         it is initially 8 bpp gray.
     (2) If type == L_PAINT_LIGHT, it colorizes non-black pixels,
         preserving antialiasing.
         If type == L_PAINT_DARK, it colorizes non-white pixels,
         preserving antialiasing.
     (3) If box is NULL, applies function to the entire image; otherwise,
         clips the operation to the intersection of the box and pix.
     (4) If colormapped, calls pixColorGrayCmap(), which applies the
         coloring algorithm only to pixels that are strictly gray.
     (5) For RGB, determines a "gray" value by averaging; then uses this
         value, plus the input rgb target, to generate the output
         pixel values.
     (6) thresh is only used for rgb; it is ignored for colormapped pix.
         If type == L_PAINT_LIGHT, use thresh = 0 if all pixels are to
         be colored (black pixels will be unaltered).
         In situations where there are a lot of black pixels,
         setting thresh > 0 will make the function considerably
         more efficient without affecting the final result.
         If type == L_PAINT_DARK, use thresh = 255 if all pixels
         are to be colored (white pixels will be unaltered).
         In situations where there are a lot of white pixels,
         setting thresh < 255 will make the function considerably
         more efficient without affecting the final result.

Definition at line 230 of file coloring.c.

References L_PAINT_DARK, and L_PAINT_LIGHT.

◆ pixColorGrayMasked()

PIX* pixColorGrayMasked ( PIX pixs,
PIX pixm,
l_int32  type,
l_int32  thresh,
l_int32  rval,
l_int32  gval,
l_int32  bval 
)

pixColorGrayMasked()

Parameters
[in]pixs8 bpp gray, rgb or colormapped image
[in]pixm1 bpp mask, through which to apply color
[in]typeL_PAINT_LIGHT, L_PAINT_DARK
[in]threshaverage value below/above which pixel is unchanged
[in]rval,gval,bvalnew color to paint
Returns
pixd colorized, or NULL on error
Notes:
     (1) This generates a new image, where some of the pixels under
         FG in the mask are colorized.
     (2) See pixColorGray() for usage with type and thresh.  Note
         that thresh is only used for rgb; it is ignored for
         colormapped images.  In most cases, the mask will be over
         the darker parts and type == L_PAINT_DARK.
     (3) If pixs is colormapped this calls pixColorMaskedCmap(),
         which adds colors to the colormap for pixd; it only adds
         colors corresponding to strictly gray colors in the colormap.
         Otherwise, if pixs is 8 bpp gray, pixd will be 32 bpp rgb.
     (4) If pixs is 32 bpp rgb, for each pixel a "gray" value is
         found by averaging.  This average is then used with the
         input rgb target to generate the output pixel values.
     (5) This can be used in conjunction with pixHasHighlightRed() to
         add highlight color to a grayscale image.

Definition at line 354 of file coloring.c.

◆ pixColorGrayRegions()

PIX* pixColorGrayRegions ( PIX pixs,
BOXA boxa,
l_int32  type,
l_int32  thresh,
l_int32  rval,
l_int32  gval,
l_int32  bval 
)

pixColorGrayRegions()

Parameters
[in]pixs2, 4 or 8 bpp gray, rgb, or colormapped
[in]boxaof regions in which to apply color
[in]typeL_PAINT_LIGHT, L_PAINT_DARK
[in]threshaverage value below/above which pixel is unchanged
[in]rval,gval,bvalnew color to paint
Returns
pixd, or NULL on error
Notes:
     (1) This generates a new image, where some of the pixels in each
         box in the boxa are colorized.  See pixColorGray() for usage
         with type and thresh.  Note that thresh is only used for
         rgb; it is ignored for colormapped images.
     (2) If the input image is colormapped, the new image will be 8 bpp
         colormapped if possible; otherwise, it will be converted
         to 32 bpp rgb.  Only pixels that are strictly gray will be
         colorized.
     (3) If the input image is not colormapped, it is converted to rgb.
         A "gray" value for a pixel is determined by averaging the
         components, and the output rgb value is determined from this.
     (4) This can be used in conjunction with pixHasHighlightRed() to
         add highlight color to a grayscale image.

Definition at line 131 of file coloring.c.

◆ pixelFractionalShift()

l_ok pixelFractionalShift ( l_int32  rval,
l_int32  gval,
l_int32  bval,
l_float32  fract,
l_uint32 *  ppixel 
)

pixelFractionalShift()

Parameters
[in]rvalred source component
[in]gvalgreen source component
[in]bvalblue source component
[in]fractnegative toward black; positive toward white
[out]ppixelresulting rgb value
Returns
0 if OK, 1 on error
Notes:
     (1) This linear transformation shifts each component a fraction
         toward either black (fract < 0) or white (fract > 0).
     (2) It changes the saturation and intensity, but leaves the hue
         invariant.  See usage in pixLinearMapToTargetColor() and
         pixMapWithInvariantHue().
     (3) fract is in the range [-1 .... +1].  If fract < 0,
         saturation is increased and brightness is reduced.  The
         opposite results if fract > 0.  If fract == -1,
         the resulting pixel is black; fract == 1 results in white.

Definition at line 1013 of file coloring.c.

References composeRGBPixel().

◆ pixelLinearMapToTargetColor()

l_ok pixelLinearMapToTargetColor ( l_uint32  scolor,
l_uint32  srcmap,
l_uint32  dstmap,
l_uint32 *  pdcolor 
)

pixelLinearMapToTargetColor()

Parameters
[in]scolorrgb source color: 0xrrggbb00
[in]srcmapsource mapping color: 0xrrggbb00
[in]dstmaptarget mapping color: 0xrrggbb00
[out]pdcolorrgb dest color: 0xrrggbb00
Returns
0 if OK, 1 on error
Notes:
     (1) This does this does a piecewise linear mapping of each
         component of scolor to dcolor, based on the relation
         between the components of srcmap and dstmap.  It is the
         same transformation, performed on a single color, as mapped
         on every pixel in a pix by pixLinearMapToTargetColor().
     (2) For each component, if the sval is larger than the smap,
         the dval will be pushed up from dmap towards white.
         Otherwise, dval will be pushed down from dmap towards black.
         This is because you can visualize the transformation as
         a linear stretching where smap moves to dmap, and everything
         else follows linearly with 0 and 255 fixed.
     (3) The mapping will in general change the hue of scolor.
         However, if the srcmap and dstmap targets are related by
         a transformation given by pixelFractionalShift(), the hue
         will be invariant.

Definition at line 770 of file coloring.c.

References composeRGBPixel(), and extractRGBValues().

◆ pixelShiftByComponent()

l_ok pixelShiftByComponent ( l_int32  rval,
l_int32  gval,
l_int32  bval,
l_uint32  srcval,
l_uint32  dstval,
l_uint32 *  ppixel 
)

pixelShiftByComponent()

Parameters
[in]rval,gval,bval
[in]srcvalsource color: 0xrrggbb00
[in]dstvaltarget color: 0xrrggbb00
[out]ppixelrgb value
Returns
0 if OK, 1 on error
Notes:
     (1) This is a linear transformation that gives the same result
         on a single pixel as pixShiftByComponent() gives
         on a pix.  Each component is handled separately.  If
         the dest component is larger than the src, then the
         component is pushed toward 255 by the same fraction as
         the src --> dest shift.

Definition at line 952 of file coloring.c.

References composeRGBPixel(), and extractRGBValues().

Referenced by pixcmapShiftByComponent().

◆ pixLinearMapToTargetColor()

PIX* pixLinearMapToTargetColor ( PIX pixd,
PIX pixs,
l_uint32  srcval,
l_uint32  dstval 
)

pixLinearMapToTargetColor()

Parameters
[in]pixd[optional]; either NULL or equal to pixs for in-place
[in]pixs32 bpp rgb
[in]srcvalsource color: 0xrrggbb00
[in]dstvaltarget color: 0xrrggbb00
Returns
pixd with all pixels mapped based on the srcval/destval mapping, or pixd on error
Notes:
     (1) For each component (r, b, g) separately, this does a piecewise
         linear mapping of the colors in pixs to colors in pixd.
         If rs and rd are the red src and dest components in srcval and
         dstval, then the range [0 ... rs] in pixs is mapped to
         [0 ... rd] in pixd.  Likewise, the range [rs ... 255] in pixs
         is mapped to [rd ... 255] in pixd.  And similarly for green
         and blue.
     (2) The mapping will in general change the hue of the pixels.
         However, if the src and dst targets are related by
         a transformation given by pixelFractionalShift(), the hue
         is invariant.  A special case is where the dest in the
         map is white (255, 255, 255) for an arbitrary srcval.
     (3) For inplace operation, call it this way:
           pixLinearMapToTargetColor(pixs, pixs, ... );
         For generating a new pixd:
           pixd = pixLinearMapToTargetColor(NULL, pixs, ...);
     (4) See pixShiftWithInvariantHue() for a special case of this function.

Definition at line 677 of file coloring.c.

◆ pixMapWithInvariantHue()

PIX* pixMapWithInvariantHue ( PIX pixd,
PIX pixs,
l_uint32  srcval,
l_float32  fract 
)

pixMapWithInvariantHue()

Parameters
[in]pixd[optional]; either NULL or equal to pixs for in-place
[in]pixs32 bpp rgb
[in]srcvalreference source color: 0xrrggbb00
[in]fractfraction toward white of dest color
Returns
pixd with all pixels mapped based on the srcval/destval mapping, or pixd on error
Notes:
     (1) The combination of srcval and fract define the linear
         hue-preserving transformation, that is applied to all pixels.
     (2) fract is in the range [-1 .... +1].  If fract < 0,
         saturation is increased and brightness is reduced.  The
         opposite results if fract > 0.  If fract == -1,
         srcval is mapped to black; if fract == 1, it is mapped to white.
     (3) For inplace operation, call it this way:
           pixMapWithInvariatHue(pixs, pixs, ... );
         For generating a new pixd:
           pixd = pixMapWithInvariantHue(NULL, pixs, ...);

Definition at line 1062 of file coloring.c.

◆ pixShiftByComponent()

PIX* pixShiftByComponent ( PIX pixd,
PIX pixs,
l_uint32  srcval,
l_uint32  dstval 
)

pixShiftByComponent()

Parameters
[in]pixd[optional]; either NULL or equal to pixs for in-place
[in]pixs32 bpp rgb, cmap OK
[in]srcvalsource color: 0xrrggbb00
[in]dstvaltarget color: 0xrrggbb00
Returns
pixd with all pixels mapped based on the srcval/destval mapping, or pixd on error
Notes:
     (1) For each component (r, b, g) separately, this does a linear
         mapping of the colors in pixs to colors in pixd.
         Let rs and rd be the red src and dest components in srcval and
         dstval, and rval is the red component of the src pixel.
         Then for all pixels in pixs, the mapping for the red
         component from pixs to pixd is:
            if (rd <= rs)   (shift toward black)
                rval --> (rd/rs) * rval
            if (rd > rs)    (shift toward white)
               (255 - rval) --> ((255 - rs)/(255 - rd)) * (255 - rval)
         Thus if rd <= rs, the red component of all pixels is
         mapped by the same fraction toward white, and if rd > rs,
         they are mapped by the same fraction toward black.
         This is essentially a different linear TRC (gamma = 1)
         for each component.  The source and target color inputs are
         just used to generate the three fractions.
     (2) Note that this mapping differs from that in
         pixLinearMapToTargetColor(), which maps rs --> rd and does
         a piecewise stretching in between.
     (3) For inplace operation, call it this way:
           pixFractionalShiftByComponent(pixs, pixs, ... )
     (4) For generating a new pixd:
           pixd = pixLinearMapToTargetColor(NULL, pixs, ...)
     (5) A simple application is to color a grayscale image.
         A light background can be colored using srcval = 0xffffff00
         and picking a target background color for dstval.
         A dark foreground can be colored by using srcval = 0x0
         and choosing a target foreground color for dstval.

Definition at line 853 of file coloring.c.

◆ pixSnapColor()

PIX* pixSnapColor ( PIX pixd,
PIX pixs,
l_uint32  srcval,
l_uint32  dstval,
l_int32  diff 
)

pixSnapColor()

Parameters
[in]pixd[optional]; either NULL or equal to pixs for in-place
[in]pixscolormapped or 8 bpp gray or 32 bpp rgb
[in]srcvalcolor center to be selected for change: 0xrrggbb00
[in]dstvaltarget color for pixels: 0xrrggbb00
[in]diffmax absolute difference, applied to all components
Returns
pixd with all pixels within diff of pixval set to pixval, or pixd on error
Notes:
     (1) For inplace operation, call it this way:
          pixSnapColor(pixs, pixs, ... )
     (2) For generating a new pixd:
          pixd = pixSnapColor(NULL, pixs, ...)
     (3) If pixs has a colormap, it is handled by pixSnapColorCmap().
     (4) All pixels within 'diff' of 'srcval', componentwise,
         will be changed to 'dstval'.

Definition at line 477 of file coloring.c.

◆ pixSnapColorCmap()

PIX* pixSnapColorCmap ( PIX pixd,
PIX pixs,
l_uint32  srcval,
l_uint32  dstval,
l_int32  diff 
)

pixSnapColorCmap()

Parameters
[in]pixd[optional]; either NULL or equal to pixs for in-place
[in]pixscolormapped
[in]srcvalcolor center to be selected for change: 0xrrggbb00
[in]dstvaltarget color for pixels: 0xrrggbb00
[in]diffmax absolute difference, applied to all components
Returns
pixd with all pixels within diff of srcval set to dstval, or pixd on error
Notes:
     (1) For inplace operation, call it this way:
          pixSnapCcmap(pixs, pixs, ... )
     (2) For generating a new pixd:
          pixd = pixSnapCmap(NULL, pixs, ...)
     (3) pixs must have a colormap.
     (4) All colors within 'diff' of 'srcval', componentwise,
         will be changed to 'dstval'.

Definition at line 562 of file coloring.c.