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

Go to the source code of this file.

Macros

#define DEBUG_CONVERT_TO_COLORMAP   0
 
#define DEBUG_UNROLLING   0
 

Functions

PIXpixThreshold8 (PIX *pixs, l_int32 d, l_int32 nlevels, l_int32 cmapflag)
 
PIXpixRemoveColormapGeneral (PIX *pixs, l_int32 type, l_int32 ifnocmap)
 
PIXpixRemoveColormap (PIX *pixs, l_int32 type)
 
l_ok pixAddGrayColormap8 (PIX *pixs)
 
PIXpixAddMinimalGrayColormap8 (PIX *pixs)
 
PIXpixConvertRGBToLuminance (PIX *pixs)
 
PIXpixConvertRGBToGrayGeneral (PIX *pixs, l_int32 type, l_float32 rwt, l_float32 gwt, l_float32 bwt)
 
PIXpixConvertRGBToGray (PIX *pixs, l_float32 rwt, l_float32 gwt, l_float32 bwt)
 
PIXpixConvertRGBToGrayFast (PIX *pixs)
 
PIXpixConvertRGBToGrayMinMax (PIX *pixs, l_int32 type)
 
PIXpixConvertRGBToGraySatBoost (PIX *pixs, l_int32 refval)
 
PIXpixConvertRGBToGrayArb (PIX *pixs, l_float32 rc, l_float32 gc, l_float32 bc)
 
PIXpixConvertRGBToBinaryArb (PIX *pixs, l_float32 rc, l_float32 gc, l_float32 bc, l_int32 thresh, l_int32 relation)
 
PIXpixConvertGrayToColormap (PIX *pixs)
 
PIXpixConvertGrayToColormap8 (PIX *pixs, l_int32 mindepth)
 
PIXpixColorizeGray (PIX *pixs, l_uint32 color, l_int32 cmapflag)
 
PIXpixConvertRGBToColormap (PIX *pixs, l_int32 ditherflag)
 
PIXpixConvertCmapTo1 (PIX *pixs)
 
l_ok pixQuantizeIfFewColors (PIX *pixs, l_int32 maxcolors, l_int32 mingraycolors, l_int32 octlevel, PIX **ppixd)
 
PIXpixConvert16To8 (PIX *pixs, l_int32 type)
 
PIXpixConvertGrayToFalseColor (PIX *pixs, l_float32 gamma)
 
PIXpixUnpackBinary (PIX *pixs, l_int32 depth, l_int32 invert)
 
PIXpixConvert1To16 (PIX *pixd, PIX *pixs, l_uint16 val0, l_uint16 val1)
 
PIXpixConvert1To32 (PIX *pixd, PIX *pixs, l_uint32 val0, l_uint32 val1)
 
PIXpixConvert1To2Cmap (PIX *pixs)
 
PIXpixConvert1To2 (PIX *pixd, PIX *pixs, l_int32 val0, l_int32 val1)
 
PIXpixConvert1To4Cmap (PIX *pixs)
 
PIXpixConvert1To4 (PIX *pixd, PIX *pixs, l_int32 val0, l_int32 val1)
 
PIXpixConvert1To8Cmap (PIX *pixs)
 
PIXpixConvert1To8 (PIX *pixd, PIX *pixs, l_uint8 val0, l_uint8 val1)
 
PIXpixConvert2To8 (PIX *pixs, l_uint8 val0, l_uint8 val1, l_uint8 val2, l_uint8 val3, l_int32 cmapflag)
 
PIXpixConvert4To8 (PIX *pixs, l_int32 cmapflag)
 
PIXpixConvert8To16 (PIX *pixs, l_int32 leftshift)
 
PIXpixConvertTo2 (PIX *pixs)
 
PIXpixConvert8To2 (PIX *pix)
 
PIXpixConvertTo4 (PIX *pixs)
 
PIXpixConvert8To4 (PIX *pix)
 
PIXpixConvertTo1Adaptive (PIX *pixs)
 
PIXpixConvertTo1 (PIX *pixs, l_int32 threshold)
 
PIXpixConvertTo1BySampling (PIX *pixs, l_int32 factor, l_int32 threshold)
 
PIXpixConvertTo8 (PIX *pixs, l_int32 cmapflag)
 
PIXpixConvertTo8BySampling (PIX *pixs, l_int32 factor, l_int32 cmapflag)
 
PIXpixConvertTo8Colormap (PIX *pixs, l_int32 dither)
 
PIXpixConvertTo16 (PIX *pixs)
 
PIXpixConvertTo32 (PIX *pixs)
 
PIXpixConvertTo32BySampling (PIX *pixs, l_int32 factor)
 
PIXpixConvert8To32 (PIX *pixs)
 
PIXpixConvertTo8Or32 (PIX *pixs, l_int32 copyflag, l_int32 warnflag)
 
PIXpixConvert24To32 (PIX *pixs)
 
PIXpixConvert32To24 (PIX *pixs)
 
PIXpixConvert32To16 (PIX *pixs, l_int32 type)
 
PIXpixConvert32To8 (PIX *pixs, l_int32 type16, l_int32 type8)
 
PIXpixRemoveAlpha (PIX *pixs)
 
PIXpixAddAlphaTo1bpp (PIX *pixd, PIX *pixs)
 
PIXpixConvertLossless (PIX *pixs, l_int32 d)
 
PIXpixConvertForPSWrap (PIX *pixs)
 
PIXpixConvertToSubpixelRGB (PIX *pixs, l_float32 scalex, l_float32 scaley, l_int32 order)
 
PIXpixConvertGrayToSubpixelRGB (PIX *pixs, l_float32 scalex, l_float32 scaley, l_int32 order)
 
PIXpixConvertColorToSubpixelRGB (PIX *pixs, l_float32 scalex, l_float32 scaley, l_int32 order)
 
void l_setNeutralBoostVal (l_int32 val)
 

Variables

static l_int32 var_NEUTRAL_BOOST_VAL = 180
 

