Leptonica  1.83.1
Image processing and image analysis suite
pix2.c File Reference
#include <string.h>
#include "allheaders.h"
#include "pix_internal.h"

Go to the source code of this file.

Macros

#define DEBUG_SERIALIZE   0
 

Functions

l_ok pixGetPixel (PIX *pix, l_int32 x, l_int32 y, l_uint32 *pval)
 
l_ok pixSetPixel (PIX *pix, l_int32 x, l_int32 y, l_uint32 val)
 
l_ok pixGetRGBPixel (PIX *pix, l_int32 x, l_int32 y, l_int32 *prval, l_int32 *pgval, l_int32 *pbval)
 
l_ok pixSetRGBPixel (PIX *pix, l_int32 x, l_int32 y, l_int32 rval, l_int32 gval, l_int32 bval)
 
l_ok pixSetCmapPixel (PIX *pix, l_int32 x, l_int32 y, l_int32 rval, l_int32 gval, l_int32 bval)
 
l_ok pixGetRandomPixel (PIX *pix, l_uint32 *pval, l_int32 *px, l_int32 *py)
 
l_ok pixClearPixel (PIX *pix, l_int32 x, l_int32 y)
 
l_ok pixFlipPixel (PIX *pix, l_int32 x, l_int32 y)
 
void setPixelLow (l_uint32 *line, l_int32 x, l_int32 depth, l_uint32 val)
 
l_ok pixGetBlackOrWhiteVal (PIX *pixs, l_int32 op, l_uint32 *pval)
 
l_ok pixClearAll (PIX *pix)
 
l_ok pixSetAll (PIX *pix)
 
l_ok pixSetAllGray (PIX *pix, l_int32 grayval)
 
l_ok pixSetAllArbitrary (PIX *pix, l_uint32 val)
 
l_ok pixSetBlackOrWhite (PIX *pixs, l_int32 op)
 
l_ok pixSetComponentArbitrary (PIX *pix, l_int32 comp, l_int32 val)
 
l_ok pixClearInRect (PIX *pix, BOX *box)
 
l_ok pixSetInRect (PIX *pix, BOX *box)
 
l_ok pixSetInRectArbitrary (PIX *pix, BOX *box, l_uint32 val)
 
l_ok pixBlendInRect (PIX *pixs, BOX *box, l_uint32 val, l_float32 fract)
 
l_ok pixSetPadBits (PIX *pix, l_int32 val)
 
l_ok pixSetPadBitsBand (PIX *pix, l_int32 by, l_int32 bh, l_int32 val)
 
l_ok pixSetOrClearBorder (PIX *pixs, l_int32 left, l_int32 right, l_int32 top, l_int32 bot, l_int32 op)
 
l_ok pixSetBorderVal (PIX *pixs, l_int32 left, l_int32 right, l_int32 top, l_int32 bot, l_uint32 val)
 
l_ok pixSetBorderRingVal (PIX *pixs, l_int32 dist, l_uint32 val)
 
l_ok pixSetMirroredBorder (PIX *pixs, l_int32 left, l_int32 right, l_int32 top, l_int32 bot)
 
PIXpixCopyBorder (PIX *pixd, PIX *pixs, l_int32 left, l_int32 right, l_int32 top, l_int32 bot)
 
PIXpixAddBorder (PIX *pixs, l_int32 npix, l_uint32 val)
 
PIXpixAddBlackOrWhiteBorder (PIX *pixs, l_int32 left, l_int32 right, l_int32 top, l_int32 bot, l_int32 op)
 
PIXpixAddBorderGeneral (PIX *pixs, l_int32 left, l_int32 right, l_int32 top, l_int32 bot, l_uint32 val)
 
PIXpixAddMultipleBlackWhiteBorders (PIX *pixs, l_int32 nblack1, l_int32 nwhite1, l_int32 nblack2, l_int32 nwhite2, l_int32 nblack3, l_int32 nwhite3)
 
PIXpixRemoveBorder (PIX *pixs, l_int32 npix)
 
PIXpixRemoveBorderGeneral (PIX *pixs, l_int32 left, l_int32 right, l_int32 top, l_int32 bot)
 
PIXpixRemoveBorderToSize (PIX *pixs, l_int32 wd, l_int32 hd)
 
PIXpixAddMirroredBorder (PIX *pixs, l_int32 left, l_int32 right, l_int32 top, l_int32 bot)
 
PIXpixAddRepeatedBorder (PIX *pixs, l_int32 left, l_int32 right, l_int32 top, l_int32 bot)
 
PIXpixAddMixedBorder (PIX *pixs, l_int32 left, l_int32 right, l_int32 top, l_int32 bot)
 
PIXpixAddContinuedBorder (PIX *pixs, l_int32 left, l_int32 right, l_int32 top, l_int32 bot)
 
l_ok pixShiftAndTransferAlpha (PIX *pixd, PIX *pixs, l_float32 shiftx, l_float32 shifty)
 
PIXpixDisplayLayersRGBA (PIX *pixs, l_uint32 val, l_int32 maxw)
 
PIXpixCreateRGBImage (PIX *pixr, PIX *pixg, PIX *pixb)
 
PIXpixGetRGBComponent (PIX *pixs, l_int32 comp)
 
l_ok pixSetRGBComponent (PIX *pixd, PIX *pixs, l_int32 comp)
 
PIXpixGetRGBComponentCmap (PIX *pixs, l_int32 comp)
 
l_ok pixCopyRGBComponent (PIX *pixd, PIX *pixs, l_int32 comp)
 
l_ok composeRGBPixel (l_int32 rval, l_int32 gval, l_int32 bval, l_uint32 *ppixel)
 
l_ok composeRGBAPixel (l_int32 rval, l_int32 gval, l_int32 bval, l_int32 aval, l_uint32 *ppixel)
 
void extractRGBValues (l_uint32 pixel, l_int32 *prval, l_int32 *pgval, l_int32 *pbval)
 
void extractRGBAValues (l_uint32 pixel, l_int32 *prval, l_int32 *pgval, l_int32 *pbval, l_int32 *paval)
 
l_int32 extractMinMaxComponent (l_uint32 pixel, l_int32 type)
 
l_ok pixGetRGBLine (PIX *pixs, l_int32 row, l_uint8 *bufr, l_uint8 *bufg, l_uint8 *bufb)
 
l_ok setLineDataVal (l_uint32 *line, l_int32 j, l_int32 d, l_uint32 val)
 
PIXpixEndianByteSwapNew (PIX *pixs)
 
l_ok pixEndianByteSwap (PIX *pixs)
 
l_int32 lineEndianByteSwap (l_uint32 *datad, l_uint32 *datas, l_int32 wpl)
 
PIXpixEndianTwoByteSwapNew (PIX *pixs)
 
l_ok pixEndianTwoByteSwap (PIX *pixs)
 
l_ok pixGetRasterData (PIX *pixs, l_uint8 **pdata, size_t *pnbytes)
 
l_ok pixInferResolution (PIX *pix, l_float32 longside, l_int32 *pres)
 
l_ok pixAlphaIsOpaque (PIX *pix, l_int32 *popaque)
 
l_uint8 ** pixSetupByteProcessing (PIX *pix, l_int32 *pw, l_int32 *ph)
 
l_ok pixCleanupByteProcessing (PIX *pix, l_uint8 **lineptrs)
 
void l_setAlphaMaskBorder (l_float32 val1, l_float32 val2)
 

Variables

static const l_uint32 rmask32 []
 
LEPT_DLL l_float32 AlphaMaskBorderVals [2] = {0.0, 0.5}
 

