boxbasic.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  MaxBoxaPtrArraySize = 10000000;
static const size_t  MaxBoxaaPtrArraySize = 1000000;
static const size_t  InitialPtrArraySize = 20;      
/*---------------------------------------------------------------------*
 *                  Box creation, destruction and copy                 *
 *---------------------------------------------------------------------*/
BOX *
boxCreate(l_int32  x,
          l_int32  y,
          l_int32  w,
          l_int32  h)
{
BOX  *box;
 
    if (w < 0 || h < 0)
        return (BOX *)ERROR_PTR("w and h not both >= 0", __func__, NULL);
    if (x < 0) {  /* take part in +quad */
        w = w + x;
        x = 0;
        if (w <= 0)
            return (BOX *)ERROR_PTR("x < 0 and box off +quad", __func__, NULL);
    }
    if (y < 0) {  /* take part in +quad */
        h = h + y;
        y = 0;
        if (h <= 0)
            return (BOX *)ERROR_PTR("y < 0 and box off +quad", __func__, NULL);
    }
 
    box = (BOX *)LEPT_CALLOC(1, sizeof(BOX));
    boxSetGeometry(box, x, y, w, h);
    box->refcount = 1;
    return box;
}
 
 
BOX *
boxCreateValid(l_int32  x,
               l_int32  y,
               l_int32  w,
               l_int32  h)
{
    if (w <= 0 || h <= 0)
        return (BOX *)ERROR_PTR("w and h not both > 0", __func__, NULL);
    return boxCreate(x, y, w, h);
}
 
 
BOX *
boxCopy(BOX  *box)
{
BOX  *boxc;
 
    if (!box)
        return (BOX *)ERROR_PTR("box not defined", __func__, NULL);
 
    boxc = boxCreate(box->x, box->y, box->w, box->h);
    return boxc;
}
 
 
BOX *
boxClone(BOX  *box)
{
 
    if (!box)
        return (BOX *)ERROR_PTR("box not defined", __func__, NULL);
 
    ++box->refcount;
    return box;
}
 
 
void
boxDestroy(BOX  **pbox)
{
BOX  *box;
 
    if (pbox == NULL) {
        L_WARNING("ptr address is null!\n", __func__);
        return;
    }
    if ((box = *pbox) == NULL)
        return;
 
    if (--box->refcount == 0)
        LEPT_FREE(box);
    *pbox = NULL;
}
 
 
/*---------------------------------------------------------------------*
 *                              Box accessors                          *
 *---------------------------------------------------------------------*/
l_ok
boxGetGeometry(const BOX *box,
               l_int32   *px,
               l_int32   *py,
               l_int32   *pw,
               l_int32   *ph)
{
    if (px) *px = 0;
    if (py) *py = 0;
    if (pw) *pw = 0;
    if (ph) *ph = 0;
    if (!box)
        return ERROR_INT("box not defined", __func__, 1);
    if (px) *px = box->x;
    if (py) *py = box->y;
    if (pw) *pw = box->w;
    if (ph) *ph = box->h;
    return 0;
}
 
 
l_ok
boxSetGeometry(BOX     *box,
               l_int32  x,
               l_int32  y,
               l_int32  w,
               l_int32  h)
{
    if (!box)
        return ERROR_INT("box not defined", __func__, 1);
    if (x != -1) box->x = x;
    if (y != -1) box->y = y;
    if (w != -1) box->w = w;
    if (h != -1) box->h = h;
    return 0;
}
 
 
l_ok
boxGetSideLocations(const BOX *box,
                    l_int32   *pl,
                    l_int32   *pr,
                    l_int32   *pt,
                    l_int32   *pb)
{
l_int32  x, y, w, h;
 
    if (pl) *pl = 0;
    if (pr) *pr = 0;
    if (pt) *pt = 0;
    if (pb) *pb = 0;
    if (!box)
        return ERROR_INT("box not defined", __func__, 1);
 
    boxGetGeometry(box, &x, &y, &w, &h);
    if (pl) *pl = x;
    if (pr) *pr = x + w - 1;
    if (pt) *pt = y;
    if (pb) *pb = y + h - 1;
    return 0;
}
 
 
l_ok
boxSetSideLocations(BOX     *box,
                    l_int32  l,
                    l_int32  r,
                    l_int32  t,
                    l_int32  b)
{
l_int32  x, y, w, h;
 
    if (!box)
        return ERROR_INT("box not defined", __func__, 1);
    x = (l != -1) ? l : box->x;
    w = (r != -1) ? r - x + 1 : box->x + box->w - x;
    y = (t != -1) ? t : box->y;
    h = (b != -1) ? b - y + 1 : box->y + box->h - y;
    boxSetGeometry(box, x, y, w, h);
    return 0;
}
 
 
l_ok
boxIsValid(BOX      *box,
           l_int32  *pvalid)
{
    if (!pvalid)
        return ERROR_INT("&valid not defined", __func__, 1);
    *pvalid = 0;
    if (!box)
        return ERROR_INT("box not defined", __func__, 1);
 
    if (box->w > 0 && box->h > 0)
        *pvalid = 1;
    return 0;
}
 
 
/*---------------------------------------------------------------------*
 *             Boxa creation, destruction, copy, extension             *
 *---------------------------------------------------------------------*/
