Leptonica  1.83.1
Image processing and image analysis suite
enhance.c File Reference
#include <math.h>
#include "allheaders.h"

Go to the source code of this file.

Functions

PIXpixGammaTRC (PIX *pixd, PIX *pixs, l_float32 gamma, l_int32 minval, l_int32 maxval)
 
PIXpixGammaTRCMasked (PIX *pixd, PIX *pixs, PIX *pixm, l_float32 gamma, l_int32 minval, l_int32 maxval)
 
PIXpixGammaTRCWithAlpha (PIX *pixd, PIX *pixs, l_float32 gamma, l_int32 minval, l_int32 maxval)
 
NUMAnumaGammaTRC (l_float32 gamma, l_int32 minval, l_int32 maxval)
 
PIXpixContrastTRC (PIX *pixd, PIX *pixs, l_float32 factor)
 
PIXpixContrastTRCMasked (PIX *pixd, PIX *pixs, PIX *pixm, l_float32 factor)
 
NUMAnumaContrastTRC (l_float32 factor)
 
PIXpixEqualizeTRC (PIX *pixd, PIX *pixs, l_float32 fract, l_int32 factor)
 
NUMAnumaEqualizeTRC (PIX *pix, l_float32 fract, l_int32 factor)
 
l_int32 pixTRCMap (PIX *pixs, PIX *pixm, NUMA *na)
 
l_int32 pixTRCMapGeneral (PIX *pixs, PIX *pixm, NUMA *nar, NUMA *nag, NUMA *nab)
 
PIXpixUnsharpMasking (PIX *pixs, l_int32 halfwidth, l_float32 fract)
 
PIXpixUnsharpMaskingGray (PIX *pixs, l_int32 halfwidth, l_float32 fract)
 
PIXpixUnsharpMaskingFast (PIX *pixs, l_int32 halfwidth, l_float32 fract, l_int32 direction)
 
PIXpixUnsharpMaskingGrayFast (PIX *pixs, l_int32 halfwidth, l_float32 fract, l_int32 direction)
 
PIXpixUnsharpMaskingGray1D (PIX *pixs, l_int32 halfwidth, l_float32 fract, l_int32 direction)
 
PIXpixUnsharpMaskingGray2D (PIX *pixs, l_int32 halfwidth, l_float32 fract)
 
PIXpixModifyHue (PIX *pixd, PIX *pixs, l_float32 fract)
 
PIXpixModifySaturation (PIX *pixd, PIX *pixs, l_float32 fract)
 
l_int32 pixMeasureSaturation (PIX *pixs, l_int32 factor, l_float32 *psat)
 
PIXpixModifyBrightness (PIX *pixd, PIX *pixs, l_float32 fract)
 
PIXpixMosaicColorShiftRGB (PIX *pixs, l_float32 roff, l_float32 goff, l_float32 boff, l_float32 delta, l_int32 nincr)
 
PIXpixColorShiftRGB (PIX *pixs, l_float32 rfract, l_float32 gfract, l_float32 bfract)
 
PIXpixDarkenGray (PIX *pixd, PIX *pixs, l_int32 thresh, l_int32 satlimit)
 
PIXpixMultConstantColor (PIX *pixs, l_float32 rfact, l_float32 gfact, l_float32 bfact)
 
PIXpixMultMatrixColor (PIX *pixs, L_KERNEL *kel)
 
PIXpixHalfEdgeByBandpass (PIX *pixs, l_int32 sm1h, l_int32 sm1v, l_int32 sm2h, l_int32 sm2v)
 

Variables

static const l_float32 EnhanceScaleFactor = 5.0
 

