Leptonica  1.82.0
Image processing and image analysis suite
pix1.c File Reference
#include <string.h>
#include "allheaders.h"

Go to the source code of this file.

Data Structures

struct  PixMemoryManager
 

Functions

static void pixFree (PIX *pix)
 
static void * pixdata_malloc (size_t size)
 
static void pixdata_free (void *ptr)
 
void setPixMemoryManager (alloc_fn allocator, dealloc_fn deallocator)
 
PIXpixCreate (l_int32 width, l_int32 height, l_int32 depth)
 
PIXpixCreateNoInit (l_int32 width, l_int32 height, l_int32 depth)
 
PIXpixCreateTemplate (const PIX *pixs)
 
PIXpixCreateTemplateNoInit (const PIX *pixs)
 
PIXpixCreateWithCmap (l_int32 width, l_int32 height, l_int32 depth, l_int32 initcolor)
 
PIXpixCreateHeader (l_int32 width, l_int32 height, l_int32 depth)
 
PIXpixClone (PIX *pixs)
 
void pixDestroy (PIX **ppix)
 
PIXpixCopy (PIX *pixd, const PIX *pixs)
 
l_ok pixResizeImageData (PIX *pixd, const PIX *pixs)
 
l_ok pixCopyColormap (PIX *pixd, const PIX *pixs)
 
l_ok pixTransferAllData (PIX *pixd, PIX **ppixs, l_int32 copytext, l_int32 copyformat)
 
l_ok pixSwapAndDestroy (PIX **ppixd, PIX **ppixs)
 
l_int32 pixGetWidth (const PIX *pix)
 
l_int32 pixSetWidth (PIX *pix, l_int32 width)
 
l_int32 pixGetHeight (const PIX *pix)
 
l_int32 pixSetHeight (PIX *pix, l_int32 height)
 
l_int32 pixGetDepth (const PIX *pix)
 
l_int32 pixSetDepth (PIX *pix, l_int32 depth)
 
l_ok pixGetDimensions (const PIX *pix, l_int32 *pw, l_int32 *ph, l_int32 *pd)
 
l_ok pixSetDimensions (PIX *pix, l_int32 w, l_int32 h, l_int32 d)
 
l_ok pixCopyDimensions (PIX *pixd, const PIX *pixs)
 
l_int32 pixGetSpp (const PIX *pix)
 
l_int32 pixSetSpp (PIX *pix, l_int32 spp)
 
l_ok pixCopySpp (PIX *pixd, const PIX *pixs)
 
l_int32 pixGetWpl (const PIX *pix)
 
l_int32 pixSetWpl (PIX *pix, l_int32 wpl)
 
l_int32 pixGetRefcount (const PIX *pix)
 
l_int32 pixChangeRefcount (PIX *pix, l_int32 delta)
 
l_int32 pixGetXRes (const PIX *pix)
 
l_int32 pixSetXRes (PIX *pix, l_int32 res)
 
l_int32 pixGetYRes (const PIX *pix)
 
l_int32 pixSetYRes (PIX *pix, l_int32 res)
 
l_ok pixGetResolution (const PIX *pix, l_int32 *pxres, l_int32 *pyres)
 
l_ok pixSetResolution (PIX *pix, l_int32 xres, l_int32 yres)
 
l_int32 pixCopyResolution (PIX *pixd, const PIX *pixs)
 
l_int32 pixScaleResolution (PIX *pix, l_float32 xscale, l_float32 yscale)
 
l_int32 pixGetInputFormat (const PIX *pix)
 
l_int32 pixSetInputFormat (PIX *pix, l_int32 informat)
 
l_int32 pixCopyInputFormat (PIX *pixd, const PIX *pixs)
 
l_int32 pixSetSpecial (PIX *pix, l_int32 special)
 
char * pixGetText (PIX *pix)
 
l_ok pixSetText (PIX *pix, const char *textstring)
 
l_ok pixAddText (PIX *pix, const char *textstring)
 
l_int32 pixCopyText (PIX *pixd, const PIX *pixs)
 
l_uint8 * pixGetTextCompNew (PIX *pix, size_t *psize)
 
l_ok pixSetTextCompNew (PIX *pix, const l_uint8 *data, size_t size)
 
PIXCMAPpixGetColormap (PIX *pix)
 
l_ok pixSetColormap (PIX *pix, PIXCMAP *colormap)
 
l_ok pixDestroyColormap (PIX *pix)
 
l_uint32 * pixGetData (PIX *pix)
 
l_int32 pixSetData (PIX *pix, l_uint32 *data)
 
l_uint32 * pixExtractData (PIX *pixs)
 
l_int32 pixFreeData (PIX *pix)
 
void ** pixGetLinePtrs (PIX *pix, l_int32 *psize)
 
l_int32 pixSizesEqual (const PIX *pix1, const PIX *pix2)
 
l_ok pixMaxAspectRatio (PIX *pixs, l_float32 *pratio)
 
l_ok pixPrintStreamInfo (FILE *fp, const PIX *pix, const char *text)
 

Variables

static struct PixMemoryManager pix_mem_manager
 
const char * ImageFileFormatExtensions []
 

