/*====================================================================*
- Copyright (C) 2001 Leptonica. All rights reserved.
- This software is distributed in the hope that it will be
- useful, but with NO WARRANTY OF ANY KIND.
- No author or distributor accepts responsibility to anyone for the
- consequences of using this software, or for whether it serves any
- particular purpose or works at all, unless he or she says so in
- writing. Everyone is granted permission to copy, modify and
- redistribute this source code, for commercial or non-commercial
- purposes, with the following restrictions: (1) the origin of this
- source code must not be misrepresented; (2) modified versions must
- be plainly marked as such; and (3) this notice may not be removed
- or altered from any source or modified source distribution.
*====================================================================*/
/*
* pix1.c
*
* The pixN.c {N = 1,2,3,4} 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, fg/bg estimation, rectangle extraction
*
*
* This file has the basic constructors, destructors and field accessors
*
* Pix memory management (allows custom allocator and deallocator)
* static void *pix_malloc()
* static void pix_free()
* void setPixMemoryManager()
*
* Pix creation
* PIX *pixCreate()
* PIX *pixCreateNoInit()
* PIX *pixCreateTemplate()
* PIX *pixCreateTemplateNoInit()
* PIX *pixCreateHeader()
* PIX *pixClone()
*
* Pix destruction
* void pixDestroy()
* static void pixFree()
*
* Pix copy
* PIX *pixCopy()
* l_int32 pixResizeImageData()
* l_int32 pixCopyColormap()
* l_int32 pixSizesEqual()
* l_int32 pixTransferAllData()
*
* 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 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()
* char *pixGetText()
* l_int32 pixSetText()
* l_int32 pixAddText()
* l_int32 pixCopyText()
* 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 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 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.
*/
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "allheaders.h"
static void pixFree(PIX *pix);
/*-------------------------------------------------------------------------*
* Pix Memory Management *
* *
* These functions give you the freedom to specify at compile or run *
* time the allocator and deallocator to be used for pix. It has no *
* effect on memory management for other data structs, which are *
* controlled by the #defines in environ.h. Likewise, the #defines *
* in environ.h have no effect on the pix memory management. *
* The default functions are malloc and free. Use setPixMemoryManager() *
* to specify other functions to use. *
*-------------------------------------------------------------------------*/
struct PixMemoryManager
{
void *(*allocator)(size_t);
void (*deallocator)(void *);
};
static struct PixMemoryManager pix_mem_manager = {
&malloc,
&free
};
static void *
pix_malloc(size_t size)
{
#ifndef COMPILER_MSVC
return (*pix_mem_manager.allocator)(size);
#else /* COMPILER_MSVC */
/* Under MSVC++, pix_mem_manager is initialized after a call
* to pix_malloc. Just ignore the custom allocator feature. */
return malloc(size);
#endif /* COMPILER_MSVC */
}
static void
pix_free(void *ptr)
{
#ifndef COMPILER_MSVC
return (*pix_mem_manager.deallocator)(ptr);
#else /* COMPILER_MSVC */
/* Under MSVC++, pix_mem_manager is initialized after a call
* to pix_malloc. Just ignore the custom allocator feature. */
return free(ptr);
#endif /* COMPILER_MSVC */
}
/*!
* setPixMemoryManager()
*
* 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).
*/
#ifndef COMPILER_MSVC
void
setPixMemoryManager(void *(allocator(size_t)),
void (deallocator(void *)))
{
if (allocator) pix_mem_manager.allocator = allocator;
if (deallocator) pix_mem_manager.deallocator = deallocator;
return;
}
#else /* COMPILER_MSVC */
/* MSVC++ wants type (*fun)(types...) syntax */
void
setPixMemoryManager(void *((*allocator)(size_t)),
void ((*deallocator)(void *)))
{
if (allocator) pix_mem_manager.allocator = allocator;
if (deallocator) pix_mem_manager.deallocator = deallocator;
return;
}
#endif /* COMPILER_MSVC */
/*--------------------------------------------------------------------*
* Pix Creation *
*--------------------------------------------------------------------*/
/*!
* pixCreate()
*
* Input: width, height, depth
* Return: pixd (with data allocated and initialized to 0),
* or null on error
*/
PIX *
pixCreate(l_int32 width,
l_int32 height,
l_int32 depth)
{
PIX *pixd;
PROCNAME("pixCreate");
if ((pixd = pixCreateNoInit(width, height, depth)) == NULL)
return (PIX *)ERROR_PTR("pixd not made", procName, NULL);
memset(pixd->data, 0, 4 * pixd->wpl * pixd->h);
return pixd;
}
/*!
* pixCreateNoInit()
*
* 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 *
pixCreateNoInit(l_int32 width,
l_int32 height,
l_int32 depth)
{
l_int32 wpl;
PIX *pixd;
l_uint32 *data;
PROCNAME("pixCreateNoInit");
pixd = pixCreateHeader(width, height, depth);
if (!pixd) return NULL;
wpl = pixGetWpl(pixd);
if ((data = (l_uint32 *)pix_malloc(4 * wpl * height)) == NULL)
return (PIX *)ERROR_PTR("pix_malloc fail for data", procName, NULL);
pixSetData(pixd, data);
pixSetPadBits(pixd, 0);
return pixd;
}
/*!
* pixCreateTemplate()
*
* Input: pixs
* Return: pixd, or null on error
*
* Notes:
* (1) Makes a Pix of the same size as the input Pix, with the
* data array allocated and initialized to 0.
* (2) Copies the other fields, including colormap if it exists.
*/
PIX *
pixCreateTemplate(PIX *pixs)
{
PIX *pixd;
PROCNAME("pixCreateTemplate");
if (!pixs)
return (PIX *)ERROR_PTR("pixs not defined", procName, NULL);
if ((pixd = pixCreateTemplateNoInit(pixs)) == NULL)
return (PIX *)ERROR_PTR("pixd not made", procName, NULL);
memset(pixd->data, 0, 4 * pixd->wpl * pixd->h);
return pixd;
}
/*!
* pixCreateTemplateNoInit()
*
* Input: pixs
* Return: 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.
*/
PIX *
pixCreateTemplateNoInit(PIX *pixs)
{
l_int32 w, h, d;
PIX *pixd;
PROCNAME("pixCreateTemplateNoInit");
if (!pixs)
return (PIX *)ERROR_PTR("pixs not defined", procName, NULL);
pixGetDimensions(pixs, &w, &h, &d);
if ((pixd = pixCreateNoInit(w, h, d)) == NULL)
return (PIX *)ERROR_PTR("pixd not made", procName, NULL);
pixCopyResolution(pixd, pixs);
pixCopyColormap(pixd, pixs);
pixCopyText(pixd, pixs);
pixCopyInputFormat(pixd, pixs);
return pixd;
}
/*!
* pixCreateHeader()
*
* Input: width, height, depth
* Return: pixd (with no data allocated), or null on error
*/
PIX *
pixCreateHeader(l_int32 width,
l_int32 height,
l_int32 depth)
{
l_int32 wpl;
PIX *pixd;
PROCNAME("pixCreateHeader");
if ((depth != 1) && (depth != 2) && (depth != 4) && (depth != 8)
&& (depth != 16) && (depth != 24) && (depth != 32))
return (PIX *)ERROR_PTR("depth must be {1, 2, 4, 8, 16, 24, 32}",
procName, NULL);
if (width <= 0)
return (PIX *)ERROR_PTR("width must be > 0", procName, NULL);
if (height <= 0)
return (PIX *)ERROR_PTR("height must be > 0", procName, NULL);
if ((pixd = (PIX *)CALLOC(1, sizeof(PIX))) == NULL)
return (PIX *)ERROR_PTR("CALLOC fail for pixd", procName, NULL);
pixSetWidth(pixd, width);
pixSetHeight(pixd, height);
pixSetDepth(pixd, depth);
wpl = (width * depth + 31) / 32;
pixSetWpl(pixd, wpl);
pixd->refcount = 1;
pixd->informat = IFF_UNKNOWN;
return pixd;
}
/*!
* pixClone()
*
* 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.
*/
PIX *
pixClone(PIX *pixs)
{
PROCNAME("pixClone");
if (!pixs)
return (PIX *)ERROR_PTR("pixs not defined", procName, NULL);
pixChangeRefcount(pixs, 1);
return pixs;
}
/*--------------------------------------------------------------------*
* Pix Destruction *
*--------------------------------------------------------------------*/
/*!
* pixDestroy()
*
* 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.
*/
void
pixDestroy(PIX **ppix)
{
PIX *pix;
PROCNAME("pixDestroy");
if (!ppix) {
L_WARNING("ptr address is null!", procName);
return;
}
if ((pix = *ppix) == NULL)
return;
pixFree(pix);
*ppix = NULL;
return;
}
/*!
* pixFree()
*
* Input: pix
* Return: void
*
* Notes:
* (1) Decrements the ref count and, if 0, destroys the pix.
*/
static void
pixFree(PIX *pix)
{
l_uint32 *data;
char *text;
if (!pix) return;
pixChangeRefcount(pix, -1);
if (pixGetRefcount(pix) <= 0) {
if ((data = pixGetData(pix)) != NULL)
pix_free(data);
if ((text = pixGetText(pix)) != NULL)
FREE(text);
pixDestroyColormap(pix);
FREE(pix);
}
return;
}
/*-------------------------------------------------------------------------*
* Pix Copy *
*-------------------------------------------------------------------------*/
/*!
* pixCopy()
*
* 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.
*/
PIX *
pixCopy(PIX *pixd, /* can be null */
PIX *pixs)
{
l_int32 bytes;
l_uint32 *datas, *datad;
PROCNAME("pixCopy");
if (!pixs)
return (PIX *)ERROR_PTR("pixs not defined", procName, NULL);
if (pixs == pixd)
return pixd;
/* Total bytes in image data */
bytes = 4 * pixGetWpl(pixs) * pixGetHeight(pixs);
/* If we're making a new pix ... */
if (!pixd) {
if ((pixd = pixCreateTemplate(pixs)) == NULL)
return (PIX *)ERROR_PTR("pixd not made", procName, NULL);
datas = pixGetData(pixs);
datad = pixGetData(pixd);
memcpy((char *)datad, (char *)datas, bytes);
return pixd;
}
/* Reallocate image data if sizes are different */
if (pixResizeImageData(pixd, pixs) == 1)
return (PIX *)ERROR_PTR("reallocation of data failed", procName, NULL);
/* Copy non-image data fields */
pixCopyColormap(pixd, pixs);
pixCopyResolution(pixd, pixs);
pixCopyInputFormat(pixd, pixs);
pixCopyText(pixd, pixs);
/* Copy image data */
datas = pixGetData(pixs);
datad = pixGetData(pixd);
memcpy((char*)datad, (char*)datas, bytes);
return pixd;
}
/*!
* pixResizeImageData()
*
* 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
pixResizeImageData(PIX *pixd,
PIX *pixs)
{
l_int32 w, h, d, wpl, bytes;
l_uint32 *data;
PROCNAME("pixResizeImageData");
if (!pixs)
return ERROR_INT("pixs not defined", procName, 1);
if (!pixd)
return ERROR_INT("pixd not defined", procName, 1);
if (pixSizesEqual(pixs, pixd)) /* nothing to do */
return 0;
pixGetDimensions(pixs, &w, &h, &d);
wpl = pixGetWpl(pixs);
pixSetWidth(pixd, w);
pixSetHeight(pixd, h);
pixSetDepth(pixd, d);
pixSetWpl(pixd, wpl);
bytes = 4 * wpl * h;
pixFreeData(pixd); /* free any existing image data */
if ((data = (l_uint32 *)pix_malloc(bytes)) == NULL)
return ERROR_INT("pix_malloc fail for data", procName, 1);
pixSetData(pixd, data);
return 0;
}
/*!
* pixCopyColormap()
*
* 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
pixCopyColormap(PIX *pixd,
PIX *pixs)
{
PIXCMAP *cmaps, *cmapd;
PROCNAME("pixCopyColormap");
if (!pixs)
return ERROR_INT("pixs not defined", procName, 1);
if (!pixd)
return ERROR_INT("pixd not defined", procName, 1);
if (pixs == pixd)
return 0; /* no-op */
pixDestroyColormap(pixd);
if ((cmaps = pixGetColormap(pixs)) == NULL) /* not an error */
return 0;
if ((cmapd = pixcmapCopy(cmaps)) == NULL)
return ERROR_INT("cmapd not made", procName, 1);
pixSetColormap(pixd, cmapd);
return 0;
}
/*!
* pixSizesEqual()
*
* Input: two pix
* Return: 1 if the two pix have same {h, w, d}; 0 otherwise.
*/
l_int32
pixSizesEqual(PIX *pix1,
PIX *pix2)
{
PROCNAME("pixSizesEqual");
if (!pix1 || !pix2)
return ERROR_INT("pix1 and pix2 not both defined", procName, 0);
if (pix1 == pix2)
return 1;
if ((pixGetWidth(pix1) != pixGetWidth(pix2)) ||
(pixGetHeight(pix1) != pixGetHeight(pix2)) ||
(pixGetDepth(pix1) != pixGetDepth(pix2)))
return 0;
else
return 1;
}
/*!
* pixTransferAllData()
*
* 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); // pixt is destroyed
* 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.
*/
l_int32
pixTransferAllData(PIX *pixd,
PIX **ppixs,
l_int32 copytext,
l_int32 copyformat)
{
l_int32 nbytes;
PIX *pixs;
PROCNAME("pixTransferAllData");
if (!ppixs)
return ERROR_INT("&pixs not defined", procName, 1);
if ((pixs = *ppixs) == NULL)
return ERROR_INT("pixs not defined", procName, 1);
if (!pixd)
return ERROR_INT("pixd not defined", procName, 1);
if (pixs == pixd) /* no-op */
return ERROR_INT("pixd == pixs", procName, 1);
if (pixGetRefcount(pixs) == 1) { /* transfer the data, cmap, text */
pixFreeData(pixd); /* dealloc any existing data */
pixSetData(pixd, pixGetData(pixs)); /* transfer new data from pixs */
pixs->data = NULL; /* pixs no longer owns data */
pixSetColormap(pixd, pixGetColormap(pixs)); /* frees old; sets new */
pixs->colormap = NULL; /* pixs no longer owns colormap */
if (copytext) {
pixSetText(pixd, pixGetText(pixs));
pixSetText(pixs, NULL);
}
} else { /* preserve pixs by making a copy of the data, cmap, text */
pixResizeImageData(pixd, pixs);
nbytes = 4 * pixGetWpl(pixs) * pixGetHeight(pixs);
memcpy((char *)pixGetData(pixd), (char *)pixGetData(pixs), nbytes);
pixCopyColormap(pixd, pixs);
if (copytext)
pixCopyText(pixd, pixs);
}
pixCopyResolution(pixd, pixs);
pixCopyDimensions(pixd, pixs);
if (copyformat)
pixCopyInputFormat(pixd, pixs);
/* This will destroy pixs if data was transferred;
* otherwise, it just decrements its refcount. */
pixDestroy(ppixs);
return 0;
}
/*--------------------------------------------------------------------*
* Accessors *
*--------------------------------------------------------------------*/
l_int32
pixGetWidth(PIX *pix)
{
PROCNAME("pixGetWidth");
if (!pix)
return ERROR_INT("pix not defined", procName, UNDEF);
return pix->w;
}
l_int32
pixSetWidth(PIX *pix,
l_int32 width)
{
PROCNAME("pixSetWidth");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
if (width < 0) {
pix->w = 0;
return ERROR_INT("width must be >= 0", procName, 1);
}
pix->w = width;
return 0;
}
l_int32
pixGetHeight(PIX *pix)
{
PROCNAME("pixGetHeight");
if (!pix)
return ERROR_INT("pix not defined", procName, UNDEF);
return pix->h;
}
l_int32
pixSetHeight(PIX *pix,
l_int32 height)
{
PROCNAME("pixSetHeight");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
if (height < 0) {
pix->h = 0;
return ERROR_INT("h must be >= 0", procName, 1);
}
pix->h = height;
return 0;
}
l_int32
pixGetDepth(PIX *pix)
{
PROCNAME("pixGetDepth");
if (!pix)
return ERROR_INT("pix not defined", procName, UNDEF);
return pix->d;
}
l_int32
pixSetDepth(PIX *pix,
l_int32 depth)
{
PROCNAME("pixSetDepth");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
if (depth < 1)
return ERROR_INT("d must be >= 1", procName, 1);
pix->d = depth;
return 0;
}
/*!
* pixGetDimensions()
*
* Input: pix
* &w, &h, &d (<optional return>; each can be null)
* Return: 0 if OK, 1 on error
*/
l_int32
pixGetDimensions(PIX *pix,
l_int32 *pw,
l_int32 *ph,
l_int32 *pd)
{
PROCNAME("pixGetDimensions");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
if (pw) *pw = pix->w;
if (ph) *ph = pix->h;
if (pd) *pd = pix->d;
return 0;
}
/*!
* pixSetDimensions()
*
* Input: pix
* w, h, d (use 0 to skip the setting for any of these)
* Return: 0 if OK, 1 on error
*/
l_int32
pixSetDimensions(PIX *pix,
l_int32 w,
l_int32 h,
l_int32 d)
{
PROCNAME("pixSetDimensions");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
if (w > 0) pixSetWidth(pix, w);
if (h > 0) pixSetHeight(pix, h);
if (d > 0) pixSetDepth(pix, d);
return 0;
}
/*!
* pixCopyDimensions()
*
* Input: pixd
* pixd
* Return: 0 if OK, 1 on error
*/
l_int32
pixCopyDimensions(PIX *pixd,
PIX *pixs)
{
PROCNAME("pixCopyDimensions");
if (!pixd)
return ERROR_INT("pixd not defined", procName, 1);
if (!pixs)
return ERROR_INT("pixs not defined", procName, 1);
if (pixs == pixd)
return 0; /* no-op */
pixSetWidth(pixd, pixGetWidth(pixs));
pixSetHeight(pixd, pixGetHeight(pixs));
pixSetDepth(pixd, pixGetDepth(pixs));
pixSetWpl(pixd, pixGetWpl(pixs));
return 0;
}
l_int32
pixGetWpl(PIX *pix)
{
PROCNAME("pixGetWpl");
if (!pix)
return ERROR_INT("pix not defined", procName, UNDEF);
return pix->wpl;
}
l_int32
pixSetWpl(PIX *pix,
l_int32 wpl)
{
PROCNAME("pixSetWpl");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
pix->wpl = wpl;
return 0;
}
l_int32
pixGetRefcount(PIX *pix)
{
PROCNAME("pixGetRefcount");
if (!pix)
return ERROR_INT("pix not defined", procName, UNDEF);
return pix->refcount;
}
l_int32
pixChangeRefcount(PIX *pix,
l_int32 delta)
{
PROCNAME("pixChangeRefcount");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
pix->refcount += delta;
return 0;
}
l_uint32
pixGetXRes(PIX *pix)
{
PROCNAME("pixGetXRes");
if (!pix)
return ERROR_INT("pix not defined", procName, 0);
return pix->xres;
}
l_int32
pixSetXRes(PIX *pix,
l_uint32 res)
{
PROCNAME("pixSetXRes");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
pix->xres = res;
return 0;
}
l_uint32
pixGetYRes(PIX *pix)
{
PROCNAME("pixGetYRes");
if (!pix)
return ERROR_INT("pix not defined", procName, 0);
return pix->yres;
}
l_int32
pixSetYRes(PIX *pix,
l_uint32 res)
{
PROCNAME("pixSetYRes");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
pix->yres = res;
return 0;
}
/*!
* pixGetResolution()
*
* Input: pix
* &xres, &yres (<optional return>; each can be null)
* Return: 0 if OK, 1 on error
*/
l_int32
pixGetResolution(PIX *pix,
l_uint32 *pxres,
l_uint32 *pyres)
{
PROCNAME("pixGetResolution");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
if (pxres) *pxres = pix->xres;
if (pyres) *pyres = pix->yres;
return 0;
}
/*!
* pixSetResolution()
*
* Input: pix
* xres, yres (use 0 to skip the setting for either of these)
* Return: 0 if OK, 1 on error
*/
l_int32
pixSetResolution(PIX *pix,
l_uint32 xres,
l_uint32 yres)
{
PROCNAME("pixSetResolution");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
if (xres > 0) pix->xres = xres;
if (yres > 0) pix->yres = yres;
return 0;
}
l_int32
pixCopyResolution(PIX *pixd,
PIX *pixs)
{
PROCNAME("pixCopyResolution");
if (!pixs)
return ERROR_INT("pixs not defined", procName, 1);
if (!pixd)
return ERROR_INT("pixd not defined", procName, 1);
if (pixs == pixd)
return 0; /* no-op */
pixSetXRes(pixd, pixGetXRes(pixs));
pixSetYRes(pixd, pixGetYRes(pixs));
return 0;
}
l_int32
pixScaleResolution(PIX *pix,
l_float32 xscale,
l_float32 yscale)
{
PROCNAME("pixScaleResolution");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
if (pix->xres != 0 && pix->yres != 0) {
pix->xres = (l_uint32)(xscale * (l_float32)(pix->xres) + 0.5);
pix->yres = (l_uint32)(yscale * (l_float32)(pix->yres) + 0.5);
}
return 0;
}
l_int32
pixGetInputFormat(PIX *pix)
{
PROCNAME("pixGetInputFormat");
if (!pix)
return ERROR_INT("pix not defined", procName, UNDEF);
return pix->informat;
}
l_int32
pixSetInputFormat(PIX *pix,
l_int32 informat)
{
PROCNAME("pixSetInputFormat");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
pix->informat = informat;
return 0;
}
l_int32
pixCopyInputFormat(PIX *pixd,
PIX *pixs)
{
PROCNAME("pixCopyInputFormat");
if (!pixs)
return ERROR_INT("pixs not defined", procName, 1);
if (!pixd)
return ERROR_INT("pixd not defined", procName, 1);
if (pixs == pixd)
return 0; /* no-op */
pixSetInputFormat(pixd, pixGetInputFormat(pixs));
return 0;
}
/*!
* pixGetText()
*
* Input: pix
* Return: ptr to existing text string
*
* Notes:
* (1) The text string belongs to the pix. The caller must
* NOT free it!
*/
char *
pixGetText(PIX *pix)
{
PROCNAME("pixGetText");
if (!pix)
return (char *)ERROR_PTR("pix not defined", procName, NULL);
return pix->text;
}
/*!
* pixSetText()
*
* 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
pixSetText(PIX *pix,
const char *textstring)
{
PROCNAME("pixSetText");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
stringReplace(&pix->text, textstring);
return 0;
}
/*!
* pixAddText()
*
* 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
pixAddText(PIX *pix,
const char *textstring)
{
char *newstring;
PROCNAME("pixAddText");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
newstring = stringJoin(pixGetText(pix), textstring);
stringReplace(&pix->text, newstring);
FREE(newstring);
return 0;
}
l_int32
pixCopyText(PIX *pixd,
PIX *pixs)
{
PROCNAME("pixCopyText");
if (!pixs)
return ERROR_INT("pixs not defined", procName, 1);
if (!pixd)
return ERROR_INT("pixd not defined", procName, 1);
if (pixs == pixd)
return 0; /* no-op */
pixSetText(pixd, pixGetText(pixs));
return 0;
}
PIXCMAP *
pixGetColormap(PIX *pix)
{
PROCNAME("pixGetColormap");
if (!pix)
return (PIXCMAP *)ERROR_PTR("pix not defined", procName, NULL);
return pix->colormap;
}
/*!
* pixSetColormap()
*
* 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
pixSetColormap(PIX *pix,
PIXCMAP *colormap)
{
PROCNAME("pixSetColormap");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
pixDestroyColormap(pix);
pix->colormap = colormap;
return 0;
}
/*!
* pixDestroyColormap()
*
* Input: pix
* Return: 0 if OK, 1 on error
*/
l_int32
pixDestroyColormap(PIX *pix)
{
PIXCMAP *cmap;
PROCNAME("pixDestroyColormap");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
if ((cmap = pix->colormap) != NULL) {
pixcmapDestroy(&cmap);
pix->colormap = NULL;
}
return 0;
}
/*!
* pixGetData()
*
* 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_uint32 *
pixGetData(PIX *pix)
{
PROCNAME("pixGetData");
if (!pix)
return (l_uint32 *)ERROR_PTR("pix not defined", procName, NULL);
return pix->data;
}
/*!
* pixSetData()
*
* Notes:
* (1) This does not free any existing data. To free existing
* data, use pixFreeData() before pixSetData().
*/
l_int32
pixSetData(PIX *pix,
l_uint32 *data)
{
PROCNAME("pixSetData");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
pix->data = data;
return 0;
}
/*!
* pixExtractData()
*
* 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_uint32 *
pixExtractData(PIX *pixs)
{
l_int32 count, bytes;
l_uint32 *data, *datas;
PROCNAME("pixExtractData");
if (!pixs)
return (l_uint32 *)ERROR_PTR("pixs not defined", procName, NULL);
count = pixGetRefcount(pixs);
if (count == 1) { /* extract */
data = pixGetData(pixs);
pixSetData(pixs, NULL);
}
else { /* refcount > 1; copy */
bytes = 4 * pixGetWpl(pixs) * pixGetHeight(pixs);
datas = pixGetData(pixs);
if ((data = (l_uint32 *)pix_malloc(bytes)) == NULL)
return (l_uint32 *)ERROR_PTR("data not made", procName, NULL);
memcpy((char *)data, (char *)datas, bytes);
}
return data;
}
/*!
* pixFreeData()
*
* 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().
*/
l_int32
pixFreeData(PIX *pix)
{
l_uint32 *data;
PROCNAME("pixFreeData");
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
if ((data = pixGetData(pix)) != NULL) {
pix_free(data);
pix->data = NULL;
}
return 0;
}
/*--------------------------------------------------------------------*
* Pix line ptrs *
*--------------------------------------------------------------------*/
/*!
* pixGetLinePtrs()
*
* 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
*/
void **
pixGetLinePtrs(PIX *pix,
l_int32 *psize)
{
l_int32 i, h, wpl;
l_uint32 *data;
void **lines;
PROCNAME("pixGetLinePtrs");
if (!pix)
return (void **)ERROR_PTR("pix not defined", procName, NULL);
h = pixGetHeight(pix);
if ((lines = (void **)CALLOC(h, sizeof(void *))) == NULL)
return (void **)ERROR_PTR("lines not made", procName, NULL);
wpl = pixGetWpl(pix);
data = pixGetData(pix);
for (i = 0; i < h; i++)
lines[i] = (void *)(data + i * wpl);
return lines;
}
/*--------------------------------------------------------------------*
* Print output for debugging *
*--------------------------------------------------------------------*/
/*!
* pixPrintStreamInfo()
*
* Input: fp (file stream)
* pix
* text (<optional> identifying string; can be null)
* Return: 0 if OK, 1 on error
*/
l_int32
pixPrintStreamInfo(FILE *fp,
PIX *pix,
const char *text)
{
PIXCMAP *cmap;
PROCNAME("pixPrintStreamInfo");
if (!fp)
return ERROR_INT("fp not defined", procName, 1);
if (!pix)
return ERROR_INT("pix not defined", procName, 1);
if (text)
fprintf(fp, " Pix Info for %s:\n", text);
fprintf(fp, " width = %d, height = %d, depth = %d\n",
pixGetWidth(pix), pixGetHeight(pix), pixGetDepth(pix));
fprintf(fp, " wpl = %d, data = %p, refcount = %d\n",
pixGetWpl(pix), pixGetData(pix), pixGetRefcount(pix));
if ((cmap = pixGetColormap(pix)) != NULL)
pixcmapWriteStream(fp, cmap);
else
fprintf(fp, " no colormap\n");
return 0;
}