Detailed Description


   This file has these basic operations:

     (1) Get and set: individual pixels, full image, rectangular region,
         pad pixels, border pixels, and color components for RGB
     (2) Add and remove border pixels
     (3) Endian byte swaps
     (4) Simple method for byte-processing images (instead of words)

     Pixel poking
          l_int32     pixGetPixel()
          l_int32     pixSetPixel()
          l_int32     pixGetRGBPixel()
          l_int32     pixSetRGBPixel()
          l_int32     pixSetCmapPixel()
          l_int32     pixGetRandomPixel()
          l_int32     pixClearPixel()
          l_int32     pixFlipPixel()
          void        setPixelLow()

     Find black or white value
          l_int32     pixGetBlackOrWhiteVal()

     Full image clear/set/set-to-arbitrary-value
          l_int32     pixClearAll()
          l_int32     pixSetAll()
          l_int32     pixSetAllGray()
          l_int32     pixSetAllArbitrary()
          l_int32     pixSetBlackOrWhite()
          l_int32     pixSetComponentArbitrary()

     Rectangular region clear/set/set-to-arbitrary-value/blend
          l_int32     pixClearInRect()
          l_int32     pixSetInRect()
          l_int32     pixSetInRectArbitrary()
          l_int32     pixBlendInRect()

     Set pad bits
          l_int32     pixSetPadBits()
          l_int32     pixSetPadBitsBand()

     Assign border pixels
          l_int32     pixSetOrClearBorder()
          l_int32     pixSetBorderVal()
          l_int32     pixSetBorderRingVal()
          l_int32     pixSetMirroredBorder()
          PIX        *pixCopyBorder()

     Add and remove border
          PIX        *pixAddBorder()
          PIX        *pixAddBlackOrWhiteBorder()
          PIX        *pixAddBorderGeneral()
          PIX        *pixAddMultipleBlackWhiteBorders()
          PIX        *pixRemoveBorder()
          PIX        *pixRemoveBorderGeneral()
          PIX        *pixRemoveBorderToSize()
          PIX        *pixAddMirroredBorder()
          PIX        *pixAddRepeatedBorder()
          PIX        *pixAddMixedBorder()
          PIX        *pixAddContinuedBorder()

     Helper functions using alpha
          l_int32     pixShiftAndTransferAlpha()
          PIX        *pixDisplayLayersRGBA()

     Color sample setting and extraction
          PIX        *pixCreateRGBImage()
          PIX        *pixGetRGBComponent()
          l_int32     pixSetRGBComponent()
          PIX        *pixGetRGBComponentCmap()
          l_int32     pixCopyRGBComponent()
          l_int32     composeRGBPixel()
          l_int32     composeRGBAPixel()
          void        extractRGBValues()
          void        extractRGBAValues()
          l_int32     extractMinMaxComponent()
          l_int32     pixGetRGBLine()

     Raster line pixel setter
          l_int32     setLineDataVal()

     Conversion between big and little endians
          PIX        *pixEndianByteSwapNew()
          l_int32     pixEndianByteSwap()
          l_int32     lineEndianByteSwap()
          PIX        *pixEndianTwoByteSwapNew()
          l_int32     pixEndianTwoByteSwap()

     Extract raster data as binary string
          l_int32     pixGetRasterData()

     Test alpha component opaqueness
          l_int32     pixAlphaIsOpaque()

     Infer resolution from image size
          l_int32     pixInferResolution()

     Setup helpers for 8 bpp byte processing
          l_uint8   **pixSetupByteProcessing()
          l_int32     pixCleanupByteProcessing()

     Setting parameters for antialias masking with alpha transforms
          void        l_setAlphaMaskBorder()

Definition in file pix2.c.

Function Documentation

◆ composeRGBAPixel()

l_ok composeRGBAPixel ( l_int32  rval,
l_int32  gval,
l_int32  bval,
l_int32  aval,
l_uint32 *  ppixel 
)

composeRGBAPixel()

Parameters
[in]rval,gval,bval,aval
[out]ppixel32-bit pixel
Returns
0 if OK; 1 on error
Notes:
     (1) All channels are 8 bits: the input values must be between
         0 and 255.  For speed, this is not enforced by masking
         with 0xff before shifting.

Definition at line 2758 of file pix2.c.

Referenced by pixcmapGetColor32(), pixcmapGetRGBA32(), and pixcmapToRGBTable().

◆ composeRGBPixel()

l_ok composeRGBPixel ( l_int32  rval,
l_int32  gval,
l_int32  bval,
l_uint32 *  ppixel 
)

composeRGBPixel()

Parameters
[in]rval,gval,bval
[out]ppixel32-bit pixel
Returns
0 if OK; 1 on error
Notes:
     (1) All channels are 8 bits: the input values must be between
         0 and 255.  For speed, this is not enforced by masking
         with 0xff before shifting.
     (2) A slower implementation uses macros:
           SET_DATA_BYTE(ppixel, COLOR_RED, rval);
           SET_DATA_BYTE(ppixel, COLOR_GREEN, gval);
           SET_DATA_BYTE(ppixel, COLOR_BLUE, bval);

Definition at line 2728 of file pix2.c.

Referenced by evalColorfillData(), makeColorfillTestData(), pixaDisplayBoxaa(), pixBlendBoxaRandom(), pixDisplayPtaa(), pixelFractionalShift(), pixelLinearMapToTargetColor(), pixelShiftByComponent(), and pixMakeGamutRGB().

◆ extractMinMaxComponent()

l_int32 extractMinMaxComponent ( l_uint32  pixel,
l_int32  type 
)

extractMinMaxComponent()

Parameters
[in]pixel32 bpp RGB
[in]typeL_CHOOSE_MIN or L_CHOOSE_MAX
Returns
component in range [0 ... 255], or NULL on error

Definition at line 2836 of file pix2.c.

References extractRGBValues().

◆ extractRGBAValues()

void extractRGBAValues ( l_uint32  pixel,
l_int32 *  prval,
l_int32 *  pgval,
l_int32 *  pbval,
l_int32 *  paval 
)

extractRGBAValues()

Parameters
[in]pixel32 bit
[out]prval[optional] red component
[out]pgval[optional] green component
[out]pbval[optional] blue component
[out]paval[optional] alpha component
Returns
void

Definition at line 2815 of file pix2.c.

◆ extractRGBValues()

void extractRGBValues ( l_uint32  pixel,
l_int32 *  prval,
l_int32 *  pgval,
l_int32 *  pbval 
)

extractRGBValues()

Parameters
[in]pixel32 bit
[out]prval[optional] red component
[out]pgval[optional] green component
[out]pbval[optional] blue component
Returns
void
Notes:
     (1) A slower implementation uses macros:
            *prval = GET_DATA_BYTE(&pixel, COLOR_RED);
            *pgval = GET_DATA_BYTE(&pixel, COLOR_GREEN);
            *pbval = GET_DATA_BYTE(&pixel, COLOR_BLUE);

Definition at line 2793 of file pix2.c.

Referenced by colorsAreSimilarForFill(), extractMinMaxComponent(), makeColorfillTestData(), pixaDisplayBoxaa(), pixcmapGrayToColor(), pixcmapShiftByComponent(), pixDisplayColorArray(), pixelColorIsValid(), pixelLinearMapToTargetColor(), pixelShiftByComponent(), pixGenerateMaskByBand32(), and pixGenerateMaskByDiscr32().

◆ l_setAlphaMaskBorder()

void l_setAlphaMaskBorder ( l_float32  val1,
l_float32  val2 
)

l_setAlphaMaskBorder()

Parameters
[in]val1,val2in [0.0 ... 1.0]
Returns
void
Notes:
     (1) This sets the opacity values used to generate the two outer
         boundary rings in the alpha mask associated with geometric
         transforms such as pixRotateWithAlpha().
     (2) The default values are val1 = 0.0 (completely transparent
         in the outermost ring) and val2 = 0.5 (half transparent
         in the second ring).  When the image is blended, this
         completely removes the outer ring (shrinking the image by
         2 in each direction), and alpha-blends with 0.5 the second ring.
         Using val1 = 0.25 and val2 = 0.75 gives a slightly more
         blurred border, with no perceptual difference at screen resolution.
     (3) The actual mask values are found by multiplying these
         normalized opacity values by 255.

Definition at line 3517 of file pix2.c.

◆ lineEndianByteSwap()