Detailed Description


   The pixN.c {N = 1,2,3,4,5} files are sorted by the type of operation.
   The primary functions in these files are:

       pix1.c: constructors, destructors and field accessors
       pix2.c: pixel poking of image, pad and border pixels
       pix3.c: masking and logical ops, counting, mirrored tiling
       pix4.c: histograms, statistics, fg/bg estimation
       pix5.c: property measurements, rectangle extraction


   This file has the basic constructors, destructors and field accessors

   Pix memory management (allows custom allocator and deallocator)
         static void  *pixdata_malloc()
         static void   pixdata_free()
         void          setPixMemoryManager()

   Pix creation
         PIX          *pixCreate()
         PIX          *pixCreateNoInit()
         PIX          *pixCreateTemplate()
         PIX          *pixCreateTemplateNoInit()
         PIX          *pixCreateWithCmap()
         PIX          *pixCreateHeader()
         PIX          *pixClone()

   Pix destruction
         void          pixDestroy()
         static void   pixFree()

   Pix copy
         PIX          *pixCopy()
         l_int32       pixResizeImageData()
         l_int32       pixCopyColormap()
         l_int32       pixTransferAllData()
         l_int32       pixSwapAndDestroy()

   Pix accessors
         l_int32       pixGetWidth()
         l_int32       pixSetWidth()
         l_int32       pixGetHeight()
         l_int32       pixSetHeight()
         l_int32       pixGetDepth()
         l_int32       pixSetDepth()
         l_int32       pixGetDimensions()
         l_int32       pixSetDimensions()
         l_int32       pixCopyDimensions()
         l_int32       pixGetSpp()
         l_int32       pixSetSpp()
         l_int32       pixCopySpp()
         l_int32       pixGetWpl()
         l_int32       pixSetWpl()
         l_int32       pixGetRefcount()
         l_int32       pixChangeRefcount()
         l_uint32      pixGetXRes()
         l_int32       pixSetXRes()
         l_uint32      pixGetYRes()
         l_int32       pixSetYRes()
         l_int32       pixGetResolution()
         l_int32       pixSetResolution()
         l_int32       pixCopyResolution()
         l_int32       pixScaleResolution()
         l_int32       pixGetInputFormat()
         l_int32       pixSetInputFormat()
         l_int32       pixCopyInputFormat()
         l_int32       pixSetSpecial()
         char         *pixGetText()
         l_int32       pixSetText()
         l_int32       pixAddText()
         l_int32       pixCopyText()
         l_uint8      *pixGetTextCompNew()
         l_int32      *pixSetTextCompNew()
         PIXCMAP      *pixGetColormap()
         l_int32       pixSetColormap()
         l_int32       pixDestroyColormap()
         l_uint32     *pixGetData()
         l_int32       pixSetData()
         l_uint32     *pixExtractData()
         l_int32       pixFreeData()

   Pix line ptrs
         void        **pixGetLinePtrs()

   Pix size comparisons
         l_int32       pixSizesEqual()
         l_int32       pixMaxAspectRatio()

   Pix debug
         l_int32       pixPrintStreamInfo()


 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
     Important notes on direct management of pix image data
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

 Custom allocator and deallocator
 --------------------------------

 At the lowest level, you can specify the function that does the
 allocation and deallocation of the data field in the pix.
 By default, this is malloc and free.  However, by calling
 setPixMemoryManager(), custom functions can be substituted.
 When using this, keep two things in mind:

  (1) Call setPixMemoryManager() before any pix have been allocated
  (2) Destroy all pix as usual, in order to prevent leaks.

 In pixalloc.c, we provide an example custom allocator and deallocator.
 To use it, you must call pmsCreate() before any pix have been allocated
 and pmsDestroy() at the end after all pix have been destroyed.


 Direct manipulation of the pix data field
 -----------------------------------------

 Memory management of the (image) data field in the pix is
 handled differently from that in the colormap or text fields.
 For colormap and text, the functions pixSetColormap() and
 pixSetText() remove the existing heap data and insert the
 new data.  For the image data, pixSetData() just reassigns the
 data field; any existing data will be lost if there isn't
 another handle for it.

 Why is pixSetData() limited in this way?  Because the image
 data can be very large, we need flexible ways to handle it,
 particularly when you want to re-use the data in a different
 context without making a copy.  Here are some different
 things you might want to do:

 (1) Use pixCopy(pixd, pixs) where pixd is not the same size
     as pixs.  This will remove the data in pixd, allocate a
     new data field in pixd, and copy the data from pixs, leaving
     pixs unchanged.

 (2) Use pixTransferAllData(pixd, &pixs, ...) to transfer the
     data from pixs to pixd without making a copy of it.  If
     pixs is not cloned, this will do the transfer and destroy pixs.
     But if the refcount of pixs is greater than 1, it just copies
     the data and decrements the ref count.

 (3) Use pixSwapAndDestroy(pixd, &pixs) to replace pixs by an
     existing pixd.  This is similar to pixTransferAllData(), but
     simpler, in that it never makes any copies and if pixs is
     cloned, the other references are not changed by this operation.

 (4) Use pixExtractData() to extract the image data from the pix
     without copying if possible.  This could be used, for example,
     to convert from a pix to some other data structure with minimal
     heap allocation.  After the data is extracated, the pixels can
     be munged and used in another context.  However, the danger
     here is that the pix might have a refcount > 1, in which case
     a copy of the data must be made and the input pix left unchanged.
     If there are no clones, the image data can be extracted without
     a copy, and the data ptr in the pix must be nulled before
     destroying it because the pix will no longer 'own' the data.

 We have provided accessors and functions here that should be
 sufficient so that you can do anything you want without
 explicitly referencing any of the pix member fields.

 However, to avoid memory smashes and leaks when doing special operations
 on the pix data field, look carefully at the behavior of the image
 data accessors and keep in mind that when you invoke pixDestroy(),
 the pix considers itself the owner of all its heap data.

Definition in file pix1.c.

Function Documentation

◆ pixAddText()

l_ok pixAddText ( PIX pix,
const char *  textstring 
)

pixAddText()

Parameters
[in]pix
[in]textstringcan be null
Returns
0 if OK, 1 on error
Notes:
     (1) This adds the new textstring to any existing text.
     (2) Either or both the existing text and the new text
         string can be null.

Definition at line 1564 of file pix1.c.

References pixGetText(), stringJoin(), stringReplace(), and Pix::text.

◆ pixClone()

PIX* pixClone ( PIX pixs)

pixClone()

Parameters
[in]pixs
Returns
same pix ptr, or NULL on error
Notes:
     (1) A "clone" is simply a handle (ptr) to an existing pix.
         It is implemented because (a) images can be large and
         hence expensive to copy, and (b) extra handles to a data
         structure need to be made with a simple policy to avoid
         both double frees and memory leaks.  Pix are reference
         counted.  The side effect of pixClone() is an increase
         by 1 in the ref count.
     (2) The protocol to be used is:
         (a) Whenever you want a new handle to an existing image,
             call pixClone(), which just bumps a ref count.
         (b) Always call pixDestroy() on all handles.  This
             decrements the ref count, nulls the handle, and
             only destroys the pix when pixDestroy() has been
             called on all handles.

Definition at line 593 of file pix1.c.

Referenced by bilateralCreate(), dewarpaApplyDisparity(), dewarpFindVertDisparity(), dewarpShowResults(), ioFormatTest(), pixaAddPix(), pixaAddPixWithText(), pixaConvertToNUpPixa(), pixaConvertToPdfData(), pixAddBorder(), pixaDisplayPairTiledInColumns(), pixaDisplayTiledAndScaled(), pixaDisplayTiledByIndex(), pixaDisplayTiledInColumns(), pixaDisplayTiledInRows(), pixaDisplayTiledWithText(), pixAffineSequential(), pixaGetPix(), pixCompareGrayByHisto(), pixComparePhotoRegionsByHisto(), pixCropToSize(), pixDecideIfTable(), pixDisplayColorArray(), pixEndianByteSwapNew(), pixEndianTwoByteSwapNew(), pixRemoveBorder(), pixRemoveBorderToSize(), pixSwapAndDestroy(), pixTilingCreate(), pixTilingGetTile(), pixWarpStereoscopic(), recogCreateDid(), recogModifyTemplate(), recogProcessLabeled(), recogShowMatch(), recogTrainingFinished(), and saConvertFilesToPdfData().

◆ pixCopy()

PIX* pixCopy ( PIX pixd,
const PIX pixs 
)

pixCopy()