Detailed Description


     Gamma TRC (tone reproduction curve) mapping
          PIX     *pixGammaTRC()
          PIX     *pixGammaTRCMasked()
          PIX     *pixGammaTRCWithAlpha()
          NUMA    *numaGammaTRC()

     Contrast enhancement
          PIX     *pixContrastTRC()
          PIX     *pixContrastTRCMasked()
          NUMA    *numaContrastTRC()

     Histogram equalization
          PIX     *pixEqualizeTRC()
          NUMA    *numaEqualizeTRC()

     Generic TRC mapper
          l_int32  pixTRCMap()
          l_int32  pixTRCMapGeneral()

     Unsharp-masking
          PIX     *pixUnsharpMasking()
          PIX     *pixUnsharpMaskingGray()
          PIX     *pixUnsharpMaskingFast()
          PIX     *pixUnsharpMaskingGrayFast()
          PIX     *pixUnsharpMaskingGray1D()
          PIX     *pixUnsharpMaskingGray2D()

     Hue and saturation modification
          PIX     *pixModifyHue()
          PIX     *pixModifySaturation()
          l_int32  pixMeasureSaturation()
          PIX     *pixModifyBrightness()

     Color shifting
          PIX     *pixMosaicColorShiftRGB()
          PIX     *pixColorShiftRGB()

     Darken gray (unsaturated) pixels
          PIX     *pixDarkenGray()

     General multiplicative constant color transform
          PIX     *pixMultConstantColor()
          PIX     *pixMultMatrixColor()

     Edge by bandpass
          PIX     *pixHalfEdgeByBandpass()

     Gamma correction, contrast enhancement and histogram equalization
     apply a simple mapping function to each pixel (or, for color
     images, to each sample (i.e., r,g,b) of the pixel).

      ~ Gamma correction either lightens the image or darkens
        it, depending on whether the gamma factor is greater
        or less than 1.0, respectively.

      ~ Contrast enhancement darkens the pixels that are already
        darker than the middle of the dynamic range (128)
        and lightens pixels that are lighter than 128.

      ~ Histogram equalization remaps to have the same number
        of image pixels at each of 256 intensity values.  This is
        a quick and dirty method of adjusting contrast and brightness
        to bring out details in both light and dark regions.

     Unsharp masking is a more complicated enhancement.
     A "high frequency" image, generated by subtracting
     the smoothed ("low frequency") part of the image from
     itself, has all the energy at the edges.  This "edge image"
     has 0 average value.  A fraction of the edge image is
     then added to the original, enhancing the differences
     between pixel values at edges.  Because we represent
     images as l_uint8 arrays, we preserve dynamic range and
     handle negative values by doing all the arithmetic on
     shifted l_uint16 arrays; the l_uint8 values are recovered
     at the end.

     Hue and saturation modification work in HSV space.  Because
     this is too large for efficient table lookup, each pixel value
     is transformed to HSV, modified, and transformed back.
     It's not the fastest way to do this, but the method is
     easily understood.

     Unsharp masking is never in-place, and returns a clone if no
     operation is to be performed.

Definition in file enhance.c.

Function Documentation

◆ numaContrastTRC()

NUMA* numaContrastTRC ( l_float32  factor)

numaContrastTRC()

Parameters
[in]factorgenerally between 0.0 [no enhancement] and 1.0, but can be larger than 1.0
Returns
na, or NULL on error
Notes:
     (1) The mapping is monotonic increasing, where 0 is mapped
         to 0 and 255 is mapped to 255.
     (2) As 'factor' is increased from 0.0 (where the mapping is linear),
         the map gets closer to its limit as a step function that
         jumps from 0 to 255 at the center (input value = 127).

Definition at line 548 of file enhance.c.

References numaMakeSequence().

Referenced by pixcmapContrastTRC().

◆ numaEqualizeTRC()

NUMA* numaEqualizeTRC ( PIX pix,
l_float32  fract,
l_int32  factor 
)

numaEqualizeTRC()

Parameters
[in]pix8 bpp, no colormap
[in]fractfraction of equalization movement of pixel values
[in]factorsubsampling factor; integer >= 1
Returns
nad, or NULL on error
Notes:
     (1) If fract == 0.0, no equalization will be performed.
         If fract == 1.0, equalization is complete.
     (2) Set the subsampling factor > 1 to reduce the amount of computation.
     (3) The map is returned as a numa with 256 values, specifying
         the equalized value (array value) for every input value
         (the array index).

Definition at line 701 of file enhance.c.

◆ numaGammaTRC()

NUMA* numaGammaTRC ( l_float32  gamma,
l_int32  minval,
l_int32  maxval 
)

numaGammaTRC()

Parameters
[in]gammagamma factor; must be > 0.0
[in]minvalinput value that gives 0 for output
[in]maxvalinput value that gives 255 for output
Returns
na, or NULL on error
Notes:
     (1) The map is returned as a numa; values are clipped to [0, 255].
     (2) For a linear mapping, set gamma = 1.0.
     (3) To force all intensities into a range within fraction delta
         of white, use: minval = -256 * (1 - delta) / delta
                        maxval = 255
     (4) To force all intensities into a range within fraction delta
         of black, use: minval = 0
                        maxval = 256 * (1 - delta) / delta