Detailed Description


     These functions convert between images of different types
     without scaling.

     Conversion from 8 bpp grayscale to 1, 2, 4 and 8 bpp
          PIX        *pixThreshold8()

     Conversion from colormap to full color or grayscale
          PIX        *pixRemoveColormapGeneral()
          PIX        *pixRemoveColormap()

     Add colormap losslessly (8 to 8)
          l_int32     pixAddGrayColormap8()
          PIX        *pixAddMinimalGrayColormap8()

     Conversion from RGB color to 8 bit gray
          PIX        *pixConvertRGBToLuminance()
          PIX        *pixConvertRGBToGrayGeneral()
          PIX        *pixConvertRGBToGray()
          PIX        *pixConvertRGBToGrayFast()
          PIX        *pixConvertRGBToGrayMinMax()
          PIX        *pixConvertRGBToGraySatBoost()
          PIX        *pixConvertRGBToGrayArb()
          PIX        *pixConvertRGBToBinaryArb()

     Conversion from grayscale to colormap
          PIX        *pixConvertGrayToColormap()  -- 2, 4, 8 bpp
          PIX        *pixConvertGrayToColormap8()  -- 8 bpp only

     Colorizing conversion from grayscale to color
          PIX        *pixColorizeGray()  -- 8 bpp or cmapped

     Conversion from RGB color to colormap
          PIX        *pixConvertRGBToColormap()

     Conversion from colormap to 1 bpp
          PIX        *pixConvertCmapTo1()

     Quantization for relatively small number of colors in source
          l_int32     pixQuantizeIfFewColors()

     Conversion from 16 bpp to 8 bpp
          PIX        *pixConvert16To8()

     Conversion from grayscale to false color
          PIX        *pixConvertGrayToFalseColor()

     Unpacking conversion from 1 bpp to 2, 4, 8, 16 and 32 bpp
          PIX        *pixUnpackBinary()
          PIX        *pixConvert1To16()
          PIX        *pixConvert1To32()

     Unpacking conversion from 1 bpp to 2 bpp
          PIX        *pixConvert1To2Cmap()
          PIX        *pixConvert1To2()

     Unpacking conversion from 1 bpp to 4 bpp
          PIX        *pixConvert1To4Cmap()
          PIX        *pixConvert1To4()

     Unpacking conversion from 1, 2 and 4 bpp to 8 bpp
          PIX        *pixConvert1To8()
          PIX        *pixConvert2To8()
          PIX        *pixConvert4To8()

     Unpacking conversion from 8 bpp to 16 bpp
          PIX        *pixConvert8To16()

     Top-level conversion to 1 bpp
          PIX        *pixConvertTo1Adaptive()
          PIX        *pixConvertTo1()
          PIX        *pixConvertTo1BySampling()

     Top-level conversion to 2 bpp
          PIX        *pixConvertTo2()
          PIX        *pixConvert8To2()

     Top-level conversion to 4 bpp
          PIX        *pixConvertTo4()
          PIX        *pixConvert8To4()

     Top-level conversion to 8 bpp
          PIX        *pixConvertTo8()
          PIX        *pixConvertTo8BySampling()
          PIX        *pixConvertTo8Colormap()

     Top-level conversion to 16 bpp
          PIX        *pixConvertTo16()

     Top-level conversion to 32 bpp (RGB)
          PIX        *pixConvertTo32()   ***
          PIX        *pixConvertTo32BySampling()   ***
          PIX        *pixConvert8To32()  ***

     Top-level conversion to 8 or 32 bpp, without colormap
          PIX        *pixConvertTo8Or32

     Conversion between 24 bpp and 32 bpp rgb
          PIX        *pixConvert24To32()
          PIX        *pixConvert32To24()

     Conversion between 32 bpp (1 spp) and 16 or 8 bpp
          PIX        *pixConvert32To16()
          PIX        *pixConvert32To8()

     Removal of alpha component by blending with white background
          PIX        *pixRemoveAlpha()

     Addition of alpha component to 1 bpp
          PIX        *pixAddAlphaTo1bpp()

     Lossless depth conversion (unpacking)
          PIX        *pixConvertLossless()

     Conversion for printing in PostScript
          PIX        *pixConvertForPSWrap()

     Scaling conversion to subpixel RGB
          PIX        *pixConvertToSubpixelRGB()
          PIX        *pixConvertGrayToSubpixelRGB()
          PIX        *pixConvertColorToSubpixelRGB()

     Setting neutral point for min/max boost conversion to gray
         void         l_setNeutralBoostVal()

Definition in file pixconv.c.

Function Documentation

◆ l_setNeutralBoostVal()

void l_setNeutralBoostVal ( l_int32  val)

l_setNeutralBoostVal()

Parameters
[in]valbetween 1 and 255; typical value is 180
Returns
void
Notes:
     (1) This raises or lowers the selected min or max RGB component value,
         depending on if that component is above or below this value.

Definition at line 4172 of file pixconv.c.

◆ pixAddAlphaTo1bpp()

PIX* pixAddAlphaTo1bpp ( PIX pixd,
PIX pixs 
)

pixAddAlphaTo1bpp()

Parameters
[in]pixd[optional] 1 bpp, can be null or equal to pixs
[in]pixs1 bpp
Returns
pixd 1 bpp with colormap and non-opaque alpha, or NULL on error
Notes:
     (1) We don't use 1 bpp colormapped images with alpha in leptonica,
         but we support generating them (here), writing to png, and reading
         the png.  On reading, they are converted to 32 bpp RGBA.
     (2) The background (0) pixels in pixs become fully transparent, and the
         foreground (1) pixels are fully opaque.  Thus, pixd is a 1 bpp
         representation of a stencil, that can be used to paint over pixels
         of a backing image that are masked by the foreground in pixs.

Definition at line 3694 of file pixconv.c.

◆ pixAddGrayColormap8()

l_ok pixAddGrayColormap8 ( PIX pixs)

pixAddGrayColormap8()

Parameters
[in]pixs8 bpp
Returns
0 if OK, 1 on error
Notes:
     (1) If pixs has a colormap, this is a no-op.

Definition at line 616 of file pixconv.c.

◆ pixAddMinimalGrayColormap8()

PIX* pixAddMinimalGrayColormap8 ( PIX pixs)

pixAddMinimalGrayColormap8()

Parameters
[in]pixs8 bpp
Returns
0 if OK, 1 on error
Notes:
     (1) This generates a colormapped version of the input image
         that has the same number of colormap entries as the
         input image has unique gray levels.

Definition at line 645 of file pixconv.c.

◆ pixColorizeGray()

PIX* pixColorizeGray ( PIX pixs,
l_uint32  color,
l_int32  cmapflag 
)

pixColorizeGray()

Parameters
[in]pixs8 bpp gray; 2, 4 or 8 bpp colormapped
[in]color32 bit rgba pixel
[in]cmapflag1 for result to have colormap; 0 for RGB
Returns
pixd 8 bpp colormapped or 32 bpp rgb, or NULL on error
Notes:
     (1) This applies the specific color to the grayscale image.
     (2) If pixs already has a colormap, it is removed to gray
         before colorizing.

Definition at line 1371 of file pixconv.c.

Referenced by pixSimpleCaptcha().

◆ pixConvert16To8()

PIX* pixConvert16To8 ( PIX pixs,
l_int32  type 
)

pixConvert16To8()

Parameters
[in]pixs16 bpp
[in]typeL_LS_BYTE, L_MS_BYTE, L_AUTO_BYTE, L_CLIP_TO_FF
Returns
pixd 8 bpp, or NULL on error
Notes:
     (1) With L_AUTO_BYTE, if the max pixel value is greater than 255,
         use the MSB; otherwise, use the LSB.
     (2) With L_CLIP_TO_FF, use min(pixel-value, 0xff) for each
         16-bit src pixel.

Definition at line 1726 of file pixconv.c.

◆ pixConvert1To16()

PIX* pixConvert1To16 ( PIX pixd,
PIX pixs,
l_uint16  val0,
l_uint16  val1 
)

pixConvert1To16()

Parameters
[in]pixd[optional] 16 bpp, can be null
[in]pixs1 bpp
[in]val016 bit value to be used for 0s in pixs
[in]val116 bit value to be used for 1s in pixs
Returns
pixd 16 bpp
Notes:
     (1) If pixd is null, a new pix is made.
     (2) If pixd is not null, it must be of equal width and height
         as pixs.  It is always returned.

Definition at line 1936 of file pixconv.c.

◆ pixConvert1To2()

PIX* pixConvert1To2 ( PIX pixd,
PIX pixs,
l_int32  val0,
l_int32  val1 
)