Parameters
[in]pixd[optional] can be null, equal to pixs, different from pixs
[in]pixs
Returns
pixd, or NULL on error
Notes:
     (1) There are three cases:
           (a) pixd == null  (makes a new pix; refcount = 1)
           (b) pixd == pixs  (no-op)
           (c) pixd != pixs  (data copy; no change in refcount)
         If the refcount of pixd > 1, case (c) will side-effect
         these handles.
     (2) The general pattern of use is:
            pixd = pixCopy(pixd, pixs);
         This will work for all three cases.
         For clarity when the case is known, you can use:
           (a) pixd = pixCopy(NULL, pixs);
           (c) pixCopy(pixd, pixs);
     (3) For case (c), we check if pixs and pixd are the same
         size (w,h,d).  If so, the data is copied directly.
         Otherwise, the data is reallocated to the correct size
         and the copy proceeds.  The refcount of pixd is unchanged.
     (4) This operation, like all others that may involve a pre-existing
         pixd, will side-effect any existing clones of pixd.

Definition at line 705 of file pix1.c.

Referenced by dewarpSinglePageRun(), findNextUnvisited(), makeColorfillTestData(), pixaAddPix(), pixAddSingleTextblock(), pixAddTextlines(), pixAffineSequential(), pixaGetPix(), pixaInitFull(), pixBlendBoxaRandom(), pixBlockconv(), pixBlockconvGray(), pixBlockconvGrayTile(), pixBlockconvGrayUnnormalized(), pixBlockconvTiled(), pixBlockrank(), pixBlocksum(), pixContrastTRC(), pixDrawBoxa(), pixDrawBoxaRandom(), pixExpandBinaryPower2(), pixExpandBinaryReplicate(), pixExpandReplicate(), pixFlipLR(), pixFlipTB(), pixInvert(), pixModifyBrightness(), pixModifySaturation(), pixPaintBoxa(), pixPaintBoxaRandom(), pixQuadraticVShear(), pixQuadraticVShearSampled(), pixResizeToMatch(), pixRotateOrth(), pixScaleByIntSampling(), pixScaleBySampling(), pixScaleToSizeRel(), pixSelectByArea(), pixSelectByAreaFraction(), pixSelectByPerimSizeRatio(), pixSelectByPerimToAreaRatio(), pixSelectBySize(), pixSelectByWidthHeightRatio(), pixSetBlackOrWhiteBoxa(), pixTranslate(), recogModifyTemplate(), recogShowMatch(), wshedRenderColors(), and wshedRenderFill().

◆ pixCopyColormap()

l_ok pixCopyColormap ( PIX pixd,
const PIX pixs 
)

pixCopyColormap()

Parameters
[in]pixd
[in]pixscopies the colormap to pixd
Returns
0 if OK, 1 on error
Notes:
     (1) This destroys the colormap in pixd, unless the operation is a no-op

Definition at line 816 of file pix1.c.

Referenced by pixaDisplayUnsplit(), pixaSplitPix(), pixExpandReplicate(), and pixRotate90().

◆ pixCopyDimensions()

l_ok pixCopyDimensions ( PIX pixd,
const PIX pixs 
)

pixCopyDimensions()

Parameters
[in]pixd
[in]pixs
Returns
0 if OK, 1 on error

Definition at line 1164 of file pix1.c.

◆ pixCopySpp()

l_ok pixCopySpp ( PIX pixd,
const PIX pixs 
)

pixCopySpp()

Parameters
[in]pixd
[in]pixs
Returns
0 if OK, 1 on error

Definition at line 1236 of file pix1.c.

Referenced by pixCreateTemplateNoInit(), and pixMirroredTiling().

◆ pixCreate()

PIX* pixCreate ( l_int32  width,
l_int32  height,
l_int32  depth 
)

pixCreate()

Parameters
[in]width,height,depth
Returns
pixd with data allocated and initialized to 0, or NULL on error

Definition at line 315 of file pix1.c.

References Pix::data, Pix::h, pixCreateNoInit(), and Pix::wpl.

Referenced by boxaCombineOverlaps(), boxaCombineOverlapsInPair(), boxaCompareRegions(), boxaDisplayTiled(), boxaGetCoverage(), ccbaDisplayBorder(), ccbaDisplayImage1(), ccbaDisplayImage2(), ccbaDisplaySPBorder(), displayHSVColorRange(), dpixConvertToPix(), evalColorfillData(), fpixaConvertLABToRGB(), fpixaConvertXYZToRGB(), fpixConvertToPix(), fpixDisplayMaxDynamicRange(), fpixRenderContours(), fpixThresholdToPix(), kernelDisplayInPix(), makeColorfillTestData(), pixaAccumulateSamples(), pixaccCreate(), pixaComparePhotoRegionsByHisto(), pixaCreateFromPix(), pixAddBorderGeneral(), pixaDisplay(), pixaDisplayRandomCmap(), pixaDisplayTiled(), pixaDisplayTiledAndScaled(), pixaDisplayTiledInRows(), pixaDisplayUnsplit(), pixaGetAlignedStats(), pixaInitFull(), pixApplyVariableGrayMap(), pixaSplitPix(), pixBlockconvAccum(), pixBlockconvGrayUnnormalized(), pixClipRectangle(), pixColorContent(), pixColorMagnitude(), pixConvert24To32(), pixCreateRGBImage(), pixCreateWithCmap(), pixCropToSize(), pixDisplayColorArray(), pixDisplayDiffBinary(), pixDitherTo2bppSpec(), pixDitherToBinarySpec(), pixExpandReplicate(), pixFindLargestRectangle(), pixGenerateFromPta(), pixGenerateMaskByBand32(), pixGenerateMaskByDiscr32(), pixInitAccumulate(), pixMakeFrameMask(), pixMakeGamutRGB(), pixMakeMaskFromLUT(), pixMakeMaskFromVal(), pixMirroredTiling(), pixPadToCenterCentroid(), pixReadStreamJpeg(), pixReadStreamPnm(), pixRemoveBorderGeneral(), pixRenderPolygon(), pixResizeToMatch(), pixRotate90(), pixSearchBinaryMaze(), pixSearchGrayMaze(), pixThresholdGrayArb(), pixThresholdTo2bpp(), pixThresholdTo4bpp(), pixThresholdToBinary(), pixVarThresholdToBinary(), pixWarpStereoscopic(), recogGetWindowedArea(), recogMakeDecodingArray(), recogShowAverageTemplates(), selaAddCrossJunctions(), selaAddTJunctions(), selDisplayInPix(), and selMakePlusSign().

◆ pixCreateHeader()

PIX* pixCreateHeader ( l_int32  width,
l_int32  height,
l_int32  depth 
)

pixCreateHeader()