Definition at line 363 of file enhance.c.

References numaAddNumber(), and numaCreate().

Referenced by pixcmapGammaTRC().

◆ pixColorShiftRGB()

PIX* pixColorShiftRGB ( PIX pixs,
l_float32  rfract,
l_float32  gfract,
l_float32  bfract 
)

pixColorShiftRGB()

Parameters
[in]pixs32 bpp rgb
[in]rfractfractional shift in red component
[in]gfractfractional shift in green component
[in]bfractfractional shift in blue component
Returns
pixd, or NULL on error
Notes:
     (1) This allows independent fractional shifts of the r,g and b
         components.  A positive shift pushes to saturation (255);
         a negative shift pushes toward 0 (black).
     (2) The effect can be imagined using a color wheel that consists
         (for our purposes) of these 6 colors, separated by 60 degrees:
            red, magenta, blue, cyan, green, yellow
     (3) So, for example, a negative shift of the blue component
         (bfract < 0) could be accompanied by positive shifts
         of red and green to make an image more yellow.
     (4) Examples of limiting cases:
           rfract = 1 ==> r = 255
           rfract = -1 ==> r = 0

Definition at line 1901 of file enhance.c.

◆ pixContrastTRC()

PIX* pixContrastTRC ( PIX pixd,
PIX pixs,
l_float32  factor 
)

pixContrastTRC()

Parameters
[in]pixd[optional] null or equal to pixs
[in]pixs8 or 32 bpp; or 2, 4 or 8 bpp with colormap
[in]factor0.0 is no enhancement
Returns
pixd always
Notes:
     (1) pixd must either be null or equal to pixs.
         For in-place operation, set pixd == pixs:
            pixContrastTRC(pixs, pixs, ...);
         To get a new image, set pixd == null:
            pixd = pixContrastTRC(NULL, pixs, ...);
     (2) If pixs is colormapped, the colormap is transformed,
         either in-place or in a copy of pixs.
     (3) Contrast is enhanced by mapping each color component
         using an atan function with maximum slope at 127.
         Pixels below 127 are lowered in intensity and pixels
         above 127 are increased.
     (4) The useful range for the contrast factor is scaled to
         be in (0.0 to 1.0), but larger values can also be used.
     (5) If factor == 0.0, no enhancement is performed; return a copy
         unless in-place, in which case this is a no-op.
     (6) For color images that are not colormapped, the mapping
         is applied to each component.

Definition at line 431 of file enhance.c.

References pixCopy().

Referenced by pixContrastTRCMasked().

◆ pixContrastTRCMasked()

PIX* pixContrastTRCMasked ( PIX pixd,
PIX pixs,
PIX pixm,
l_float32  factor 
)

pixContrastTRCMasked()

Parameters
[in]pixd[optional] null or equal to pixs
[in]pixs8 or 32 bpp; or 2, 4 or 8 bpp with colormap
[in]pixm[optional] null or 1 bpp
[in]factor0.0 is no enhancement
Returns
pixd always
Notes:
     (1) Same as pixContrastTRC() except mapping is optionally over
         a subset of pixels described by pixm.
     (2) Masking does not work for colormapped images.
     (3) See pixContrastTRC() for details on how to use the parameters.

Definition at line 491 of file enhance.c.

References pixContrastTRC().

◆ pixDarkenGray()

PIX* pixDarkenGray ( PIX pixd,
PIX pixs,
l_int32  thresh,
l_int32  satlimit 
)

pixDarkenGray()

Parameters
[in]pixd[optional] can be null or equal to pixs
[in]pixs32 bpp rgb
[in]threshpixels with max component >= thresh are unchanged
[in]satlimitpixels with saturation >= satlimit are unchanged
Returns
pixd, or NULL on error
Notes:
     (1) This darkens gray pixels, by a fraction (sat/satlimit), where
         the saturation, sat, is the component difference (max - min).
         The pixel value is unchanged if sat >= satlimit.  A typical
         value of satlimit might be 40; the larger the value, the
         more that pixels with a smaller saturation will be darkened.
     (2) Pixels with max component >= thresh are unchanged. This can be
         used to prevent bright pixels with low saturation from being
         darkened.  Setting thresh == 0 is a no-op; setting thresh == 255
         causes the darkening to be applied to all pixels.
     (3) This function is useful to enhance pixels relative to a
         gray background.
     (4) A related function that builds a 1 bpp mask over the gray
         pixels is pixMaskOverGrayPixels().

