pixabasic.c

Go to the documentation of this file.

/*====================================================================*
 -  Copyright (C) 2001 Leptonica.  All rights reserved.
 -
 -  Redistribution and use in source and binary forms, with or without
 -  modification, are permitted provided that the following conditions
 -  are met:
 -  1. Redistributions of source code must retain the above copyright
 -     notice, this list of conditions and the following disclaimer.
 -  2. Redistributions in binary form must reproduce the above
 -     copyright notice, this list of conditions and the following
 -     disclaimer in the documentation and/or other materials
 -     provided with the distribution.
 -
 -  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 -  ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 -  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 -  A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL ANY
 -  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 -  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 -  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 -  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 -  OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 -  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 -  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *====================================================================*/
 
#ifdef HAVE_CONFIG_H
#include <config_auto.h>
#endif  /* HAVE_CONFIG_H */
 
#include <string.h>
#include "allheaders.h"
#include "pix_internal.h"
 
    /* Bounds on array sizes */
static const size_t  MaxInitPtrArraySize = 100000;
static const size_t  MaxPixaPtrArraySize = 5000000;
static const size_t  MaxPixaaPtrArraySize = 1000000;
static const size_t  InitialPtrArraySize = 20;      
    /* Static functions */
static l_int32 pixaExtendArray(PIXA  *pixa);
static l_int32 pixaaExtendArray(PIXAA *paa);
 
/*---------------------------------------------------------------------*
 *                    Pixa creation, destruction, copy                 *
 *---------------------------------------------------------------------*/
PIXA *
pixaCreate(l_int32  n)
{
PIXA  *pixa;
 
    if (n <= 0 || n > MaxInitPtrArraySize)
        n = InitialPtrArraySize;
 
    pixa = (PIXA *)LEPT_CALLOC(1, sizeof(PIXA));
    pixa->n = 0;
    pixa->nalloc = n;
    pixa->refcount = 1;
    pixa->pix = (PIX **)LEPT_CALLOC(n, sizeof(PIX *));
    pixa->boxa = boxaCreate(n);
    if (!pixa->pix || !pixa->boxa) {
        pixaDestroy(&pixa);
        return (PIXA *)ERROR_PTR("pix or boxa not made", __func__, NULL);
    }
    return pixa;
}
 
 
PIXA *
pixaCreateFromPix(PIX     *pixs,
                  l_int32  n,
                  l_int32  cellw,
                  l_int32  cellh)
{
l_int32  w, h, d, nw, nh, i, j, index;
PIX     *pix1, *pix2;
PIXA    *pixa;
 
    if (!pixs)
        return (PIXA *)ERROR_PTR("pixs not defined", __func__, NULL);
    if (n <= 0)
        return (PIXA *)ERROR_PTR("n must be > 0", __func__, NULL);
 
    if ((pixa = pixaCreate(n)) == NULL)
        return (PIXA *)ERROR_PTR("pixa not made", __func__, NULL);
    pixGetDimensions(pixs, &w, &h, &d);
    if ((pix1 = pixCreate(cellw, cellh, d)) == NULL) {
        pixaDestroy(&pixa);
        return (PIXA *)ERROR_PTR("pix1 not made", __func__, NULL);
    }
 
    nw = (w + cellw - 1) / cellw;
    nh = (h + cellh - 1) / cellh;
    for (i = 0, index = 0; i < nh; i++) {
        for (j = 0; j < nw && index < n; j++, index++) {
            pixRasterop(pix1, 0, 0, cellw, cellh, PIX_SRC, pixs,
                   j * cellw, i * cellh);
            if (d == 1 && !pixClipToForeground(pix1, &pix2, NULL))
                pixaAddPix(pixa, pix2, L_INSERT);
            else
                pixaAddPix(pixa, pix1, L_COPY);
        }
    }
 
    pixDestroy(&pix1);
    return pixa;
}
 
 
PIXA *
pixaCreateFromBoxa(PIX      *pixs,
                   BOXA     *boxa,
                   l_int32   start,
                   l_int32   num,
                   l_int32  *pcropwarn)
{
l_int32  i, n, end, w, h, wbox, hbox, cropwarn;
BOX     *box, *boxc;
PIX     *pixd;
PIXA    *pixad;
 
    if (!pixs)
        return (PIXA *)ERROR_PTR("pixs not defined", __func__, NULL);
    if (!boxa)
        return (PIXA *)ERROR_PTR("boxa not defined", __func__, NULL);
    if (num < 0)
        return (PIXA *)ERROR_PTR("num must be >= 0", __func__, NULL);
 
    n = boxaGetCount(boxa);
    end = (num == 0) ? n - 1 : L_MIN(start + num - 1, n - 1);
    if ((pixad = pixaCreate(end - start + 1)) == NULL)
        return (PIXA *)ERROR_PTR("pixad not made", __func__, NULL);
 
    boxaGetExtent(boxa, &wbox, &hbox, NULL);
    pixGetDimensions(pixs, &w, &h, NULL);
    cropwarn = FALSE;
    if (wbox > w || hbox > h)
        cropwarn = TRUE;
    if (pcropwarn)
        *pcropwarn = cropwarn;
 
    for (i = start; i <= end; i++) {
        box = boxaGetBox(boxa, i, L_COPY);
        if (cropwarn) {  /* if box is outside pixs, pixd is NULL */
            pixd = pixClipRectangle(pixs, box, &boxc);  /* may be NULL */
            if (pixd) {
                pixaAddPix(pixad, pixd, L_INSERT);
                pixaAddBox(pixad, boxc, L_INSERT);
            }
            boxDestroy(&box);
        } else {
            pixd = pixClipRectangle(pixs, box, NULL);
            pixaAddPix(pixad, pixd, L_INSERT);
            pixaAddBox(pixad, box, L_INSERT);
        }
    }
 
    return pixad;
}
 
 
PIXA *
pixaSplitPix(PIX      *pixs,
             l_int32   nx,
             l_int32   ny,
             l_int32   borderwidth,
             l_uint32  bordercolor)
{
l_int32  w, h, d, cellw, cellh, i, j;
PIX     *pix1;
PIXA    *pixa;
 
    if (!pixs)
        return (PIXA *)ERROR_PTR("pixs not defined", __func__, NULL);
    if (nx <= 0 || ny <= 0)
        return (PIXA *)ERROR_PTR("nx and ny must be > 0", __func__, NULL);
    borderwidth = L_MAX(0, borderwidth);
 
    if ((pixa = pixaCreate(nx * ny)) == NULL)
        return (PIXA *)ERROR_PTR("pixa not made", __func__, NULL);
    pixGetDimensions(pixs, &w, &h, &d);
    cellw = (w + nx - 1) / nx;  /* round up */
    cellh = (h + ny - 1) / ny;
 
    for (i = 0; i < ny; i++) {
        for (j = 0; j < nx; j++) {
            if ((pix1 = pixCreate(cellw + 2 * borderwidth,
                                  cellh + 2 * borderwidth, d)) == NULL) {
                pixaDestroy(&pixa);
                return (PIXA *)ERROR_PTR("pix1 not made", __func__, NULL);
            }
            pixCopyColormap(pix1, pixs);
            if (borderwidth == 0) {  /* initialize full image to white */
                if (d == 1)
                    pixClearAll(pix1);
                else
                    pixSetAll(pix1);
            } else {
                pixSetAllArbitrary(pix1, bordercolor);
            }
            pixRasterop(pix1, borderwidth, borderwidth, cellw, cellh,
                        PIX_SRC, pixs, j * cellw, i * cellh);
            pixaAddPix(pixa, pix1, L_INSERT);
        }
    }
 
    return pixa;
}
 
 
void
pixaDestroy(PIXA  **ppixa)
{
l_int32  i;
PIXA    *pixa;
 
    if (ppixa == NULL) {
        L_WARNING("ptr address is NULL!\n", __func__);
        return;
    }
 
    if ((pixa = *ppixa) == NULL)
        return;
 
        /* Decrement the refcount.  If it is 0, destroy the pixa. */
    if (--pixa->refcount == 0) {
        for (i = 0; i < pixa->n; i++)
            pixDestroy(&pixa->pix[i]);
        LEPT_FREE(pixa->pix);
        boxaDestroy(&pixa->boxa);
        LEPT_FREE(pixa);
    }
 
    *ppixa = NULL;
}
 
 
PIXA *
pixaCopy(PIXA    *pixa,
         l_int32  copyflag)
{
l_int32  i, nb;
BOX     *boxc = NULL;
PIX     *pixc;
PIXA    *pixac;
 
    if (!pixa)
        return (PIXA *)ERROR_PTR("pixa not defined", __func__, NULL);
 
    if (copyflag == L_CLONE) {
        ++pixa->refcount;
        return pixa;
    }
 
    if (copyflag != L_COPY && copyflag != L_COPY_CLONE)
        return (PIXA *)ERROR_PTR("invalid copyflag", __func__, NULL);
 
    if ((pixac = pixaCreate(pixa->n)) == NULL)
        return (PIXA *)ERROR_PTR("pixac not made", __func__, NULL);
    nb = pixaGetBoxaCount(pixa);
    for (i = 0; i < pixa->n; i++) {
        if (copyflag == L_COPY) {
            pixc = pixaGetPix(pixa, i, L_COPY);
            if (i < nb) boxc = pixaGetBox(pixa, i, L_COPY);
        } else {  /* copy-clone */
            pixc = pixaGetPix(pixa, i, L_CLONE);
            if (i < nb) boxc = pixaGetBox(pixa, i, L_CLONE);
        }
        pixaAddPix(pixac, pixc, L_INSERT);
        if (i < nb) pixaAddBox(pixac, boxc, L_INSERT);
    }
 
    return pixac;
}
 
 
 