Parameters
[in]width,height,depth
Returns
pixd with no data allocated, or NULL on error
Notes:
     (1) It is assumed that all 32 bit pix have 3 spp.  If there is
         a valid alpha channel, this will be set to 4 spp later.
     (2) All pixCreate*() functions call pixCreateHeader().
         If the number of bytes to be allocated is larger than the
         maximum value in an int32, we can get overflow, resulting
         in a smaller amount of memory actually being allocated.
         Later, an attempt to access memory that wasn't allocated will
         cause a crash.  So to avoid crashing a program (or worse)
         with bad (or malicious) input, we limit the requested
         allocation of image data in a typesafe way.

Definition at line 504 of file pix1.c.

Referenced by pixCreateNoInit().

◆ pixCreateNoInit()

PIX* pixCreateNoInit ( l_int32  width,
l_int32  height,
l_int32  depth 
)

pixCreateNoInit()

Parameters
[in]width,height,depth
Returns
pixd with data allocated but not initialized, or NULL on error
Notes:
     (1) Pad bits are set to avoid reading uninitialized data, because
         some optimized routines read from pad bits.
     (2) Initializing memory is very fast, so this optimization is
         not used in the library.

Definition at line 346 of file pix1.c.

References pixCreateHeader().

Referenced by pixCreate(), and pixCreateTemplateNoInit().

◆ pixCreateTemplate()

◆ pixCreateTemplateNoInit()

PIX* pixCreateTemplateNoInit ( const PIX pixs)

pixCreateTemplateNoInit()

Parameters
[in]pixs
Returns
pixd, or NULL on error
Notes:
     (1) Makes a Pix of the same size as the input Pix, with
         the data array allocated but not initialized to 0.
     (2) Copies the other fields, including colormap if it exists.
     (3) Pad bits are set to avoid reading uninitialized data, because
         some optimized routines read from pad bits.
     (4) Initializing memory is very fast, so this optimization is
         not used in the library.

Definition at line 417 of file pix1.c.

References pixCopySpp(), pixCreateNoInit(), and pixGetDimensions().

Referenced by pixCreateTemplate().

◆ pixCreateWithCmap()

PIX* pixCreateWithCmap ( l_int32  width,
l_int32  height,
l_int32  depth,
l_int32  initcolor 
)

pixCreateWithCmap()

Parameters
[in]width
[in]height
[in]depth2, 4 or 8 bpp
[in]initcolorL_SET_BLACK, L_SET_WHITE
Returns
pixd with the initialization color assigned to all pixels, or NULL on error.
Notes:
     (1) Creates a pix with a cmap, initialized to value 0.
     (2) Initializes the pix black or white by adding that color
         to the cmap at index 0.

Definition at line 458 of file pix1.c.

References L_SET_BLACK, pixcmapAddColor(), pixcmapCreate(), pixCreate(), and pixSetColormap().

◆ pixDestroy()

void pixDestroy ( PIX **  ppix)

pixDestroy()

Parameters
[in,out]ppixwill be set to null before returning
Returns
void
Notes:
     (1) Decrements the ref count and, if 0, destroys the pix.
     (2) Always nulls the input ptr.

Definition at line 621 of file pix1.c.

References pixFree().

Referenced by bilateralCreate(), bilateralDestroy(), boxaCombineOverlaps(), boxaCompareRegions(), boxaDisplayTiled(), boxaGetCoverage(), ccbaDestroy(), ccbaDisplayImage1(), ccbaDisplayImage2(), ccbDestroy(), convertImageDataToPdf(), convertImageDataToPdfData(), convertNumberedMasksToBoxaa(), convertToPdfData(), convertToPdfDataSegmented(), convertToPdfSegmented(), dewarpaApplyDisparity(), dewarpaApplyInit(), dewarpaShowArrays(), dewarpDestroy(), dewarpMinimize(), dewarpSinglePage(), displayHSVColorRange(), evalColorfillData(), findNextUnvisited(), fpixaDisplayQuadtree(), ioFormatTest(), kernelDisplayInPix(), l_colorfillDestroy(), l_generateFlateData(), makeColorfillTestData(), pixaAddBorderGeneral(), pixaAddPix(), pixaAddTextlines(), pixaAddTextNumber(), pixaccDestroy(), pixaccMultConstAccumulate(), pixaCentroids(), pixaClear(), pixaClipToForeground(), pixaClipToPix(), pixaComparePhotoRegionsByHisto(), pixaConvertTo1(), pixaConvertTo32(), pixaConvertTo8(), pixaConvertTo8Colormap(), pixaConvertToNUpPixa(), pixaConvertToPdfData(), pixaConvertToSameDepth(), pixaCountText(), pixaCreateFromPix(), pixAddWithIndicator(), pixaDestroy(), pixaDisplayOnLattice(), pixaDisplayPairTiledInColumns(), pixaDisplayTiled(), pixaDisplayTiledAndScaled(), pixaDisplayTiledByIndex(), pixaDisplayTiledInRows(), pixaDisplayTiledWithText(), pixaDisplayUnsplit(), pixaEqual(), pixAffineSequential(), pixaFindAreaFraction(), pixaFindDimensions(), pixaFindPerimSizeRatio(), pixaFindPerimToAreaRatio(), pixaFindStrokeWidth(), pixaFindWidthHeightProduct(), pixaFindWidthHeightRatio(), pixaGetAlignedStats(), pixaGetLinePtrs(), pixaGetPixDimensions(), pixaIsFull(), pixaMakeFromTiledPixa(), pixaModifyStrokeWidth(), pixaMorphSequenceByComponent(), pixaRemovePix(), pixaRemovePixAndSave(), pixaReplacePix(), pixaRotateOrth(), pixaScaleToSizeRel(), pixaSelectByNumConnComp(), pixaSetFullSizeBoxa(), pixaSetStrokeWidth(), pixaSetText(), pixaSplitIntoFiles(), pixaThinConnected(), pixaTranslate(), pixAutoPhotoinvert(), pixaWriteStream(), pixBlockconvGrayUnnormalized(), pixBlockrank(), pixClose(), pixCloseGeneralized(), pixCompareGrayByHisto(), pixComparePhotoRegionsByHisto(), pixCompareWithTranslation(), pixConvertTo1BySampling(), pixConvertTo32BySampling(), pixConvertTo8BySampling(), pixCorrelationBinary(), pixCropAlignedToCentroid(), pixDecideIfTable(), pixDecideIfText(), pixDilate(), pixDisplayColorArray(), pixDisplayDiffBinary(), pixDisplayOutliers(), pixDisplayPtaa(), pixFindStrokeLength(), pixGetGrayHistogramTiled(), pixGetOuterBorder(), pixHMT(), pixMirroredTiling(), pixMorphSequenceByComponent(), pixOpen(), pixOpenGeneralized(), pixReadStreamJpeg(), pixRemoveWithIndicator(), pixRenderHorizEndPoints(), pixSimpleCaptcha(), pixSwapAndDestroy(), pixThresholdForFgBg(), pixTilingDestroy(), pixTilingGetTile(), pixWarpStereoscopic(), pixWriteStreamPS(), recogAddCharstrLabels(), recogAddDigitPadTemplates(), recogAverageSamples(), recogCreateFromPixaNoFinish(), recogDebugAverages(), recogDestroy(), recogDestroyDid(), recogDisplayOutlier(), recogGetWindowedArea(), recogIdentifyPixa(), recogMakeBootDigitTemplates(), recogMakeDecodingArray(), recogModifyTemplate(), recogRescoreDidResult(), recogShowAverageTemplates(), recogShowMatch(), recogShowMatchesInRange(), recogShowPath(), recogTrainFromBoot(), recogTrainingFinished(), recogTrainLabeled(), saConvertFilesToPdfData(), selaAddCrossJunctions(), selaAddTJunctions(), selaCreateFromColorPixa(), selaDisplayInPix(), selMakePlusSign(), selReadFromColorImage(), showExtractNumbers(), wshedDestroy(), wshedRenderColors(), and wshedRenderFill().