l_int32 lineEndianByteSwap ( l_uint32 *  datad,
l_uint32 *  datas,
l_int32  wpl 
)

lineEndianByteSwap()

Parameters
[in]dataddest byte array data, reordered on little-endians
[in]datasa src line of pix data)
[in]wplnumber of 32 bit words in the line
Returns
0 if OK, 1 on error
Notes:
     (1) This is used on little-endian platforms to swap
         the bytes within each word in the line of image data.
         Bytes 0 <==> 3 and 1 <==> 2 are swapped in the dest
         byte array data8d, relative to the pix data in datas.
     (2) The bytes represent 8 bit pixel values.  They are swapped
         for little endians so that when the dest array datad
         is addressed by bytes, the pixels are chosen sequentially
         from left to right in the image.

Definition at line 3097 of file pix2.c.

◆ pixAddBlackOrWhiteBorder()

PIX* pixAddBlackOrWhiteBorder ( PIX pixs,
l_int32  left,
l_int32  right,
l_int32  top,
l_int32  bot,
l_int32  op 
)

pixAddBlackOrWhiteBorder()

Parameters
[in]pixsall depths; colormap ok
[in]left,right,top,botnumber of pixels added
[in]opL_GET_BLACK_VAL, L_GET_WHITE_VAL
Returns
pixd with the added exterior pixels, or NULL on error
Notes:
     (1) See pixGetBlackOrWhiteVal() for possible side effect (adding
         a color to a colormap).
     (2) The only complication is that pixs may have a colormap.
         There are two ways to add the black or white border:
         (a) As done here (simplest, most efficient)
         (b) l_int32 ws, hs, d;
             pixGetDimensions(pixs, &ws, &hs, &d);
             Pix *pixd = pixCreate(ws + left + right, hs + top + bot, d);
             PixColormap *cmap = pixGetColormap(pixs);
             if (cmap != NULL)
                 pixSetColormap(pixd, pixcmapCopy(cmap));
             pixSetBlackOrWhite(pixd, L_SET_WHITE);  // uses cmap
             pixRasterop(pixd, left, top, ws, hs, PIX_SET, pixs, 0, 0);

Definition at line 1811 of file pix2.c.

References L_GET_BLACK_VAL, L_GET_WHITE_VAL, pixAddBorderGeneral(), and pixGetBlackOrWhiteVal().

Referenced by pixAddMultipleBlackWhiteBorders(), pixaDisplayPairTiledInColumns(), pixDisplayOutliers(), and showExtractNumbers().

◆ pixAddBorder()

PIX* pixAddBorder ( PIX pixs,
l_int32  npix,
l_uint32  val 
)

pixAddBorder()

Parameters
[in]pixsall depths; colormap ok
[in]npixnumber of pixels to be added to each side
[in]valvalue of added border pixels
Returns
pixd with the added exterior pixels, or NULL on error
Notes:
     (1) See pixGetBlackOrWhiteVal() for values of black and white pixels.

Definition at line 1773 of file pix2.c.

References pixAddBorderGeneral(), and pixClone().

Referenced by pixaDisplayTiledAndScaled(), pixaDisplayTiledInColumns(), pixaDisplayTiledInRows(), pixDisplayColorArray(), pixGetOuterBorder(), pixSimpleCaptcha(), and recogDebugAverages().

◆ pixAddBorderGeneral()

PIX* pixAddBorderGeneral ( PIX pixs,
l_int32  left,
l_int32  right,
l_int32  top,
l_int32  bot,
l_uint32  val 
)

pixAddBorderGeneral()

Parameters
[in]pixsall depths; colormap ok
[in]left,right,top,botnumber of pixels added
[in]valvalue of added border pixels
Returns
pixd with the added exterior pixels, or NULL on error
Notes:
     (1) For binary images:
            white:  val = 0
            black:  val = 1
         For grayscale images:
            white:  val = 2 ** d - 1
            black:  val = 0
         For rgb color images:
            white:  val = 0xffffff00
            black:  val = 0
         For colormapped images, set val to the appropriate colormap index.
     (2) If the added border is either black or white, you can use
            pixAddBlackOrWhiteBorder()
         The black and white values for all images can be found with
            pixGetBlackOrWhiteVal()
         which, if pixs is cmapped, may add an entry to the colormap.
         Alternatively, if pixs has a colormap, you can find the index
         of the pixel whose intensity is closest to white or black:
            white: pixcmapGetRankIntensity(cmap, 1.0, &index);
            black: pixcmapGetRankIntensity(cmap, 0.0, &index);
         and use that for val.

Definition at line 1863 of file pix2.c.

References pixCreate(), and pixGetDimensions().

Referenced by pixaAddBorderGeneral(), pixAddBlackOrWhiteBorder(), pixAddBorder(), pixAddContinuedBorder(), pixAddMirroredBorder(), pixAddMixedBorder(), pixAddRepeatedBorder(), pixaDisplayTiledByIndex(), pixaDisplayTiledWithText(), pixAffineSequential(), recogShowMatch(), and recogShowPath().

◆ pixAddContinuedBorder()

PIX* pixAddContinuedBorder ( PIX pixs,
l_int32  left,
l_int32  right,
l_int32  top,
l_int32  bot 
)

pixAddContinuedBorder()

Parameters
[in]pixsall depths; colormap ok
[in]left,right,top,botpixels on each side to be added
Returns
pixd, or NULL on error
Notes:
     (1) This adds pixels on each side whose values are equal to
         the value on the closest boundary pixel.

Definition at line 2250 of file pix2.c.

References PIX_SRC, pixAddBorderGeneral(), pixGetDimensions(), and pixRasterop().

◆ pixAddMirroredBorder()

PIX* pixAddMirroredBorder ( PIX pixs,
l_int32  left,
l_int32  right,
l_int32  top,
l_int32  bot 
)

pixAddMirroredBorder()

Parameters
[in]pixsall depths; colormap ok
[in]left,right,top,botnumber of pixels added
Returns
pixd, or NULL on error
Notes:
     (1) This applies what is effectively mirror boundary conditions.
         For the added border pixels in pixd, the pixels in pixs
         near the border are mirror-copied into the border region.
     (2) This is useful for avoiding special operations near
         boundaries when doing image processing operations
         such as rank filters and convolution.  In use, one first
         adds mirrored pixels to each side of the image.  The number
         of pixels added on each side is half the filter dimension.
         Then the image processing operations proceed over a
         region equal to the size of the original image, and
         write directly into a dest pix of the same size as pixs.
     (3) The general pixRasterop() is used for an in-place operation here
         because there is no overlap between the src and dest rectangles.

Definition at line 2100 of file pix2.c.

References PIX_SRC, pixAddBorderGeneral(), pixGetDimensions(), and pixRasterop().

Referenced by bilateralCreate(), pixBlockconvGrayUnnormalized(), pixSobelEdgeFilter(), and pixTilingGetTile().

◆ pixAddMixedBorder()

PIX* pixAddMixedBorder ( PIX pixs,
l_int32  left,
l_int32  right,
l_int32  top,
l_int32  bot 
)

pixAddMixedBorder()

Parameters
[in]pixsall depths; colormap ok
[in]left,right,top,botnumber of pixels added
Returns
pixd, or NULL on error
Notes:
     (1) This applies mirrored boundary conditions horizontally
         and repeated b.c. vertically.
     (2) It is specifically used for avoiding special operations
         near boundaries when convolving a hue-saturation histogram
         with a given window size.  The repeated b.c. are used
         vertically for hue, and the mirrored b.c. are used
         horizontally for saturation.  The number of pixels added
         on each side is approximately (but not quite) half the
         filter dimension.  The image processing operations can
         then proceed over a region equal to the size of the original
         image, and write directly into a dest pix of the same
         size as pixs.
     (3) The general pixRasterop() can be used for an in-place
         operation here because there is no overlap between the
         src and dest rectangles.

Definition at line 2205 of file pix2.c.