Definition at line 1998 of file enhance.c.

◆ pixEqualizeTRC()

PIX* pixEqualizeTRC ( PIX pixd,
PIX pixs,
l_float32  fract,
l_int32  factor 
)

pixEqualizeTRC()

Parameters
[in]pixd[optional] null or equal to pixs
[in]pixs8 bpp gray, 32 bpp rgb, or colormapped
[in]fractfraction of equalization movement of pixel values
[in]factorsubsampling factor; integer >= 1
Returns
pixd, or NULL on error
Notes:
     (1) pixd must either be null or equal to pixs.
         For in-place operation, set pixd == pixs:
            pixEqualizeTRC(pixs, pixs, ...);
         To get a new image, set pixd == null:
            pixd = pixEqualizeTRC(NULL, pixs, ...);
     (2) In histogram equalization, a tone reproduction curve
         mapping is used to make the number of pixels at each
         intensity equal.
     (3) If fract == 0.0, no equalization is performed; return a copy
         unless in-place, in which case this is a no-op.
         If fract == 1.0, equalization is complete.
     (4) Set the subsampling factor > 1 to reduce the amount of computation.
     (5) If pixs is colormapped, the colormap is removed and
         converted to rgb or grayscale.
     (6) If pixs has color, equalization is done in each channel
         separately.
     (7) Note that even if there is a colormap, we can get an
         in-place operation because the intermediate image pixt
         is copied back to pixs (which for in-place is the same
         as pixd).

Definition at line 616 of file enhance.c.

◆ pixGammaTRC()

PIX* pixGammaTRC ( PIX pixd,
PIX pixs,
l_float32  gamma,
l_int32  minval,
l_int32  maxval 
)

pixGammaTRC()

Parameters
[in]pixd[optional] null or equal to pixs
[in]pixs8 or 32 bpp; or 2, 4 or 8 bpp with colormap
[in]gammagamma correction; must be > 0.0
[in]minvalinput value that gives 0 for output; can be < 0
[in]maxvalinput value that gives 255 for output; can be > 255
Returns
pixd always
Notes:
     (1) pixd must either be null or equal to pixs.
         For in-place operation, set pixd == pixs:
            pixGammaTRC(pixs, pixs, ...);
         To get a new image, set pixd == null:
            pixd = pixGammaTRC(NULL, pixs, ...);
     (2) If pixs is colormapped, the colormap is transformed,
         either in-place or in a copy of pixs.
     (3) We use a gamma mapping between minval and maxval.
     (4) If gamma < 1.0, the image will appear darker;
         if gamma > 1.0, the image will appear lighter;
     (5) If gamma = 1.0 and minval = 0 and maxval = 255, no
         enhancement is performed; return a copy unless in-place,
         in which case this is a no-op.
     (6) For color images that are not colormapped, the mapping
         is applied to each component.
     (7) minval and maxval are not restricted to the interval [0, 255].
         If minval < 0, an input value of 0 is mapped to a
         nonzero output.  This will turn black to gray.
         If maxval > 255, an input value of 255 is mapped to
         an output value less than 255.  This will turn
         white (e.g., in the background) to gray.
     (8) Increasing minval darkens the image.
     (9) Decreasing maxval bleaches the image.
     (10) Simultaneously increasing minval and decreasing maxval
          will darken the image and make the colors more intense;
          e.g., minval = 50, maxval = 200.
     (11) See numaGammaTRC() for further examples of use.
     (12) Use pixTRCMapGeneral() if applying different mappings
          to each channel in an RGB image.

Definition at line 176 of file enhance.c.

Referenced by pixGammaTRCMasked().

◆ pixGammaTRCMasked()

PIX* pixGammaTRCMasked ( PIX pixd,
PIX pixs,
PIX pixm,
l_float32  gamma,
l_int32  minval,
l_int32  maxval 
)

pixGammaTRCMasked()

Parameters
[in]pixd[optional] null or equal to pixs
[in]pixs8 or 32 bpp; not colormapped
[in]pixm[optional] null or 1 bpp
[in]gammagamma correction; must be > 0.0
[in]minvalinput value that gives 0 for output; can be < 0
[in]maxvalinput value that gives 255 for output; can be > 255
Returns
pixd always
Notes:
     (1) Same as pixGammaTRC() except mapping is optionally over
         a subset of pixels described by pixm.
     (2) Masking does not work for colormapped images.
     (3) See pixGammaTRC() for details on how to use the parameters.