pixConvert1To2()

Parameters
[in]pixd[optional] 2 bpp, can be null
[in]pixs1 bpp
[in]val02 bit value to be used for 0s in pixs
[in]val12 bit value to be used for 1s in pixs
Returns
pixd 2 bpp
Notes:
     (1) If pixd is null, a new pix is made.
     (2) If pixd is not null, it must be of equal width and height
         as pixs.  It is always returned.
     (3) A simple unpacking might use val0 = 0 and val1 = 3.
     (4) If you want a colormapped pixd, use pixConvert1To2Cmap().

Definition at line 2110 of file pixconv.c.

◆ pixConvert1To2Cmap()

PIX* pixConvert1To2Cmap ( PIX pixs)

pixConvert1To2Cmap()

Parameters
[in]pixs1 bpp
Returns
pixd 2 bpp, cmapped
Notes:
     (1) Input 0 is mapped to (255, 255, 255); 1 is mapped to (0, 0, 0)

Definition at line 2069 of file pixconv.c.

◆ pixConvert1To32()

PIX* pixConvert1To32 ( PIX pixd,
PIX pixs,
l_uint32  val0,
l_uint32  val1 
)

pixConvert1To32()

Parameters
[in]pixd[optional] 32 bpp, can be null
[in]pixs1 bpp
[in]val032 bit value to be used for 0s in pixs
[in]val132 bit value to be used for 1s in pixs
Returns
pixd 32 bpp
Notes:
     (1) If pixd is null, a new pix is made.
     (2) If pixd is not null, it must be of equal width and height
         as pixs.  It is always returned.

Definition at line 2008 of file pixconv.c.

◆ pixConvert1To4()

PIX* pixConvert1To4 ( PIX pixd,
PIX pixs,
l_int32  val0,
l_int32  val1 
)

pixConvert1To4()

Parameters
[in]pixd[optional] 4 bpp, can be null
[in]pixs1 bpp
[in]val04 bit value to be used for 0s in pixs
[in]val14 bit value to be used for 1s in pixs
Returns
pixd 4 bpp
Notes:
     (1) If pixd is null, a new pix is made.
     (2) If pixd is not null, it must be of equal width and height
         as pixs.  It is always returned.
     (3) A simple unpacking might use val0 = 0 and val1 = 15, or v.v.
     (4) If you want a colormapped pixd, use pixConvert1To4Cmap().

Definition at line 2228 of file pixconv.c.

◆ pixConvert1To4Cmap()

PIX* pixConvert1To4Cmap ( PIX pixs)

pixConvert1To4Cmap()

Parameters
[in]pixs1 bpp
Returns
pixd 4 bpp, cmapped
Notes:
     (1) Input 0 is mapped to (255, 255, 255); 1 is mapped to (0, 0, 0)

Definition at line 2187 of file pixconv.c.

◆ pixConvert1To8()

PIX* pixConvert1To8 ( PIX pixd,
PIX pixs,
l_uint8  val0,
l_uint8  val1 
)

pixConvert1To8()

Parameters
[in]pixd[optional] 8 bpp, can be null
[in]pixs1 bpp
[in]val08 bit value to be used for 0s in pixs
[in]val18 bit value to be used for 1s in pixs
Returns
pixd 8 bpp
Notes:
     (1) If pixd is null, a new pix is made.
     (2) If pixd is not null, it must be of equal width and height
         as pixs.  It is always returned.
     (3) A simple unpacking might use val0 = 0 and val1 = 255, or v.v.
     (4) To have a colormap associated with the 8 bpp pixd,
         use pixConvert1To8Cmap().

Definition at line 2345 of file pixconv.c.

◆ pixConvert1To8Cmap()

PIX* pixConvert1To8Cmap ( PIX pixs)

pixConvert1To8Cmap()

Parameters
[in]pixs1 bpp
Returns
pixd 8 bpp, cmapped
Notes:
     (1) Input 0 is mapped to (255, 255, 255); 1 is mapped to (0, 0, 0)

Definition at line 2304 of file pixconv.c.

◆ pixConvert24To32()

PIX* pixConvert24To32 ( PIX pixs)

pixConvert24To32()

Parameters
[in]pixs24 bpp rgb
Returns
pixd 32 bpp rgb, or NULL on error
Notes:
     (1) 24 bpp rgb pix are not supported in leptonica, except for a small
         number of formatted write operations.  The data is a byte array,
         with pixels in order r,g,b, and padded to 32 bit boundaries
         in each line.
     (2) Because 24 bpp rgb pix are conveniently generated by programs
         such as xpdf (which has SplashBitmaps that store the raster
         data in consecutive 24-bit rgb pixels), it is useful to provide
         24 bpp pix that simply incorporate that data.  The only things
         we can do with these are:
           (a) write them to file in png, jpeg, tiff and pnm
           (b) interconvert between 24 and 32 bpp in memory (for testing).

Definition at line 3461 of file pixconv.c.

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

◆ pixConvert2To8()

PIX* pixConvert2To8 ( PIX pixs,
l_uint8  val0,
l_uint8  val1,
l_uint8  val2,
l_uint8  val3,
l_int32  cmapflag 
)

pixConvert2To8()

Parameters
[in]pixs2 bpp
[in]val08 bit value to be used for 00 in pixs
[in]val18 bit value to be used for 01 in pixs
[in]val28 bit value to be used for 10 in pixs
[in]val38 bit value to be used for 11 in pixs
[in]cmapflagTRUE if pixd is to have a colormap; FALSE otherwise
Returns
pixd 8 bpp, or NULL on error
Notes:
     ~ A simple unpacking might use val0 = 0,
       val1 = 85 (0x55), val2 = 170 (0xaa), val3 = 255.
     ~ If cmapflag is TRUE:
         ~ The 8 bpp image is made with a colormap.
         ~ If pixs has a colormap, the input values are ignored and
           the 8 bpp image is made using the colormap
         ~ If pixs does not have a colormap, the input values are
           used to build the colormap.
     ~ If cmapflag is FALSE:
         ~ The 8 bpp image is made without a colormap.
         ~ If pixs has a colormap, the input values are ignored,
           the colormap is removed, and the values stored in the 8 bpp
           image are from the colormap.
         ~ If pixs does not have a colormap, the input values are
           used to populate the 8 bpp image.

Definition at line 2434 of file pixconv.c.

◆ pixConvert32To16()

PIX* pixConvert32To16 ( PIX pixs,
l_int32  type 
)

pixConvert32To16()

Parameters
[in]pixs32 bpp, single component
[in]typeL_LS_TWO_BYTES, L_MS_TWO_BYTES, L_CLIP_TO_FFFF
Returns
pixd 16 bpp , or NULL on error
Notes:
     (1) The data in pixs is typically used for labelling.
         It is an array of l_uint32 values, not rgb or rgba.

Definition at line 3560 of file pixconv.c.

◆ pixConvert32To24()

PIX* pixConvert32To24 ( PIX pixs)

pixConvert32To24()

Parameters
[in]pixs32 bpp rgb
Returns
pixd 24 bpp rgb, or NULL on error
Notes:
     (1) See pixconvert24To32().

Definition at line 3509 of file pixconv.c.

References pixGetData(), and pixGetDimensions().

◆ pixConvert32To8()

PIX* pixConvert32To8 ( PIX pixs,
l_int32  type16,
l_int32  type8 
)