References PIX_SRC, pixAddBorderGeneral(), pixGetDimensions(), and pixRasterop().

◆ pixAddMultipleBlackWhiteBorders()

PIX* pixAddMultipleBlackWhiteBorders ( PIX pixs,
l_int32  nblack1,
l_int32  nwhite1,
l_int32  nblack2,
l_int32  nwhite2,
l_int32  nblack3,
l_int32  nwhite3 
)

pixAddMultipleBlackWhiteBorders()

Parameters
[in]pixsall depths; colormap ok
[in]nblack1width of first black border
[in]nwhite1width of first white border
[in]nblack2width of second black border
[in]nwhite2width of second white border
[in]nblack3width of third black border
[in]nwhite3width of third white border
Returns
pixd with the added borders, or NULL on error
Notes:
     (1) This is a convenience function for adding up to 3 black and
         3 white borders, alternating black and white.
     (2) Each of the 6 args gives the width of the next border, starting
         with a black border.  Any of the args can be 0, skipping
         the addition of that border.
     (3) Maximum allowed border width is 500 for any border.

Definition at line 1931 of file pix2.c.

References L_GET_BLACK_VAL, L_GET_WHITE_VAL, pixAddBlackOrWhiteBorder(), pixClone(), and pixDestroy().

◆ pixAddRepeatedBorder()

PIX* pixAddRepeatedBorder ( PIX pixs,
l_int32  left,
l_int32  right,
l_int32  top,
l_int32  bot 
)

pixAddRepeatedBorder()

Parameters
[in]pixsall depths; colormap ok
[in]left,right,top,botnumber of pixels added
Returns
pixd, or NULL on error
Notes:
     (1) This applies a repeated border, as if the central part of
         the image is tiled over the plane.  So, for example, the
         pixels in the left border come from the right side of the image.
     (2) The general pixRasterop() is used for an in-place operation here
         because there is no overlap between the src and dest rectangles.

Definition at line 2151 of file pix2.c.

References PIX_SRC, pixAddBorderGeneral(), pixGetDimensions(), and pixRasterop().

◆ pixAlphaIsOpaque()

l_ok pixAlphaIsOpaque ( PIX pix,
l_int32 *  popaque 
)

pixAlphaIsOpaque()

Parameters
[in]pix32 bpp, spp == 4
[out]popaque1 if spp == 4 and all alpha component values are 255 (opaque); 0 otherwise
Returns
0 if OK, 1 on error
Notes:
     1) On error, opaque is returned as 0 (FALSE).

Definition at line 3378 of file pix2.c.

◆ pixBlendInRect()

l_ok pixBlendInRect ( PIX pixs,
BOX box,
l_uint32  val,
l_float32  fract 
)

pixBlendInRect()

Parameters
[in]pixs32 bpp rgb
[in]box[optional] in which all pixels will be blended
[in]valblend value; 0xrrggbb00
[in]fractfraction of color to be blended with each pixel in pixs
Returns
0 if OK; 1 on error
Notes:
     (1) This is an in-place function.  It blends the input color val
         with the pixels in pixs in the specified rectangle.
         If no rectangle is specified, it blends over the entire image.

Definition at line 1262 of file pix2.c.

Referenced by pixBlendBoxaRandom().

◆ pixCleanupByteProcessing()

l_ok pixCleanupByteProcessing ( PIX pix,
l_uint8 **  lineptrs 
)

pixCleanupByteProcessing()

Parameters
[in]pix8 bpp, no colormap
[in]lineptrsptrs to the beginning of each raster line of data
Returns
0 if OK, 1 on error
Notes:
     (1) This must be called after processing that was initiated
         by pixSetupByteProcessing() has finished.

Definition at line 3477 of file pix2.c.

References pixEndianByteSwap().

◆ pixClearAll()

l_ok pixClearAll ( PIX pix)

pixClearAll()

Parameters
[in]pixall depths; use cmapped with caution
Returns
0 if OK, 1 on error
Notes:
     (1) Clears all data to 0.  For 1 bpp, this is white; for grayscale
         or color, this is black.
     (2) Caution: for colormapped pix, this sets the color to the first
         one in the colormap.  Be sure that this is the intended color!

Definition at line 773 of file pix2.c.

References Pix::data, Pix::h, and Pix::wpl.

Referenced by pixaAccumulateSamples(), pixaSplitPix(), pixDilate(), and pixHMT().

◆ pixClearInRect()

l_ok pixClearInRect ( PIX pix,
BOX box 
)

pixClearInRect()

Parameters
[in]pixall depths; can be cmapped
[in]boxin which all pixels will be cleared
Returns
0 if OK, 1 on error
Notes:
     (1) Clears all data in rect to 0.  For 1 bpp, this is white;
         for grayscale or color, this is black.
     (2) Caution: for colormapped pix, this sets the color to the first
         one in the colormap.  Be sure that this is the intended color!

Definition at line 1090 of file pix2.c.

References boxGetGeometry(), PIX_CLR, and pixRasterop().

◆ pixClearPixel()

l_ok pixClearPixel ( PIX pix,
l_int32  x,
l_int32  y 
)

pixClearPixel()

Parameters
[in]pixany depth; warning if colormapped
[in]x,ypixel coords
Returns
0 if OK; 1 or 2 on error.
Notes:
     (1) If the point is outside the image, this returns an error (2),
         with 0 in pval.  To avoid spamming output, it fails silently.

Definition at line 530 of file pix2.c.

◆ pixCopyBorder()

PIX* pixCopyBorder ( PIX pixd,
PIX pixs,
l_int32  left,
l_int32  right,
l_int32  top,
l_int32  bot 
)

pixCopyBorder()

Parameters
[in]pixdall depths; colormap ok; can be NULL
[in]pixssame depth and size as pixd
[in]left,right,top,botnumber of pixels to copy
Returns
pixd, or NULL on error if pixd is not defined
Notes:
     (1) pixd can be null, but otherwise it must be the same size
         and depth as pixs.  Always returns pixd.
     (2) This is useful in situations where by setting a few border
         pixels we can avoid having to copy all pixels in pixs into
         pixd as an initialization step for some operation.
         Nevertheless, for safety, if making a new pixd, all the
         non-border pixels are initialized to 0.

Definition at line 1721 of file pix2.c.

References PIX_SRC, pixCreateTemplate(), pixGetDimensions(), pixRasterop(), and pixSizesEqual().

◆ pixCopyRGBComponent()

l_ok pixCopyRGBComponent ( PIX pixd,
PIX pixs,
l_int32  comp 
)

pixCopyRGBComponent()

Parameters
[in]pixd32 bpp
[in]pixs32 bpp
[in]compone of the set: {COLOR_RED, COLOR_GREEN, COLOR_BLUE, L_ALPHA_CHANNEL}
Returns
0 if OK; 1 on error
Notes:
     (1) The two images are registered to the UL corner.  The sizes
         are usually the same, and a warning is issued if they differ.

Definition at line 2669 of file pix2.c.

◆ pixCreateRGBImage()

PIX* pixCreateRGBImage ( PIX pixr,
PIX pixg,
PIX pixb 
)

pixCreateRGBImage()

Parameters
[in]pixr8 bpp red pix
[in]pixg8 bpp green pix
[in]pixb8 bpp blue pix
Returns
32 bpp pix, interleaved with 4 samples/pixel, or NULL on error
Notes:
     (1) the 4th byte, sometimes called the "alpha channel",
         and which is often used for blending between different
         images, is left with 0 value.
     (2) see Note (4) in pix.h for details on storage of
         8-bit samples within each 32-bit word.
     (3) This implementation, setting the r, g and b components
         sequentially, is much faster than setting them in parallel
         by constructing an RGB dest pixel and writing it to dest.
         The reason is there are many more cache misses when reading
         from 3 input images simultaneously.

Definition at line 2410 of file pix2.c.

References pixCreate(), and pixGetDimensions().

◆ pixDisplayLayersRGBA()