Definition at line 242 of file enhance.c.

References pixGammaTRC().

◆ pixGammaTRCWithAlpha()

PIX* pixGammaTRCWithAlpha ( PIX pixd,
PIX pixs,
l_float32  gamma,
l_int32  minval,
l_int32  maxval 
)

pixGammaTRCWithAlpha()

Parameters
[in]pixd[optional] null or equal to pixs
[in]pixs32 bpp
[in]gammagamma correction; must be > 0.0
[in]minvalinput value that gives 0 for output; can be < 0
[in]maxvalinput value that gives 255 for output; can be > 255
Returns
pixd always
Notes:
     (1) See usage notes in pixGammaTRC().
     (2) This version saves the alpha channel.  It is only valid
         for 32 bpp (no colormap), and is a bit slower.

Definition at line 304 of file enhance.c.

◆ pixHalfEdgeByBandpass()

PIX* pixHalfEdgeByBandpass ( PIX pixs,
l_int32  sm1h,
l_int32  sm1v,
l_int32  sm2h,
l_int32  sm2v 
)

pixHalfEdgeByBandpass()

Parameters
[in]pixs8 bpp gray or 32 bpp rgb
[in]sm1h,sm1v"half-widths" of smoothing filter sm1
[in]sm2h,sm2v"half-widths" of smoothing filter sm2; require sm2 != sm1
Returns
pixd, or NULL on error
Notes:
     (1) We use symmetric smoothing filters of odd dimension,
         typically use 3, 5, 7, etc.  The smoothing parameters
         for these are 1, 2, 3, etc.  The filter size is related
         to the smoothing parameter by
              size = 2 * smoothing + 1
     (2) Because we take the difference of two lowpass filters,
         this is actually a bandpass filter.
     (3) We allow both filters to be anisotropic.
     (4) Consider either the h or v component of the 2 filters.
         Depending on whether sm1 > sm2 or sm2 > sm1, we get
         different halves of the smoothed gradients (or "edges").
         This difference of smoothed signals looks more like
         a second derivative of a transition, which we rectify
         by not allowing the signal to go below zero.  If sm1 < sm2,
         the sm2 transition is broader, so the difference between
         sm1 and sm2 signals is positive on the upper half of
         the transition.  Likewise, if sm1 > sm2, the sm1 - sm2
         signal difference is positive on the lower half of
         the transition.

Definition at line 2275 of file enhance.c.

◆ pixMeasureSaturation()

l_int32 pixMeasureSaturation ( PIX pixs,
l_int32  factor,
l_float32 *  psat 
)

pixMeasureSaturation()

Parameters
[in]pixs32 bpp rgb
[in]factorsubsampling factor; integer >= 1
[out]psataverage saturation
Returns
0 if OK, 1 on error

Definition at line 1658 of file enhance.c.

References pixGetData(), and pixGetDimensions().

◆ pixModifyBrightness()

PIX* pixModifyBrightness ( PIX pixd,
PIX pixs,
l_float32  fract 
)

pixModifyBrightness()

Parameters
[in]pixd[optional] can be null, existing or equal to pixs
[in]pixs32 bpp rgb
[in]fractbetween -1.0 and 1.0
Returns
pixd, or NULL on error
Notes:
     (1) If fract > 0.0, it gives the fraction that the v-parameter,
         which is max(r,g,b), is moved from its initial value toward 255.
         If fract < 0.0, it gives the fraction that the v-parameter
         is moved from its initial value toward 0.
         The limiting values for fract = -1.0 (1.0) thus set the
         v-parameter to 0 (255).
     (2) If fract = 0, no modification is requested; return a copy
         unless in-place, in which case this is a no-op.
     (3) This leaves hue and saturation invariant.
     (4) See discussion of color-modification methods, in coloring.c.

Definition at line 1718 of file enhance.c.

References pixCopy(), pixGetData(), and pixGetDimensions().

◆ pixModifyHue()

PIX* pixModifyHue ( PIX pixd,
PIX pixs,
l_float32  fract 
)

pixModifyHue()