BOXA *
boxaCreate(l_int32  n)
{
BOXA  *boxa;
 
    if (n <= 0 || n > MaxBoxaPtrArraySize)
        n = InitialPtrArraySize;
 
    boxa = (BOXA *)LEPT_CALLOC(1, sizeof(BOXA));
    boxa->n = 0;
    boxa->nalloc = n;
    boxa->refcount = 1;
    if ((boxa->box = (BOX **)LEPT_CALLOC(n, sizeof(BOX *))) == NULL) {
        boxaDestroy(&boxa);
        return (BOXA *)ERROR_PTR("boxa ptrs not made", __func__, NULL);
    }
    return boxa;
}
 
 
BOXA *
boxaCopy(BOXA    *boxa,
         l_int32  copyflag)
{
l_int32  i;
BOX     *boxc;
BOXA    *boxac;
 
    if (!boxa)
        return (BOXA *)ERROR_PTR("boxa not defined", __func__, NULL);
 
    if (copyflag == L_CLONE) {
        boxa->refcount++;
        return boxa;
    }
 
    if (copyflag != L_COPY && copyflag != L_COPY_CLONE)
        return (BOXA *)ERROR_PTR("invalid copyflag", __func__, NULL);
 
    if ((boxac = boxaCreate(boxa->nalloc)) == NULL)
        return (BOXA *)ERROR_PTR("boxac not made", __func__, NULL);
    for (i = 0; i < boxa->n; i++) {
        if (copyflag == L_COPY)
            boxc = boxaGetBox(boxa, i, L_COPY);
        else   /* copy-clone */
            boxc = boxaGetBox(boxa, i, L_CLONE);
        boxaAddBox(boxac, boxc, L_INSERT);
    }
    return boxac;
}
 
 
void
boxaDestroy(BOXA  **pboxa)
{
l_int32  i;
BOXA    *boxa;
 
    if (pboxa == NULL) {
        L_WARNING("ptr address is null!\n", __func__);
        return;
    }
 
    if ((boxa = *pboxa) == NULL)
        return;
 
        /* Decrement the ref count.  If it is 0, destroy the boxa. */
    if (--boxa->refcount == 0) {
        for (i = 0; i < boxa->n; i++)
            boxDestroy(&boxa->box[i]);
        LEPT_FREE(boxa->box);
        LEPT_FREE(boxa);
    }
 
    *pboxa = NULL;
}
 
 
l_ok
boxaAddBox(BOXA    *boxa,
           BOX     *box,
           l_int32  copyflag)
{
l_int32  n;
BOX     *boxc;
 
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
    if (!box)
        return ERROR_INT("box not defined", __func__, 1);
 
    if (copyflag == L_INSERT)
        boxc = box;
    else if (copyflag == L_COPY)
        boxc = boxCopy(box);
    else if (copyflag == L_CLONE)
        boxc = boxClone(box);
    else
        return ERROR_INT("invalid copyflag", __func__, 1);
    if (!boxc)
        return ERROR_INT("boxc not made", __func__, 1);
 
    n = boxaGetCount(boxa);
    if (n >= boxa->nalloc) {
        if (boxaExtendArray(boxa)) {
            if (copyflag != L_INSERT)
                boxDestroy(&boxc);
            return ERROR_INT("extension failed", __func__, 1);
        }
    }
    boxa->box[n] = boxc;
    boxa->n++;
    return 0;
}
 
 
l_ok
boxaExtendArray(BOXA  *boxa)
{
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
 
    return boxaExtendArrayToSize(boxa, 2 * boxa->nalloc);
}
 
 
l_ok
boxaExtendArrayToSize(BOXA   *boxa,
                      size_t  size)
{
size_t  oldsize, newsize;
 
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
    if (boxa->nalloc > MaxBoxaPtrArraySize)  /* belt & suspenders */
        return ERROR_INT("boxa has too many ptrs", __func__, 1);
    if (size > MaxBoxaPtrArraySize)
        return ERROR_INT("size > 10M box ptrs; too large", __func__, 1);
    if (size <= boxa->nalloc) {
        L_INFO("size too small; no extension\n", __func__);
        return 0;
    }
 
    oldsize = boxa->nalloc * sizeof(BOX *);
    newsize = size * sizeof(BOX *);
    if ((boxa->box = (BOX **)reallocNew((void **)&boxa->box,
                                        oldsize, newsize)) == NULL)
        return ERROR_INT("new ptr array not returned", __func__, 1);
    boxa->nalloc = size;
    return 0;
}
 
 
/*---------------------------------------------------------------------*
 *                             Boxa accessors                          *
 *---------------------------------------------------------------------*/