PIX* pixDisplayLayersRGBA ( PIX pixs,
l_uint32  val,
l_int32  maxw 
)

pixDisplayLayersRGBA()

Parameters
[in]pixscmap or 32 bpp rgba
[in]val32 bit unsigned color to use as background
[in]maxwmax output image width; 0 for no scaling
Returns
pixd showing various image views, or NULL on error
Notes:
     (1) Use val == 0xffffff00 for white background.
     (2) Three views are given:
          ~ the image with a fully opaque alpha
          ~ the alpha layer
          ~ the image as it would appear with a white background.

Definition at line 2340 of file pix2.c.

◆ pixEndianByteSwap()

l_ok pixEndianByteSwap ( PIX pixs)

pixEndianByteSwap()

Parameters
[in]pixs
Returns
0 if OK, 1 on error
Notes:
     (1) This is used on little-endian platforms to swap
         the bytes within a word; bytes 0 and 3 are swapped,
         and bytes 1 and 2 are swapped.
     (2) This is required for little-endians in situations
         where we convert from a serialized byte order that is
         in raster order, as one typically has in file formats,
         to one with MSB-to-the-left in each 32-bit word, or v.v.
         See pix.h for a description of the canonical format
         (MSB-to-the left) that is used for both little-endian
         and big-endian platforms.   For big-endians, the
         MSB-to-the-left word order has the bytes in raster
         order when serialized, so no byte flipping is required.

Definition at line 3041 of file pix2.c.

References pixGetData().

Referenced by pixCleanupByteProcessing().

◆ pixEndianByteSwapNew()

PIX* pixEndianByteSwapNew ( PIX pixs)

pixEndianByteSwapNew()

Parameters
[in]pixs
Returns
pixd, or NULL on error
Notes:
     (1) This is used to convert the data in a pix to a
         serialized byte buffer in raster order, and, for RGB,
         in order RGBA.  This requires flipping bytes within
         each 32-bit word for little-endian platforms, because the
         words have a MSB-to-the-left rule, whereas byte raster-order
         requires the left-most byte in each word to be byte 0.
         For big-endians, no swap is necessary, so this returns a clone.
     (2) Unlike pixEndianByteSwap(), which swaps the bytes in-place,
         this returns a new pix (or a clone).  We provide this
         because often when serialization is done, the source
         pix needs to be restored to canonical little-endian order,
         and this requires a second byte swap.  In such a situation,
         it is twice as fast to make a new pix in big-endian order,
         use it, and destroy it.

Definition at line 2979 of file pix2.c.

References pixClone(), and pixGetData().

◆ pixEndianTwoByteSwap()

l_ok pixEndianTwoByteSwap ( PIX pixs)

pixEndianTwoByteSwap()

Parameters
[in]pixs
Returns
0 if OK, 1 on error
Notes:
     (1) This is used on little-endian platforms to swap the
         2-byte entities within a 32-bit word.
     (2) This is equivalent to a full byte swap, as performed
         by pixEndianByteSwap(), followed by byte swaps in
         each of the 16-bit entities separately.

Definition at line 3200 of file pix2.c.

References pixGetData().

◆ pixEndianTwoByteSwapNew()

PIX* pixEndianTwoByteSwapNew ( PIX pixs)

pixEndianTwoByteSwapNew()

Parameters
[in]pixs
Returns
0 if OK, 1 on error
Notes:
     (1) This is used on little-endian platforms to swap the
         2-byte entities within a 32-bit word.
     (2) This is equivalent to a full byte swap, as performed
         by pixEndianByteSwap(), followed by byte swaps in
         each of the 16-bit entities separately.
     (3) Unlike pixEndianTwoByteSwap(), which swaps the shorts in-place,
         this returns a new pix (or a clone).  We provide this
         to avoid having to swap twice in situations where the input
         pix must be restored to canonical little-endian order.

Definition at line 3148 of file pix2.c.

References pixClone(), and pixGetData().

◆ pixFlipPixel()

l_ok pixFlipPixel ( PIX pix,
l_int32  x,
l_int32  y 
)

pixFlipPixel()

Parameters
[in]pixany depth, warning if colormapped
[in]x,ypixel coords
Returns
0 if OK; 1 or 2 on error
Notes:
     (1) If the point is outside the image, this returns an error (2),
         with 0 in pval.  To avoid spamming output, it fails silently.

Definition at line 590 of file pix2.c.

◆ pixGetBlackOrWhiteVal()

l_ok pixGetBlackOrWhiteVal ( PIX pixs,
l_int32  op,
l_uint32 *  pval 
)

pixGetBlackOrWhiteVal()

Parameters
[in]pixsall depths; cmap ok
[in]opL_GET_BLACK_VAL, L_GET_WHITE_VAL
[out]pvalpixel value
Returns
0 if OK; 1 on error
Notes:
     (1) Side effect.  For a colormapped image, if the requested
         color is not present and there is room to add it in the cmap,
         it is added and the new index is returned.  If there is no room,
         the index of the closest color in intensity is returned.

Definition at line 719 of file pix2.c.

References L_GET_BLACK_VAL, and L_GET_WHITE_VAL.

Referenced by pixAddBlackOrWhiteBorder().

◆ pixGetPixel()

l_ok pixGetPixel ( PIX pix,
l_int32  x,
l_int32  y,
l_uint32 *  pval 
)

pixGetPixel()

Parameters
[in]pix
[in]x,ypixel coords
[out]pvalpixel value
Returns
0 if OK; 1 or 2 on error
Notes:
     (1) This returns the value in the data array.  If the pix is
         colormapped, it returns the colormap index, not the rgb value.
     (2) Because of the function overhead and the parameter checking,
         this is much slower than using the GET_DATA_*() macros directly.
         Speed on a 1 Mpixel RGB image, using a 3 GHz machine:
           * pixGet/pixSet: ~25 Mpix/sec
           * GET_DATA/SET_DATA: ~350 MPix/sec
         If speed is important and you're doing random access into
         the pix, use pixGetLinePtrs() and the array access macros.
     (3) If the point is outside the image, this returns an error (2),
         with 0 in pval.  To avoid spamming output, it fails silently.

Definition at line 192 of file pix2.c.

References pixGetDimensions().

Referenced by getCutPathForHole(), kernelCreateFromPix(), localSearchForBackground(), pixColorFillFromSeed(), pixelIsOnColorBoundary(), pixGetRandomPixel(), pixGetVisitedNeighbors(), pixSearchBinaryMaze(), and pixSearchGrayMaze().

◆ pixGetRandomPixel()

l_ok pixGetRandomPixel ( PIX pix,
l_uint32 *  pval,
l_int32 *  px,
l_int32 *  py 
)

pixGetRandomPixel()

Parameters
[in]pixany depth; can be colormapped
[out]pval[optional] pixel value
[out]px[optional] x coordinate chosen; can be null
[out]py[optional] y coordinate chosen; can be null
Returns
0 if OK; 1 on error
Notes:
     (1) If the pix is colormapped, it returns the rgb value.

Definition at line 480 of file pix2.c.

References pixGetDimensions(), and pixGetPixel().

◆ pixGetRasterData()

l_ok pixGetRasterData ( PIX pixs,
l_uint8 **  pdata,
size_t *  pnbytes 
)

pixGetRasterData()

Parameters
[in]pixs1, 8, 32 bpp
[out]pdataraster data in memory
[out]pnbytesnumber of bytes in data string
Returns
0 if OK, 1 on error
Notes:
     (1) This returns the raster data as a byte string, padded to the
         byte.  For 1 bpp, the first pixel is the MSbit in the first byte.
         For rgb, the bytes are in (rgb) order.  This is the format
         required for flate encoding of pixels in a PostScript file.

Definition at line 3252 of file pix2.c.

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

◆ pixGetRGBComponent()

PIX* pixGetRGBComponent ( PIX pixs,
l_int32  comp 
)

pixGetRGBComponent()