pixConvert32To8()

Parameters
[in]pixs32 bpp, single component
[in]type16L_LS_TWO_BYTES, L_MS_TWO_BYTES, L_CLIP_TO_FFFF
[in]type8L_LS_BYTE, L_MS_BYTE, L_CLIP_TO_FF
Returns
pixd 8 bpp, or NULL on error

Definition at line 3622 of file pixconv.c.

◆ pixConvert4To8()

PIX* pixConvert4To8 ( PIX pixs,
l_int32  cmapflag 
)

pixConvert4To8()

Parameters
[in]pixs4 bpp
[in]cmapflagTRUE if pixd is to have a colormap; FALSE otherwise
Returns
pixd 8 bpp, or NULL on error
Notes:
     ~ If cmapflag is TRUE:
         ~ pixd is made with a colormap.
         ~ If pixs has a colormap, it is copied and the colormap
           index values are placed in pixd.
         ~ If pixs does not have a colormap, a colormap with linear
           trc is built and the pixel values in pixs are placed in
           pixd as colormap index values.
     ~ If cmapflag is FALSE:
         ~ pixd is made without a colormap.
         ~ If pixs has a colormap, it is removed and the values stored
           in pixd are from the colormap (converted to gray).
         ~ If pixs does not have a colormap, the pixel values in pixs
           are used, with shift replication, to populate pixd.

Definition at line 2544 of file pixconv.c.

◆ pixConvert8To16()

PIX* pixConvert8To16 ( PIX pixs,
l_int32  leftshift 
)

pixConvert8To16()

Parameters
[in]pixs8 bpp; colormap removed to gray
[in]leftshiftnumber of bits: 0 is no shift; 8 replicates in MSB and LSB of dest
Returns
pixd 16 bpp, or NULL on error
Notes:
     (1) For left shift of 8, the 8 bit value is replicated in both
         the MSB and the LSB of the pixels in pixd.  That way, we get
         proportional mapping, with a correct map from 8 bpp white
         (0xff) to 16 bpp white (0xffff).

Definition at line 2627 of file pixconv.c.

References pixGetDimensions().

◆ pixConvert8To2()

PIX* pixConvert8To2 ( PIX pix)

pixConvert8To2()

Parameters
[in]pix8 bpp; colormap OK
Returns
pixd 2 bpp, or NULL on error
Notes:
     (1) Any existing colormap is removed to gray.

Definition at line 2741 of file pixconv.c.

◆ pixConvert8To32()

PIX* pixConvert8To32 ( PIX pixs)

pixConvert8To32()

Parameters
[in]pixs8 bpp
Returns
32 bpp rgb pix, or NULL on error
Notes:
     (1) If there is no colormap, replicates the gray value
         into the 3 MSB of the dest pixel.

Definition at line 3332 of file pixconv.c.

◆ pixConvert8To4()

PIX* pixConvert8To4 ( PIX pix)

pixConvert8To4()

Parameters
[in]pix8 bpp; colormap OK
Returns
pixd 4 bpp, or NULL on error
Notes:
     (1) Any existing colormap is removed to gray.

Definition at line 2845 of file pixconv.c.

◆ pixConvertCmapTo1()

PIX* pixConvertCmapTo1 ( PIX pixs)

pixConvertCmapTo1()

Parameters
[in]pixscmapped
Returns
pixd 1 bpp, or NULL on error
Notes:
     (1) This is an extreme color quantizer.  It decides which
         colors map to FG (black) and which to BG (white).
     (2) This uses two heuristics to make the decision:
         (a) colors similar to each other are likely to be in the same class
         (b) there is usually much less FG than BG.

Definition at line 1518 of file pixconv.c.

◆ pixConvertColorToSubpixelRGB()

PIX* pixConvertColorToSubpixelRGB ( PIX pixs,
l_float32  scalex,
l_float32  scaley,
l_int32  order 
)

pixConvertColorToSubpixelRGB()

Parameters
[in]pixs32 bpp or colormapped
[in]scalex,scaley
[in]orderof subpixel rgb color components in composition of pixd: L_SUBPIXEL_ORDER_RGB, L_SUBPIXEL_ORDER_BGR, L_SUBPIXEL_ORDER_VRGB, L_SUBPIXEL_ORDER_VBGR
Returns
pixd 32 bpp, or NULL on error
Notes:
     (1) If pixs has a colormap, it is removed to 32 bpp rgb.
         If the colormap has no color, pixConvertGrayToSubpixelRGB()
         should be called instead, because it will give the same result
         more efficiently.  The function pixConvertToSubpixelRGB()
         will do the best thing for all cases.
     (2) For horizontal subpixel splitting, the input rgb image
         is rescaled by scaley vertically and by 3.0 times
         scalex horizontally.  Then for each horizontal triplet
         of pixels, the r component of the final pixel is selected
         from the r component of the appropriate pixel in the triplet,
         and likewise for g and b.  Vertical subpixel splitting is
         handled similarly.

Definition at line 4071 of file pixconv.c.

◆ pixConvertForPSWrap()

PIX* pixConvertForPSWrap ( PIX pixs)

pixConvertForPSWrap()

Parameters
[in]pixs1, 2, 4, 8, 16, 32 bpp
Returns
pixd 1, 8, or 32 bpp, or NULL on error
Notes:
     (1) For wrapping in PostScript, we convert pixs to
         1 bpp, 8 bpp (gray) and 32 bpp (RGB color).
     (2) Colormaps are removed.  For pixs with colormaps, the
         images are converted to either 8 bpp gray or 32 bpp
         RGB, depending on whether the colormap has color content.
     (3) Images without colormaps, that are not 1 bpp or 32 bpp,
         are converted to 8 bpp gray.

Definition at line 3823 of file pixconv.c.

Referenced by pixWriteStreamPS(), and pixWriteStringPS().

◆ pixConvertGrayToColormap()

PIX* pixConvertGrayToColormap ( PIX pixs)

pixConvertGrayToColormap()

Parameters
[in]pixs2, 4 or 8 bpp grayscale
Returns
pixd 2, 4 or 8 bpp with colormap, or NULL on error
Notes:
     (1) This is a simple interface for adding a colormap to a
         2, 4 or 8 bpp grayscale image without causing any
         quantization.  There is some similarity to operations
         in grayquant.c, such as pixThresholdOn8bpp(), where
         the emphasis is on quantization with an arbitrary number
         of levels, and a colormap is an option.
     (2) Returns a copy if pixs already has a colormap.
     (3) For 8 bpp src, this is a lossless transformation.
     (4) For 2 and 4 bpp src, this generates a colormap that
         assumes full coverage of the gray space, with equally spaced
         levels: 4 levels for d = 2 and 16 levels for d = 4.
     (5) In all cases, the depth of the dest is the same as the src.

Definition at line 1223 of file pixconv.c.

◆ pixConvertGrayToColormap8()

PIX* pixConvertGrayToColormap8 ( PIX pixs,
l_int32  mindepth 
)

pixConvertGrayToColormap8()