Parameters
[in]pixd[optional] can be null or equal to pixs
[in]pixs32 bpp rgb
[in]fractbetween -1.0 and 1.0
Returns
pixd, or NULL on error
Notes:
     (1) pixd must either be null or equal to pixs.
         For in-place operation, set pixd == pixs:
            pixEqualizeTRC(pixs, pixs, ...);
         To get a new image, set pixd == null:
            pixd = pixEqualizeTRC(NULL, pixs, ...);
     (2) Use fract > 0.0 to increase hue value; < 0.0 to decrease it.
         1.0 (or -1.0) represents a 360 degree rotation; i.e., no change.
     (3) If no modification is requested (fract = -1.0 or 0 or 1.0),
         return a copy unless in-place, in which case this is a no-op.
     (4) This leaves saturation and intensity invariant.
     (5) See discussion of color-modification methods, in coloring.c.

Definition at line 1533 of file enhance.c.

◆ pixModifySaturation()

PIX* pixModifySaturation ( PIX pixd,
PIX pixs,
l_float32  fract 
)

pixModifySaturation()

Parameters
[in]pixd[optional] can be null, existing or equal to pixs
[in]pixs32 bpp rgb
[in]fractbetween -1.0 and 1.0
Returns
pixd, or NULL on error
Notes:
     (1) If fract > 0.0, it gives the fraction that the pixel
         saturation is moved from its initial value toward 255.
         If fract < 0.0, it gives the fraction that the pixel
         saturation is moved from its initial value toward 0.
         The limiting values for fract = -1.0 (1.0) thus set the
         saturation to 0 (255).
     (2) If fract = 0, no modification is requested; return a copy
         unless in-place, in which case this is a no-op.
     (3) This leaves hue and intensity invariant.
     (4) See discussion of color-modification methods, in coloring.c.

Definition at line 1605 of file enhance.c.

References pixCopy(), pixGetData(), and pixGetDimensions().

◆ pixMosaicColorShiftRGB()

PIX* pixMosaicColorShiftRGB ( PIX pixs,
l_float32  roff,
l_float32  goff,
l_float32  boff,
l_float32  delta,
l_int32  nincr 
)

pixMosaicColorShiftRGB()

Parameters
[in]pixs32 bpp rgb
[in]roffcenter offset of red component
[in]goffcenter offset of green component
[in]boffcenter offset of blue component
[in]deltaincrements from center offsets [0.0 - 0.1]; use 0.0 to get the default (0.04)
[in]nincrnumber of increments in each (positive and negative) direction; use 0 to get the default (2).
Returns
pix, or NULL on error
Notes:
     (1) This generates a mosaic view of the effect of shifting the RGB
         components.  See pixColorShiftRGB() for details on the shifting.
     (2) The offsets (roff, goff, boff) set the color center point,
         and the deviations from this are shown separately for deltas
         in r, g and b.  For each component, we show 2 * nincr + 1
         images.
     (3) The pix must have minimum dimensions of 100 and an aspect
         ratio not exceeding 5.0.
     (4) Usage: color prints differ from the original due to three factors:
         illumination, calibration of the camera in acquisition,
         and calibration of the printer.  This function can be used
         to iteratively match a color print to the original.  On each
         iteration, the center offsets are set to the best match so
         far, and the delta increments are typically reduced.

Definition at line 1797 of file enhance.c.

◆ pixMultConstantColor()

PIX* pixMultConstantColor ( PIX pixs,
l_float32  rfact,
l_float32  gfact,
l_float32  bfact 
)

pixMultConstantColor()

Parameters
[in]pixscolormapped or rgb
[in]rfactred multiplicative factor
[in]gfactgreen multiplicative factor
[in]bfactblue multiplicative factor
Returns
pixd colormapped or rgb, with colors scaled, or NULL on error
Notes:
     (1) rfact, gfact and bfact can only have non-negative values.
         They can be greater than 1.0.  All transformed component
         values are clipped to the interval [0, 255].
     (2) For multiplication with a general 3x3 matrix of constants,
         use pixMultMatrixColor().

Definition at line 2068 of file enhance.c.

References pixGetDimensions().

◆ pixMultMatrixColor()

PIX* pixMultMatrixColor ( PIX pixs,
L_KERNEL kel 
)

pixMultMatrixColor()