Parameters
[in]pixs32 bpp, or colormapped
[in]compone of {COLOR_RED, COLOR_GREEN, COLOR_BLUE, L_ALPHA_CHANNEL}
Returns
pixd the selected 8 bpp component image of the input 32 bpp image or NULL on error
Notes:
     (1) Three calls to this function generate the r, g and b 8 bpp
         component images.  This is much faster than generating the
         three images in parallel, by extracting a src pixel and setting
         the pixels of each component image from it.  The reason is
         there are many more cache misses when writing to three
         output images simultaneously.

Definition at line 2464 of file pix2.c.

Referenced by pixWarpStereoscopic().

◆ pixGetRGBComponentCmap()

PIX* pixGetRGBComponentCmap ( PIX pixs,
l_int32  comp 
)

pixGetRGBComponentCmap()

Parameters
[in]pixscolormapped
[in]compone of the set: {COLOR_RED, COLOR_GREEN, COLOR_BLUE}
Returns
pixd the selected 8 bpp component image of the input cmapped image, or NULL on error
Notes:
     (1) In leptonica, we do not support alpha in colormaps.

Definition at line 2581 of file pix2.c.

◆ pixGetRGBLine()

l_ok pixGetRGBLine ( PIX pixs,
l_int32  row,
l_uint8 *  bufr,
l_uint8 *  bufg,
l_uint8 *  bufb 
)

pixGetRGBLine()

Parameters
[in]pixs32 bpp
[in]row
[in]bufrarray of red samples; size w bytes
[in]bufgarray of green samples; size w bytes
[in]bufbarray of blue samples; size w bytes
Returns
0 if OK; 1 on error
Notes:
     (1) This puts rgb components from the input line in pixs
         into the given buffers.

Definition at line 2870 of file pix2.c.

◆ pixGetRGBPixel()

l_ok pixGetRGBPixel ( PIX pix,
l_int32  x,
l_int32  y,
l_int32 *  prval,
l_int32 *  pgval,
l_int32 *  pbval 
)

pixGetRGBPixel()

Parameters
[in]pix32 bpp rgb, not colormapped
[in]x,ypixel coords
[out]prval[optional] red component
[out]pgval[optional] green component
[out]pbval[optional] blue component
Returns
0 if OK; 1 or 2 on error
Notes:
     (1) If the point is outside the image, this returns an error (2),
         with 0 in pval.  To avoid spamming output, it fails silently.

Definition at line 328 of file pix2.c.

References pixGetDimensions().

◆ pixInferResolution()

l_ok pixInferResolution ( PIX pix,
l_float32  longside,
l_int32 *  pres 
)

pixInferResolution()

Parameters
[in]pix
[in]longsideassumed max dimension, in inches
[out]presresolution (ppi)
Returns
0 if OK, 1 on error
Notes:
     (1) This finds the resolution, assuming that the longest side
         of the image is longside.  On error, returns 300 ppi.
     (2) This is useful for computing resolution for generating pdfs,
         when the images are scanned from pages of known size.
         There, longside is typically about 11.0.

Definition at line 3334 of file pix2.c.

References pixGetDimensions().

◆ pixRemoveBorder()

PIX* pixRemoveBorder ( PIX pixs,
l_int32  npix 
)

pixRemoveBorder()

Parameters
[in]pixsall depths; colormap ok
[in]npixnumber to be removed from each of the 4 sides
Returns
pixd with pixels removed around border, or NULL on error

Definition at line 1977 of file pix2.c.

References pixClone(), and pixRemoveBorderGeneral().

◆ pixRemoveBorderGeneral()

PIX* pixRemoveBorderGeneral ( PIX pixs,
l_int32  left,
l_int32  right,
l_int32  top,
l_int32  bot 
)

pixRemoveBorderGeneral()

Parameters
[in]pixsall depths; colormap ok
[in]left,right,top,botnumber of pixels removed
Returns
pixd with pixels removed around border, or NULL on error

Definition at line 1996 of file pix2.c.

References pixCreate(), and pixGetDimensions().

Referenced by pixAffineSequential(), pixRemoveBorder(), and pixRemoveBorderToSize().

◆ pixRemoveBorderToSize()

PIX* pixRemoveBorderToSize ( PIX pixs,
l_int32  wd,
l_int32  hd 
)

pixRemoveBorderToSize()

Parameters
[in]pixsall depths; colormap ok
[in]wdtarget width; use 0 if only removing from height
[in]hdtarget height; use 0 if only removing from width
Returns
pixd with pixels removed around border, or NULL on error
Notes:
     (1) Removes pixels as evenly as possible from the sides of the
         image, leaving the central part.
     (2) Returns clone if no pixels requested removed, or the target
         sizes are larger than the image.

Definition at line 2047 of file pix2.c.

References pixClone(), pixGetDimensions(), and pixRemoveBorderGeneral().

◆ pixSetAll()

l_ok pixSetAll ( PIX pix)

pixSetAll()

Parameters
[in]pixall depths; use cmapped with caution
Returns
0 if OK, 1 on error
Notes:
     (1) Sets all data to 1.  For 1 bpp, this is black; for grayscale
         or color, this is white.
     (2) Caution: for colormapped pix, this sets the pixel value to the
         maximum value supported by the colormap: 2^d - 1.  However, this
         color may not be defined, because the colormap may not be full.

Definition at line 799 of file pix2.c.

Referenced by boxaCombineOverlaps(), boxaCombineOverlapsInPair(), boxaCompareRegions(), boxaDisplayTiled(), kernelDisplayInPix(), pixaDisplayTiled(), pixaDisplayTiledAndScaled(), pixaDisplayTiledInRows(), pixaSplitPix(), pixBlockrank(), pixErode(), pixHMT(), pixMakeFrameMask(), pixPadToCenterCentroid(), pixSearchGrayMaze(), selaAddCrossJunctions(), and selaAddTJunctions().

◆ pixSetAllArbitrary()

l_ok pixSetAllArbitrary ( PIX pix,
l_uint32  val 
)

pixSetAllArbitrary()

Parameters
[in]pixall depths; use cmapped with caution
[in]valvalue to set all pixels
Returns
0 if OK; 1 on error
Notes:
     (1) Caution 1!  For colormapped pix, val is used as an index
         into a colormap.  Be sure that index refers to the intended color.
         If the color is not in the colormap, you should first add it
         and then call this function.
     (2) Caution 2!  For 32 bpp pix, the interpretation of the LSB
         of val depends on whether spp == 3 (RGB) or spp == 4 (RGBA).
         For RGB, the LSB is ignored in image transformations.
         For RGBA, the LSB is interpreted as the alpha (transparency)
         component; full transparency has alpha == 0x0, whereas
         full opacity has alpha = 0xff.  An RGBA image with full
         opacity behaves like an RGB image.
     (3) As an example of (2), suppose you want to initialize a 32 bpp
         pix with partial opacity, say 0xee337788.  If the pix is 3 spp,
         the 0x88 alpha component will be ignored and may be changed
         in subsequent processing.  However, if the pix is 4 spp, the
         alpha component will be retained and used. The function
         pixCreate(w, h, 32) makes an RGB image by default, and
         pixSetSpp(pix, 4) can be used to promote an RGB image to RGBA.

Definition at line 929 of file pix2.c.

Referenced by pixaccCreate(), pixaDisplayUnsplit(), pixaSplitPix(), pixDisplayColorArray(), pixInitAccumulate(), and recogShowAverageTemplates().

◆ pixSetAllGray()

l_ok pixSetAllGray ( PIX pix,
l_int32  grayval 
)

pixSetAllGray()

Parameters
[in]pixall depths, cmap ok
[in]grayvalin range 0 ... 255
Returns
0 if OK; 1 on error
Notes:
     (1) N.B.  For all images, grayval == 0 represents black and
         grayval == 255 represents white.
     (2) For depth < 8, we do our best to approximate the gray level.
         For 1 bpp images, any grayval < 128 is black; >= 128 is white.
         For 32 bpp images, each r,g,b component is set to grayval,
         and the alpha component is preserved.
     (3) If pix is colormapped, it adds the gray value, replicated in
         all components, to the colormap if it's not there and there
         is room.  If the colormap is full, it finds the closest color in
         L2 distance of components.  This index is written to all pixels.