Parameters
[in]pixs8 bpp grayscale
[in]mindepthof pixd; valid values are 2, 4 and 8
Returns
pixd 2, 4 or 8 bpp with colormap, or NULL on error
Notes:
     (1) Returns a copy if pixs already has a colormap.
     (2) This is a lossless transformation; there is no quantization.
         We compute the number of different gray values in pixs,
         and construct a colormap that has exactly these values.
     (3) 'mindepth' is the minimum depth of pixd.  If mindepth == 8,
         pixd will always be 8 bpp.  Let the number of different
         gray values in pixs be ngray.  If mindepth == 4, we attempt
         to save pixd as a 4 bpp image, but if ngray > 16,
         pixd must be 8 bpp.  Likewise, if mindepth == 2,
         the depth of pixd will be 2 if ngray <= 4 and 4 if ngray > 4
         but <= 16.

Definition at line 1276 of file pixconv.c.

◆ pixConvertGrayToFalseColor()

PIX* pixConvertGrayToFalseColor ( PIX pixs,
l_float32  gamma 
)

pixConvertGrayToFalseColor()

Parameters
[in]pixs8 or 16 bpp grayscale
[in]gamma(factor) 0.0 or 1.0 for default; > 1.0 for brighter; 2.0 is quite nice
Returns
pixd 8 bpp with colormap, or NULL on error
Notes:
     (1) For 8 bpp input, this simply adds a colormap to the input image.
     (2) For 16 bpp input, it first converts to 8 bpp, using the MSB,
         and then adds the colormap.
     (3) The colormap is modeled after the Matlab "jet" configuration.

Definition at line 1820 of file pixconv.c.

◆ pixConvertGrayToSubpixelRGB()

PIX* pixConvertGrayToSubpixelRGB ( PIX pixs,
l_float32  scalex,
l_float32  scaley,
l_int32  order 
)

pixConvertGrayToSubpixelRGB()

Parameters
[in]pixs8 bpp or colormapped
[in]scalex,scaley
[in]orderof subpixel rgb color components in composition of pixd: L_SUBPIXEL_ORDER_RGB, L_SUBPIXEL_ORDER_BGR, L_SUBPIXEL_ORDER_VRGB, L_SUBPIXEL_ORDER_VBGR
Returns
pixd 32 bpp, or NULL on error
Notes:
     (1) If pixs has a colormap, it is removed to 8 bpp.
     (2) For horizontal subpixel splitting, the input gray image
         is rescaled by scaley vertically and by 3.0 times
         scalex horizontally.  Then each horizontal triplet
         of pixels is mapped back to a single rgb pixel, with the
         r, g and b values being assigned from the triplet of gray values.
         Similar operations are used for vertical subpixel splitting.
     (3) This is a form of subpixel rendering that tends to give the
         resulting text a sharper and somewhat chromatic display.
         For horizontal subpixel splitting, the observable difference
         between order=L_SUBPIXEL_ORDER_RGB and
         order=L_SUBPIXEL_ORDER_BGR is reduced by optical diffusers
         in the display that make the pixel color appear to emerge
         from the entire pixel.

Definition at line 3968 of file pixconv.c.

◆ pixConvertLossless()

PIX* pixConvertLossless ( PIX pixs,
l_int32  d 
)

pixConvertLossless()

Parameters
[in]pixs1, 2, 4, 8 bpp, not cmapped
[in]ddestination depth: 2, 4 or 8
Returns
pixd 2, 4 or 8 bpp, or NULL on error
Notes:
     (1) This is a lossless unpacking (depth-increasing)
         conversion.  If ds is the depth of pixs, then
          ~ if d < ds, returns NULL
          ~ if d == ds, returns a copy
          ~ if d > ds, does the unpacking conversion
     (2) If pixs has a colormap, this is an error.

Definition at line 3734 of file pixconv.c.

◆ pixConvertRGBToBinaryArb()

PIX* pixConvertRGBToBinaryArb ( PIX pixs,
l_float32  rc,
l_float32  gc,
l_float32  bc,
l_int32  thresh,
l_int32  relation 
)

pixConvertRGBToBinaryArb()

Parameters
[in]pixs32 bpp RGB
[in]rc,gc,bcarithmetic factors; can be negative
[in]threshbinarization threshold
[in]relationL_SELECT_IF_LT, L_SELECT_IF_GT L_SELECT_IF_LTE, L_SELECT_IF_GTE
Returns
1 bpp pix, or NULL on error
Notes:
     (1) This makes a 1 bpp mask from an RGB image, using an arbitrary
         linear combination of the rgb color components, along with
         a threshold and a selection choice of the gray value relative
         to thresh.

Definition at line 1168 of file pixconv.c.

◆ pixConvertRGBToColormap()

PIX* pixConvertRGBToColormap ( PIX pixs,
l_int32  ditherflag 
)

pixConvertRGBToColormap()

Parameters
[in]pixs32 bpp rgb
[in]ditherflag1 to dither, 0 otherwise
Returns
pixd 2, 4 or 8 bpp with colormap, or NULL on error
Notes:
     (1) This function has two relatively simple modes of color
         quantization:
           (a) If the image is made orthographically and has not more
               than 256 'colors' at the level 4 octcube leaves,
               it is quantized nearly exactly.  The ditherflag
               is ignored.
           (b) Most natural images have more than 256 different colors;
               in that case we use adaptive octree quantization,
               with dithering if requested.
     (2) If there are not more than 256 occupied level 4 octcubes,
         the color in the colormap that represents all pixels in
         one of those octcubes is given by the first pixel that
         falls into that octcube.
     (3) Dithering gives better visual results on images where
         there is a color wash (a slow variation of color), but it
         is about twice as slow and results in significantly larger
         files when losslessly compressed (e.g., into png).

Definition at line 1456 of file pixconv.c.

◆ pixConvertRGBToGray()

PIX* pixConvertRGBToGray ( PIX pixs,
l_float32  rwt,
l_float32  gwt,
l_float32  bwt 
)

pixConvertRGBToGray()

Parameters
[in]pixs32 bpp RGB
[in]rwt,gwt,bwtnon-negative; these should add to 1.0, or use 0.0 for default
Returns
8 bpp pix, or NULL on error
Notes:
     (1) Use a weighted average of the RGB values.

Definition at line 815 of file pixconv.c.

Referenced by pixConvertRGBToLuminance().

◆ pixConvertRGBToGrayArb()

PIX* pixConvertRGBToGrayArb ( PIX pixs,
l_float32  rc,
l_float32  gc,
l_float32  bc 
)

pixConvertRGBToGrayArb()

Parameters
[in]pixs32 bpp RGB
[in]rc,gc,bcarithmetic factors; can be negative
Returns
8 bpp pix, or NULL on error
Notes:
     (1) This converts to gray using an arbitrary linear combination
         of the rgb color components.  It differs from pixConvertToGray(),
         which uses only positive coefficients that sum to 1.
     (2) The gray output values are clipped to 0 and 255.

Definition at line 1108 of file pixconv.c.

◆ pixConvertRGBToGrayFast()

PIX* pixConvertRGBToGrayFast ( PIX pixs)

pixConvertRGBToGrayFast()

Parameters
[in]pixs32 bpp RGB
Returns
8 bpp pix, or NULL on error
Notes:
     (1) This function should be used if speed of conversion
         is paramount, and the green channel can be used as
         a fair representative of the RGB intensity.  It is
         several times faster than pixConvertRGBToGray().
     (2) To combine RGB to gray conversion with subsampling,
         use pixScaleRGBToGrayFast() instead.