l_int32
boxaGetCount(const BOXA  *boxa)
{
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 0);
    return boxa->n;
}
 
 
l_int32
boxaGetValidCount(BOXA  *boxa)
{
l_int32  n, i, w, h, count;
 
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 0);
 
    n = boxaGetCount(boxa);
    for (i = 0, count = 0; i < n; i++) {
        boxaGetBoxGeometry(boxa, i, NULL, NULL, &w, &h);
        if (w > 0 && h > 0)
            count++;
    }
    return count;
}
 
 
BOX *
boxaGetBox(BOXA    *boxa,
           l_int32  index,
           l_int32  accessflag)
{
    if (!boxa)
        return (BOX *)ERROR_PTR("boxa not defined", __func__, NULL);
    if (index < 0 || index >= boxa->n)
        return (BOX *)ERROR_PTR("index not valid", __func__, NULL);
 
    if (accessflag == L_COPY)
        return boxCopy(boxa->box[index]);
    else if (accessflag == L_CLONE)
        return boxClone(boxa->box[index]);
    else
        return (BOX *)ERROR_PTR("invalid accessflag", __func__, NULL);
}
 
 
BOX *
boxaGetValidBox(BOXA    *boxa,
                l_int32  index,
                l_int32  accessflag)
{
l_int32  w, h;
BOX     *box;
 
    if (!boxa)
        return (BOX *)ERROR_PTR("boxa not defined", __func__, NULL);
 
    if ((box = boxaGetBox(boxa, index, accessflag)) == NULL)
        return (BOX *)ERROR_PTR("box not returned", __func__, NULL);
    boxGetGeometry(box, NULL, NULL, &w, &h);
    if (w <= 0 || h <= 0)  /* not valid, but not necessarily an error */
        boxDestroy(&box);
    return box;
}
 
 
NUMA *
boxaFindInvalidBoxes(BOXA  *boxa)
{
l_int32  i, n, w, h;
NUMA    *na;
 
    if (!boxa)
        return (NUMA *)ERROR_PTR("boxa not defined", __func__, NULL);
 
    n = boxaGetCount(boxa);
    if (boxaGetValidCount(boxa) == n)
        return NULL;
 
    na = numaMakeConstant(0, n);
    for (i = 0; i < n; i++) {
        boxaGetBoxGeometry(boxa, i, NULL, NULL, &w, &h);
        if (w == 0 || h == 0)
            numaSetValue(na, i, 1);
    }
    return na;
}
 
 
l_ok
boxaGetBoxGeometry(BOXA     *boxa,
                   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 (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
    if (index < 0 || index >= boxa->n)
        return ERROR_INT("index not valid", __func__, 1);
 
    if ((box = boxaGetBox(boxa, index, L_CLONE)) == NULL)
        return ERROR_INT("box not found!", __func__, 1);
    boxGetGeometry(box, px, py, pw, ph);
    boxDestroy(&box);
    return 0;
}
 
 
l_ok
boxaIsFull(BOXA     *boxa,
           l_int32  *pfull)
{
l_int32  i, n, full;
BOX     *box;
 
    if (!pfull)
        return ERROR_INT("&full not defined", __func__, 1);
    *pfull = 0;
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
 
    n = boxaGetCount(boxa);
    full = 1;
    for (i = 0; i < n; i++) {
        if ((box = boxaGetBox(boxa, i, L_CLONE)) == NULL) {
            full = 0;
            break;
        }
        boxDestroy(&box);
    }
    *pfull = full;
    return 0;
}
 
 
/*---------------------------------------------------------------------*
 *                        Boxa array modifiers                         *
 *---------------------------------------------------------------------*/
l_ok
boxaReplaceBox(BOXA    *boxa,
               l_int32  index,
               BOX     *box)
{
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
    if (index < 0 || index >= boxa->n)
        return ERROR_INT("index not valid", __func__, 1);
    if (!box)
        return ERROR_INT("box not defined", __func__, 1);
 
    boxDestroy(&(boxa->box[index]));
    boxa->box[index] = box;
    return 0;
}
 
 
l_ok
boxaInsertBox(BOXA    *boxa,
              l_int32  index,
              BOX     *box)
{
l_int32  i, n;
BOX    **array;
 
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
    n = boxaGetCount(boxa);
    if (index < 0 || index > n) {
        L_ERROR("index %d not in [0,...,%d]\n", __func__, index, n);
        return 1;
    }
    if (!box)
        return ERROR_INT("box not defined", __func__, 1);
 
    if (n >= boxa->nalloc) {
        if (boxaExtendArray(boxa))
            return ERROR_INT("extension failed", __func__, 1);
    }
    array = boxa->box;
    boxa->n++;
    for (i = n; i > index; i--)
        array[i] = array[i - 1];
    array[index] = box;
    return 0;
}
 
 
l_ok
boxaRemoveBox(BOXA    *boxa,
              l_int32  index)
{
    return boxaRemoveBoxAndSave(boxa, index, NULL);
}
 
 
l_ok
boxaRemoveBoxAndSave(BOXA    *boxa,
                     l_int32  index,
                     BOX    **pbox)
{
l_int32  i, n;
BOX    **array;
 
    if (pbox) *pbox = NULL;
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
    n = boxaGetCount(boxa);
    if (index < 0 || index >= n) {
        L_ERROR("index %d not in [0,...,%d]\n", __func__, index, n - 1);
        return 1;
    }
 
    if (pbox)
        *pbox = boxaGetBox(boxa, index, L_CLONE);
    array = boxa->box;
    boxDestroy(&array[index]);
    for (i = index + 1; i < n; i++)
        array[i - 1] = array[i];
    array[n - 1] = NULL;
    boxa->n--;
 
    return 0;
}
 
 
BOXA *
boxaSaveValid(BOXA    *boxas,
              l_int32  copyflag)
{
l_int32  i, n;
BOX     *box;
BOXA    *boxad;
 
    if (!boxas)
        return (BOXA *)ERROR_PTR("boxas not defined", __func__, NULL);
    if (copyflag != L_COPY && copyflag != L_CLONE)
        return (BOXA *)ERROR_PTR("invalid copyflag", __func__, NULL);
 
    n = boxaGetCount(boxas);
    boxad = boxaCreate(n);
    for (i = 0; i < n; i++) {
        if ((box = boxaGetValidBox(boxas, i, copyflag)) != NULL)
            boxaAddBox(boxad, box, L_INSERT);
    }
 
    return boxad;
}
 
 
l_ok
boxaInitFull(BOXA  *boxa,
             BOX   *box)
{
l_int32  i, n;
BOX     *boxt;
 
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
 
    n = boxa->nalloc;
    boxa->n = n;
    for (i = 0; i < n; i++) {
        if (box)
            boxt = boxCopy(box);
        else
            boxt = boxCreate(0, 0, 0, 0);
        boxaReplaceBox(boxa, i, boxt);
    }
    return 0;
}
 
 
l_ok
boxaClear(BOXA  *boxa)
{
l_int32  i, n;
 
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
 
    n = boxaGetCount(boxa);
    for (i = 0; i < n; i++)
        boxDestroy(&boxa->box[i]);
    boxa->n = 0;
    return 0;
}
 
 
/*--------------------------------------------------------------------------*
 *                     Boxaa creation, destruction                          *
 *--------------------------------------------------------------------------*/
BOXAA *
boxaaCreate(l_int32  n)
{
BOXAA  *baa;
 
    if (n <= 0 || n > MaxBoxaaPtrArraySize)
        n = InitialPtrArraySize;
 
    baa = (BOXAA *)LEPT_CALLOC(1, sizeof(BOXAA));
    if ((baa->boxa = (BOXA **)LEPT_CALLOC(n, sizeof(BOXA *))) == NULL) {
        boxaaDestroy(&baa);
        return (BOXAA *)ERROR_PTR("boxa ptr array not made", __func__, NULL);
    }
    baa->nalloc = n;
    baa->n = 0;
    return baa;
}
 
 
BOXAA *
boxaaCopy(BOXAA   *baas,
          l_int32  copyflag)
{
l_int32  i, n;
BOXA    *boxa;
BOXAA   *baad;
 
    if (!baas)
        return (BOXAA *)ERROR_PTR("baas not defined", __func__, NULL);
    if (copyflag != L_COPY && copyflag != L_CLONE)
        return (BOXAA *)ERROR_PTR("invalid copyflag", __func__, NULL);
 
    n = boxaaGetCount(baas);
    baad = boxaaCreate(n);
    for (i = 0; i < n; i++) {
        boxa = boxaaGetBoxa(baas, i, copyflag);
        boxaaAddBoxa(baad, boxa, L_INSERT);
    }
 
    return baad;
}
 
 
void
boxaaDestroy(BOXAA  **pbaa)
{
l_int32  i;
BOXAA   *baa;
 
    if (pbaa == NULL) {
        L_WARNING("ptr address is NULL!\n", __func__);
        return;
    }
 
    if ((baa = *pbaa) == NULL)
        return;
 
    for (i = 0; i < baa->n; i++)
        boxaDestroy(&baa->boxa[i]);
    LEPT_FREE(baa->boxa);
    LEPT_FREE(baa);
    *pbaa = NULL;
}
 
 
 
/*--------------------------------------------------------------------------*
 *                              Add Boxa to Boxaa                           *
 *--------------------------------------------------------------------------*/
l_ok
boxaaAddBoxa(BOXAA   *baa,
             BOXA    *ba,
             l_int32  copyflag)
{
l_int32  n;
BOXA    *bac;
 
    if (!baa)
        return ERROR_INT("baa not defined", __func__, 1);
    if (!ba)
        return ERROR_INT("ba not defined", __func__, 1);
    if (copyflag != L_INSERT && copyflag != L_COPY && copyflag != L_CLONE)
        return ERROR_INT("invalid copyflag", __func__, 1);
 
    if (copyflag == L_INSERT)
        bac = ba;
    else
        bac = boxaCopy(ba, copyflag);
 
    n = boxaaGetCount(baa);
    if (n >= baa->nalloc) {
        if (boxaaExtendArray(baa))
            return ERROR_INT("extension failed", __func__, 1);
    }
    baa->boxa[n] = bac;
    baa->n++;
    return 0;
}
 
 
l_ok
boxaaExtendArray(BOXAA  *baa)
{
    if (!baa)
        return ERROR_INT("baa not defined", __func__, 1);
 
    return boxaaExtendArrayToSize(baa, 2 * baa->nalloc);
}
 
 
l_ok
boxaaExtendArrayToSize(BOXAA   *baa,
                       l_int32  size)
{
size_t  oldsize, newsize;
 
    if (!baa)
        return ERROR_INT("baa not defined", __func__, 1);
    if (baa->nalloc > MaxBoxaaPtrArraySize)  /* belt & suspenders */
        return ERROR_INT("baa has too many ptrs", __func__, 1);
    if (size > MaxBoxaaPtrArraySize)
        return ERROR_INT("size > 1M boxa ptrs; too large", __func__, 1);
    if (size <= baa->nalloc) {
        L_INFO("size too small; no extension\n", __func__);
        return 0;
    }
 
    oldsize = baa->nalloc * sizeof(BOXA *);
    newsize = size * sizeof(BOXA *);
    if ((baa->boxa = (BOXA **)reallocNew((void **)&baa->boxa,
                                         oldsize, newsize)) == NULL)
        return ERROR_INT("new ptr array not returned", __func__, 1);
    baa->nalloc = size;
    return 0;
}
 
 
/*----------------------------------------------------------------------*
 *                           Boxaa accessors                            *
 *----------------------------------------------------------------------*/
l_int32
boxaaGetCount(BOXAA  *baa)
{
    if (!baa)
        return ERROR_INT("baa not defined", __func__, 0);
    return baa->n;
}
 
 
l_int32
boxaaGetBoxCount(BOXAA  *baa)
{
BOXA    *boxa;
l_int32  n, sum, i;
 
    if (!baa)
        return ERROR_INT("baa not defined", __func__, 0);
 
    n = boxaaGetCount(baa);
    for (sum = 0, i = 0; i < n; i++) {
        boxa = boxaaGetBoxa(baa, i, L_CLONE);
        sum += boxaGetCount(boxa);
        boxaDestroy(&boxa);
    }
 
    return sum;
}
 
 
BOXA *
boxaaGetBoxa(BOXAA   *baa,
             l_int32  index,
             l_int32  accessflag)
{
l_int32  n;
 
    if (!baa)
        return (BOXA *)ERROR_PTR("baa not defined", __func__, NULL);
    n = boxaaGetCount(baa);
    if (index < 0 || index >= n)
        return (BOXA *)ERROR_PTR("index not valid", __func__, NULL);
    if (accessflag != L_COPY && accessflag != L_CLONE)
        return (BOXA *)ERROR_PTR("invalid accessflag", __func__, NULL);
 
    return boxaCopy(baa->boxa[index], accessflag);
}
 
 
BOX *
boxaaGetBox(BOXAA   *baa,
            l_int32  iboxa,
            l_int32  ibox,
            l_int32  accessflag)
{
BOX   *box;
BOXA  *boxa;
 
    if ((boxa = boxaaGetBoxa(baa, iboxa, L_CLONE)) == NULL)
        return (BOX *)ERROR_PTR("boxa not retrieved", __func__, NULL);
    if ((box = boxaGetBox(boxa, ibox, accessflag)) == NULL)
        L_ERROR("box not retrieved\n", __func__);
    boxaDestroy(&boxa);
    return box;
}
 
 
/*----------------------------------------------------------------------*
 *                           Boxaa array modifiers                      *
 *----------------------------------------------------------------------*/
l_ok
boxaaInitFull(BOXAA  *baa,
              BOXA   *boxa)
{
l_int32  i, n;
BOXA    *boxat;
 
    if (!baa)
        return ERROR_INT("baa not defined", __func__, 1);
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
 
    n = baa->nalloc;
    baa->n = n;
    for (i = 0; i < n; i++) {
        boxat = boxaCopy(boxa, L_COPY);
        boxaaReplaceBoxa(baa, i, boxat);
    }
    return 0;
}
 
 
l_ok
boxaaExtendWithInit(BOXAA   *baa,
                    l_int32  maxindex,
                    BOXA    *boxa)
{
l_int32  i, n;
 
    if (!baa)
        return ERROR_INT("baa not defined", __func__, 1);
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
 
        /* Extend the ptr array if necessary */
    n = boxaaGetCount(baa);
    if (maxindex < n) return 0;
    if (boxaaExtendArrayToSize(baa, maxindex + 1))
        return ERROR_INT("extension failed", __func__, 1);
 
        /* Fill the new entries with copies of boxa */
    for (i = n; i <= maxindex; i++)
        boxaaAddBoxa(baa, boxa, L_COPY);
    return 0;
}
 
 
l_ok
boxaaReplaceBoxa(BOXAA   *baa,
                 l_int32  index,
                 BOXA    *boxa)
{
l_int32  n;
 
    if (!baa)
        return ERROR_INT("baa not defined", __func__, 1);
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
    n = boxaaGetCount(baa);
    if (index < 0 || index >= n)
        return ERROR_INT("index not valid", __func__, 1);
 
    boxaDestroy(&baa->boxa[index]);
    baa->boxa[index] = boxa;
    return 0;
}
 
 
l_ok
boxaaInsertBoxa(BOXAA   *baa,
                l_int32  index,
                BOXA    *boxa)
{
l_int32  i, n;
BOXA   **array;
 
    if (!baa)
        return ERROR_INT("baa not defined", __func__, 1);
    n = boxaaGetCount(baa);
    if (index < 0 || index > n) {
        L_ERROR("index %d not in [0,...,%d]\n", __func__, index, n);
        return 1;
    }
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
 
    if (n >= baa->nalloc) {
        if (boxaaExtendArray(baa))
            return ERROR_INT("extension failed", __func__, 1);
    }
    array = baa->boxa;
    baa->n++;
    for (i = n; i > index; i--)
        array[i] = array[i - 1];
    array[index] = boxa;
    return 0;
}
 
 
l_ok
boxaaRemoveBoxa(BOXAA   *baa,
                l_int32  index)
{
l_int32  i, n;
BOXA   **array;
 
    if (!baa)
        return ERROR_INT("baa not defined", __func__, 1);
    n = boxaaGetCount(baa);
    if (index < 0 || index >= n)
        return ERROR_INT("index not valid", __func__, 1);
 
    array = baa->boxa;
    boxaDestroy(&array[index]);
    for (i = index + 1; i < n; i++)
        array[i - 1] = array[i];
    array[n - 1] = NULL;
    baa->n--;
 
    return 0;
}
 
 
l_ok
boxaaAddBox(BOXAA   *baa,
            l_int32  index,
            BOX     *box,
            l_int32  accessflag)
{
l_int32  n;
BOXA    *boxa;
    if (!baa)
        return ERROR_INT("baa not defined", __func__, 1);
    n = boxaaGetCount(baa);
    if (index < 0 || index >= n)
        return ERROR_INT("index not valid", __func__, 1);
    if (accessflag != L_INSERT && accessflag != L_COPY && accessflag != L_CLONE)
        return ERROR_INT("invalid accessflag", __func__, 1);
 
    boxa = boxaaGetBoxa(baa, index, L_CLONE);
    boxaAddBox(boxa, box, accessflag);
    boxaDestroy(&boxa);
    return 0;
}
 
 
/*---------------------------------------------------------------------*
 *                        Boxaa serialized I/O                         *
 *---------------------------------------------------------------------*/
BOXAA *
boxaaReadFromFiles(const char  *dirname,
                   const char  *substr,
                   l_int32      first,
                   l_int32      nfiles)
{
char    *fname;
l_int32  i, n;
BOXA    *boxa;
BOXAA   *baa;
SARRAY  *sa;
 
  if (!dirname)
      return (BOXAA *)ERROR_PTR("dirname not defined", __func__, NULL);
 
  sa = getSortedPathnamesInDirectory(dirname, substr, first, nfiles);
  if (!sa || ((n = sarrayGetCount(sa)) == 0)) {
      sarrayDestroy(&sa);
      return (BOXAA *)ERROR_PTR("no pixa files found", __func__, NULL);
  }
 
  baa = boxaaCreate(n);
  for (i = 0; i < n; i++) {
      fname = sarrayGetString(sa, i, L_NOCOPY);
      if ((boxa = boxaRead(fname)) == NULL) {
          L_ERROR("boxa not read for %d-th file", __func__, i);
          continue;
      }
      boxaaAddBoxa(baa, boxa, L_INSERT);
  }
 
  sarrayDestroy(&sa);
  return baa;
}
 
 
BOXAA *
boxaaRead(const char  *filename)
{
FILE   *fp;
BOXAA  *baa;
 
    if (!filename)
        return (BOXAA *)ERROR_PTR("filename not defined", __func__, NULL);
 
    if ((fp = fopenReadStream(filename)) == NULL)
        return (BOXAA *)ERROR_PTR_1("stream not opened",
                                    filename, __func__, NULL);
    baa = boxaaReadStream(fp);
    fclose(fp);
    if (!baa)
        return (BOXAA *)ERROR_PTR_1("boxaa not read",
                                    filename, __func__, NULL);
    return baa;
}
 
 
BOXAA *
boxaaReadStream(FILE  *fp)
{
l_int32  n, i, x, y, w, h, version;
l_int32  ignore;
BOXA    *boxa;
BOXAA   *baa;
 
    if (!fp)
        return (BOXAA *)ERROR_PTR("stream not defined", __func__, NULL);
 
    if (fscanf(fp, "\nBoxaa Version %d\n", &version) != 1)
        return (BOXAA *)ERROR_PTR("not a boxaa file", __func__, NULL);
    if (version != BOXAA_VERSION_NUMBER)
        return (BOXAA *)ERROR_PTR("invalid boxa version", __func__, NULL);
    if (fscanf(fp, "Number of boxa = %d\n", &n) != 1)
        return (BOXAA *)ERROR_PTR("not a boxaa file", __func__, NULL);
    if (n < 0)
        return (BOXAA *)ERROR_PTR("num boxa ptrs < 0", __func__, NULL);
    if (n > MaxBoxaaPtrArraySize)
        return (BOXAA *)ERROR_PTR("too many boxa ptrs", __func__, NULL);
    if (n == 0) L_INFO("the boxaa is empty\n", __func__);
 
    if ((baa = boxaaCreate(n)) == NULL)
        return (BOXAA *)ERROR_PTR("boxaa not made", __func__, NULL);
    for (i = 0; i < n; i++) {
        if (fscanf(fp, "\nBoxa[%d] extent: x = %d, y = %d, w = %d, h = %d",
                   &ignore, &x, &y, &w, &h) != 5) {
            boxaaDestroy(&baa);
            return (BOXAA *)ERROR_PTR("boxa descr not valid", __func__, NULL);
        }
        if ((boxa = boxaReadStream(fp)) == NULL) {
            boxaaDestroy(&baa);
            return (BOXAA *)ERROR_PTR("boxa not made", __func__, NULL);
        }
        boxaaAddBoxa(baa, boxa, L_INSERT);
    }
    return baa;
}
 
 
BOXAA *
boxaaReadMem(const l_uint8  *data,
             size_t          size)
{
FILE   *fp;
BOXAA  *baa;
 
    if (!data)
        return (BOXAA *)ERROR_PTR("data not defined", __func__, NULL);
    if ((fp = fopenReadFromMemory(data, size)) == NULL)
        return (BOXAA *)ERROR_PTR("stream not opened", __func__, NULL);
 
    baa = boxaaReadStream(fp);
    fclose(fp);
    if (!baa) L_ERROR("baa not read\n", __func__);
    return baa;
}
 
 
l_ok
boxaaWrite(const char  *filename,
           BOXAA       *baa)
{
l_int32  ret;
FILE    *fp;
 
    if (!filename)
        return ERROR_INT("filename not defined", __func__, 1);
    if (!baa)
        return ERROR_INT("baa not defined", __func__, 1);
 
    if ((fp = fopenWriteStream(filename, "w")) == NULL)
        return ERROR_INT_1("stream not opened", filename, __func__, 1);
    ret = boxaaWriteStream(fp, baa);
    fclose(fp);
    if (ret)
        return ERROR_INT_1("baa not written to stream", filename, __func__, 1);
    return 0;
}
 
 
l_ok
boxaaWriteStream(FILE   *fp,
                 BOXAA  *baa)
{
l_int32  n, i, x, y, w, h;
BOX     *box;
BOXA    *boxa;
 
    if (!fp)
        return ERROR_INT("stream not defined", __func__, 1);
    if (!baa)
        return ERROR_INT("baa not defined", __func__, 1);
 
    n = boxaaGetCount(baa);
    fprintf(fp, "\nBoxaa Version %d\n", BOXAA_VERSION_NUMBER);
    fprintf(fp, "Number of boxa = %d\n", n);
 
    for (i = 0; i < n; i++) {
        if ((boxa = boxaaGetBoxa(baa, i, L_CLONE)) == NULL)
            return ERROR_INT("boxa not found", __func__, 1);
        boxaGetExtent(boxa, NULL, NULL, &box);
        boxGetGeometry(box, &x, &y, &w, &h);
        fprintf(fp, "\nBoxa[%d] extent: x = %d, y = %d, w = %d, h = %d",
                i, x, y, w, h);
        boxaWriteStream(fp, boxa);
        boxDestroy(&box);
        boxaDestroy(&boxa);
    }
    return 0;
}
 
 
l_ok
boxaaWriteMem(l_uint8  **pdata,
              size_t    *psize,
              BOXAA     *baa)
{
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 (!baa)
        return ERROR_INT("baa not defined", __func__, 1);
 
#if HAVE_FMEMOPEN
    if ((fp = open_memstream((char **)pdata, psize)) == NULL)
        return ERROR_INT("stream not opened", __func__, 1);
    ret = boxaaWriteStream(fp, baa);
    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 = boxaaWriteStream(fp, baa);
    rewind(fp);
    *pdata = l_binaryReadStream(fp, psize);
    fclose(fp);
#endif  /* HAVE_FMEMOPEN */
    return ret;
}
 
 
/*---------------------------------------------------------------------*
 *                         Boxa serialized I/O                         *
 *---------------------------------------------------------------------*/
BOXA *
boxaRead(const char  *filename)
{
FILE  *fp;
BOXA  *boxa;
 
    if (!filename)
        return (BOXA *)ERROR_PTR("filename not defined", __func__, NULL);
 
    if ((fp = fopenReadStream(filename)) == NULL)
        return (BOXA *)ERROR_PTR_1("stream not opened",
                                   filename, __func__, NULL);
    boxa = boxaReadStream(fp);
    fclose(fp);
    if (!boxa)
        return (BOXA *)ERROR_PTR_1("boxa not read",
                                   filename, __func__, NULL);
    return boxa;
}
 
 
BOXA *
boxaReadStream(FILE  *fp)
{
l_int32  n, i, x, y, w, h, version;
l_int32  ignore;
BOX     *box;
BOXA    *boxa;
 
    if (!fp)
        return (BOXA *)ERROR_PTR("stream not defined", __func__, NULL);
 
    if (fscanf(fp, "\nBoxa Version %d\n", &version) != 1)
        return (BOXA *)ERROR_PTR("not a boxa file", __func__, NULL);
    if (version != BOXA_VERSION_NUMBER)
        return (BOXA *)ERROR_PTR("invalid boxa version", __func__, NULL);
    if (fscanf(fp, "Number of boxes = %d\n", &n) != 1)
        return (BOXA *)ERROR_PTR("not a boxa file", __func__, NULL);
    if (n < 0)
        return (BOXA *)ERROR_PTR("num box ptrs < 0", __func__, NULL);
    if (n > MaxBoxaPtrArraySize)
        return (BOXA *)ERROR_PTR("too many box ptrs", __func__, NULL);
    if (n == 0) L_INFO("the boxa is empty\n", __func__);
 
    if ((boxa = boxaCreate(n)) == NULL)
        return (BOXA *)ERROR_PTR("boxa not made", __func__, NULL);
    for (i = 0; i < n; i++) {
        if (fscanf(fp, "  Box[%d]: x = %d, y = %d, w = %d, h = %d\n",
                &ignore, &x, &y, &w, &h) != 5) {
            boxaDestroy(&boxa);
            return (BOXA *)ERROR_PTR("box descr not valid", __func__, NULL);
        }
        box = boxCreate(x, y, w, h);
        boxaAddBox(boxa, box, L_INSERT);
    }
    return boxa;
}
 
 
BOXA *
boxaReadMem(const l_uint8  *data,
            size_t          size)
{
FILE  *fp;
BOXA  *boxa;
 
    if (!data)
        return (BOXA *)ERROR_PTR("data not defined", __func__, NULL);
    if ((fp = fopenReadFromMemory(data, size)) == NULL)
        return (BOXA *)ERROR_PTR("stream not opened", __func__, NULL);
 
    boxa = boxaReadStream(fp);
    fclose(fp);
    if (!boxa) L_ERROR("boxa not read\n", __func__);
    return boxa;
}
 
 
l_ok
boxaWriteDebug(const char  *filename,
               BOXA        *boxa)
{
    if (LeptDebugOK) {
        return boxaWrite(filename, boxa);
    } else {
        L_INFO("write to named temp file %s is disabled\n", __func__, filename);
        return 0;
    }
}
 
 
l_ok
boxaWrite(const char  *filename,
          BOXA        *boxa)
{
l_int32  ret;
FILE    *fp;
 
    if (!filename)
        return ERROR_INT("filename not defined", __func__, 1);
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
 
    if ((fp = fopenWriteStream(filename, "w")) == NULL)
        return ERROR_INT_1("stream not opened", filename, __func__, 1);
    ret = boxaWriteStream(fp, boxa);
    fclose(fp);
    if (ret)
        return ERROR_INT_1("boxa not written to stream", filename, __func__, 1);
 
    return 0;
}
 
 
l_ok
boxaWriteStream(FILE  *fp,
                BOXA  *boxa)
{
l_int32  n, i;
BOX     *box;
 
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
    if (!fp)
        return boxaWriteStderr(boxa);
 
    n = boxaGetCount(boxa);
    fprintf(fp, "\nBoxa Version %d\n", BOXA_VERSION_NUMBER);
    fprintf(fp, "Number of boxes = %d\n", n);
    for (i = 0; i < n; i++) {
        if ((box = boxaGetBox(boxa, i, L_CLONE)) == NULL)
            return ERROR_INT("box not found", __func__, 1);
        fprintf(fp, "  Box[%d]: x = %d, y = %d, w = %d, h = %d\n",
                i, box->x, box->y, box->w, box->h);
        boxDestroy(&box);
    }
    return 0;
}
 
 
l_ok
boxaWriteStderr(BOXA  *boxa)
{
l_int32  n, i;
BOX     *box;
 
    if (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
 
    n = boxaGetCount(boxa);
    lept_stderr("\nBoxa Version %d\n", BOXA_VERSION_NUMBER);
    lept_stderr("Number of boxes = %d\n", n);
    for (i = 0; i < n; i++) {
        if ((box = boxaGetBox(boxa, i, L_CLONE)) == NULL)
            return ERROR_INT("box not found", __func__, 1);
        lept_stderr("  Box[%d]: x = %d, y = %d, w = %d, h = %d\n",
                i, box->x, box->y, box->w, box->h);
        boxDestroy(&box);
    }
    return 0;
}
 
 
l_ok
boxaWriteMem(l_uint8  **pdata,
             size_t    *psize,
             BOXA      *boxa)
{
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 (!boxa)
        return ERROR_INT("boxa not defined", __func__, 1);
 
#if HAVE_FMEMOPEN
    if ((fp = open_memstream((char **)pdata, psize)) == NULL)
        return ERROR_INT("stream not opened", __func__, 1);
    ret = boxaWriteStream(fp, boxa);
    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 = boxaWriteStream(fp, boxa);
    rewind(fp);
    *pdata = l_binaryReadStream(fp, psize);
    fclose(fp);
#endif  /* HAVE_FMEMOPEN */
    return ret;
}
 
 
/*---------------------------------------------------------------------*
 *                            Debug printing                           *
 *---------------------------------------------------------------------*/
l_ok
boxPrintStreamInfo(FILE  *fp,
                   BOX   *box)
{
    if (!box)
        return ERROR_INT("box not defined", __func__, 1);
 
    if (!fp) {  /* output to stderr */
        lept_stderr(" Box: x = %d, y = %d, w = %d, h = %d\n",
                    box->x, box->y, box->w, box->h);
    } else {
        fprintf(fp, " Box: x = %d, y = %d, w = %d, h = %d\n",
                box->x, box->y, box->w, box->h);
    }
    return 0;
}