/*---------------------------------------------------------------------*
 *                              Pixa addition                          *
 *---------------------------------------------------------------------*/
l_ok
pixaAddPix(PIXA    *pixa,
           PIX     *pix,
           l_int32  copyflag)
{
l_int32  n;
PIX     *pixc;
 
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    if (copyflag == L_INSERT)
        pixc = pix;
    else if (copyflag == L_COPY)
        pixc = pixCopy(NULL, pix);
    else if (copyflag == L_CLONE)
        pixc = pixClone(pix);
    else
        return ERROR_INT("invalid copyflag", __func__, 1);
    if (!pixc)
        return ERROR_INT("pixc not made", __func__, 1);
 
    n = pixaGetCount(pixa);
    if (n >= pixa->nalloc) {
        if (pixaExtendArray(pixa)) {
            if (copyflag != L_INSERT)
                pixDestroy(&pixc);
            return ERROR_INT("extension failed", __func__, 1);
        }
    }
 
    pixa->pix[n] = pixc;
    pixa->n++;
    return 0;
}
 
 
l_ok
pixaAddBox(PIXA    *pixa,
           BOX     *box,
           l_int32  copyflag)
{
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    if (!box)
        return ERROR_INT("box not defined", __func__, 1);
    if (copyflag != L_INSERT && copyflag != L_COPY && copyflag != L_CLONE)
        return ERROR_INT("invalid copyflag", __func__, 1);
 
    boxaAddBox(pixa->boxa, box, copyflag);
    return 0;
}
 
 
static l_int32
pixaExtendArray(PIXA  *pixa)
{
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
 
    return pixaExtendArrayToSize(pixa, 2 * pixa->nalloc);
}
 
 
l_ok
pixaExtendArrayToSize(PIXA   *pixa,
                      size_t  size)
{
size_t  oldsize, newsize;
 
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    if (pixa->nalloc > MaxPixaPtrArraySize)  /* belt & suspenders */
        return ERROR_INT("pixa has too many ptrs", __func__, 1);
    if (size > MaxPixaPtrArraySize)
        return ERROR_INT("size > 5M ptrs; too large", __func__, 1);
    if (size <= pixa->nalloc) {
        L_INFO("size too small; no extension\n", __func__);
        return 0;
    }
 
    oldsize = pixa->nalloc * sizeof(PIX *);
    newsize = size * sizeof(PIX *);
    if ((pixa->pix = (PIX **)reallocNew((void **)&pixa->pix,
                                         oldsize, newsize)) == NULL)
        return ERROR_INT("new ptr array not returned", __func__, 1);
    pixa->nalloc = size;
    return boxaExtendArrayToSize(pixa->boxa, size);
}
 
 
/*---------------------------------------------------------------------*
 *                             Pixa accessors                          *
 *---------------------------------------------------------------------*/