Definition at line 891 of file pixconv.c.

◆ pixConvertRGBToGrayGeneral()

PIX* pixConvertRGBToGrayGeneral ( PIX pixs,
l_int32  type,
l_float32  rwt,
l_float32  gwt,
l_float32  bwt 
)

pixConvertRGBToGrayGeneral()

Parameters
[in]pixs32 bpp RGB
[in]typecolor selection flag
[in]rwt,gwt,bwtignored if type != L_SELECT_WEIGHTED; if used, must sum to 1.0.
Returns
8 bpp pix, or NULL on error
Notes:
     (1) The color selection flag is one of: L_SELECT_RED, L_SELECT_GREEN,
         L_SELECT_BLUE, L_SELECT_MIN, L_SELECT_MAX, L_SELECT_AVERAGE,
         L_SELECT_HUE, L_SELECT_SATURATION, L_SELECT_WEIGHTED.
     (2) The weights, if used, must all be non-negative and must sum to 1.0.

Definition at line 756 of file pixconv.c.

◆ pixConvertRGBToGrayMinMax()

PIX* pixConvertRGBToGrayMinMax ( PIX pixs,
l_int32  type 
)

pixConvertRGBToGrayMinMax()

Parameters
[in]pixs32 bpp RGB
[in]typeL_CHOOSE_MIN, L_CHOOSE_MAX, L_CHOOSE_MAXDIFF, L_CHOOSE_MIN_BOOST, L_CHOOSE_MAX_BOOST
Returns
8 bpp pix, or NULL on error
Notes:
     (1) This chooses various components or combinations of them,
         from the three RGB sample values.  In addition to choosing
         the min, max, and maxdiff (difference between max and min),
         this also allows boosting the min and max about a reference
         value.
     (2) The default reference value for boosting the min and max
         is 200.  This can be changed with l_setNeutralBoostVal()
     (3) The result with L_CHOOSE_MAXDIFF is surprisingly sensitive
         to a jpeg compression/decompression cycle with quality = 75.

Definition at line 947 of file pixconv.c.

◆ pixConvertRGBToGraySatBoost()

PIX* pixConvertRGBToGraySatBoost ( PIX pixs,
l_int32  refval 
)

pixConvertRGBToGraySatBoost()

Parameters
[in]pixs32 bpp rgb
[in]refvalbetween 1 and 255; typ. less than 128
Returns
pixd 8 bpp, or NULL on error
Notes:
     (1) This returns the max component value, boosted by
         the saturation. The maximum boost occurs where
         the maximum component value is equal to some reference value.
         This particular weighting is due to Dany Qumsiyeh.
     (2) For gray pixels (zero saturation), this returns
         the intensity of any component.
     (3) For fully saturated pixels ('fullsat'), this rises linearly
         with the max value and has a slope equal to 255 divided
         by the reference value; for a max value greater than
         the reference value, it is clipped to 255.
     (4) For saturation values in between, the output is a linear
         combination of (2) and (3), weighted by saturation.
         It falls between these two curves, and does not exceed 255.
     (5) This can be useful for distinguishing an object that has nonzero
         saturation from a gray background.  For this, the refval
         should be chosen near the expected value of the background,
         to achieve maximum saturation boost there.

Definition at line 1032 of file pixconv.c.

References pixGetDimensions().

◆ pixConvertRGBToLuminance()

PIX* pixConvertRGBToLuminance ( PIX pixs)

pixConvertRGBToLuminance()

Parameters
[in]pixs32 bpp RGB
Returns
8 bpp pix, or NULL on error
Notes:
     (1) Use a standard luminance conversion.

Definition at line 732 of file pixconv.c.

References pixConvertRGBToGray().

◆ pixConvertTo1()

PIX* pixConvertTo1 ( PIX pixs,
l_int32  threshold 
)

pixConvertTo1()

Parameters
[in]pixs1, 2, 4, 8, 16, 24 or 32 bpp
[in]thresholdfor final binarization, relative to 8 bpp
Returns
pixd 1 bpp, or NULL on error
Notes:
     (1) This is a top-level function, with simple default values
         used in pixConvertTo8() if unpacking is necessary.
     (2) Any existing colormap is removed.
     (3) If the input image has 1 bpp and no colormap, the operation is
         lossless and a copy is returned.

Definition at line 2952 of file pixconv.c.

Referenced by dewarpaApplyInit(), pixaConvertTo1(), pixaDisplayTiledAndScaled(), pixaDisplayTiledInRows(), pixAutoPhotoinvert(), pixCompareWithTranslation(), pixConvertTo1BySampling(), and recogTrainFromBoot().

◆ pixConvertTo16()

PIX* pixConvertTo16 ( PIX pixs)

pixConvertTo16()

Parameters
[in]pixs1, 8 bpp
Returns
pixd 16 bpp, or NULL on error

Usage: Top-level function, with simple default values for unpacking. 1 bpp: val0 = 0xffff, val1 = 0 8 bpp: replicates the 8 bit value in both the MSB and LSB of the 16 bit pixel.

Definition at line 3199 of file pixconv.c.

◆ pixConvertTo1Adaptive()

PIX* pixConvertTo1Adaptive ( PIX pixs)

pixConvertTo1Adaptive()

Parameters
[in]pixs1, 2, 4, 8, 16, 24 or 32 bpp
Returns
pixd 1 bpp, or NULL on error
Notes:
     (1) This is a top-level function, that uses default values for
         adaptive thresholding, if necessary.  Otherwise, it is the same as
         pixConvertTo1(), which uses a global threshold for binarization.

Definition at line 2895 of file pixconv.c.

◆ pixConvertTo1BySampling()

PIX* pixConvertTo1BySampling ( PIX pixs,
l_int32  factor,
l_int32  threshold 
)

pixConvertTo1BySampling()

Parameters
[in]pixs1, 2, 4, 8, 16, 24 or 32 bpp
[in]factorsubsampling factor; integer >= 1
[in]thresholdfor final binarization, relative to 8 bpp
Returns
pixd 1 bpp, or NULL on error
Notes:
     (1) This is a quick and dirty, top-level converter.
     (2) See pixConvertTo1() for default values.

Definition at line 3006 of file pixconv.c.

References pixConvertTo1(), pixDestroy(), and pixScaleBySampling().

◆ pixConvertTo2()

PIX* pixConvertTo2 ( PIX pixs)

pixConvertTo2()

Parameters
[in]pixs1, 2, 4, 8, 24, 32 bpp; colormap OK but will be removed
Returns
pixd 2 bpp, or NULL on error
Notes:
     (1) This is a top-level function, with simple default values
         used in pixConvertTo8() if unpacking is necessary.
     (2) Any existing colormap is removed; the result is always gray.
     (3) If the input image has 2 bpp and no colormap, the operation is
         lossless and a copy is returned.

Definition at line 2691 of file pixconv.c.

◆ pixConvertTo32()

PIX* pixConvertTo32 ( PIX pixs)

pixConvertTo32()

Parameters
[in]pixs1, 2, 4, 8, 16, 24 or 32 bpp
Returns
pixd 32 bpp, or NULL on error