◆ pixDestroyColormap()

l_ok pixDestroyColormap ( PIX pix)

pixDestroyColormap()

Parameters
[in]pix
Returns
0 if OK, 1 on error

Definition at line 1728 of file pix1.c.

References Pix::colormap, and pixcmapDestroy().

Referenced by pixSetColormap().

◆ pixExtractData()

l_uint32* pixExtractData ( PIX pixs)

pixExtractData()

Parameters
[in]pix
Returns
ptr to data, or null on error
Notes:
     (1) This extracts the pix image data for use in another context.
         The caller still needs to use pixDestroy() on the input pix.
     (2) If refcount == 1, the data is extracted and the
         pix->data ptr is set to NULL.
     (3) If refcount > 1, this simply returns a copy of the data,
         using the pix allocator, and leaving the input pix unchanged.

Definition at line 1817 of file pix1.c.

◆ pixFree()

static void pixFree ( PIX pix)
static

pixFree()

Parameters
[in]pix
Returns
void
Notes:
     (1) Decrements the ref count and, if 0, destroys the pix.

Definition at line 651 of file pix1.c.

Referenced by pixDestroy().

◆ pixFreeData()

l_int32 pixFreeData ( PIX pix)

pixFreeData()

Parameters
[in]pix
Returns
0 if OK, 1 on error
Notes:
     (1) This frees the data and sets the pix data ptr to null.
         It should be used before pixSetData() in the situation where
         you want to free any existing data before doing
         a subsequent assignment with pixSetData().

Definition at line 1858 of file pix1.c.

References pixGetData().

◆ pixGetData()

l_uint32* pixGetData ( PIX pix)

pixGetData()

Parameters
[in]pix
Returns
ptr to image data
Notes:
     (1) This gives a new handle for the data.  The data is still
         owned by the pix, so do not call LEPT_FREE() on it.
     (2) This cannot guarantee that the pix data returned will not
         be changed, so pix cannot be declared const.  And because
         most imaging operations call this for access to the data,
         this prevents them from declaring pix to be const, even if
         they only use the data for inspection.

Definition at line 1763 of file pix1.c.

References Pix::data.

Referenced by bilateralApply(), bilateralCreate(), dpixConvertToPix(), fpixConvertToPix(), fpixDisplayMaxDynamicRange(), fpixRenderContours(), fpixThresholdToPix(), makeGrayQuantColormapArb(), pixaComparePhotoRegionsByHisto(), pixAddConstantGray(), pixAffineColor(), pixApplyHorizDisparity(), pixApplyVertDisparity(), pixBilinearColor(), pixBlockconvAccum(), pixCentroid(), pixColorContent(), pixColorMagnitude(), pixConvert24To32(), pixConvert32To24(), pixEndianByteSwap(), pixEndianByteSwapNew(), pixEndianTwoByteSwap(), pixEndianTwoByteSwapNew(), pixFindLargestRectangle(), pixFlipLR(), pixFlipTB(), pixFreeData(), pixGetColorRegion(), pixGetOuterBorder(), pixGetRasterData(), pixMeasureSaturation(), pixModifyBrightness(), pixModifySaturation(), pixMultConstantGray(), pixMultiplyGray(), pixNumberOccupiedOctcubes(), pixNumColors(), pixProjectiveColor(), pixQuadraticVShearSampled(), pixRasterop(), pixRasteropHip(), pixRasteropVip(), pixSetBorderVal(), pixSetLowContrast(), pixSetPadBits(), pixSetPadBitsBand(), pixSetPixel(), pixSobelEdgeFilter(), pixStretchHorizontalLI(), pixStretchHorizontalSampled(), and pixTwoSidedEdgeFilter().

◆ pixGetDimensions()

l_ok pixGetDimensions ( const PIX pix,
l_int32 *  pw,
l_int32 *  ph,
l_int32 *  pd 
)

pixGetDimensions()

Parameters
[in]pix
[out]pw,ph,pd[optional] each can be null
Returns
0 if OK, 1 on error

Definition at line 1113 of file pix1.c.

References Pix::d, Pix::h, and Pix::w.