l_int32
pixaGetCount(PIXA  *pixa)
{
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 0);
 
    return pixa->n;
}
 
 
PIX *
pixaGetPix(PIXA    *pixa,
           l_int32  index,
           l_int32  accesstype)
{
PIX  *pix;
 
    if (!pixa)
        return (PIX *)ERROR_PTR("pixa not defined", __func__, NULL);
    if (index < 0 || index >= pixa->n)
        return (PIX *)ERROR_PTR("index not valid", __func__, NULL);
    if ((pix = pixa->pix[index]) == NULL) {
        L_ERROR("no pix at pixa[%d]\n", __func__, index);
        return (PIX *)ERROR_PTR("pix not found!", __func__, NULL);
    }
 
    if (accesstype == L_COPY)
        return pixCopy(NULL, pix);
    else if (accesstype == L_CLONE)
        return pixClone(pix);
    else
        return (PIX *)ERROR_PTR("invalid accesstype", __func__, NULL);
}
 
 
l_ok
pixaGetPixDimensions(PIXA     *pixa,
                     l_int32   index,
                     l_int32  *pw,
                     l_int32  *ph,
                     l_int32  *pd)
{
PIX  *pix;
 
    if (pw) *pw = 0;
    if (ph) *ph = 0;
    if (pd) *pd = 0;
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    if (index < 0 || index >= pixa->n)
        return ERROR_INT("index not valid", __func__, 1);
 
    if ((pix = pixaGetPix(pixa, index, L_CLONE)) == NULL)
        return ERROR_INT("pix not found!", __func__, 1);
    pixGetDimensions(pix, pw, ph, pd);
    pixDestroy(&pix);
    return 0;
}
 
 
BOXA *
pixaGetBoxa(PIXA    *pixa,
            l_int32  accesstype)
{
    if (!pixa)
        return (BOXA *)ERROR_PTR("pixa not defined", __func__, NULL);
    if (!pixa->boxa)
        return (BOXA *)ERROR_PTR("boxa not defined", __func__, NULL);
    if (accesstype != L_COPY && accesstype != L_CLONE &&
        accesstype != L_COPY_CLONE)
        return (BOXA *)ERROR_PTR("invalid accesstype", __func__, NULL);
 
    return boxaCopy(pixa->boxa, accesstype);
}
 
 
l_int32
pixaGetBoxaCount(PIXA  *pixa)
{
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 0);
 
    return boxaGetCount(pixa->boxa);
}
 
 
BOX *
pixaGetBox(PIXA    *pixa,
           l_int32  index,
           l_int32  accesstype)
{
BOX  *box;
 
    if (!pixa)
        return (BOX *)ERROR_PTR("pixa not defined", __func__, NULL);
    if (!pixa->boxa)
        return (BOX *)ERROR_PTR("boxa not defined", __func__, NULL);
    if (index < 0 || index >= pixa->boxa->n)
        return (BOX *)ERROR_PTR("index not valid", __func__, NULL);
    if (accesstype != L_COPY && accesstype != L_CLONE)
        return (BOX *)ERROR_PTR("invalid accesstype", __func__, NULL);
 
    box = pixa->boxa->box[index];
    if (box) {
        if (accesstype == L_COPY)
            return boxCopy(box);
        else  /* accesstype == L_CLONE */
            return boxClone(box);
    } else {
        return NULL;
    }
}
 
 
l_ok
pixaGetBoxGeometry(PIXA     *pixa,
                   l_int32   index,
                   l_int32  *px,
                   l_int32  *py,
                   l_int32  *pw,
                   l_int32  *ph)
{
BOX  *box;
 
    if (px) *px = 0;
    if (py) *py = 0;
    if (pw) *pw = 0;
    if (ph) *ph = 0;
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    if (index < 0 || index >= pixa->n)
        return ERROR_INT("index not valid", __func__, 1);
 
    if ((box = pixaGetBox(pixa, index, L_CLONE)) == NULL)
        return ERROR_INT("box not found!", __func__, 1);
    boxGetGeometry(box, px, py, pw, ph);
    boxDestroy(&box);
    return 0;
}
 
 
l_ok
pixaSetBoxa(PIXA    *pixa,
            BOXA    *boxa,
            l_int32  accesstype)
{
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
    if (accesstype != L_INSERT && accesstype != L_COPY &&
        accesstype != L_CLONE)
        return ERROR_INT("invalid access type", __func__, 1);
 
    boxaDestroy(&pixa->boxa);
    if (accesstype == L_INSERT)
        pixa->boxa = boxa;
    else
        pixa->boxa = boxaCopy(boxa, accesstype);
 
    return 0;
}
 
 
PIX **
pixaGetPixArray(PIXA  *pixa)
{
    if (!pixa)
        return (PIX **)ERROR_PTR("pixa not defined", __func__, NULL);
 
    return pixa->pix;
}
 
 
l_ok
pixaVerifyDepth(PIXA     *pixa,
                l_int32  *psame,
                l_int32  *pmaxd)
{
l_int32  i, n, d, maxd, same;
 
    if (pmaxd) *pmaxd = 0;
    if (!psame)
        return ERROR_INT("psame not defined", __func__, 1);
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    if ((n = pixaGetCount(pixa)) == 0)
        return ERROR_INT("no pix in pixa", __func__, 1);
 
    same = 1;
    pixaGetPixDimensions(pixa, 0, NULL, NULL, &maxd);
    for (i = 1; i < n; i++) {
        if (pixaGetPixDimensions(pixa, i, NULL, NULL, &d))
            return ERROR_INT("pix depth not found", __func__, 1);
        maxd = L_MAX(maxd, d);
        if (d != maxd)
            same = 0;
    }
    *psame = same;
    if (pmaxd) *pmaxd = maxd;
    return 0;
}
 
 
l_ok
pixaVerifyDimensions(PIXA     *pixa,
                     l_int32  *psame,
                     l_int32  *pmaxw,
                     l_int32  *pmaxh)
{
l_int32  i, n, w, h, maxw, maxh, same;
 
    if (pmaxw) *pmaxw = 0;
    if (pmaxh) *pmaxh = 0;
    if (!psame)
        return ERROR_INT("psame not defined", __func__, 1);
    *psame = 0;
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    if ((n = pixaGetCount(pixa)) == 0)
        return ERROR_INT("no pix in pixa", __func__, 1);
 
    same = 1;
    pixaGetPixDimensions(pixa, 0, &maxw, &maxh, NULL);
    for (i = 1; i < n; i++) {
        if (pixaGetPixDimensions(pixa, i, &w, &h, NULL))
            return ERROR_INT("pix dimensions not found", __func__, 1);
        maxw = L_MAX(maxw, w);
        maxh = L_MAX(maxh, h);
        if (w != maxw || h != maxh)
            same = 0;
    }
    *psame = same;
    if (pmaxw) *pmaxw = maxw;
    if (pmaxh) *pmaxh = maxh;
    return 0;
}
 
 
l_ok
pixaIsFull(PIXA     *pixa,
           l_int32  *pfullpa,
           l_int32  *pfullba)
{
l_int32  i, n, full;
BOXA    *boxa;
PIX     *pix;
 
    if (pfullpa) *pfullpa = 0;
    if (pfullba) *pfullba = 0;
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
 
    n = pixaGetCount(pixa);
    if (pfullpa) {
        full = 1;
        for (i = 0; i < n; i++) {
            if ((pix = pixaGetPix(pixa, i, L_CLONE)) == NULL) {
                full = 0;
                break;
            }
            pixDestroy(&pix);
        }
        *pfullpa = full;
    }
    if (pfullba) {
        boxa = pixaGetBoxa(pixa, L_CLONE);
        boxaIsFull(boxa, pfullba);
        boxaDestroy(&boxa);
    }
    return 0;
}
 
 
l_ok
pixaCountText(PIXA     *pixa,
              l_int32  *pntext)
{
char    *text;
l_int32  i, n;
PIX     *pix;
 
    if (!pntext)
        return ERROR_INT("&ntext not defined", __func__, 1);
    *pntext = 0;
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
 
    n = pixaGetCount(pixa);
    for (i = 0; i < n; i++) {
        if ((pix = pixaGetPix(pixa, i, L_CLONE)) == NULL)
            continue;
        text = pixGetText(pix);
        if (text && strlen(text) > 0)
            (*pntext)++;
        pixDestroy(&pix);
    }
 
    return 0;
}
 
 
l_ok
pixaSetText(PIXA        *pixa,
            const char  *text,
            SARRAY      *sa)
{
char    *str;
l_int32  i, n;
PIX     *pix;
 
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
 
    n = pixaGetCount(pixa);
    if (sa && (sarrayGetCount(sa) != n))
        return ERROR_INT("pixa and sa sizes differ", __func__, 1);
 
    if (!sa) {
        for (i = 0; i < n; i++) {
            if ((pix = pixaGetPix(pixa, i, L_CLONE)) == NULL)
                continue;
            pixSetText(pix, text);
            pixDestroy(&pix);
        }
        return 0;
    }
 
    for (i = 0; i < n; i++) {
        if ((pix = pixaGetPix(pixa, i, L_CLONE)) == NULL)
            continue;
        str = sarrayGetString(sa, i, L_NOCOPY);
        pixSetText(pix, str);
        pixDestroy(&pix);
    }
 
    return 0;
}
 
 
void ***
pixaGetLinePtrs(PIXA     *pixa,
                l_int32  *psize)
{
l_int32  i, n, same;
void   **lineptrs;
void  ***lineset;
PIX     *pix;
 
    if (psize) *psize = 0;
    if (!pixa)
        return (void ***)ERROR_PTR("pixa not defined", __func__, NULL);
    pixaVerifyDepth(pixa, &same, NULL);
    if (!same)
        return (void ***)ERROR_PTR("pixa not all same depth", __func__, NULL);
    n = pixaGetCount(pixa);
    if (psize) *psize = n;
    if ((lineset = (void ***)LEPT_CALLOC(n, sizeof(void **))) == NULL)
        return (void ***)ERROR_PTR("lineset not made", __func__, NULL);
    for (i = 0; i < n; i++) {
        pix = pixaGetPix(pixa, i, L_CLONE);
        lineptrs = pixGetLinePtrs(pix, NULL);
        lineset[i] = lineptrs;
        pixDestroy(&pix);
    }
 
    return lineset;
}
 
 
/*---------------------------------------------------------------------*
 *                         Pixa output info                            *
 *---------------------------------------------------------------------*/
l_ok
pixaWriteStreamInfo(FILE  *fp,
                    PIXA  *pixa)
{
char     *text;
l_int32   i, n, w, h, d, spp, count, hastext;
PIX      *pix;
PIXCMAP  *cmap;
 
    if (!fp)
        return ERROR_INT("stream not defined", __func__, 1);
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
 
    n = pixaGetCount(pixa);
    for (i = 0; i < n; i++) {
        if ((pix = pixaGetPix(pixa, i, L_CLONE)) == NULL) {
            fprintf(fp, "%d: no pix at this index\n", i);
            continue;
        }
        pixGetDimensions(pix, &w, &h, &d);
        spp = pixGetSpp(pix);
        text = pixGetText(pix);
        hastext = (text && strlen(text) > 0);
        if ((cmap = pixGetColormap(pix)) != NULL)
            count = pixcmapGetCount(cmap);
        fprintf(fp, "Pix %d: w = %d, h = %d, d = %d, spp = %d",
                i, w, h, d, spp);
        if (cmap) fprintf(fp, ", cmap(%d colors)", count);
        if (hastext) fprintf(fp, ", text = %s", text);
        fprintf(fp, "\n");
        pixDestroy(&pix);
    }
 
    return 0;
}
 
 
/*---------------------------------------------------------------------*
 *                       Pixa array modifiers                          *
 *---------------------------------------------------------------------*/