Parameters
[in]pixscolormapped or rgb
[in]kelkernel 3x3 matrix of floats
Returns
pixd colormapped or rgb, or NULL on error
Notes:
     (1) The kernel is a data structure used mostly for floating point
         convolution.  Here it is a 3x3 matrix of floats that are used
         to transform the pixel values by matrix multiplication:
           nrval = a[0,0] * rval + a[0,1] * gval + a[0,2] * bval
           ngval = a[1,0] * rval + a[1,1] * gval + a[1,2] * bval
           nbval = a[2,0] * rval + a[2,1] * gval + a[2,2] * bval
     (2) The matrix can be generated in several ways.
         See kernel.c for details.  Here are two of them:
           (a) kel = kernelCreate(3, 3);
               kernelSetElement(kel, 0, 0, val00);
               kernelSetElement(kel, 0, 1, val01);
               ...
           (b) from a static string; e.g.,:
               const char *kdata = " 0.6  0.3 -0.2 "
                                   " 0.1  1.2  0.4 "
                                   " -0.4 0.2  0.9 ";
               kel = kernelCreateFromString(3, 3, 0, 0, kdata);
     (3) For the special case where the matrix is diagonal, it is easier
         to use pixMultConstantColor().
     (4) Matrix entries can have positive and negative values, and can
         be larger than 1.0.  All transformed component values
         are clipped to [0, 255].

Definition at line 2168 of file enhance.c.

References kernelGetParameters(), and pixGetDimensions().

◆ pixTRCMap()

l_int32 pixTRCMap ( PIX pixs,
PIX pixm,
NUMA na 
)

pixTRCMap()

Parameters
[in]pixs8 grayscale or 32 bpp rgb; not colormapped
[in]pixm[optional] 1 bpp mask
[in]namapping array
Returns
0 if OK, 1 on error
Notes:
     (1) This operation is in-place on pixs.
     (2) For 32 bpp, this applies the same map to each of the r,g,b
         components.
     (3) The mapping array is of size 256, and it maps the input
         index into values in the range [0, 255].
     (4) If defined, the optional 1 bpp mask pixm has its origin
         aligned with pixs, and the map function is applied only
         to pixels in pixs under the fg of pixm.
     (5) For 32 bpp, this does not save the alpha channel.

Definition at line 766 of file enhance.c.

◆ pixTRCMapGeneral()

l_int32 pixTRCMapGeneral ( PIX pixs,
PIX pixm,
NUMA nar,
NUMA nag,
NUMA nab 
)

pixTRCMapGeneral()

Parameters
[in]pixs32 bpp rgb; not colormapped
[in]pixm[optional] 1 bpp mask
[in]nar,nag,nabmapping arrays
Returns
0 if OK, 1 on error
Notes:
     (1) This operation is in-place on pixs.
     (2) Each of the r,g,b mapping arrays is of size 256. They map the
         input value for that color component into values in the
         range [0, 255].
     (3) In the special case where the r, g and b mapping arrays are
         all the same, call pixTRCMap() instead.
     (4) If defined, the optional 1 bpp mask pixm has its origin
         aligned with pixs, and the map function is applied only
         to pixels in pixs under the fg of pixm.
     (5) The alpha channel is not saved.

Definition at line 886 of file enhance.c.

◆ pixUnsharpMasking()

PIX* pixUnsharpMasking ( PIX pixs,
l_int32  halfwidth,
l_float32  fract 
)

pixUnsharpMasking()

Parameters
[in]pixsall depths except 1 bpp; with or without colormaps
[in]halfwidth"half-width" of smoothing filter
[in]fractfraction of edge added back into image
Returns
pixd, or NULL on error
Notes:
     (1) We use symmetric smoothing filters of odd dimension,
         typically use sizes of 3, 5, 7, etc.  The halfwidth parameter
         for these is (size - 1)/2; i.e., 1, 2, 3, etc.
     (2) The fract parameter is typically taken in the
         range:  0.2 < fract < 0.7
     (3) Returns a clone if no sharpening is requested.

Definition at line 979 of file enhance.c.

◆ pixUnsharpMaskingFast()

PIX* pixUnsharpMaskingFast ( PIX pixs,
l_int32  halfwidth,
l_float32  fract,
l_int32  direction 
)

pixUnsharpMaskingFast()