Usage: Top-level function, with simple default values for unpacking. 1 bpp: val0 = 255, val1 = 0 and then replication into R, G and B components 2 bpp: if colormapped, use the colormap values; otherwise, use val0 = 0, val1 = 0x55, val2 = 0xaa, val3 = 255 and replicate gray into R, G and B components 4 bpp: if colormapped, use the colormap values; otherwise, replicate 2 nybs into a byte, and then into R,G,B components 8 bpp: if colormapped, use the colormap values; otherwise, replicate gray values into R, G and B components 16 bpp: replicate MSB into R, G and B components 24 bpp: unpack the pixels, maintaining word alignment on each scanline 32 bpp: makes a copy

Notes:
     (1) Never returns a clone of pixs.

Definition at line 3246 of file pixconv.c.

Referenced by dewarpFindVertDisparity(), fpixaDisplayQuadtree(), pixaConvertTo32(), pixaConvertToSameDepth(), pixaDisplayOnLattice(), pixaDisplayPairTiledInColumns(), pixaDisplayTiled(), pixaDisplayTiledAndScaled(), pixaDisplayTiledByIndex(), pixaDisplayTiledInRows(), pixaDisplayTiledWithText(), pixBlendBoxaRandom(), pixCompareGrayByHisto(), pixConvertTo32BySampling(), pixDisplayPtaa(), pixWarpStereoscopic(), recogShowAverageTemplates(), recogShowMatch(), recogShowPath(), and wshedRenderColors().

◆ pixConvertTo32BySampling()

PIX* pixConvertTo32BySampling ( PIX pixs,
l_int32  factor 
)

pixConvertTo32BySampling()

Parameters
[in]pixs1, 2, 4, 8, 16, 24 or 32 bpp
[in]factorsubmsampling factor; integer >= 1
Returns
pixd 32 bpp, or NULL on error
Notes:
     (1) This is a fast, quick/dirty, top-level converter.
     (2) See pixConvertTo32() for default values.

Definition at line 3299 of file pixconv.c.

References pixConvertTo32(), pixDestroy(), and pixScaleBySampling().

◆ pixConvertTo4()

PIX* pixConvertTo4 ( PIX pixs)

pixConvertTo4()

Parameters
[in]pixs1, 2, 4, 8, 24, 32 bpp; colormap OK but will be removed
Returns
pixd 4 bpp, or NULL on error
Notes:
     (1) This is a top-level function, with simple default values
         used in pixConvertTo8() if unpacking is necessary.
     (2) Any existing colormap is removed; the result is always gray.
     (3) If the input image has 4 bpp and no colormap, the operation is
         lossless and a copy is returned.

Definition at line 2795 of file pixconv.c.

◆ pixConvertTo8()

PIX* pixConvertTo8 ( PIX pixs,
l_int32  cmapflag 
)

pixConvertTo8()

Parameters
[in]pixs1, 2, 4, 8, 16, 24 or 32 bpp
[in]cmapflagTRUE if pixd is to have a colormap; FALSE otherwise
Returns
pixd 8 bpp, or NULL on error
Notes:
     (1) This is a top-level function, with simple default values
         for unpacking.
     (2) The result, pixd, is made with a colormap if specified.
         It is always a new image -- never a clone.  For example,
         if d == 8, and cmapflag matches the existence of a cmap
         in pixs, the operation is lossless and it returns a copy.
     (3) The default values used are:
         ~ 1 bpp: val0 = 255, val1 = 0
         ~ 2 bpp: 4 bpp:  even increments over dynamic range
         ~ 8 bpp: lossless if cmap matches cmapflag
         ~ 16 bpp: use most significant byte
     (4) If 24 bpp or 32 bpp RGB, this is converted to gray.
         For color quantization, you must specify the type explicitly,
         using the color quantization code.

Definition at line 3055 of file pixconv.c.

Referenced by boxaaDisplay(), pixaConvertTo8(), pixaConvertToSameDepth(), pixaDisplayPairTiledInColumns(), pixaDisplayTiledAndScaled(), pixaDisplayTiledInRows(), pixCompareGrayByHisto(), pixConvertTo8BySampling(), pixCropAlignedToCentroid(), pixGetGrayHistogramTiled(), pixPadToCenterCentroid(), pixRenderRandomCmapPtaa(), pixSimpleCaptcha(), and showExtractNumbers().

◆ pixConvertTo8BySampling()

PIX* pixConvertTo8BySampling ( PIX pixs,
l_int32  factor,
l_int32  cmapflag 
)

pixConvertTo8BySampling()

Parameters
[in]pixs1, 2, 4, 8, 16 or 32 bpp
[in]factorsubmsampling factor; integer >= 1
[in]cmapflagTRUE if pixd is to have a colormap; FALSE otherwise
Returns
pixd 8 bpp, or NULL on error
Notes:
     (1) This is a fast, quick/dirty, top-level converter.
     (2) See pixConvertTo8() for default values.

Definition at line 3124 of file pixconv.c.

References pixConvertTo8(), pixDestroy(), and pixScaleBySampling().

Referenced by pixSplitDistributionFgBg(), and pixThresholdForFgBg().

◆ pixConvertTo8Colormap()

PIX* pixConvertTo8Colormap ( PIX pixs,
l_int32  dither 
)

pixConvertTo8Colormap()

Parameters
[in]pixs1, 2, 4, 8, 16 or 32 bpp
[in]dither1 to dither if necessary; 0 otherwise
Returns
pixd 8 bpp, cmapped, or NULL on error
Notes:
     (1) This is a top-level function, with simple default values
         for unpacking.
     (2) The result, pixd, is always made with a colormap.
     (3) If d == 8, the operation is lossless and it returns a copy.
     (4) The default values used for increasing depth are:
         ~ 1 bpp: val0 = 255, val1 = 0
         ~ 2 bpp: 4 bpp:  even increments over dynamic range
     (5) For 16 bpp, use the most significant byte.
     (6) For 32 bpp RGB, use octcube quantization with optional dithering.

Definition at line 3166 of file pixconv.c.

Referenced by pixaConvertTo8Colormap().

◆ pixConvertTo8Or32()

PIX* pixConvertTo8Or32 ( PIX pixs,
l_int32  copyflag,
l_int32  warnflag 
)

pixConvertTo8Or32()

Parameters
[in]pixs1, 2, 4, 8, 16, with or without colormap; or 32 bpp rgb
[in]copyflagL_CLONE or L_COPY
[in]warnflag1 to issue warning if colormap is removed; else 0
Returns
pixd 8 bpp grayscale or 32 bpp rgb, or NULL on error
Notes:
     (1) If there is a colormap, the colormap is removed to 8 or 32 bpp,
         depending on whether the colors in the colormap are all gray.
     (2) If the input is either rgb or 8 bpp without a colormap,
         this returns either a clone or a copy, depending on copyflag.
     (3) Otherwise, the pix is converted to 8 bpp grayscale.
         In all cases, pixd does not have a colormap.

Definition at line 3400 of file pixconv.c.

References L_CLONE, and L_COPY.

◆ pixConvertToSubpixelRGB()

PIX* pixConvertToSubpixelRGB ( PIX pixs,
l_float32  scalex,
l_float32  scaley,
l_int32  order 
)

pixConvertToSubpixelRGB()