l_ok
pixaReplacePix(PIXA    *pixa,
               l_int32  index,
               PIX     *pix,
               BOX     *box)
{
BOXA  *boxa;
 
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    if (index < 0 || index >= pixa->n)
        return ERROR_INT("index not valid", __func__, 1);
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    pixDestroy(&(pixa->pix[index]));
    pixa->pix[index] = pix;
 
    if (box) {
        boxa = pixa->boxa;
        if (index > boxa->n)
            return ERROR_INT("boxa index not valid", __func__, 1);
        boxaReplaceBox(boxa, index, box);
    }
 
    return 0;
}
 
 
l_ok
pixaInsertPix(PIXA    *pixa,
              l_int32  index,
              PIX     *pixs,
              BOX     *box)
{
l_int32  i, n;
 
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    n = pixaGetCount(pixa);
    if (index < 0 || index > n) {
        L_ERROR("index %d not in [0,...,%d]\n", __func__, index, n);
        return 1;
    }
    if (!pixs)
        return ERROR_INT("pixs not defined", __func__, 1);
 
    if (n >= pixa->nalloc) {  /* extend both ptr arrays */
        if (pixaExtendArray(pixa))
            return ERROR_INT("extension failed", __func__, 1);
        if (boxaExtendArray(pixa->boxa))
            return ERROR_INT("extension failed", __func__, 1);
    }
    pixa->n++;
    for (i = n; i > index; i--)
      pixa->pix[i] = pixa->pix[i - 1];
    pixa->pix[index] = pixs;
 
        /* Optionally, insert the box */
    if (box)
        boxaInsertBox(pixa->boxa, index, box);
    return 0;
}
 
 
l_ok
pixaRemovePix(PIXA    *pixa,
              l_int32  index)
{
l_int32  i, n, nbox;
BOXA    *boxa;
PIX    **array;
 
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    n = pixaGetCount(pixa);
    if (index < 0 || index >= n) {
        L_ERROR("index %d not in [0,...,%d]\n", __func__, index, n - 1);
        return 1;
    }
 
        /* Remove the pix */
    array = pixa->pix;
    pixDestroy(&array[index]);
    for (i = index + 1; i < n; i++)
        array[i - 1] = array[i];
    array[n - 1] = NULL;
    pixa->n--;
 
        /* Remove the box if it exists */
    boxa = pixa->boxa;
    nbox = boxaGetCount(boxa);
    if (index < nbox)
        boxaRemoveBox(boxa, index);
 
    return 0;
}
 
 
l_ok
pixaRemovePixAndSave(PIXA    *pixa,
                     l_int32  index,
                     PIX    **ppix,
                     BOX    **pbox)
{
l_int32  i, n, nbox;
BOXA    *boxa;
PIX    **array;
 
    if (ppix) *ppix = NULL;
    if (pbox) *pbox = NULL;
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    n = pixaGetCount(pixa);
    if (index < 0 || index >= n) {
        L_ERROR("index %d not in [0,...,%d]\n", __func__, index, n - 1);
        return 1;
    }
 
        /* Remove the pix */
    array = pixa->pix;
    if (ppix)
        *ppix = pixaGetPix(pixa, index, L_CLONE);
    pixDestroy(&array[index]);
    for (i = index + 1; i < n; i++)
        array[i - 1] = array[i];
    array[n - 1] = NULL;
    pixa->n--;
 
        /* Remove the box if it exists  */
    boxa = pixa->boxa;
    nbox = boxaGetCount(boxa);
    if (index < nbox)
        boxaRemoveBoxAndSave(boxa, index, pbox);
 
    return 0;
}
 
 
l_ok
pixaRemoveSelected(PIXA  *pixa,
                   NUMA  *naindex)
{
l_int32  i, n, index;
NUMA    *na1;
 
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    if (!naindex)
        return ERROR_INT("naindex not defined", __func__, 1);
    if ((n = numaGetCount(naindex)) == 0)
        return ERROR_INT("naindex is empty", __func__, 1);
 
        /* Remove from highest indices first */
    na1 = numaSort(NULL, naindex, L_SORT_DECREASING);
    for (i = 0; i < n; i++) {
        numaGetIValue(na1, i, &index);
        pixaRemovePix(pixa, index);
    }
    numaDestroy(&na1);
    return 0;
}
 
 
l_ok
pixaInitFull(PIXA  *pixa,
             PIX   *pix,
             BOX   *box)
{
l_int32  i, n;
PIX     *pix1;
 
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
 
    n = pixa->nalloc;
    pixa->n = n;
    for (i = 0; i < n; i++) {
        if (pix)
            pix1 = pixCopy(NULL, pix);
        else
            pix1 = pixCreate(1, 1, 1);
        pixaReplacePix(pixa, i, pix1, NULL);
    }
    if (box)
        boxaInitFull(pixa->boxa, box);
 
    return 0;
}
 
 
l_ok
pixaClear(PIXA  *pixa)
{
l_int32  i, n;
 
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
 
    n = pixaGetCount(pixa);
    for (i = 0; i < n; i++)
        pixDestroy(&pixa->pix[i]);
    pixa->n = 0;
    return boxaClear(pixa->boxa);
}
 
 
/*---------------------------------------------------------------------*
 *                      Pixa and Pixaa combination                     *
 *---------------------------------------------------------------------*/
l_ok
pixaJoin(PIXA    *pixad,
         PIXA    *pixas,
         l_int32  istart,
         l_int32  iend)
{
l_int32  i, n, nb;
BOXA    *boxas, *boxad;
PIX     *pix;
 
    if (!pixad)
        return ERROR_INT("pixad not defined", __func__, 1);
    if (!pixas || ((n = pixaGetCount(pixas)) == 0))
        return 0;
 
    if (istart < 0)
        istart = 0;
    if (iend < 0 || iend >= n)
        iend = n - 1;
    if (istart > iend)
        return ERROR_INT("istart > iend; nothing to add", __func__, 1);
 
    for (i = istart; i <= iend; i++) {
        pix = pixaGetPix(pixas, i, L_CLONE);
        pixaAddPix(pixad, pix, L_INSERT);
    }
 
    boxas = pixaGetBoxa(pixas, L_CLONE);
    boxad = pixaGetBoxa(pixad, L_CLONE);
    nb = pixaGetBoxaCount(pixas);
    iend = L_MIN(iend, nb - 1);
    boxaJoin(boxad, boxas, istart, iend);
    boxaDestroy(&boxas);  /* just the clones */
    boxaDestroy(&boxad);
    return 0;
}
 
 
PIXA *
pixaInterleave(PIXA    *pixa1,
               PIXA    *pixa2,
               l_int32  copyflag)
{
l_int32  i, n1, n2, n, nb1, nb2;
BOX     *box;
PIX     *pix;
PIXA    *pixad;
 
    if (!pixa1)
        return (PIXA *)ERROR_PTR("pixa1 not defined", __func__, NULL);
    if (!pixa2)
        return (PIXA *)ERROR_PTR("pixa2 not defined", __func__, NULL);
    if (copyflag != L_COPY && copyflag != L_CLONE)
        return (PIXA *)ERROR_PTR("invalid copyflag", __func__, NULL);
    n1 = pixaGetCount(pixa1);
    n2 = pixaGetCount(pixa2);
    n = L_MIN(n1, n2);
    if (n == 0)
        return (PIXA *)ERROR_PTR("at least one input pixa is empty",
                                 __func__, NULL);
    if (n1 != n2)
        L_WARNING("counts differ: %d != %d\n", __func__, n1, n2);
 
    pixad = pixaCreate(2 * n);
    nb1 = pixaGetBoxaCount(pixa1);
    nb2 = pixaGetBoxaCount(pixa2);
    for (i = 0; i < n; i++) {
        pix = pixaGetPix(pixa1, i, copyflag);
        pixaAddPix(pixad, pix, L_INSERT);
        if (i < nb1) {
            box = pixaGetBox(pixa1, i, L_COPY);
            pixaAddBox(pixad, box, L_INSERT);
        }
        pix = pixaGetPix(pixa2, i, copyflag);
        pixaAddPix(pixad, pix, L_INSERT);
        if (i < nb2) {
            box = pixaGetBox(pixa2, i, L_COPY);
            pixaAddBox(pixad, box, L_INSERT);
        }
    }
 
    return pixad;
}
 
 
l_ok
pixaaJoin(PIXAA   *paad,
          PIXAA   *paas,
          l_int32  istart,
          l_int32  iend)
{
l_int32  i, n;
PIXA    *pixa;
 
    if (!paad)
        return ERROR_INT("pixaad not defined", __func__, 1);
    if (!paas)
        return 0;
 
    if (istart < 0)
        istart = 0;
    n = pixaaGetCount(paas, NULL);
    if (iend < 0 || iend >= n)
        iend = n - 1;
    if (istart > iend)
        return ERROR_INT("istart > iend; nothing to add", __func__, 1);
 
    for (i = istart; i <= iend; i++) {
        pixa = pixaaGetPixa(paas, i, L_CLONE);
        pixaaAddPixa(paad, pixa, L_INSERT);
    }
 
    return 0;
}
 
 
/*---------------------------------------------------------------------*
 *                    Pixaa creation and destruction                   *
 *---------------------------------------------------------------------*/
