Leptonica
1.54
|
static void pix_free | ( | void * | ptr | ) | [static] |
static void* pix_malloc | ( | size_t | size | ) | [static] |
l_int32 pixAddText | ( | PIX * | pix, |
const char * | textstring | ||
) |
Input: pix textstring Return: 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.
l_int32 pixChangeRefcount | ( | PIX * | pix, |
l_int32 | delta | ||
) |
Input: pix Return: 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.
Input: pixd (<optional>; can be null, or equal to pixs, or different from pixs) pixs Return: 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.
l_int32 pixCopyColormap | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
Input: src and dest Pix Return: 0 if OK, 1 on error
Notes: (1) This always destroys any colormap in pixd (except if the operation is a no-op.
l_int32 pixCopyDimensions | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
Input: pixd pixd Return: 0 if OK, 1 on error
l_int32 pixCopyInputFormat | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
l_int32 pixCopyResolution | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
l_int32 pixCopyText | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
Input: width, height, depth Return: pixd (with data allocated and initialized to 0), or null on error
PIX* pixCreateHeader | ( | l_int32 | width, |
l_int32 | height, | ||
l_int32 | depth | ||
) |
Input: width, height, depth Return: pixd (with no data allocated), or null on error
PIX* pixCreateNoInit | ( | l_int32 | width, |
l_int32 | height, | ||
l_int32 | depth | ||
) |
Input: width, height, depth Return: pixd (with data allocated but not initialized), or null on error
Notes: (1) Must set pad bits to avoid reading unitialized data, because some optimized routines (e.g., pixConnComp()) read from pad bits.
PIX* pixCreateTemplate | ( | PIX * | pixs | ) |
PIX* pixCreateTemplateNoInit | ( | PIX * | pixs | ) |
void pixDestroy | ( | PIX ** | ppix | ) |
Input: &pix <will be="" nulled>=""> Return: void
Notes: (1) Decrements the ref count and, if 0, destroys the pix. (2) Always nulls the input ptr.
l_int32 pixDestroyColormap | ( | PIX * | pix | ) |
Input: pix Return: 0 if OK, 1 on error
l_uint32* pixExtractData | ( | PIX * | pixs | ) |
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.
l_int32 pixFreeData | ( | PIX * | pix | ) |
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().
PIXCMAP* pixGetColormap | ( | PIX * | pix | ) |
l_uint32* pixGetData | ( | PIX * | pix | ) |
Notes: (1) This gives a new handle for the data. The data is still owned by the pix, so do not call FREE() on it.
l_int32 pixGetDepth | ( | PIX * | pix | ) |
Input: pix &w, &h, &d (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
l_int32 pixGetHeight | ( | PIX * | pix | ) |
l_int32 pixGetInputFormat | ( | PIX * | pix | ) |
void** pixGetLinePtrs | ( | PIX * | pix, |
l_int32 * | psize | ||
) |
Input: pix &size (<optional return>=""> array size, which is the pix height) Return: 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 ... 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 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);
l_int32 pixGetRefcount | ( | PIX * | pix | ) |
l_int32 pixGetResolution | ( | PIX * | pix, |
l_int32 * | pxres, | ||
l_int32 * | pyres | ||
) |
Input: pix &xres, &yres (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
char* pixGetText | ( | PIX * | pix | ) |
Input: pix Return: ptr to existing text string
Notes: (1) The text string belongs to the pix. The caller must NOT free it!
l_int32 pixGetWidth | ( | PIX * | pix | ) |
l_int32 pixGetXRes | ( | PIX * | pix | ) |
l_int32 pixGetYRes | ( | PIX * | pix | ) |
l_int32 pixPrintStreamInfo | ( | FILE * | fp, |
PIX * | pix, | ||
const char * | text | ||
) |
Input: fp (file stream) pix text (<optional> identifying string; can be null) Return: 0 if OK, 1 on error
l_int32 pixResizeImageData | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
Input: pixd (gets new uninitialized buffer for image data) pixs (determines the size of the buffer; not changed) Return: 0 if OK, 1 on error
Notes: (1) This removes any existing image data from pixd and allocates an uninitialized buffer that will hold the amount of image data that is in pixs.
l_int32 pixScaleResolution | ( | PIX * | pix, |
l_float32 | xscale, | ||
l_float32 | yscale | ||
) |
l_int32 pixSetColormap | ( | PIX * | pix, |
PIXCMAP * | colormap | ||
) |
Input: pix colormap (to be assigned) Return: 0 if OK, 1 on error.
Notes: (1) Unlike with the pix data field, pixSetColormap() destroys any existing colormap before assigning the new one. Because colormaps are not ref counted, it is important that the new colormap does not belong to any other pix.
l_int32 pixSetData | ( | PIX * | pix, |
l_uint32 * | data | ||
) |
Notes: (1) This does not free any existing data. To free existing data, use pixFreeData() before pixSetData().
l_int32 pixSetDepth | ( | PIX * | pix, |
l_int32 | depth | ||
) |
Input: pix w, h, d (use 0 to skip the setting for any of these) Return: 0 if OK, 1 on error
l_int32 pixSetHeight | ( | PIX * | pix, |
l_int32 | height | ||
) |
l_int32 pixSetInputFormat | ( | PIX * | pix, |
l_int32 | informat | ||
) |
l_int32 pixSetResolution | ( | PIX * | pix, |
l_int32 | xres, | ||
l_int32 | yres | ||
) |
Input: pix xres, yres (use 0 to skip the setting for either of these) Return: 0 if OK, 1 on error
l_int32 pixSetText | ( | PIX * | pix, |
const char * | textstring | ||
) |
Input: pix textstring (can be null) Return: 0 if OK, 1 on error
Notes: (1) This removes any existing textstring and puts a copy of the input textstring there.
l_int32 pixSetWidth | ( | PIX * | pix, |
l_int32 | width | ||
) |
l_int32 pixSetXRes | ( | PIX * | pix, |
l_int32 | res | ||
) |
l_int32 pixSetYRes | ( | PIX * | pix, |
l_int32 | res | ||
) |
l_int32 pixSizesEqual | ( | PIX * | pix1, |
PIX * | pix2 | ||
) |
Input: two pix Return: 1 if the two pix have same {h, w, d}; 0 otherwise.
l_int32 pixSwapAndDestroy | ( | PIX ** | ppixd, |
PIX ** | ppixs | ||
) |
Input: &pixd (<optional, return> input pixd can be null, and it must be different from pixs) &pixs (will be nulled after the swap) Return: 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 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]
Input: pixd (must be different from pixs) &pixs (will be nulled if refcount goes to 0) copytext (1 to copy the text field; 0 to skip) copyformat (1 to copy the informat field; 0 to skip) Return: 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; } 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.
void setPixMemoryManager | ( | void * | allocator(size_t), |
void(deallocator(void *)) | |||
) |
Input: allocator (<optional>; use null to skip) deallocator (<optional>; use null to skip) Return: void
Notes: (1) Use this to change the alloc and/or dealloc functions; e.g., setPixMemoryManager(my_malloc, my_free).
const char* ImageFileFormatExtensions[] |
struct PixMemoryManager pix_mem_manager [static] |
{ &malloc, &free }