Referenced by bilateralCreate(), boxaaDisplay(), dewarpPopulateFullRes(), evalColorfillData(), getCutPathForHole(), identifyWatershedBasin(), ioFormatTest(), kernelCreateFromPix(), localSearchForBackground(), makeGrayQuantColormapArb(), nextOnPixelInRaster(), pixaccCreateFromPix(), pixaccMultConstAccumulate(), pixaCreateFromBoxa(), pixaCreateFromPix(), pixAddBorderGeneral(), pixAddConstantGray(), pixAddContinuedBorder(), pixAddMirroredBorder(), pixAddMixedBorder(), pixAddRepeatedBorder(), pixAddRGB(), pixAddSingleTextblock(), pixAddTextlines(), pixaDisplayTiledAndScaled(), pixaDisplayTiledByIndex(), pixAffineColor(), pixAffineGray(), pixAffinePtaWithAlpha(), pixAffineSampled(), pixaFindDimensions(), pixaFindWidthHeightProduct(), pixaFindWidthHeightRatio(), pixaGetPixDimensions(), pixaMakeFromTiledPix(), pixApplyHorizDisparity(), pixApplyVariableGrayMap(), pixApplyVertDisparity(), pixaRotateOrth(), pixaSetFullSizeBoxa(), pixaSplitPix(), pixAverageByColumn(), pixAverageByRow(), pixAverageOnLine(), pixaWriteStreamInfo(), pixBilinearColor(), pixBilinearGray(), pixBilinearPtaWithAlpha(), pixBilinearSampled(), pixBlendWithGrayMask(), pixBlockconv(), pixBlockconvAccum(), pixBlockconvGray(), pixBlockconvGrayTile(), pixBlockconvGrayUnnormalized(), pixBlockconvTiled(), pixBlockrank(), pixBlocksum(), pixCentroid(), pixClipRectangle(), pixClipRectangleWithBorder(), pixColorContent(), pixColorMagnitude(), pixCombineMasked(), pixCombineMaskedGeneral(), pixCompareGrayByHisto(), pixComparePhotoRegionsByHisto(), pixCompareTilesByHisto(), pixConvert24To32(), pixConvert32To24(), pixConvert8To16(), pixConvertRGBToGraySatBoost(), pixConvertRGBToHue(), pixConvertRGBToSaturation(), pixConvertRGBToValue(), pixCopyBorder(), pixCreateFromPixcomp(), pixCreateRGBImage(), pixCreateTemplateNoInit(), pixCropAlignedToCentroid(), pixCropToMatch(), pixCropToSize(), pixDilate(), pixDisplayDiffBinary(), pixDisplayPtaa(), pixDitherTo2bppSpec(), pixDitherToBinarySpec(), pixelIsOnColorBoundary(), pixEqualWithAlpha(), pixErode(), pixExpandBinaryPower2(), pixExpandBinaryReplicate(), pixExpandReplicate(), pixExtractOnLine(), pixFindHorizontalRuns(), pixFindLargestRectangle(), pixFindPageForeground(), pixFindVerticalRuns(), pixFlipLR(), pixFlipTB(), pixGenerateFlateData(), pixGenerateMaskByBand32(), pixGenerateMaskByDiscr32(), pixGetAverageTiled(), pixGetColorHistogram(), pixGetColorHistogramMasked(), pixGetColorRegion(), pixGetMaxColorIndex(), pixGetOuterBorder(), pixGetPixel(), pixGetRandomPixel(), pixGetRasterData(), pixGetRGBPixel(), pixHMT(), pixHShearLI(), pixInferResolution(), pixMakeMaskFromLUT(), pixMakeMaskFromVal(), pixMaskOverColorPixels(), pixMaskOverColorRange(), pixMaxAspectRatio(), pixMaxDynamicRange(), pixMeasureSaturation(), pixMinMaxNearLine(), pixMirroredTiling(), pixModifyBrightness(), pixModifySaturation(), pixMultConstantColor(), pixMultConstantGray(), pixMultiplyGray(), pixMultMatrixColor(), pixNumberOccupiedOctcubes(), pixNumColors(), pixPadToCenterCentroid(), pixPrepare1bpp(), pixProjectiveColor(), pixProjectiveGray(), pixProjectivePtaWithAlpha(), pixProjectiveSampled(), pixQuadraticVShear(), pixQuadraticVShearLI(), pixQuadraticVShearSampled(), pixRandomHarmonicWarp(), pixRasterop(), pixRasteropHip(), pixRasteropIP(), pixRasteropVip(), pixReadBarcodes(), pixRemoveBorderGeneral(), pixRemoveBorderToSize(), pixRenderGridArb(), pixRenderPlotFromNuma(), pixResizeImageData(), pixResizeToMatch(), pixRotate90(), pixRotateBySampling(), pixRotateWithAlpha(), pixScaleAreaMapToSize(), pixScaleBySamplingToSize(), pixScaleSmoothToSize(), pixScaleToSize(), pixScaleToSizeRel(), pixScaleWithAlpha(), pixSearchBinaryMaze(), pixSearchGrayMaze(), pixSelectByArea(), pixSelectByAreaFraction(), pixSelectByPerimSizeRatio(), pixSelectByPerimToAreaRatio(), pixSelectBySize(), pixSelectByWidthHeightRatio(), pixSerializeToMemory(), pixSetBorderRingVal(), pixSetBorderVal(), pixSetInRectArbitrary(), pixSetLowContrast(), pixSetMirroredBorder(), pixSetOrClearBorder(), pixSetPadBits(), pixSetPadBitsBand(), pixSetPixel(), pixSetRGBPixel(), pixSetTextblock(), pixSobelEdgeFilter(), pixStretchHorizontalLI(), pixStretchHorizontalSampled(), pixThresholdGrayArb(), pixThresholdTo2bpp(), pixThresholdTo4bpp(), pixThresholdToBinary(), pixTilingCreate(), pixTilingGetTile(), pixTilingPaintTile(), pixTwoSidedEdgeFilter(), pixUnsharpMaskingGray(), pixUnsharpMaskingGray1D(), pixUnsharpMaskingGray2D(), pixVarianceByColumn(), pixVarianceByRow(), pixVarianceInRect(), pixVarThresholdToBinary(), pixVShearLI(), pixWarpStereoscopic(), pixWriteStreamAsciiPnm(), pixWriteStreamJpeg(), pixWriteStreamPam(), pixWriteStreamPnm(), pixWriteStringPS(), pixWriteToTiffStream(), ptaGetNeighborPixLocs(), recogGetWindowedArea(), recogMakeDecodingArray(), recogModifyTemplate(), regTestCompareSimilarPix(), selaDisplayInPix(), selCreateFromPix(), selectDefaultPdfEncoding(), wshedApply(), and wshedRenderColors().

◆ pixGetLinePtrs()

void** pixGetLinePtrs ( PIX pix,
l_int32 *  psize 
)

pixGetLinePtrs()

Parameters
[in]pix
[out]psize[optional] array size, which is the pix height
Returns
array of line ptrs, or NULL on error
Notes:
     (1) This is intended to be used for fast random pixel access.
         For example, for an 8 bpp image,
             val = GET_DATA_BYTE(lines8[i], j);
         is equivalent to, but much faster than,
             pixGetPixel(pix, j, i, &val);
     (2) How much faster?  For 1 bpp, it's from 6 to 10x faster.
         For 8 bpp, it's an amazing 30x faster.  So if you are
         doing random access over a substantial part of the image,
         use this line ptr array.
     (3) When random access is used in conjunction with a stack,
         queue or heap, the overall computation time depends on
         the operations performed on each struct that is popped
         or pushed, and whether we are using a priority queue (O(logn))
         or a queue or stack (O(1)).  For example, for maze search,
         the overall ratio of time for line ptrs vs. pixGet/Set* is
            Maze type     Type                   Time ratio
              binary      queue                     0.4
              gray        heap (priority queue)     0.6
     (4) Because this returns a void** and the accessors take void*,
         the compiler cannot check the pointer types.  It is
         strongly recommended that you adopt a naming scheme for
         the returned ptr arrays that indicates the pixel depth.
         (This follows the original intent of Simonyi's "Hungarian"
         application notation, where naming is used proactively
         to make errors visibly obvious.)  By doing this, you can
         tell by inspection if the correct accessor is used.
         For example, for an 8 bpp pixg:
             void **lineg8 = pixGetLinePtrs(pixg, NULL);
             val = GET_DATA_BYTE(lineg8[i], j);  // fast access; BYTE, 8
             ...
             LEPT_FREE(lineg8);  // don't forget this
     (5) These are convenient for accessing bytes sequentially in an
         8 bpp grayscale image.  People who write image processing code
         on 8 bpp images are accustomed to grabbing pixels directly out
         of the raster array.  Note that for little endians, you first
         need to reverse the byte order in each 32-bit word.
         Here's a typical usage pattern:
             pixEndianByteSwap(pix);   // always safe; no-op on big-endians
             l_uint8 **lineptrs = (l_uint8 **)pixGetLinePtrs(pix, NULL);
             pixGetDimensions(pix, &w, &h, NULL);
             for (i = 0; i < h; i++) {
                 l_uint8 *line = lineptrs[i];
                 for (j = 0; j < w; j++) {
                     val = line[j];
                     ...
                 }
             }
             pixEndianByteSwap(pix);  // restore big-endian order
             LEPT_FREE(lineptrs);
         This can be done even more simply as follows:
             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 1949 of file pix1.c.