PIXAA *
pixaaCreate(l_int32  n)
{
PIXAA  *paa;
 
    if (n <= 0 || n > MaxInitPtrArraySize)
        n = InitialPtrArraySize;
 
    paa = (PIXAA *)LEPT_CALLOC(1, sizeof(PIXAA));
    paa->n = 0;
    paa->nalloc = n;
    if ((paa->pixa = (PIXA **)LEPT_CALLOC(n, sizeof(PIXA *))) == NULL) {
        pixaaDestroy(&paa);
        return (PIXAA *)ERROR_PTR("pixa ptrs not made", __func__, NULL);
    }
    paa->boxa = boxaCreate(n);
 
    return paa;
}
 
 
PIXAA *
pixaaCreateFromPixa(PIXA    *pixa,
                    l_int32  n,
                    l_int32  type,
                    l_int32  copyflag)
{
l_int32  count, i, j, npixa;
PIX     *pix;
PIXA    *pixat = NULL;
PIXAA   *paa;
 
    if (!pixa)
        return (PIXAA *)ERROR_PTR("pixa not defined", __func__, NULL);
    count = pixaGetCount(pixa);
    if (count == 0)
        return (PIXAA *)ERROR_PTR("no pix in pixa", __func__, NULL);
    if (n <= 0)
        return (PIXAA *)ERROR_PTR("n must be > 0", __func__, NULL);
    if (type != L_CHOOSE_CONSECUTIVE && type != L_CHOOSE_SKIP_BY)
        return (PIXAA *)ERROR_PTR("invalid type", __func__, NULL);
    if (copyflag != L_CLONE && copyflag != L_COPY)
        return (PIXAA *)ERROR_PTR("invalid copyflag", __func__, NULL);
 
    if (type == L_CHOOSE_CONSECUTIVE)
        npixa = (count + n - 1) / n;
    else  /* L_CHOOSE_SKIP_BY */
        npixa = L_MIN(n, count);
    paa = pixaaCreate(npixa);
    if (type == L_CHOOSE_CONSECUTIVE) {
        for (i = 0; i < count; i++) {
            if (i % n == 0)
                pixat = pixaCreate(n);
            pix = pixaGetPix(pixa, i, copyflag);
            pixaAddPix(pixat, pix, L_INSERT);
            if (i % n == n - 1)
                pixaaAddPixa(paa, pixat, L_INSERT);
        }
        if (i % n != 0)
            pixaaAddPixa(paa, pixat, L_INSERT);
    } else {  /* L_CHOOSE_SKIP_BY */
        for (i = 0; i < npixa; i++) {
            pixat = pixaCreate(count / npixa + 1);
            for (j = i; j < count; j += n) {
                pix = pixaGetPix(pixa, j, copyflag);
                pixaAddPix(pixat, pix, L_INSERT);
            }
            pixaaAddPixa(paa, pixat, L_INSERT);
        }
    }
 
    return paa;
}
 
 
void
pixaaDestroy(PIXAA  **ppaa)
{
l_int32  i;
PIXAA   *paa;
 
    if (ppaa == NULL) {
        L_WARNING("ptr address is NULL!\n", __func__);
        return;
    }
 
    if ((paa = *ppaa) == NULL)
        return;
 
    for (i = 0; i < paa->n; i++)
        pixaDestroy(&paa->pixa[i]);
    LEPT_FREE(paa->pixa);
    boxaDestroy(&paa->boxa);
    LEPT_FREE(paa);
    *ppaa = NULL;
}
 
 
/*---------------------------------------------------------------------*
 *                             Pixaa addition                          *
 *---------------------------------------------------------------------*/
l_ok
pixaaAddPixa(PIXAA   *paa,
             PIXA    *pixa,
             l_int32  copyflag)
{
l_int32  n;
PIXA    *pixac;
 
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 1);
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
    if (copyflag != L_INSERT && copyflag != L_COPY &&
        copyflag != L_CLONE && copyflag != L_COPY_CLONE)
        return ERROR_INT("invalid copyflag", __func__, 1);
 
    if (copyflag == L_INSERT) {
        pixac = pixa;
    } else {
        if ((pixac = pixaCopy(pixa, copyflag)) == NULL)
            return ERROR_INT("pixac not made", __func__, 1);
    }
 
    n = pixaaGetCount(paa, NULL);
    if (n >= paa->nalloc) {
        if (pixaaExtendArray(paa)) {
            if (copyflag != L_INSERT)
                pixaDestroy(&pixac);
            return ERROR_INT("extension failed", __func__, 1);
        }
    }
    paa->pixa[n] = pixac;
    paa->n++;
    return 0;
}
 
 
static l_int32
pixaaExtendArray(PIXAA  *paa)
{
size_t  oldsize, newsize;
 
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 1);
    if (paa->nalloc > MaxPixaaPtrArraySize)  /* belt & suspenders */
        return ERROR_INT("paa has too many ptrs", __func__, 1);
    oldsize = paa->nalloc * sizeof(PIXA *);
    newsize = 2 * oldsize;
    if (newsize > 8 * MaxPixaaPtrArraySize)
        return ERROR_INT("newsize > 8 MB; too large", __func__, 1);
 
    if ((paa->pixa = (PIXA **)reallocNew((void **)&paa->pixa,
                                         oldsize, newsize)) == NULL)
        return ERROR_INT("new ptr array not returned", __func__, 1);
 
    paa->nalloc *= 2;
    return 0;
}
 
 
l_ok
pixaaAddPix(PIXAA   *paa,
            l_int32  index,
            PIX     *pix,
            BOX     *box,
            l_int32  copyflag)
{
PIXA  *pixa;
 
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 1);
    if (!pix)
        return ERROR_INT("pix not defined", __func__, 1);
 
    if ((pixa = pixaaGetPixa(paa, index, L_CLONE)) == NULL)
        return ERROR_INT("pixa not found", __func__, 1);
    pixaAddPix(pixa, pix, copyflag);
    if (box) pixaAddBox(pixa, box, copyflag);
    pixaDestroy(&pixa);
    return 0;
}
 
 
l_ok
pixaaAddBox(PIXAA   *paa,
            BOX     *box,
            l_int32  copyflag)
{
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 1);
    if (!box)
        return ERROR_INT("box not defined", __func__, 1);
    if (copyflag != L_INSERT && copyflag != L_COPY && copyflag != L_CLONE)
        return ERROR_INT("invalid copyflag", __func__, 1);
 
    boxaAddBox(paa->boxa, box, copyflag);
    return 0;
}
 
 
 
/*---------------------------------------------------------------------*
 *                            Pixaa accessors                          *
 *---------------------------------------------------------------------*/