Definition at line 839 of file pix2.c.

Referenced by pixApplyHorizDisparity(), and pixApplyVertDisparity().

◆ pixSetBlackOrWhite()

l_ok pixSetBlackOrWhite ( PIX pixs,
l_int32  op 
)

pixSetBlackOrWhite()

Parameters
[in]pixsall depths; cmap ok
[in]opL_SET_BLACK, L_SET_WHITE
Returns
0 if OK; 1 on error
Notes:
     (1) Function for setting all pixels in an image to either black
         or white.
     (2) If pixs is colormapped, it adds black or white to the
         colormap if it's not there and there is room.  If the colormap
         is full, it finds the closest color in intensity.
         This index is written to all pixels.

Definition at line 997 of file pix2.c.

References L_SET_BLACK, and L_SET_WHITE.

Referenced by pixCopyWithBoxa(), pixQuadraticVShearSampled(), pixStretchHorizontalLI(), and pixStretchHorizontalSampled().

◆ pixSetBorderRingVal()

l_ok pixSetBorderRingVal ( PIX pixs,
l_int32  dist,
l_uint32  val 
)

pixSetBorderRingVal()

Parameters
[in]pixsany depth; cmap OK
[in]distdistance from outside; must be > 0; first ring is 1
[in]valvalue to set at each border pixel
Returns
0 if OK; 1 on error
Notes:
     (1) The rings are single-pixel-wide rectangular sets of
         pixels at a given distance from the edge of the pix.
         This sets all pixels in a given ring to a value.

Definition at line 1623 of file pix2.c.

References pixGetDimensions(), and pixSetPixel().

◆ pixSetBorderVal()

l_ok pixSetBorderVal ( PIX pixs,
l_int32  left,
l_int32  right,
l_int32  top,
l_int32  bot,
l_uint32  val 
)

pixSetBorderVal()

Parameters
[in]pixs8, 16 or 32 bpp
[in]left,right,top,botamount to set
[in]valvalue to set at each border pixel
Returns
0 if OK; 1 on error
Notes:
     (1) The border region is defined to be the region in the
         image within a specific distance of each edge.  Here, we
         allow the pixels within a specified distance of each
         edge to be set independently.  This sets the pixels
         in the border region to the given input value.
     (2) For efficiency, use pixSetOrClearBorder() if
         you're setting the border to either black or white.
     (3) If d != 32, the input value should be masked off
         to the appropriate number of least significant bits.
     (4) The code is easily generalized for 2 or 4 bpp.

Definition at line 1521 of file pix2.c.

References pixGetData(), and pixGetDimensions().

Referenced by boxaDisplayTiled().

◆ pixSetCmapPixel()

l_ok pixSetCmapPixel ( PIX pix,
l_int32  x,
l_int32  y,
l_int32  rval,
l_int32  gval,
l_int32  bval 
)

pixSetCmapPixel()

Parameters
[in]pix2, 4 or 8 bpp, colormapped
[in]x,ypixel coords
[in]rvalred component
[in]gvalgreen component
[in]bvalblue component
Returns
0 if OK; 1 or 2 on error
Notes:
     (1) If the point is outside the image, this returns an error (2),
         and to avoid spamming output, it fails silently.
     (2) - If the color already exists, use it.
  • If the color does not exist in the colormap, it is added if possible.
  • If there is not room in the colormap for the new color: * if d < 8, return 2 with a warning. * if d == 8, find and use the nearest color. (3) Note that this operation scales with the number of colors in the colormap, and therefore can be very expensive if an attempt is made to set many pixels. (In that case, it should be implemented with a map:rgb-->index for efficiency.) This is best used with very small images.

Definition at line 434 of file pix2.c.

◆ pixSetComponentArbitrary()

l_ok pixSetComponentArbitrary ( PIX pix,
l_int32  comp,
l_int32  val 
)

pixSetComponentArbitrary()

Parameters
[in]pix32 bpp
[in]compCOLOR_RED, COLOR_GREEN, COLOR_BLUE, L_ALPHA_CHANNEL
[in]valvalue to set this component
Returns
0 if OK; 1 on error
Notes:
     (1) For example, this can be used to set the alpha component to opaque:
             pixSetComponentArbitrary(pix, L_ALPHA_CHANNEL, 255)

Definition at line 1042 of file pix2.c.

◆ pixSetInRect()

l_ok pixSetInRect ( PIX pix,
BOX box 
)

pixSetInRect()

Parameters
[in]pixall depths, can be cmapped
[in]boxin which all pixels will be set
Returns
0 if OK, 1 on error
Notes:
     (1) Sets all data in rect to 1.  For 1 bpp, this is black;
         for grayscale or color, this is white.
     (2) Caution: for colormapped pix, this sets the pixel value to the
         maximum value supported by the colormap: 2^d - 1.  However, this
         color may not be defined, because the colormap may not be full.

Definition at line 1123 of file pix2.c.

◆ pixSetInRectArbitrary()

l_ok pixSetInRectArbitrary ( PIX pix,
BOX box,
l_uint32  val 
)

pixSetInRectArbitrary()

Parameters
[in]pixall depths; can be cmapped
[in]boxin which all pixels will be set to val
[in]valvalue to set all pixels
Returns
0 if OK; 1 on error
Notes:
     (1) For colormapped pix, be sure the value is the intended
         one in the colormap.
     (2) Caution: for colormapped pix, this sets each pixel in the
         rect to the color at the index equal to val.  Be sure that
         this index exists in the colormap and that it is the intended one!

Definition at line 1163 of file pix2.c.

References pixGetDimensions().

◆ pixSetMirroredBorder()

l_ok pixSetMirroredBorder ( PIX pixs,
l_int32  left,
l_int32  right,
l_int32  top,
l_int32  bot 
)

pixSetMirroredBorder()

Parameters
[in]pixsall depths; colormap ok
[in]left,right,top,botnumber of pixels to set
Returns
0 if OK, 1 on error
Notes:
     (1) This applies what is effectively mirror boundary conditions
         to a border region in the image.  It is in-place.
     (2) This is useful for setting pixels near the border to a
         value representative of the near pixels to the interior.
     (3) The general pixRasterop() is used for an in-place operation here
         because there is no overlap between the src and dest rectangles.

Definition at line 1672 of file pix2.c.

References PIX_SRC, pixGetDimensions(), and pixRasterop().

◆ pixSetOrClearBorder()

l_ok pixSetOrClearBorder ( PIX pixs,
l_int32  left,
l_int32  right,
l_int32  top,
l_int32  bot,
l_int32  op 
)

pixSetOrClearBorder()

Parameters
[in]pixsall depths
[in]left,right,top,botamount to set or clear
[in]opoperation PIX_SET or PIX_CLR
Returns
0 if OK; 1 on error
Notes:
     (1) The border region is defined to be the region in the
         image within a specific distance of each edge.  Here, we
         allow the pixels within a specified distance of each
         edge to be set independently.  This either sets or
         clears all pixels in the border region.
     (2) For binary images, use PIX_SET for black and PIX_CLR for white.
     (3) For grayscale or color images, use PIX_SET for white
         and PIX_CLR for black.

Definition at line 1474 of file pix2.c.

References PIX_CLR, PIX_SET, pixGetDimensions(), and pixRasterop().

◆ pixSetPadBits()

l_ok pixSetPadBits ( PIX pix,
l_int32  val 
)

pixSetPadBits()