Referenced by pixaGetLinePtrs(), pixFindLargestRectangle(), pixSearchBinaryMaze(), and pixSearchGrayMaze().

◆ pixGetResolution()

l_ok pixGetResolution ( const PIX pix,
l_int32 *  pxres,
l_int32 *  pyres 
)

pixGetResolution()

Parameters
[in]pix
[out]pxres,pyres[optional] each can be null
Returns
0 if OK, 1 on error

Definition at line 1361 of file pix1.c.

References Pix::xres, and Pix::yres.

◆ pixGetText()

char* pixGetText ( PIX pix)

pixGetText()

Parameters
[in]pix
Returns
ptr to existing text string
Notes:
     (1) The text string belongs to the pix:
         * the caller must NOT free it
         * it must not be used after the pix is destroyed

Definition at line 1512 of file pix1.c.

References Pix::text.

Referenced by pixaAddPixWithText(), pixaAddTextlines(), pixaComparePhotoRegionsByHisto(), pixaCountText(), pixAddSingleTextblock(), pixAddText(), pixAddTextlines(), pixaDisplayTiledByIndex(), pixaDisplayTiledWithText(), pixDisplayOutliers(), pixGetTextCompNew(), pixGetTileCount(), recogAddDigitPadTemplates(), and recogCreateFromPixaNoFinish().

◆ pixGetTextCompNew()

l_uint8* pixGetTextCompNew ( PIX pix,
size_t *  psize 
)

pixGetTextCompNew()

Parameters
[in]pix
[out]psizethis number of bytes of returned binary data
Returns
ptr to binary data derived from the text string in the pix, after decoding and uncompressing
Notes:
     (1) The ascii string in the text field of the input pix was
         previously stored there using pixSetTextCompNew().
     (2) This retrieves the string and performs ascii85 decoding
         followed by decompression on it.  The returned binary data
         is owned by the caller and must be freed.

Definition at line 1617 of file pix1.c.

References pixGetText().

◆ pixMaxAspectRatio()

l_ok pixMaxAspectRatio ( PIX pixs,
l_float32 *  pratio 
)

pixMaxAspectRatio()

Parameters
[in]pixs32 bpp rgb
[out]pratiomax aspect ratio, >= 1.0; -1.0 on error
Returns
0 if OK, 1 on error

Definition at line 2013 of file pix1.c.

References pixGetDimensions().

◆ pixPrintStreamInfo()

l_ok pixPrintStreamInfo ( FILE *  fp,
const PIX pix,
const char *  text 
)

pixPrintStreamInfo()

Parameters
[in]fpfile stream
[in]pix
[in]text[optional] identifying string; can be null
Returns
0 if OK, 1 on error

Definition at line 2050 of file pix1.c.

◆ pixResizeImageData()

l_ok pixResizeImageData ( PIX pixd,
const PIX pixs 
)

pixResizeImageData()

Parameters
[in]pixdgets new uninitialized buffer for image data
[in]pixsdetermines the size of the buffer; not changed
Returns
0 if OK, 1 on error
Notes:
     (1) If the sizes of data in pixs and pixd are unequal, this
         frees the existing image data in pixd and allocates
         an uninitialized buffer that will hold the required amount
         of image data in pixs.  The image data from pixs is not
         copied into the new buffer.
     (2) On failure to allocate, pixd is unchanged.

Definition at line 768 of file pix1.c.

References pixGetDimensions(), and pixSizesEqual().

◆ pixSetColormap()

l_ok pixSetColormap ( PIX pix,
PIXCMAP colormap 
)

pixSetColormap()

Parameters
[in]pix
[in]colormapoptional; can be null.
Returns
0 if OK, 1 on error.
Notes:
     (1) If colormap is not defined, this is a no-op.
     (2) This destroys any existing colormap before assigning the
         new colormap to pix.
     (3) If the colormap is not valid, this returns 1.  The caller
         should check if there is a possibility that the pix and
         colormap depths differ.
     (4) This does not do the work of checking pixs for a pixel value
         that is out of bounds for the colormap -- that only needs to
         be done when reading and writing with an I/O library like
         png and gif.
     (5) Because colormaps are not ref counted, the new colormap
         must not belong to any other pix.

Definition at line 1699 of file pix1.c.

References Pix::colormap, pixcmapIsValid(), and pixDestroyColormap().

Referenced by fpixRenderContours(), makeColorfillTestData(), pixaDisplayRandomCmap(), pixCreateWithCmap(), pixDisplayDiffBinary(), and pixRenderRandomCmapPtaa().

◆ pixSetData()

l_int32 pixSetData ( PIX pix,
l_uint32 *  data 
)

pixSetData()

Parameters
[in]pix
[in]data
Returns
0 if OK, 1 on error
Notes:
     (1) This does not free any existing data.  To free existing
         data, use pixFreeData() before pixSetData().

Definition at line 1787 of file pix1.c.

References Pix::data.

◆ pixSetDimensions()

l_ok pixSetDimensions ( PIX pix,
l_int32  w,
l_int32  h,
l_int32  d 
)

pixSetDimensions()

Parameters
[in]pix
[in]w,h,duse 0 to skip the setting for any of these
Returns
0 if OK, 1 on error

Definition at line 1140 of file pix1.c.

◆ pixSetResolution()

l_ok pixSetResolution ( PIX pix,
l_int32  xres,
l_int32  yres 
)

pixSetResolution()

Parameters
[in]pix
[in]xres,yresuse 0 to skip setting a value for either of these
Returns
0 if OK, 1 on error

Definition at line 1387 of file pix1.c.

References Pix::xres, and Pix::yres.

Referenced by pixaComparePhotoRegionsByHisto(), and pixCreateFromPixcomp().

◆ pixSetText()

l_ok pixSetText ( PIX pix,
const char *  textstring 
)

pixSetText()

Parameters
[in]pix
[in]textstringcan be null
Returns
0 if OK, 1 on error
Notes:
     (1) This removes any existing textstring and puts a copy of
         the input textstring there.

Definition at line 1536 of file pix1.c.

References stringReplace(), and Pix::text.