l_int32
pixaaGetCount(PIXAA  *paa,
              NUMA  **pna)
{
l_int32  i, n;
NUMA    *na;
PIXA    *pixa;
 
    if (pna) *pna = NULL;
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 0);
 
    n = paa->n;
    if (pna) {
        if ((na = numaCreate(n)) == NULL)
            return ERROR_INT("na not made", __func__, 0);
        *pna = na;
        for (i = 0; i < n; i++) {
            pixa = pixaaGetPixa(paa, i, L_CLONE);
            numaAddNumber(na, pixaGetCount(pixa));
            pixaDestroy(&pixa);
        }
    }
    return n;
}
 
 
PIXA *
pixaaGetPixa(PIXAA   *paa,
             l_int32  index,
             l_int32  accesstype)
{
PIXA  *pixa;
 
    if (!paa)
        return (PIXA *)ERROR_PTR("paa not defined", __func__, NULL);
    if (index < 0 || index >= paa->n)
        return (PIXA *)ERROR_PTR("index not valid", __func__, NULL);
    if (accesstype != L_COPY && accesstype != L_CLONE &&
        accesstype != L_COPY_CLONE)
        return (PIXA *)ERROR_PTR("invalid accesstype", __func__, NULL);
 
    if ((pixa = paa->pixa[index]) == NULL) {  /* shouldn't happen! */
        L_ERROR("missing pixa[%d]\n", __func__, index);
        return (PIXA *)ERROR_PTR("pixa not found at index", __func__, NULL);
    }
    return pixaCopy(pixa, accesstype);
}
 
 
BOXA *
pixaaGetBoxa(PIXAA   *paa,
             l_int32  accesstype)
{
    if (!paa)
        return (BOXA *)ERROR_PTR("paa not defined", __func__, NULL);
    if (accesstype != L_COPY && accesstype != L_CLONE)
        return (BOXA *)ERROR_PTR("invalid access type", __func__, NULL);
 
    return boxaCopy(paa->boxa, accesstype);
}
 
 
PIX *
pixaaGetPix(PIXAA   *paa,
            l_int32  index,
            l_int32  ipix,
            l_int32  accessflag)
{
PIX   *pix;
PIXA  *pixa;
 
    if ((pixa = pixaaGetPixa(paa, index, L_CLONE)) == NULL)
        return (PIX *)ERROR_PTR("pixa not retrieved", __func__, NULL);
    if ((pix = pixaGetPix(pixa, ipix, accessflag)) == NULL)
        L_ERROR("pix not retrieved\n", __func__);
    pixaDestroy(&pixa);
    return pix;
}
 
 
l_ok
pixaaVerifyDepth(PIXAA    *paa,
                 l_int32  *psame,
                 l_int32  *pmaxd)
{
l_int32  i, n, d, maxd, same, samed;
PIXA    *pixa;
 
    if (pmaxd) *pmaxd = 0;
    if (!psame)
        return ERROR_INT("psame not defined", __func__, 1);
    *psame = 0;
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 1);
    if ((n = pixaaGetCount(paa, NULL)) == 0)
        return ERROR_INT("no pixa in paa", __func__, 1);
 
    pixa = pixaaGetPixa(paa, 0, L_CLONE);
    pixaVerifyDepth(pixa, &same, &maxd);  /* init same, maxd with first pixa */
    pixaDestroy(&pixa);
    for (i = 1; i < n; i++) {
        pixa = pixaaGetPixa(paa, i, L_CLONE);
        pixaVerifyDepth(pixa, &samed, &d);
        pixaDestroy(&pixa);
        maxd = L_MAX(maxd, d);
        if (!samed || maxd != d)
            same = 0;
    }
    *psame = same;
    if (pmaxd) *pmaxd = maxd;
    return 0;
}
 
 
l_ok
pixaaVerifyDimensions(PIXAA    *paa,
                      l_int32  *psame,
                      l_int32  *pmaxw,
                      l_int32  *pmaxh)
{
l_int32  i, n, w, h, maxw, maxh, same, same2;
PIXA    *pixa;
 
    if (pmaxw) *pmaxw = 0;
    if (pmaxh) *pmaxh = 0;
    if (!psame)
        return ERROR_INT("psame not defined", __func__, 1);
    *psame = 0;
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 1);
    if ((n = pixaaGetCount(paa, NULL)) == 0)
        return ERROR_INT("no pixa in paa", __func__, 1);
 
        /* Init same; init maxw and maxh from first pixa */
    pixa = pixaaGetPixa(paa, 0, L_CLONE);
    pixaVerifyDimensions(pixa, &same, &maxw, &maxh);
    pixaDestroy(&pixa);
 
    for (i = 1; i < n; i++) {
        pixa = pixaaGetPixa(paa, i, L_CLONE);
        pixaVerifyDimensions(pixa, &same2, &w, &h);
        pixaDestroy(&pixa);
        maxw = L_MAX(maxw, w);
        maxh = L_MAX(maxh, h);
        if (!same2 || maxw != w || maxh != h)
            same = 0;
    }
    *psame = same;
    if (pmaxw) *pmaxw = maxw;
    if (pmaxh) *pmaxh = maxh;
    return 0;
}
 
 
l_int32
pixaaIsFull(PIXAA    *paa,
            l_int32  *pfull)
{
l_int32  i, n, full;
PIXA    *pixa;
 
    if (!pfull)
        return ERROR_INT("&full not defined", __func__, 0);
    *pfull = 0;
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 0);
 
    n = pixaaGetCount(paa, NULL);
    full = 1;
    for (i = 0; i < n; i++) {
        pixa = pixaaGetPixa(paa, i, L_CLONE);
        pixaIsFull(pixa, &full, NULL);
        pixaDestroy(&pixa);
        if (!full) break;
    }
    *pfull = full;
    return 0;
}
 
 
/*---------------------------------------------------------------------*
 *                         Pixaa array modifiers                       *
 *---------------------------------------------------------------------*/
l_ok
pixaaInitFull(PIXAA  *paa,
              PIXA   *pixa)
{
l_int32  i, n;
PIXA    *pixat;
 
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 1);
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
 
    n = paa->nalloc;
    paa->n = n;
    for (i = 0; i < n; i++) {
        pixat = pixaCopy(pixa, L_COPY);
        pixaaReplacePixa(paa, i, pixat);
    }
 
    return 0;
}
 
 
l_ok
pixaaReplacePixa(PIXAA   *paa,
                 l_int32  index,
                 PIXA    *pixa)
{
 
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 1);
    if (index < 0 || index >= paa->n)
        return ERROR_INT("index not valid", __func__, 1);
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
 
    pixaDestroy(&(paa->pixa[index]));
    paa->pixa[index] = pixa;
    return 0;
}
 
 
l_ok
pixaaClear(PIXAA  *paa)
{
l_int32  i, n;
 
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 1);
 
    n = pixaaGetCount(paa, NULL);
    for (i = 0; i < n; i++)
        pixaDestroy(&paa->pixa[i]);
    paa->n = 0;
    return 0;
}
 
 
l_ok
pixaaTruncate(PIXAA  *paa)
{
l_int32  i, n, np;
PIXA    *pixa;
 
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 1);
 
    n = pixaaGetCount(paa, NULL);
    for (i = n - 1; i >= 0; i--) {
        pixa = pixaaGetPixa(paa, i, L_CLONE);
        if (!pixa) {
            paa->n--;
            continue;
        }
        np = pixaGetCount(pixa);
        pixaDestroy(&pixa);
        if (np == 0) {
            pixaDestroy(&paa->pixa[i]);
            paa->n--;
        } else {
            break;
        }
    }
    return 0;
}
 
 
 
/*---------------------------------------------------------------------*
 *                          Pixa serialized I/O                        *
 *---------------------------------------------------------------------*/