Parameters
[in]pix1, 2, 4, 8, 16, 32 bpp
[in]val0 or 1
Returns
0 if OK; 1 on error
Notes:
     (1) The pad bits are the bits that expand each scanline to a
         multiple of 32 bits.  They are usually not used in
         image processing operations.  When boundary conditions
         are important, as in seedfill, they must be set properly.
     (2) This sets the value of the pad bits (if any) in the last
         32-bit word in each scanline.
     (3) For 32 bpp pix, there are no pad bits, so this is a no-op.
     (4) When writing formatted output, such as tiff, png or jpeg,
         the pad bits have no effect on the raster image that is
         generated by reading back from the file.  However, in some
         cases, the compressed file itself will depend on the pad
         bits.  This is seen, for example, in Windows with 2 and 4 bpp
         tiff-compressed images that have pad bits on each scanline.
         It is sometimes convenient to use a golden file with a
         byte-by-byte check to verify invariance.  Consequently,
         and because setting the pad bits is cheap, the pad bits are
         set to 0 before writing these compressed files.

Definition at line 1346 of file pix2.c.

References pixGetData(), and pixGetDimensions().

Referenced by pixCentroid(), pixGetRasterData(), and pixWriteToTiffStream().

◆ pixSetPadBitsBand()

l_ok pixSetPadBitsBand ( PIX pix,
l_int32  by,
l_int32  bh,
l_int32  val 
)

pixSetPadBitsBand()

Parameters
[in]pix1, 2, 4, 8, 16, 32 bpp
[in]bystarting y value of band
[in]bhheight of band
[in]val0 or 1
Returns
0 if OK; 1 on error
Notes:
     (1) The pad bits are the bits that expand each scanline to a
         multiple of 32 bits.  They are usually not used in
         image processing operations.  When boundary conditions
         are important, as in seedfill, they must be set properly.
     (2) This sets the value of the pad bits (if any) in the last
         32-bit word in each scanline, within the specified
         band of raster lines.
     (3) For 32 bpp pix, there are no pad bits, so this is a no-op.

Definition at line 1404 of file pix2.c.

References pixGetData(), and pixGetDimensions().

◆ pixSetPixel()

l_ok pixSetPixel ( PIX pix,
l_int32  x,
l_int32  y,
l_uint32  val 
)

pixSetPixel()

Parameters
[in]pix
[in]x,ypixel coords
[in]valvalue to be inserted
Returns
0 if OK; 1 or 2 on error
Notes:
     (1) Warning: the input value is not checked for overflow with respect
         the the depth of pix, and the sign bit (if any) is ignored.
         * For d == 1, val > 0 sets the bit on.
         * For d == 2, 4, 8 and 16, val is masked to the maximum allowable
           pixel value, and any (invalid) higher order bits are discarded.
     (2) See pixGetPixel() for information on performance.
     (3) If the point is outside the image, this returns an error (2),
         with 0 in pval.  To avoid spamming output, it fails silently.

Definition at line 263 of file pix2.c.

References pixGetData(), and pixGetDimensions().

Referenced by ccbaDisplayBorder(), ccbaDisplayImage1(), ccbaDisplayImage2(), ccbaDisplaySPBorder(), identifyWatershedBasin(), kernelDisplayInPix(), makeColorfillTestData(), pixDisplayPtaa(), pixGenerateFromPta(), pixMakeGamutRGB(), pixSetBorderRingVal(), selaAddCrossJunctions(), and selaAddTJunctions().

◆ pixSetRGBComponent()

l_ok pixSetRGBComponent ( PIX pixd,
PIX pixs,
l_int32  comp 
)

pixSetRGBComponent()

Parameters
[in]pixd32 bpp
[in]pixs8 bpp
[in]compone of the set: {COLOR_RED, COLOR_GREEN, COLOR_BLUE, L_ALPHA_CHANNEL}
Returns
0 if OK; 1 on error
Notes:
     (1) This places the 8 bpp pixel in pixs into the
         specified component (properly interleaved) in pixd,
     (2) The two images are registered to the UL corner; the sizes
         need not be the same, but a warning is issued if they differ.

Definition at line 2521 of file pix2.c.

◆ pixSetRGBPixel()

l_ok pixSetRGBPixel ( PIX pix,
l_int32  x,
l_int32  y,
l_int32  rval,
l_int32  gval,
l_int32  bval 
)

pixSetRGBPixel()

Parameters
[in]pix32 bpp rgb
[in]x,ypixel coords
[in]rvalred component
[in]gvalgreen component
[in]bvalblue component
Returns
0 if OK; 1 or 2 on error
Notes:
     (1) If the point is outside the image, this returns an error (2),
         and to avoid spamming output, it fails silently.

Definition at line 378 of file pix2.c.

References pixGetDimensions().

Referenced by displayHSVColorRange().

◆ pixSetupByteProcessing()

l_uint8** pixSetupByteProcessing ( PIX pix,
l_int32 *  pw,
l_int32 *  ph 
)

pixSetupByteProcessing()

Parameters
[in]pix8 bpp, no colormap
[out]pw[optional] width
[out]ph[optional] height
Returns
line ptr array, or NULL on error
Notes:
     (1) This is a simple helper for processing 8 bpp images with
         direct byte access.  It can swap byte order within each word.
     (2) After processing, you must call pixCleanupByteProcessing(),
         which frees the lineptr array and restores byte order.
     (3) Usage:
             l_uint8 **lineptrs = pixSetupByteProcessing(pix, &w, &h);
             for (i = 0; i < h; i++) {
                 l_uint8 *line = lineptrs[i];
                 for (j = 0; j < w; j++) {
                     val = line[j];
                     ...
                 }
             }
             pixCleanupByteProcessing(pix, lineptrs);

Definition at line 3441 of file pix2.c.

◆ pixShiftAndTransferAlpha()

l_ok pixShiftAndTransferAlpha ( PIX pixd,
PIX pixs,
l_float32  shiftx,
l_float32  shifty 
)

pixShiftAndTransferAlpha()

Parameters
[in]pixd32 bpp
[in]pixs32 bpp
[in]shiftx,shifty
Returns
0 if OK; 1 on error

Definition at line 2291 of file pix2.c.

◆ setLineDataVal()

l_ok setLineDataVal ( l_uint32 *  line,
l_int32  j,
l_int32  d,
l_uint32  val 
)

setLineDataVal()

Parameters
[in]lineptr to first word in raster line data
[in]jindex of pixels into the raster line
[in]ddepth of the pixel
[in]valpixel value to be set
Returns
0 if OK, 1 on error
Notes:
     (1) This is a convenience function to set a pixel value in a
         raster line where the depth of the image can have different
         values (1, 2, 4, 8, 16 or 32).

Definition at line 2923 of file pix2.c.

References SET_DATA_BIT_VAL, SET_DATA_BYTE, SET_DATA_DIBIT, SET_DATA_QBIT, and SET_DATA_TWO_BYTES.

◆ setPixelLow()

void setPixelLow ( l_uint32 *  line,
l_int32  x,
l_int32  depth,
l_uint32  val 
)

setPixelLow()

Parameters
[in]lineptr to beginning of line,
[in]xpixel location in line
[in]depthbpp
[in]valto be inserted
Returns
void
Notes:
     (1) Caution: input variables are not checked!

Definition at line 665 of file pix2.c.

References CLEAR_DATA_BIT, lept_stderr(), SET_DATA_BIT, SET_DATA_BYTE, SET_DATA_DIBIT, SET_DATA_QBIT, and SET_DATA_TWO_BYTES.

Variable Documentation

◆ rmask32

const l_uint32 rmask32[]
static
Initial value:
= {0x0,
0x00000001, 0x00000003, 0x00000007, 0x0000000f,
0x0000001f, 0x0000003f, 0x0000007f, 0x000000ff,
0x000001ff, 0x000003ff, 0x000007ff, 0x00000fff,
0x00001fff, 0x00003fff, 0x00007fff, 0x0000ffff,
0x0001ffff, 0x0003ffff, 0x0007ffff, 0x000fffff,
0x001fffff, 0x003fffff, 0x007fffff, 0x00ffffff,
0x01ffffff, 0x03ffffff, 0x07ffffff, 0x0fffffff,
0x1fffffff, 0x3fffffff, 0x7fffffff, 0xffffffff}

Definition at line 144 of file pix2.c.