Referenced by pixaSetText(), pixCreateFromPixcomp(), pixDisplayOutliers(), recogAddCharstrLabels(), recogIdentifyPixa(), and recogTrainFromBoot().

◆ pixSetTextCompNew()

l_ok pixSetTextCompNew ( PIX pix,
const l_uint8 *  data,
size_t  size 
)

pixSetTextCompNew()

Parameters
[in]pix
[in]databinary data
[in]sizenumber of bytes of binary data
Returns
0 if OK, 1 on error
Notes:
     (1) This receives binary data and performs compression and ascii85
         encoding on it.  The ascii result is stored in the input pix,
         replacing any string that may be there.
     (2) The input data can be reconstructed using pixGetTextCompNew().

Definition at line 1648 of file pix1.c.

References stringReplace(), and Pix::text.

◆ pixSizesEqual()

l_int32 pixSizesEqual ( const PIX pix1,
const PIX pix2 
)

pixSizesEqual()

Parameters
[in]pix1,pix2
Returns
1 if the two pix have same {h, w, d}; 0 otherwise.

Definition at line 1985 of file pix1.c.

Referenced by pixApplyVariableGrayMap(), pixCopyBorder(), pixEqualWithCmap(), pixGetPSNR(), pixResizeImageData(), pixSetLowContrast(), pixTestForSimilarity(), and pixVarThresholdToBinary().

◆ pixSwapAndDestroy()

l_ok pixSwapAndDestroy ( PIX **  ppixd,
PIX **  ppixs 
)

pixSwapAndDestroy()

Parameters
[out]ppixd[optional] input pixd can be null, and it must be different from pixs
[in,out]ppixswill be nulled after the swap
Returns
0 if OK, 1 on error
Notes:
     (1) Simple operation to change the handle name safely.
         After this operation, the original image in pixd has
         been destroyed, pixd points to what was pixs, and
         the input pixs ptr has been nulled.
     (2) This works safely whether or not pixs and pixd are cloned.
         If pixs is cloned, the other handles still point to
         the original image, with the ref count reduced by 1.
     (3) Usage example:
Pix *pix1 = pixRead("...");
Pix *pix2 = function(pix1, ...);
pixSwapAndDestroy(&pix1, &pix2);
pixDestroy(&pix1); // holds what was in pix2
void pixDestroy(PIX **ppix)
pixDestroy()
Definition: pix1.c:621
l_ok pixSwapAndDestroy(PIX **ppixd, PIX **ppixs)
pixSwapAndDestroy()
Definition: pix1.c:993
PIX * pixRead(const char *filename)
pixRead()
Definition: readfile.c:193
Definition: pix.h:139
Example with clones ([] shows ref count of image generated by the function):
Pix *pixs = pixRead("...");
Pix *pix1 = pixClone(pixs);
Pix *pix2 = function(pix1, ...); [1]
Pix *pix3 = pixClone(pix2); [1] --> [2]
pixSwapAndDestroy(&pix1, &pix2);
pixDestroy(&pixs); // still holds read image
pixDestroy(&pix1); // holds what was in pix2 [2] --> [1]
pixDestroy(&pix3); // holds what was in pix2 [1] --> [0]
PIX * pixClone(PIX *pixs)
pixClone()
Definition: pix1.c:593

Definition at line 993 of file pix1.c.

References pixClone(), and pixDestroy().

◆ pixTransferAllData()

l_ok pixTransferAllData ( PIX pixd,
PIX **  ppixs,
l_int32  copytext,
l_int32  copyformat 
)

pixTransferAllData()

Parameters
[in]pixdmust be different from pixs
[in,out]ppixswill be nulled if refcount goes to 0
[in]copytext1 to copy the text field; 0 to skip
[in]copyformat1 to copy the informat field; 0 to skip
Returns
0 if OK, 1 on error
Notes:
     (1) This does a complete data transfer from pixs to pixd,
         followed by the destruction of pixs (refcount permitting).
     (2) If the refcount of pixs is 1, pixs is destroyed.  Otherwise,
         the data in pixs is copied (rather than transferred) to pixd.
     (3) This operation, like all others with a pre-existing pixd,
         will side-effect any existing clones of pixd.  The pixd
         refcount does not change.
     (4) When might you use this?  Suppose you have an in-place Pix
         function (returning void) with the typical signature:
             void function-inplace(PIX *pix, ...)
         where "..." are non-pointer input parameters, and suppose
         further that you sometimes want to return an arbitrary Pix
         in place of the input Pix.  There are two ways you can do this:
         (a) The straightforward way is to change the function
             signature to take the address of the Pix ptr:
void function-inplace(PIX **ppix, ...) {
PIX *pixt = function-makenew(*ppix);
pixDestroy(ppix);
*ppix = pixt;
return;
}
Here, the input and returned pix are different, as viewed by the calling function, and the inplace function is expected to destroy the input pix to avoid a memory leak. (b) Keep the signature the same and use pixTransferAllData() to return the new Pix in the input Pix struct:
void function-inplace(PIX *pix, ...) {
PIX *pixt = function-makenew(pix);
pixTransferAllData(pix, &pixt, 0, 0);
// pixDestroy() is called on pixt
return;
}
l_ok pixTransferAllData(PIX *pixd, PIX **ppixs, l_int32 copytext, l_int32 copyformat)
pixTransferAllData()
Definition: pix1.c:902
Here, the input and returned pix are the same, as viewed by the calling function, and the inplace function must never destroy the input pix, because the calling function maintains an unchanged handle to it.

Definition at line 902 of file pix1.c.

◆ setPixMemoryManager()

void setPixMemoryManager ( alloc_fn  allocator,
dealloc_fn  deallocator 
)

setPixMemoryManager()

Parameters
[in]allocator[optional] use NULL to skip
[in]deallocator[optional] use NULL to skip
Returns
void
Notes:
     (1) Use this to change the alloc and/or dealloc functions;
         e.g., setPixMemoryManager(my_malloc, my_free).
     (2) The C99 standard (section 6.7.5.3, par. 8) says:
           A declaration of a parameter as "function returning type"
           shall be adjusted to "pointer to function returning type"
         so that it can be in either of these two forms:
           (a) type (function-ptr(type, ...))
           (b) type ((*function-ptr)(type, ...))
         because form (a) is implictly converted to form (b), as in the
         definition of struct PixMemoryManager above.  So, for example,
         we should be able to declare either of these:
           (a) void *(allocator(size_t))
           (b) void *((*allocator)(size_t))
         However, MSVC++ only accepts the second version.

Definition at line 296 of file pix1.c.

References pix_mem_manager.

Variable Documentation

◆ pix_mem_manager

struct PixMemoryManager pix_mem_manager
static
Initial value:
= {
&malloc,
&free
}

Default Pix memory manager

Definition at line 205 of file pix1.c.

Referenced by setPixMemoryManager().