PIXA *
pixaRead(const char  *filename)
{
FILE  *fp;
PIXA  *pixa;
 
#if !HAVE_LIBPNG     /* defined in environ.h and config_auto.h */
    return (PIXA *)ERROR_PTR("no libpng: can't read data", __func__, NULL);
#endif  /* !HAVE_LIBPNG */
 
    if (!filename)
        return (PIXA *)ERROR_PTR("filename not defined", __func__, NULL);
 
    if ((fp = fopenReadStream(filename)) == NULL)
        return (PIXA *)ERROR_PTR_1("stream not opened",
                                   filename, __func__, NULL);
    pixa = pixaReadStream(fp);
    fclose(fp);
    if (!pixa)
        return (PIXA *)ERROR_PTR_1("pixa not read",
                                   filename, __func__, NULL);
    return pixa;
}
 
 
PIXA *
pixaReadStream(FILE  *fp)
{
l_int32  n, i, xres, yres, version;
l_int32  ignore;
BOXA    *boxa;
PIX     *pix;
PIXA    *pixa;
 
#if !HAVE_LIBPNG     /* defined in environ.h and config_auto.h */
    return (PIXA *)ERROR_PTR("no libpng: can't read data", __func__, NULL);
#endif  /* !HAVE_LIBPNG */
 
    if (!fp)
        return (PIXA *)ERROR_PTR("stream not defined", __func__, NULL);
 
    if (fscanf(fp, "\nPixa Version %d\n", &version) != 1)
        return (PIXA *)ERROR_PTR("not a pixa file", __func__, NULL);
    if (version != PIXA_VERSION_NUMBER)
        return (PIXA *)ERROR_PTR("invalid pixa version", __func__, NULL);
    if (fscanf(fp, "Number of pix = %d\n", &n) != 1)
        return (PIXA *)ERROR_PTR("not a pixa file", __func__, NULL);
    if (n < 0)
        return (PIXA *)ERROR_PTR("num pix ptrs < 0", __func__, NULL);
    if (n > MaxPixaPtrArraySize)
        return (PIXA *)ERROR_PTR("too many pix ptrs", __func__, NULL);
    if (n == 0) L_INFO("the pixa is empty\n", __func__);
 
    if ((boxa = boxaReadStream(fp)) == NULL)
        return (PIXA *)ERROR_PTR("boxa not made", __func__, NULL);
    if ((pixa = pixaCreate(n)) == NULL) {
        boxaDestroy(&boxa);
        return (PIXA *)ERROR_PTR("pixa not made", __func__, NULL);
    }
    boxaDestroy(&pixa->boxa);
    pixa->boxa = boxa;
 
    for (i = 0; i < n; i++) {
        if ((fscanf(fp, " pix[%d]: xres = %d, yres = %d\n",
              &ignore, &xres, &yres)) != 3) {
            pixaDestroy(&pixa);
            return (PIXA *)ERROR_PTR("res reading error", __func__, NULL);
        }
        if ((pix = pixReadStreamPng(fp)) == NULL) {
            pixaDestroy(&pixa);
            return (PIXA *)ERROR_PTR("pix not read", __func__, NULL);
        }
        pixSetXRes(pix, xres);
        pixSetYRes(pix, yres);
        pixaAddPix(pixa, pix, L_INSERT);
    }
    return pixa;
}
 
 
PIXA *
pixaReadMem(const l_uint8  *data,
            size_t          size)
{
FILE  *fp;
PIXA  *pixa;
 
    if (!data)
        return (PIXA *)ERROR_PTR("data not defined", __func__, NULL);
    if ((fp = fopenReadFromMemory(data, size)) == NULL)
        return (PIXA *)ERROR_PTR("stream not opened", __func__, NULL);
 
    pixa = pixaReadStream(fp);
    fclose(fp);
    if (!pixa) L_ERROR("pixa not read\n", __func__);
    return pixa;
}
 
 
l_ok
pixaWriteDebug(const char  *fname,
               PIXA        *pixa)
{
    if (LeptDebugOK) {
        return pixaWrite(fname, pixa);
    } else {
        L_INFO("write to named temp file %s is disabled\n", __func__, fname);
        return 0;
    }
}
 
 
l_ok
pixaWrite(const char  *filename,
          PIXA        *pixa)
{
l_int32  ret;
FILE    *fp;
 
#if !HAVE_LIBPNG     /* defined in environ.h and config_auto.h */
    return ERROR_INT("no libpng: can't write data", __func__, 1);
#endif  /* !HAVE_LIBPNG */
 
    if (!filename)
        return ERROR_INT("filename not defined", __func__, 1);
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
 
    if ((fp = fopenWriteStream(filename, "wb")) == NULL)
        return ERROR_INT_1("stream not opened", filename, __func__, 1);
    ret = pixaWriteStream(fp, pixa);
    fclose(fp);
    if (ret)
        return ERROR_INT_1("pixa not written to stream", filename, __func__, 1);
    return 0;
}
 
 
l_ok
pixaWriteStream(FILE  *fp,
                PIXA  *pixa)
{
l_int32  n, i;
PIX     *pix;
 
#if !HAVE_LIBPNG     /* defined in environ.h and config_auto.h */
    return ERROR_INT("no libpng: can't write data", __func__, 1);
#endif  /* !HAVE_LIBPNG */
 
    if (!fp)
        return ERROR_INT("stream not defined", __func__, 1);
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
 
    n = pixaGetCount(pixa);
    fprintf(fp, "\nPixa Version %d\n", PIXA_VERSION_NUMBER);
    fprintf(fp, "Number of pix = %d\n", n);
    boxaWriteStream(fp, pixa->boxa);
    for (i = 0; i < n; i++) {
        if ((pix = pixaGetPix(pixa, i, L_CLONE)) == NULL)
            return ERROR_INT("pix not found", __func__, 1);
        fprintf(fp, " pix[%d]: xres = %d, yres = %d\n",
                i, pix->xres, pix->yres);
        pixWriteStreamPng(fp, pix, 0.0);
        pixDestroy(&pix);
    }
    return 0;
}
 
 
l_ok
pixaWriteMem(l_uint8  **pdata,
             size_t    *psize,
             PIXA      *pixa)
{
l_int32  ret;
FILE    *fp;
 
    if (pdata) *pdata = NULL;
    if (psize) *psize = 0;
    if (!pdata)
        return ERROR_INT("&data not defined", __func__, 1);
    if (!psize)
        return ERROR_INT("&size not defined", __func__, 1);
    if (!pixa)
        return ERROR_INT("pixa not defined", __func__, 1);
 
#if HAVE_FMEMOPEN
    if ((fp = open_memstream((char **)pdata, psize)) == NULL)
        return ERROR_INT("stream not opened", __func__, 1);
    ret = pixaWriteStream(fp, pixa);
    fputc('\0', fp);
    fclose(fp);
    if (*psize > 0) *psize = *psize - 1;
#else
    L_INFO("no fmemopen API --> work-around: write to temp file\n", __func__);
  #ifdef _WIN32
    if ((fp = fopenWriteWinTempfile()) == NULL)
        return ERROR_INT("tmpfile stream not opened", __func__, 1);
  #else
    if ((fp = tmpfile()) == NULL)
        return ERROR_INT("tmpfile stream not opened", __func__, 1);
  #endif  /* _WIN32 */
    ret = pixaWriteStream(fp, pixa);
    rewind(fp);
    *pdata = l_binaryReadStream(fp, psize);
    fclose(fp);
#endif  /* HAVE_FMEMOPEN */
    return ret;
}
 
 
PIXA *
pixaReadBoth(const char  *filename)
{
char    buf[32];
char   *sname;
PIXA   *pixa;
PIXAC  *pac;
 
    if (!filename)
        return (PIXA *)ERROR_PTR("filename not defined", __func__, NULL);
 
    l_getStructStrFromFile(filename, L_STR_NAME, &sname);
    if (!sname)
        return (PIXA *)ERROR_PTR("struct name not found", __func__, NULL);
    snprintf(buf, sizeof(buf), "%s", sname);
    LEPT_FREE(sname);
 
    if (strcmp(buf, "Pixacomp") == 0) {
        if ((pac = pixacompRead(filename)) == NULL)
            return (PIXA *)ERROR_PTR("pac not made", __func__, NULL);
        pixa = pixaCreateFromPixacomp(pac, L_COPY);
        pixacompDestroy(&pac);
    } else if (strcmp(buf, "Pixa") == 0) {
        if ((pixa = pixaRead(filename)) == NULL)
            return (PIXA *)ERROR_PTR("pixa not made", __func__, NULL);
    } else {
        return (PIXA *)ERROR_PTR("invalid file type", __func__, NULL);
    }
    return pixa;
}
 
 
/*---------------------------------------------------------------------*
 *                         Pixaa serialized I/O                        *
 *---------------------------------------------------------------------*/