Parameters
[in]pixs8 bpp grayscale, 32 bpp rgb, or colormapped
[in]scalex,scaleyanisotropic scaling permitted between source and destination
[in]orderof subpixel rgb color components in composition of pixd: L_SUBPIXEL_ORDER_RGB, L_SUBPIXEL_ORDER_BGR, L_SUBPIXEL_ORDER_VRGB, L_SUBPIXEL_ORDER_VBGR
Returns
pixd 32 bpp, or NULL on error
Notes:
     (1) If pixs has a colormap, it is removed based on its contents
         to either 8 bpp gray or rgb.
     (2) For horizontal subpixel splitting, the input image
         is rescaled by scaley vertically and by 3.0 times
         scalex horizontally.  Then each horizontal triplet
         of pixels is mapped back to a single rgb pixel, with the
         r, g and b values being assigned based on the pixel triplet.
         For gray triplets, the r, g, and b values are set equal to
         the three gray values.  For color triplets, the r, g and b
         values are set equal to the components from the appropriate
         subpixel.  Vertical subpixel splitting is handled similarly.
     (3) See pixConvertGrayToSubpixelRGB() and
         pixConvertColorToSubpixelRGB() for further details.

Definition at line 3900 of file pixconv.c.

◆ pixQuantizeIfFewColors()

l_ok pixQuantizeIfFewColors ( PIX pixs,
l_int32  maxcolors,
l_int32  mingraycolors,
l_int32  octlevel,
PIX **  ppixd 
)

pixQuantizeIfFewColors()

Parameters
[in]pixs8 bpp gray or 32 bpp rgb
[in]maxcolorsmax number of colors allowed to be returned from pixColorsForQuantization(); use 0 for default
[in]mingraycolorsmin number of gray levels that a grayscale image is quantized to; use 0 for default
[in]octlevelfor octcube quantization: 3 or 4
[out]ppixd2,4 or 8 bpp quantized; null if too many colors
Returns
0 if OK, 1 on error or if pixs can't be quantized into a small number of colors.
Notes:
     (1) This is a wrapper that tests if the pix can be quantized
         with good quality using a small number of colors.  If so,
         it does the quantization, defining a colormap and using
         pixels whose value is an index into the colormap.
     (2) If the image has color, it is quantized with 8 bpp pixels.
         If the image is essentially grayscale, the pixels are
         either 4 or 8 bpp, depending on the size of the required
         colormap.
     (3) octlevel = 4 generates a larger colormap and larger
         compressed image than octlevel = 3.  If image quality is
         important, you should use octlevel = 4.
     (4) If the image already has a colormap, it returns a clone.

Definition at line 1627 of file pixconv.c.

◆ pixRemoveAlpha()

PIX* pixRemoveAlpha ( PIX pixs)

pixRemoveAlpha()

Parameters
[in]pixsany depth
Returns
pixd if 32 bpp rgba, pixs blended over a white background; a clone of pixs otherwise, and NULL on error
Notes:
     (1) This is a wrapper on pixAlphaBlendUniform()

Definition at line 3659 of file pixconv.c.

◆ pixRemoveColormap()

PIX* pixRemoveColormap ( PIX pixs,
l_int32  type 
)

pixRemoveColormap()

Parameters
[in]pixssee restrictions below
[in]typeREMOVE_CMAP_TO_BINARY, REMOVE_CMAP_TO_GRAYSCALE, REMOVE_CMAP_TO_FULL_COLOR, REMOVE_CMAP_WITH_ALPHA, REMOVE_CMAP_BASED_ON_SRC
Returns
pixd without colormap, or NULL on error
Notes:
     (1) If pixs does not have a colormap, a clone is returned.
     (2) Otherwise, the input pixs is restricted to 1, 2, 4 or 8 bpp.
     (3) Use REMOVE_CMAP_TO_BINARY only on 1 bpp pix.
     (4) For grayscale conversion from RGB, use a weighted average
         of RGB values, and always return an 8 bpp pix, regardless
         of whether the input pixs depth is 2, 4 or 8 bpp.
     (5) REMOVE_CMAP_TO_FULL_COLOR ignores the alpha component and
         returns a 32 bpp pix with spp == 3 and the alpha bytes are 0.
     (6) For REMOVE_CMAP_BASED_ON_SRC, if there is no color, this
         returns either a 1 bpp or 8 bpp grayscale pix.
         If there is color, this returns a 32 bpp pix, with either:
          * 3 spp, if the alpha values are all 255 (opaque), or
          * 4 spp (preserving the alpha), if any alpha values are not 255.

Definition at line 324 of file pixconv.c.

◆ pixRemoveColormapGeneral()

PIX* pixRemoveColormapGeneral ( PIX pixs,
l_int32  type,
l_int32  ifnocmap 
)

pixRemoveColormapGeneral()

Parameters
[in]pixsany depth, with or without colormap
[in]typeREMOVE_CMAP_TO_BINARY, REMOVE_CMAP_TO_GRAYSCALE, REMOVE_CMAP_TO_FULL_COLOR, REMOVE_CMAP_WITH_ALPHA, REMOVE_CMAP_BASED_ON_SRC
[in]ifnocmapL_CLONE, L_COPY
Returns
pixd always a new pix; without colormap, or NULL on error
Notes:
     (1) Convenience function that allows choice between returning
         a clone or a copy if pixs does not have a colormap.
     (2) See pixRemoveColormap().

Definition at line 276 of file pixconv.c.

References L_CLONE, and L_COPY.

◆ pixThreshold8()

PIX* pixThreshold8 ( PIX pixs,
l_int32  d,
l_int32  nlevels,
l_int32  cmapflag 
)

pixThreshold8()

Parameters
[in]pixs8 bpp grayscale
[in]ddestination depth: 1, 2, 4 or 8
[in]nlevelsnumber of levels to be used for colormap
[in]cmapflag1 if makes colormap; 0 otherwise
Returns
pixd thresholded with standard dest thresholds, or NULL on error
Notes:
     (1) This uses, by default, equally spaced "target" values
         that depend on the number of levels, with thresholds
         halfway between.  For N levels, with separation (N-1)/255,
         there are N-1 fixed thresholds.
     (2) For 1 bpp destination, the number of levels can only be 2
         and if a cmap is made, black is (0,0,0) and white
         is (255,255,255), which is opposite to the convention
         without a colormap.
     (3) For 1, 2 and 4 bpp, the nlevels arg is used if a colormap
         is made; otherwise, we take the most significant bits
         from the src that will fit in the dest.
     (4) For 8 bpp, the input pixs is quantized to nlevels.  The
         dest quantized with that mapping, either through a colormap
         table or directly with 8 bit values.
     (5) Typically you should not use make a colormap for 1 bpp dest.
     (6) This is not dithering.  Each pixel is treated independently.

Definition at line 210 of file pixconv.c.

◆ pixUnpackBinary()

PIX* pixUnpackBinary ( PIX pixs,
l_int32  depth,
l_int32  invert 
)

pixUnpackBinary()

Parameters
[in]pixs1 bpp
[in]depthof destination: 2, 4, 8, 16 or 32 bpp
[in]invert0: binary 0 --> grayscale 0 binary 1 --> grayscale 0xff... 1: binary 0 --> grayscale 0xff... binary 1 --> grayscale 0
Returns
pixd 2, 4, 8, 16 or 32 bpp, or NULL on error
Notes:
     (1) This function calls special cases of pixConvert1To*(),
         for 2, 4, 8, 16 and 32 bpp destinations.

Definition at line 1873 of file pixconv.c.