Parameters
[in]pixsall depths except 1 bpp; with or without colormaps
[in]halfwidth"half-width" of smoothing filter; 1 and 2 only
[in]fractfraction of high frequency added to image
[in]directionL_HORIZ, L_VERT, L_BOTH_DIRECTIONS
Returns
pixd, or NULL on error
Notes:
     (1) The fast version uses separable 1-D filters directly on
         the input image.  The halfwidth is either 1 (full width = 3)
         or 2 (full width = 5).
     (2) The fract parameter is typically taken in the
           range:  0.2 < fract < 0.7
     (3) To skip horizontal sharpening, use fracth = 0.0; ditto for fractv
     (4) For one dimensional filtering (as an example):
         For halfwidth = 1, the low-pass filter is
             L:    1/3    1/3   1/3
         and the high-pass filter is
             H = I - L:   -1/3   2/3   -1/3
         For halfwidth = 2, the low-pass filter is
             L:    1/5    1/5   1/5    1/5    1/5
         and the high-pass filter is
             H = I - L:   -1/5  -1/5   4/5  -1/5   -1/5
         The new sharpened pixel value is found by adding some fraction
         of the high-pass filter value (which sums to 0) to the
         initial pixel value:
             N = I + fract * H
     (5) For 2D, the sharpening filter is not separable, because the
         vertical filter depends on the horizontal location relative
         to the filter origin, and v.v.   So we either do the full
         2D filter (for halfwidth == 1) or do the low-pass
         convolution separably and then compose with the original pix.
     (6) Returns a clone if no sharpening is requested.

Definition at line 1141 of file enhance.c.

◆ pixUnsharpMaskingGray()

PIX* pixUnsharpMaskingGray ( PIX pixs,
l_int32  halfwidth,
l_float32  fract 
)

pixUnsharpMaskingGray()

Parameters
[in]pixs8 bpp; no colormap
[in]halfwidth"half-width" of smoothing filter
[in]fractfraction of edge added back into image
Returns
pixd, or NULL on error
Notes:
     (1) We use symmetric smoothing filters of odd dimension,
         typically use sizes of 3, 5, 7, etc.  The halfwidth parameter
         for these is (size - 1)/2; i.e., 1, 2, 3, etc.
     (2) The fract parameter is typically taken in the range:
         0.2 < fract < 0.7
     (3) Returns a clone if no sharpening is requested.

Definition at line 1046 of file enhance.c.

References pixGetDimensions().

◆ pixUnsharpMaskingGray1D()

PIX* pixUnsharpMaskingGray1D ( PIX pixs,
l_int32  halfwidth,
l_float32  fract,
l_int32  direction 
)

pixUnsharpMaskingGray1D()

Parameters
[in]pixs8 bpp; no colormap
[in]halfwidth"half-width" of smoothing filter: 1 or 2
[in]fractfraction of high frequency added to image
[in]directionfiltering direction; use L_HORIZ or L_VERT
Returns
pixd, or NULL on error
Notes:
     (1) For usage and explanation of the algorithm, see notes
         in pixUnsharpMaskingFast().
     (2) Returns a clone if no sharpening is requested.

Definition at line 1257 of file enhance.c.

References pixGetDimensions().

◆ pixUnsharpMaskingGray2D()

PIX* pixUnsharpMaskingGray2D ( PIX pixs,
l_int32  halfwidth,
l_float32  fract 
)

pixUnsharpMaskingGray2D()

Parameters
[in]pixs8 bpp; no colormap
[in]halfwidth"half-width" of smoothing filter: 1 or 2
[in]fractfraction of high frequency added to image
Returns
pixd, or NULL on error
Notes:
     (1) This is for halfwidth == 1, 2.
     (2) The lowpass filter is implemented separably.
     (3) Returns a clone if no sharpening is requested.

Definition at line 1389 of file enhance.c.

References pixGetDimensions().

◆ pixUnsharpMaskingGrayFast()

PIX* pixUnsharpMaskingGrayFast ( PIX pixs,
l_int32  halfwidth,
l_float32  fract,
l_int32  direction 
)

pixUnsharpMaskingGrayFast()

Parameters
[in]pixs8 bpp; no colormap
[in]halfwidth"half-width" of smoothing filter: 1 or 2
[in]fractfraction of high frequency added to image
[in]directionL_HORIZ, L_VERT, L_BOTH_DIRECTIONS
Returns
pixd, or NULL on error
Notes:
     (1) For usage and explanation of the algorithm, see notes
         in pixUnsharpMaskingFast().
     (2) Returns a clone if no sharpening is requested.

Definition at line 1210 of file enhance.c.