PIXAA *
pixaaReadFromFiles(const char  *dirname,
                   const char  *substr,
                   l_int32      first,
                   l_int32      nfiles)
{
char    *fname;
l_int32  i, n;
PIXA    *pixa;
PIXAA   *paa;
SARRAY  *sa;
 
  if (!dirname)
      return (PIXAA *)ERROR_PTR("dirname not defined", __func__, NULL);
 
  sa = getSortedPathnamesInDirectory(dirname, substr, first, nfiles);
  if (!sa || ((n = sarrayGetCount(sa)) == 0)) {
      sarrayDestroy(&sa);
      return (PIXAA *)ERROR_PTR("no pixa files found", __func__, NULL);
  }
 
  paa = pixaaCreate(n);
  for (i = 0; i < n; i++) {
      fname = sarrayGetString(sa, i, L_NOCOPY);
      if ((pixa = pixaRead(fname)) == NULL) {
          L_ERROR("pixa not read for %d-th file", __func__, i);
          continue;
      }
      pixaaAddPixa(paa, pixa, L_INSERT);
  }
 
  sarrayDestroy(&sa);
  return paa;
}
 
 
PIXAA *
pixaaRead(const char  *filename)
{
FILE   *fp;
PIXAA  *paa;
 
#if !HAVE_LIBPNG     /* defined in environ.h and config_auto.h */
    return (PIXAA *)ERROR_PTR("no libpng: can't read data", __func__, NULL);
#endif  /* !HAVE_LIBPNG */
 
    if (!filename)
        return (PIXAA *)ERROR_PTR("filename not defined", __func__, NULL);
 
    if ((fp = fopenReadStream(filename)) == NULL)
        return (PIXAA *)ERROR_PTR_1("stream not opened",
                                    filename, __func__, NULL);
    paa = pixaaReadStream(fp);
    fclose(fp);
    if (!paa)
        return (PIXAA *)ERROR_PTR_1("paa not read", filename, __func__, NULL);
    return paa;
}
 
 
PIXAA *
pixaaReadStream(FILE  *fp)
{
l_int32  n, i, version;
l_int32  ignore;
BOXA    *boxa;
PIXA    *pixa;
PIXAA   *paa;
 
#if !HAVE_LIBPNG     /* defined in environ.h and config_auto.h */
    return (PIXAA *)ERROR_PTR("no libpng: can't read data", __func__, NULL);
#endif  /* !HAVE_LIBPNG */
 
    if (!fp)
        return (PIXAA *)ERROR_PTR("stream not defined", __func__, NULL);
 
    if (fscanf(fp, "\nPixaa Version %d\n", &version) != 1)
        return (PIXAA *)ERROR_PTR("not a pixaa file", __func__, NULL);
    if (version != PIXAA_VERSION_NUMBER)
        return (PIXAA *)ERROR_PTR("invalid pixaa version", __func__, NULL);
    if (fscanf(fp, "Number of pixa = %d\n", &n) != 1)
        return (PIXAA *)ERROR_PTR("not a pixaa file", __func__, NULL);
    if (n < 0)
        return (PIXAA *)ERROR_PTR("num pixa ptrs < 0", __func__, NULL);
    if (n > MaxPixaaPtrArraySize)
        return (PIXAA *)ERROR_PTR("too many pixa ptrs", __func__, NULL);
    if (n == 0) L_INFO("the pixaa is empty\n", __func__);
 
    if ((paa = pixaaCreate(n)) == NULL)
        return (PIXAA *)ERROR_PTR("paa not made", __func__, NULL);
    if ((boxa = boxaReadStream(fp)) == NULL) {
        pixaaDestroy(&paa);
        return (PIXAA *)ERROR_PTR("boxa not made", __func__, NULL);
    }
    boxaDestroy(&paa->boxa);
    paa->boxa = boxa;
 
    for (i = 0; i < n; i++) {
        if ((fscanf(fp, "\n\n --------------- pixa[%d] ---------------\n",
                    &ignore)) != 1) {
            pixaaDestroy(&paa);
            return (PIXAA *)ERROR_PTR("text reading", __func__, NULL);
        }
        if ((pixa = pixaReadStream(fp)) == NULL) {
            pixaaDestroy(&paa);
            return (PIXAA *)ERROR_PTR("pixa not read", __func__, NULL);
        }
        pixaaAddPixa(paa, pixa, L_INSERT);
    }
 
    return paa;
}
 
 
PIXAA *
pixaaReadMem(const l_uint8  *data,
             size_t          size)
{
FILE   *fp;
PIXAA  *paa;
 
    if (!data)
        return (PIXAA *)ERROR_PTR("data not defined", __func__, NULL);
    if ((fp = fopenReadFromMemory(data, size)) == NULL)
        return (PIXAA *)ERROR_PTR("stream not opened", __func__, NULL);
 
    paa = pixaaReadStream(fp);
    fclose(fp);
    if (!paa) L_ERROR("paa not read\n", __func__);
    return paa;
}
 
 
l_ok
pixaaWrite(const char  *filename,
           PIXAA       *paa)
{
l_int32  ret;
FILE    *fp;
 
#if !HAVE_LIBPNG     /* defined in environ.h and config_auto.h */
    return ERROR_INT("no libpng: can't read data", __func__, 1);
#endif  /* !HAVE_LIBPNG */
 
    if (!filename)
        return ERROR_INT("filename not defined", __func__, 1);
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 1);
 
    if ((fp = fopenWriteStream(filename, "wb")) == NULL)
        return ERROR_INT_1("stream not opened", filename, __func__, 1);
    ret = pixaaWriteStream(fp, paa);
    fclose(fp);
    if (ret)
        return ERROR_INT_1("paa not written to stream", filename, __func__, 1);
    return 0;
}
 
 
l_ok
pixaaWriteStream(FILE   *fp,
                 PIXAA  *paa)
{
l_int32  n, i;
PIXA    *pixa;
 
#if !HAVE_LIBPNG     /* defined in environ.h and config_auto.h */
    return ERROR_INT("no libpng: can't read data", __func__, 1);
#endif  /* !HAVE_LIBPNG */
 
    if (!fp)
        return ERROR_INT("stream not defined", __func__, 1);
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 1);
 
    n = pixaaGetCount(paa, NULL);
    fprintf(fp, "\nPixaa Version %d\n", PIXAA_VERSION_NUMBER);
    fprintf(fp, "Number of pixa = %d\n", n);
    boxaWriteStream(fp, paa->boxa);
    for (i = 0; i < n; i++) {
        if ((pixa = pixaaGetPixa(paa, i, L_CLONE)) == NULL)
            return ERROR_INT("pixa not found", __func__, 1);
        fprintf(fp, "\n\n --------------- pixa[%d] ---------------\n", i);
        pixaWriteStream(fp, pixa);
        pixaDestroy(&pixa);
    }
    return 0;
}
 
 
l_ok
pixaaWriteMem(l_uint8  **pdata,
              size_t    *psize,
              PIXAA     *paa)
{
l_int32  ret;
FILE    *fp;
 
    if (pdata) *pdata = NULL;
    if (psize) *psize = 0;
    if (!pdata)
        return ERROR_INT("&data not defined", __func__, 1);
    if (!psize)
        return ERROR_INT("&size not defined", __func__, 1);
    if (!paa)
        return ERROR_INT("paa not defined", __func__, 1);
 
#if HAVE_FMEMOPEN
    if ((fp = open_memstream((char **)pdata, psize)) == NULL)
        return ERROR_INT("stream not opened", __func__, 1);
    ret = pixaaWriteStream(fp, paa);
    fputc('\0', fp);
    fclose(fp);
    if (*psize > 0) *psize = *psize - 1;
#else
    L_INFO("no fmemopen API --> work-around: write to temp file\n", __func__);
  #ifdef _WIN32
    if ((fp = fopenWriteWinTempfile()) == NULL)
        return ERROR_INT("tmpfile stream not opened", __func__, 1);
  #else
    if ((fp = tmpfile()) == NULL)
        return ERROR_INT("tmpfile stream not opened", __func__, 1);
  #endif  /* _WIN32 */
    ret = pixaaWriteStream(fp, paa);
    rewind(fp);
    *pdata = l_binaryReadStream(fp, psize);
    fclose(fp);
#endif  /* HAVE_FMEMOPEN */
    return ret;
}