Leptonica  1.82.0
Image processing and image analysis suite
boxfunc1.c File Reference
#include "allheaders.h"

Go to the source code of this file.

Functions

static l_int32 boxHasOverlapInXorY (l_int32 c1, l_int32 s1, l_int32 c2, l_int32 s2)
 
static l_int32 boxGetDistanceInXorY (l_int32 c1, l_int32 s1, l_int32 c2, l_int32 s2)
 
l_ok boxContains (BOX *box1, BOX *box2, l_int32 *presult)
 
l_ok boxIntersects (BOX *box1, BOX *box2, l_int32 *presult)
 
BOXAboxaContainedInBox (BOXA *boxas, BOX *box)
 
l_ok boxaContainedInBoxCount (BOXA *boxa, BOX *box, l_int32 *pcount)
 
l_ok boxaContainedInBoxa (BOXA *boxa1, BOXA *boxa2, l_int32 *pcontained)
 
BOXAboxaIntersectsBox (BOXA *boxas, BOX *box)
 
l_ok boxaIntersectsBoxCount (BOXA *boxa, BOX *box, l_int32 *pcount)
 
BOXAboxaClipToBox (BOXA *boxas, BOX *box)
 
BOXAboxaCombineOverlaps (BOXA *boxas, PIXA *pixadb)
 
l_ok boxaCombineOverlapsInPair (BOXA *boxas1, BOXA *boxas2, BOXA **pboxad1, BOXA **pboxad2, PIXA *pixadb)
 
BOXboxOverlapRegion (BOX *box1, BOX *box2)
 
BOXboxBoundingRegion (BOX *box1, BOX *box2)
 
l_ok boxOverlapFraction (BOX *box1, BOX *box2, l_float32 *pfract)
 
l_ok boxOverlapArea (BOX *box1, BOX *box2, l_int32 *parea)
 
BOXAboxaHandleOverlaps (BOXA *boxas, l_int32 op, l_int32 range, l_float32 min_overlap, l_float32 max_ratio, NUMA **pnamap)
 
l_ok boxOverlapDistance (BOX *box1, BOX *box2, l_int32 *ph_ovl, l_int32 *pv_ovl)
 
l_ok boxSeparationDistance (BOX *box1, BOX *box2, l_int32 *ph_sep, l_int32 *pv_sep)
 
l_ok boxCompareSize (BOX *box1, BOX *box2, l_int32 type, l_int32 *prel)
 
l_ok boxContainsPt (BOX *box, l_float32 x, l_float32 y, l_int32 *pcontains)
 
BOXboxaGetNearestToPt (BOXA *boxa, l_int32 x, l_int32 y)
 
BOXboxaGetNearestToLine (BOXA *boxa, l_int32 x, l_int32 y)
 
l_ok boxaFindNearestBoxes (BOXA *boxa, l_int32 dist_select, l_int32 range, NUMAA **pnaaindex, NUMAA **pnaadist)
 
l_ok boxaGetNearestByDirection (BOXA *boxa, l_int32 i, l_int32 dir, l_int32 dist_select, l_int32 range, l_int32 *pindex, l_int32 *pdist)
 
l_ok boxGetCenter (BOX *box, l_float32 *pcx, l_float32 *pcy)
 
l_ok boxIntersectByLine (BOX *box, l_int32 x, l_int32 y, l_float32 slope, l_int32 *px1, l_int32 *py1, l_int32 *px2, l_int32 *py2, l_int32 *pn)
 
BOXboxClipToRectangle (BOX *box, l_int32 wi, l_int32 hi)
 
l_ok boxClipToRectangleParams (BOX *box, l_int32 w, l_int32 h, l_int32 *pxstart, l_int32 *pystart, l_int32 *pxend, l_int32 *pyend, l_int32 *pbw, l_int32 *pbh)
 
BOXboxRelocateOneSide (BOX *boxd, BOX *boxs, l_int32 loc, l_int32 sideflag)
 
BOXAboxaAdjustSides (BOXA *boxas, l_int32 delleft, l_int32 delright, l_int32 deltop, l_int32 delbot)
 
l_ok boxaAdjustBoxSides (BOXA *boxa, l_int32 index, l_int32 delleft, l_int32 delright, l_int32 deltop, l_int32 delbot)
 
BOXboxAdjustSides (BOX *boxd, BOX *boxs, l_int32 delleft, l_int32 delright, l_int32 deltop, l_int32 delbot)
 
BOXAboxaSetSide (BOXA *boxad, BOXA *boxas, l_int32 side, l_int32 val, l_int32 thresh)
 
l_ok boxSetSide (BOX *boxs, l_int32 side, l_int32 val, l_int32 thresh)
 
BOXAboxaAdjustWidthToTarget (BOXA *boxad, BOXA *boxas, l_int32 sides, l_int32 target, l_int32 thresh)
 
BOXAboxaAdjustHeightToTarget (BOXA *boxad, BOXA *boxas, l_int32 sides, l_int32 target, l_int32 thresh)
 
l_ok boxEqual (BOX *box1, BOX *box2, l_int32 *psame)
 
l_ok boxaEqual (BOXA *boxa1, BOXA *boxa2, l_int32 maxdist, NUMA **pnaindex, l_int32 *psame)
 
l_ok boxSimilar (BOX *box1, BOX *box2, l_int32 leftdiff, l_int32 rightdiff, l_int32 topdiff, l_int32 botdiff, l_int32 *psimilar)
 
l_ok boxaSimilar (BOXA *boxa1, BOXA *boxa2, l_int32 leftdiff, l_int32 rightdiff, l_int32 topdiff, l_int32 botdiff, l_int32 debug, l_int32 *psimilar, NUMA **pnasim)
 
l_ok boxaJoin (BOXA *boxad, BOXA *boxas, l_int32 istart, l_int32 iend)
 
l_ok boxaaJoin (BOXAA *baad, BOXAA *baas, l_int32 istart, l_int32 iend)
 
l_ok boxaSplitEvenOdd (BOXA *boxa, l_int32 fillflag, BOXA **pboxae, BOXA **pboxao)
 
BOXAboxaMergeEvenOdd (BOXA *boxae, BOXA *boxao, l_int32 fillflag)
 

Detailed Description

     Box geometry
          l_int32   boxContains()
          l_int32   boxIntersects()
          BOXA     *boxaContainedInBox()
          l_int32   boxaContainedInBoxCount()
          l_int32   boxaContainedInBoxa()
          BOXA     *boxaIntersectsBox()
          l_int32   boxaIntersectsBoxCount()
          BOXA     *boxaClipToBox()
          BOXA     *boxaCombineOverlaps()
          l_int32   boxaCombineOverlapsInPair()
          BOX      *boxOverlapRegion()
          BOX      *boxBoundingRegion()
          l_int32   boxOverlapFraction()
          l_int32   boxOverlapArea()
          BOXA     *boxaHandleOverlaps()
          l_int32   boxOverlapDistance()
          l_int32   boxSeparationDistance()
          l_int32   boxCompareSize()
          l_int32   boxContainsPt()
          BOX      *boxaGetNearestToPt()
          BOX      *boxaGetNearestToLine()
          l_int32   boxaFindNearestBoxes()
          l_int32   boxaGetNearestByDirection()
   static l_int32   boxHasOverlapInXorY()
   static l_int32   boxGetDistanceInXorY()
          l_int32   boxIntersectByLine()
          l_int32   boxGetCenter()
          BOX      *boxClipToRectangle()
          l_int32   boxClipToRectangleParams()
          BOX      *boxRelocateOneSide()
          BOXA     *boxaAdjustSides()
          BOXA     *boxaAdjustBoxSides()
          BOX      *boxAdjustSides()
          BOXA     *boxaSetSide()
          l_int32   boxSetSide()
          BOXA     *boxaAdjustWidthToTarget()
          BOXA     *boxaAdjustHeightToTarget()
          l_int32   boxEqual()
          l_int32   boxaEqual()
          l_int32   boxSimilar()
          l_int32   boxaSimilar()
     Boxa combine and split
          l_int32   boxaJoin()
          l_int32   boxaaJoin()
          l_int32   boxaSplitEvenOdd()
          BOXA     *boxaMergeEvenOdd()

Definition in file boxfunc1.c.

Function Documentation

◆ boxaAdjustBoxSides()

l_ok boxaAdjustBoxSides ( BOXA boxa,
l_int32  index,
l_int32  delleft,
l_int32  delright,
l_int32  deltop,
l_int32  delbot 
)

boxaAdjustBoxSides()

Parameters
[in]boxas
[in]index
[in]delleft,delright,deltop,delbotchanges to box side locs
Returns
0 if OK, 1 on error
Notes:
     (1) In-place operation on a box in a boxa.
     (2) New box dimensions are cropped at left and top to x >= 0 and y >= 0.
     (3) If a box ends up with no area, an error message is emitted,
         but the box dimensions are not changed.
     (4) See boxaAdjustSides().

Definition at line 1943 of file boxfunc1.c.

References boxAdjustSides(), boxaGetBox(), boxDestroy(), and L_CLONE.

◆ boxaAdjustHeightToTarget()

BOXA* boxaAdjustHeightToTarget ( BOXA boxad,
BOXA boxas,
l_int32  sides,
l_int32  target,
l_int32  thresh 
)

boxaAdjustHeightToTarget()

Parameters
[in]boxaduse NULL to get a new one
[in]boxas
[in]sidesL_ADJUST_TOP, L_ADJUST_BOT, L_ADJUST_TOP_AND_BOT
[in]targettarget height if differs by more than thresh
[in]threshmin abs difference in height to cause adjustment
Returns
boxad, or NULL on error
Notes:
     (1) Conditionally adjusts the height of each box, by moving
         the indicated edges (top and/or bot) if the height differs
         by thresh or more from target.
     (2) Use boxad == NULL for a new boxa, and boxad == boxas for in-place.
         Use one of these:
              boxad = boxaAdjustHeightToTarget(NULL, boxas, ...);   // new
              boxaAdjustHeightToTarget(boxas, boxas, ...);  // in-place

Definition at line 2223 of file boxfunc1.c.

References boxaCopy(), boxaGetCount(), boxaGetValidBox(), boxDestroy(), boxGetGeometry(), boxSetGeometry(), L_ADJUST_BOT, L_ADJUST_TOP, L_ADJUST_TOP_AND_BOT, L_CLONE, and L_COPY.

◆ boxaAdjustSides()

BOXA* boxaAdjustSides ( BOXA boxas,
l_int32  delleft,
l_int32  delright,
l_int32  deltop,
l_int32  delbot 
)

boxaAdjustSides()

Parameters
[in]boxas
[in]delleft,delright,deltop,delbotchanges in location of each side for each box
Returns
boxad, or NULL on error
Notes:
     (1) New box dimensions are cropped at left and top to x >= 0 and y >= 0.
     (2) If the width or height of a box goes to 0, we generate a box with
         w == 1 and h == 1, as a placeholder.
     (3) See boxAdjustSides().

Definition at line 1893 of file boxfunc1.c.

References boxaAddBox(), boxaCreate(), boxAdjustSides(), boxaGetBox(), boxaGetCount(), boxCreate(), boxDestroy(), boxGetGeometry(), L_COPY, and L_INSERT.

◆ boxaAdjustWidthToTarget()

BOXA* boxaAdjustWidthToTarget ( BOXA boxad,
BOXA boxas,
l_int32  sides,
l_int32  target,
l_int32  thresh 
)

boxaAdjustWidthToTarget()

Parameters
[in]boxaduse NULL to get a new one; same as boxas for in-place
[in]boxas
[in]sidesL_ADJUST_LEFT, L_ADJUST_RIGHT, L_ADJUST_LEFT_AND_RIGHT
[in]targettarget width if differs by more than thresh
[in]threshmin abs difference in width to cause adjustment
Returns
boxad, or NULL on error
Notes:
     (1) Conditionally adjusts the width of each box, by moving
         the indicated edges (left and/or right) if the width differs
         by thresh or more from target.
     (2) Use boxad == NULL for a new boxa, and boxad == boxas for in-place.
         Use one of these:
              boxad = boxaAdjustWidthToTarget(NULL, boxas, ...);   // new
              boxaAdjustWidthToTarget(boxas, boxas, ...);  // in-place

Definition at line 2155 of file boxfunc1.c.

References boxaCopy(), boxaGetCount(), boxaGetValidBox(), boxDestroy(), boxGetGeometry(), boxSetGeometry(), L_ADJUST_LEFT, L_ADJUST_LEFT_AND_RIGHT, L_ADJUST_RIGHT, L_CLONE, and L_COPY.

◆ boxaaJoin()

l_ok boxaaJoin ( BOXAA baad,
BOXAA baas,
l_int32  istart,
l_int32  iend 
)

boxaaJoin()

Parameters
[in]baaddest boxaa; add to this one
[in]baassource boxaa; add from this one
[in]istartstarting index in baas
[in]iendending index in baas; use -1 to cat all
Returns
0 if OK, 1 on error
Notes:
     (1) This appends a clone of each indicated boxa in baas to baad
     (2) istart < 0 is taken to mean 'read from the start' (istart = 0)
     (3) iend < 0 means 'read to the end'
     (4) if baas == NULL, this is a no-op.

Definition at line 2586 of file boxfunc1.c.

References boxaaAddBoxa(), boxaaGetBoxa(), boxaaGetCount(), L_CLONE, and L_INSERT.

◆ boxaClipToBox()

BOXA* boxaClipToBox ( BOXA boxas,
BOX box 
)

boxaClipToBox()

Parameters
[in]boxas
[in]boxfor clipping
Returns
boxad boxa with boxes in boxas clipped to box, or NULL on error
Notes:
     (1) All boxes in boxa not intersecting with box are removed, and
         the remaining boxes are clipped to box.

Definition at line 419 of file boxfunc1.c.

References boxaAddBox(), boxaCreate(), boxaGetCount(), boxaGetValidBox(), boxDestroy(), boxIsValid(), boxOverlapRegion(), L_CLONE, and L_INSERT.

◆ boxaCombineOverlaps()

BOXA* boxaCombineOverlaps ( BOXA boxas,
PIXA pixadb 
)

boxaCombineOverlaps()

Parameters
[in]boxas
[in,out]pixadbdebug output
Returns
boxad where each set of boxes in boxas that overlap are combined into a single bounding box in boxad, or NULL on error.
Notes:
     (1) If there are no overlapping boxes, it simply returns a copy
         of boxas.
     (2) Input an empty pixadb, using pixaCreate(0), for debug output.
         The output gives 2 visualizations of the boxes per iteration;
         boxes in red before, and added boxes in green after. Note that
         all pixels in the red boxes are contained in the green ones.
     (3) The alternative method of painting each rectangle and finding
         the 4-connected components gives a different result in
         general, because two non-overlapping (but touching)
         rectangles, when rendered, are 4-connected and will be joined.
     (4) A bad case computationally is to have n boxes, none of which
         overlap.  Then you have one iteration with O(n^2) compares.
         This is still faster than painting each rectangle and finding
         the bounding boxes of the connected components, even for
         thousands of rectangles.

Definition at line 478 of file boxfunc1.c.

References boxaCopy(), boxaDestroy(), boxaGetCount(), boxaGetExtent(), boxaGetValidBox(), boxaReplaceBox(), boxaSaveValid(), boxBoundingRegion(), boxCopy(), boxCreate(), boxDestroy(), boxIntersects(), L_COPY, L_INSERT, pixaAddPix(), pixCreate(), pixDestroy(), pixRenderBoxaArb(), and pixSetAll().

Referenced by boxaCombineOverlapsInPair().

◆ boxaCombineOverlapsInPair()

l_ok boxaCombineOverlapsInPair ( BOXA boxas1,
BOXA boxas2,
BOXA **  pboxad1,
BOXA **  pboxad2,
PIXA pixadb 
)

boxaCombineOverlapsInPair()

Parameters
[in]boxas1input boxa1
[in]boxas2input boxa2
[out]pboxad1output boxa1
[out]pboxad2output boxa2
[in,out]pixadbdebug output
Returns
0 if OK, 1 on error
Notes:
     (1) One of three things happens to each box in boxa1 and boxa2:
          * it gets absorbed into a larger box that it overlaps with
          * it absorbs a smaller (by area) box that it overlaps with
            and gets larger, using the bounding region of the 2 boxes
          * it is unchanged (including absorbing smaller boxes that
            are contained within it).
     (2) If all the boxes from one of the input boxa are absorbed, this
         returns an empty boxa.
     (3) Input an empty pixadb, using pixaCreate(0), for debug output
     (4) This is useful if different operations are to be carried out
         on possibly overlapping rectangular regions, and it is desired
         to have only one operation on any rectangular region.

Definition at line 572 of file boxfunc1.c.

References boxaCombineOverlaps(), boxaCopy(), boxaDestroy(), boxaGetArea(), boxaGetCount(), boxaGetExtent(), boxaGetValidBox(), boxaReplaceBox(), boxaSaveValid(), boxBoundingRegion(), boxCompareSize(), boxCopy(), boxCreate(), boxDestroy(), boxIntersects(), L_COPY, L_INSERT, L_SORT_BY_AREA, pixaAddPix(), pixCreate(), pixRenderBoxaArb(), and pixSetAll().

◆ boxaContainedInBox()

BOXA* boxaContainedInBox ( BOXA boxas,
BOX box 
)

boxaContainedInBox()

Parameters
[in]boxas
[in]boxfor containment
Returns
boxad boxa with all boxes in boxas that are entirely contained in box, or NULL on error
Notes:
     (1) All boxes in boxas that are entirely outside box are removed.
     (2) If box is not valid, returns an empty boxa.

Definition at line 188 of file boxfunc1.c.

References boxaAddBox(), boxaCreate(), boxaGetCount(), boxaGetValidBox(), boxContains(), boxDestroy(), boxIsValid(), L_CLONE, and L_COPY.

◆ boxaContainedInBoxa()

l_ok boxaContainedInBoxa ( BOXA boxa1,
BOXA boxa2,
l_int32 *  pcontained 
)

boxaContainedInBoxa()

Parameters
[in]boxa1,boxa2
[out]pcontained1 if every box in boxa2 is contained in some box in boxa1; 0 otherwise
Returns
0 if OK, 1 on error

Definition at line 276 of file boxfunc1.c.

References boxaGetCount(), boxaGetValidBox(), boxContains(), boxDestroy(), and L_CLONE.

◆ boxaContainedInBoxCount()

l_ok boxaContainedInBoxCount ( BOXA boxa,
BOX box,
l_int32 *  pcount 
)

boxaContainedInBoxCount()

Parameters
[in]boxa
[in]boxfor selecting contained boxes in boxa
[out]pcountnumber of boxes intersecting the box
Returns
0 if OK, 1 on error
Notes:
     (1) If box is not valid, returns a zero count.

Definition at line 234 of file boxfunc1.c.

References boxaGetCount(), boxaGetValidBox(), boxContains(), boxDestroy(), boxIsValid(), and L_CLONE.

◆ boxAdjustSides()

BOX* boxAdjustSides ( BOX boxd,
BOX boxs,
l_int32  delleft,
l_int32  delright,
l_int32  deltop,
l_int32  delbot 
)

boxAdjustSides()

Parameters
[in]boxd[optional]; this can be null, equal to boxs, or different from boxs
[in]boxsstarting box; to have sides adjusted
[in]delleft,delright,deltop,delbotchanges in location of each side
Returns
boxd, or NULL on error or if the computed boxd has width or height <= 0.
Notes:
     (1) Set boxd == NULL to get new box; boxd == boxs for in-place;
         or otherwise to resize existing boxd.
     (2) For usage, suggest one of these:
              boxd = boxAdjustSides(NULL, boxs, ...);   // new
              boxAdjustSides(boxs, boxs, ...);          // in-place
              boxAdjustSides(boxd, boxs, ...);          // other
     (3) New box dimensions are cropped at left and top to x >= 0 and y >= 0.
     (4) For example, to expand in-place by 20 pixels on each side, use
            boxAdjustSides(box, box, -20, 20, -20, 20);

Definition at line 1991 of file boxfunc1.c.

References boxCreate(), boxGetGeometry(), and boxSetGeometry().

Referenced by boxaAdjustBoxSides(), boxaAdjustSides(), pixaAddBorderGeneral(), pixClipRectangleWithBorder(), and showExtractNumbers().

◆ boxaEqual()

l_ok boxaEqual ( BOXA boxa1,
BOXA boxa2,
l_int32  maxdist,
NUMA **  pnaindex,
l_int32 *  psame 
)

boxaEqual()

Parameters
[in]boxa1
[in]boxa2
[in]maxdist
[out]pnaindex[optional] index array of correspondences
[out]psame1 if equal; 0 otherwise
Returns
0 if OK, 1 on error
Notes:
     (1) The two boxa are the "same" if they contain the same
         boxes and each box is within maxdist of its counterpart
         in their positions within the boxa.  This allows for
         small rearrangements.  Use 0 for maxdist if the boxa
         must be identical.
     (2) This applies only to geometry and ordering; refcounts
         are not considered.
     (3) maxdist allows some latitude in the ordering of the boxes.
         For the boxa to be the "same", corresponding boxes must
         be within maxdist of each other.  Note that for large
         maxdist, we should use a hash function for efficiency.
     (4) naindex[i] gives the position of the box in boxa2 that
         corresponds to box i in boxa1.  It is only returned if the
         boxa are equal.

Definition at line 2325 of file boxfunc1.c.

References boxaGetBox(), boxaGetCount(), boxDestroy(), boxEqual(), L_CLONE, numaDestroy(), numaMakeConstant(), and numaReplaceNumber().

Referenced by pixaEqual().

◆ boxaFindNearestBoxes()

l_ok boxaFindNearestBoxes ( BOXA boxa,
l_int32  dist_select,
l_int32  range,
NUMAA **  pnaaindex,
NUMAA **  pnaadist 
)

boxaFindNearestBoxes()

Parameters
[in]boxaeither unsorted, or 2D sorted in LR/TB scan order
[in]dist_selectL_NON_NEGATIVE, L_ALL
[in]rangesearch distance from box i; use 0 to search entire boxa (e.g., if it's not 2D sorted)
[out]pnaaindexfor each box in boxa, contains a numa of 4 box indices (per direction) of the nearest box
[out]pnaadistfor each box in boxa, this contains a numa
Returns
0 if OK, 1 on error
Notes:
     (1) See boxaGetNearestByDirection() for usage of dist_select
         and range.

Definition at line 1363 of file boxfunc1.c.

References boxaGetCount(), boxaGetNearestByDirection(), L_FROM_BOT, L_FROM_LEFT, L_FROM_RIGHT, L_FROM_TOP, L_INSERT, numaaAddNuma(), numaaCreate(), numaAddNumber(), and numaCreate().

◆ boxaGetNearestByDirection()

l_ok boxaGetNearestByDirection ( BOXA boxa,
l_int32  i,
l_int32  dir,
l_int32  dist_select,
l_int32  range,
l_int32 *  pindex,
l_int32 *  pdist 
)

boxaGetNearestByDirection()

Parameters
[in]boxaeither unsorted, or 2D sorted in LR/TB scan order
[in]ibox we test against
[in]dirdirection to look: L_FROM_LEFT, L_FROM_RIGHT, L_FROM_TOP, L_FROM_BOT
[in]dist_selectL_NON_NEGATIVE, L_ALL
[in]rangesearch distance from box i; use 0 to search entire boxa (e.g., if it's not 2D sorted)
[out]pindexindex in boxa of nearest box with overlapping coordinates in the indicated direction; -1 if there is no box
[out]pdistdistance of the nearest box in the indicated direction; 100000 if no box
Returns
0 if OK, 1 on error
Notes:
     (1) For efficiency, use a LR/TD sorted boxa, which can be
         made by flattening a 2D sorted boxaa.  In that case,
         range can be some positive integer like 50.
     (2) If boxes overlap, the distance will be < 0.  Use dist_select
         to determine if these should count or not.  If L_ALL, then
         one box will match as the nearest to another in 2 or more
         directions.

Definition at line 1444 of file boxfunc1.c.

References boxaGetBoxGeometry(), boxaGetCount(), boxGetDistanceInXorY(), boxHasOverlapInXorY(), L_ALL, L_FROM_BOT, L_FROM_LEFT, L_FROM_RIGHT, L_FROM_TOP, and L_NON_NEGATIVE.

Referenced by boxaFindNearestBoxes().

◆ boxaGetNearestToLine()

BOX* boxaGetNearestToLine ( BOXA boxa,
l_int32  x,
l_int32  y 
)

boxaGetNearestToLine()

Parameters
[in]boxa
[in]x,y(y = -1 for vertical line; x = -1 for horiz line)
Returns
box with centroid closest to the given line, or NULL if no boxes in boxa
Notes:
     (1) For a horizontal line at some value y, get the minimum of the
         distance |yc - y| from the box centroid yc value to y;
         likewise minimize |xc - x| for a vertical line at x.
     (2) Input y < 0, x >= 0 to indicate a vertical line at x, and
         x < 0, y >= 0 for a horizontal line at y.

Definition at line 1305 of file boxfunc1.c.

References boxaGetBox(), boxaGetCount(), boxaGetValidBox(), boxDestroy(), boxGetCenter(), L_CLONE, and L_COPY.

◆ boxaGetNearestToPt()

BOX* boxaGetNearestToPt ( BOXA boxa,
l_int32  x,
l_int32  y 
)

boxaGetNearestToPt()

Parameters
[in]boxa
[in]x,ypoint
Returns
box with centroid closest to the given point [x,y], or NULL if no boxes in boxa
Notes:
     (1) Uses euclidean distance between centroid and point.

Definition at line 1252 of file boxfunc1.c.

References boxaGetBox(), boxaGetCount(), boxaGetValidBox(), boxDestroy(), boxGetCenter(), L_CLONE, and L_COPY.

◆ boxaHandleOverlaps()

BOXA* boxaHandleOverlaps ( BOXA boxas,
l_int32  op,
l_int32  range,
l_float32  min_overlap,
l_float32  max_ratio,
NUMA **  pnamap 
)

boxaHandleOverlaps()

Parameters
[in]boxas
[in]opL_COMBINE, L_REMOVE_SMALL
[in]rangeforward distance over which overlaps are checked; > 0
[in]min_overlapminimum fraction of smaller box required for overlap to count; 0.0 to ignore
[in]max_ratiomaximum fraction of small/large areas for overlap to count; 1.0 to ignore
[out]pnamap[optional] combining map
Returns
boxad, or NULL on error.
Notes:
     (1) For all n(n-1)/2 box pairings, if two boxes overlap, either:
         (a) op == L_COMBINE: get the bounding region for the two,
             replace the larger with the bounding region, and remove
             the smaller of the two, or
         (b) op == L_REMOVE_SMALL: just remove the smaller.
     (2) If boxas is 2D sorted, range can be small, but if it is
         not spatially sorted, range should be large to allow all
         pairwise comparisons to be made.
     (3) The min_overlap parameter allows ignoring small overlaps.
         If min_overlap == 1.0, only boxes fully contained in larger
         boxes can be considered for removal; if min_overlap == 0.0,
         this constraint is ignored.
     (4) The max_ratio parameter allows ignoring overlaps between
         boxes that are not too different in size.  If max_ratio == 0.0,
         no boxes can be removed; if max_ratio == 1.0, this constraint
         is ignored.

Definition at line 914 of file boxfunc1.c.

References boxaAddBox(), boxaCopy(), boxaCreate(), boxaDestroy(), boxaGetBox(), boxaGetCount(), boxaGetValidBox(), boxaReplaceBox(), boxBoundingRegion(), boxDestroy(), boxGetGeometry(), boxOverlapArea(), L_CLONE, L_COMBINE, L_COPY, L_INSERT, L_REMOVE_SMALL, numaDestroy(), numaGetIValue(), numaMakeConstant(), and numaSetValue().

Referenced by boxaSort2d().

◆ boxaIntersectsBox()

BOXA* boxaIntersectsBox ( BOXA boxas,
BOX box 
)

boxaIntersectsBox()

Parameters
[in]boxas
[in]boxfor intersecting
Returns
boxad boxa with all boxes in boxas that intersect box, or NULL on error
Notes:
     (1) All boxes in boxa that intersect with box (i.e., are completely
         or partially contained in box) are retained.

Definition at line 331 of file boxfunc1.c.

References boxaAddBox(), boxaCreate(), boxaGetCount(), boxaGetValidBox(), boxDestroy(), boxIntersects(), boxIsValid(), L_CLONE, and L_COPY.

◆ boxaIntersectsBoxCount()

l_ok boxaIntersectsBoxCount ( BOXA boxa,
BOX box,
l_int32 *  pcount 
)

boxaIntersectsBoxCount()

Parameters
[in]boxa
[in]boxfor selecting intersecting boxes in boxa
[out]pcountnumber of boxes intersecting the box
Returns
0 if OK, 1 on error

Definition at line 372 of file boxfunc1.c.

References boxaGetCount(), boxaGetValidBox(), boxDestroy(), boxIntersects(), boxIsValid(), and L_CLONE.

◆ boxaJoin()

l_ok boxaJoin ( BOXA boxad,
BOXA boxas,
l_int32  istart,
l_int32  iend 
)

boxaJoin()

Parameters
[in]boxaddest boxa; add to this one
[in]boxassource boxa; add from this one
[in]istartstarting index in boxas
[in]iendending index in boxas; use -1 to cat all
Returns
0 if OK, 1 on error
Notes:
     (1) This appends a clone of each indicated box in boxas to boxad
     (2) istart < 0 is taken to mean 'read from the start' (istart = 0)
     (3) iend < 0 means 'read to the end'
     (4) if boxas == NULL or has no boxes, this is a no-op.

Definition at line 2537 of file boxfunc1.c.

References boxaAddBox(), boxaGetBox(), boxaGetCount(), L_CLONE, and L_INSERT.

Referenced by boxaSort2d(), pixacompJoin(), and pixaJoin().

◆ boxaMergeEvenOdd()

BOXA* boxaMergeEvenOdd ( BOXA boxae,
BOXA boxao,
l_int32  fillflag 
)

boxaMergeEvenOdd()

Parameters
[in]boxaeboxes to go in even positions in merged boxa
[in]boxaoboxes to go in odd positions in merged boxa
[in]fillflag1 if there are invalid boxes in placeholders
Returns
boxad merged, or NULL on error
Notes:
     (1) This is essentially the inverse of boxaSplitEvenOdd().
         Typically, boxae and boxao were generated by boxaSplitEvenOdd(),
         and the value of fillflag needs to be the same in both calls.
     (2) If fillflag == 1, both boxae and boxao are of the same size;
         otherwise boxae may have one more box than boxao.

Definition at line 2700 of file boxfunc1.c.

References boxaAddBox(), boxaCreate(), boxaGetBox(), boxaGetCount(), L_COPY, and L_INSERT.

Referenced by boxaFillSequence(), boxaReconcileAllByMedian(), boxaReconcilePairWidth(), and boxaSmoothSequenceMedian().

◆ boxaSetSide()

BOXA* boxaSetSide ( BOXA boxad,
BOXA boxas,
l_int32  side,
l_int32  val,
l_int32  thresh 
)

boxaSetSide()

Parameters
[in]boxaduse NULL to get a new one; same as boxas for in-place
[in]boxas
[in]sideL_SET_LEFT, L_SET_RIGHT, L_SET_TOP, L_SET_BOT
[in]vallocation to set for given side, for each box
[in]threshmin abs difference to cause resetting to val
Returns
boxad, or NULL on error
Notes:
     (1) Sets the given side of each box.  Use boxad == NULL for a new
         boxa, and boxad == boxas for in-place.
     (2) Use one of these:
              boxad = boxaSetSide(NULL, boxas, ...);   // new
              boxaSetSide(boxas, boxas, ...);  // in-place

Definition at line 2043 of file boxfunc1.c.

References boxaCopy(), boxaGetBox(), boxaGetCount(), boxDestroy(), boxSetSide(), L_CLONE, L_COPY, L_SET_BOT, L_SET_LEFT, L_SET_RIGHT, and L_SET_TOP.

◆ boxaSimilar()

l_ok boxaSimilar ( BOXA boxa1,
BOXA boxa2,
l_int32  leftdiff,
l_int32  rightdiff,
l_int32  topdiff,
l_int32  botdiff,
l_int32  debug,
l_int32 *  psimilar,
NUMA **  pnasim 
)

boxaSimilar()

Parameters
[in]boxa1
[in]boxa2
[in]leftdiff,rightdiff,topdiff,botdiff
[in]debugoutput details of non-similar boxes
[out]psimilar1 if similar; 0 otherwise
[out]pnasim[optional] na containing 1 if similar; else 0
Returns
0 if OK, 1 on error
Notes:
     (1) See boxSimilar() for parameter usage.
     (2) Corresponding boxes are taken in order in the two boxa.
     (3) nasim is an indicator array with a (0/1) for each box pair.
     (4) With nasim or debug == 1, boxes continue to be tested
         after failure.

Definition at line 2463 of file boxfunc1.c.

References boxaGetBox(), boxaGetCount(), boxDestroy(), boxSimilar(), L_CLONE, numaAddNumber(), and numaCreate().

◆ boxaSplitEvenOdd()

l_ok boxaSplitEvenOdd ( BOXA boxa,
l_int32  fillflag,
BOXA **  pboxae,
BOXA **  pboxao 
)

boxaSplitEvenOdd()

Parameters
[in]boxa
[in]fillflag1 to put invalid boxes in place; 0 to omit
[out]pboxae,pboxaosave even and odd boxes in their separate boxa, setting the other type to invalid boxes.
Returns
0 if OK, 1 on error
Notes:
     (1) If fillflag == 1, boxae has copies of the even boxes
         in their original location, and nvalid boxes are placed
         in the odd array locations.  And v.v.
     (2) If fillflag == 0, boxae has only copies of the even boxes.

Definition at line 2636 of file boxfunc1.c.

References boxaAddBox(), boxaCreate(), boxaGetBox(), boxaGetCount(), boxCreate(), L_COPY, and L_INSERT.

Referenced by boxaFillSequence(), boxaMedianDimensions(), boxaReconcileAllByMedian(), boxaReconcilePairWidth(), boxaSizeVariation(), and boxaSmoothSequenceMedian().

◆ boxBoundingRegion()

BOX* boxBoundingRegion ( BOX box1,
BOX box2 
)

boxBoundingRegion()

Parameters
[in]box1,box2
Returns
box of bounding region containing the input boxes; NULL on error
Notes:
     (1) This is the geometric union of the two rectangles.
     (2) Invalid boxes are ignored.  This returns an invalid box
         if both input boxes are invalid.
     (3) For the geometric union of a boxa, use boxaGetExtent().

Definition at line 760 of file boxfunc1.c.

References boxCopy(), boxCreate(), boxGetGeometry(), and boxIsValid().

Referenced by boxaCombineOverlaps(), boxaCombineOverlapsInPair(), and boxaHandleOverlaps().

◆ boxClipToRectangle()

BOX* boxClipToRectangle ( BOX box,
l_int32  wi,
l_int32  hi 
)

boxClipToRectangle()

Parameters
[in]box
[in]wi,hirectangle representing image
Returns
part of box within given rectangle, or NULL on error or if box is entirely outside the rectangle
Notes:
     (1) This can be used to clip a rectangle to an image.
         The clipping rectangle is assumed to have a UL corner at (0, 0),
         and a LR corner at (wi - 1, hi - 1).

Definition at line 1728 of file boxfunc1.c.

References boxCopy(), Box::h, Box::w, Box::x, and Box::y.

Referenced by boxaGetCoverage(), boxClipToRectangleParams(), and pixClipRectangle().

◆ boxClipToRectangleParams()

l_ok boxClipToRectangleParams ( BOX box,
l_int32  w,
l_int32  h,
l_int32 *  pxstart,
l_int32 *  pystart,
l_int32 *  pxend,
l_int32 *  pyend,
l_int32 *  pbw,
l_int32 *  pbh 
)

boxClipToRectangleParams()

Parameters
[in]box[optional] requested box; can be null
[in]w,hclipping box size; typ. the size of an image
[out]pxstartstart x coordinate
[out]pystartstart y coordinate
[out]pxendone pixel beyond clipping box
[out]pyendone pixel beyond clipping box
[out]pbw[optional] clipped width
[out]pbh[optional] clipped height
Returns
0 if OK; 1 on error
Notes:
     (1) The return value should be checked.  If it is 1, the
         returned parameter values are bogus.
     (2) This simplifies the selection of pixel locations within
         a given rectangle:
            for (i = ystart; i < yend; i++ {
                ...
                for (j = xstart; j < xend; j++ {
                    ....

Definition at line 1785 of file boxfunc1.c.

References boxClipToRectangle(), boxDestroy(), and boxGetGeometry().

◆ boxCompareSize()

l_ok boxCompareSize ( BOX box1,
BOX box2,
l_int32  type,
l_int32 *  prel 
)

boxCompareSize()

Parameters
[in]box1,box2
[in]typeL_SORT_BY_WIDTH, L_SORT_BY_HEIGHT, L_SORT_BY_MAX_DIMENSION, L_SORT_BY_PERIMETER, L_SORT_BY_AREA,
[out]prel1 if box1 > box2, 0 if the same, -1 if box1 < box2
Returns
0 if OK, 1 on error
Notes:
     (1) We're re-using the SORT enum for these comparisons.

Definition at line 1162 of file boxfunc1.c.

References boxGetGeometry(), boxIsValid(), L_SORT_BY_AREA, L_SORT_BY_HEIGHT, L_SORT_BY_MAX_DIMENSION, L_SORT_BY_PERIMETER, and L_SORT_BY_WIDTH.

Referenced by boxaCombineOverlapsInPair().

◆ boxContains()

l_ok boxContains ( BOX box1,
BOX box2,
l_int32 *  presult 
)

boxContains()

Parameters
[in]box1,box2
[out]presult1 if box2 is entirely contained within box1; 0 otherwise
Returns
0 if OK, 1 on error

Definition at line 106 of file boxfunc1.c.

References boxGetGeometry(), and boxIsValid().

Referenced by boxaContainedInBox(), boxaContainedInBoxa(), and boxaContainedInBoxCount().

◆ boxContainsPt()

l_ok boxContainsPt ( BOX box,
l_float32  x,
l_float32  y,
l_int32 *  pcontains 
)

boxContainsPt()

Parameters
[in]box
[in]x,ya point
[out]pcontains1 if box contains point; 0 otherwise
Returns
0 if OK, 1 on error.

Definition at line 1217 of file boxfunc1.c.

References boxGetGeometry().

Referenced by ptaGetInsideBox().

◆ boxEqual()

l_ok boxEqual ( BOX box1,
BOX box2,
l_int32 *  psame 
)

boxEqual()

Parameters
[in]box1
[in]box2
[out]psame1 if equal; 0 otherwise
Returns
0 if OK, 1 on error

Definition at line 2278 of file boxfunc1.c.

References Box::h, Box::w, Box::x, and Box::y.

Referenced by boxaEqual().

◆ boxGetCenter()

l_ok boxGetCenter ( BOX box,
l_float32 *  pcx,
l_float32 *  pcy 
)

boxGetCenter()

Parameters
[in]box
[out]pcx,pcylocation of center of box
Returns
0 if OK, 1 on error or if box is not valid

Definition at line 1583 of file boxfunc1.c.

References boxGetGeometry().

Referenced by boxaGetNearestToLine(), boxaGetNearestToPt(), and boxaSelectPivotBox().

◆ boxGetDistanceInXorY()

static l_int32 boxGetDistanceInXorY ( l_int32  c1,
l_int32  s1,
l_int32  c2,
l_int32  s2 
)
static

boxGetDistanceInXorY()

Parameters
[in]c1left or top coordinate of box1
[in]s1width or height of box1
[in]c2left or top coordinate of box2
[in]s2width or height of box2
Returns
distance between them (if < 0, box2 overlaps box1 in the dimension considered)

Definition at line 1560 of file boxfunc1.c.

Referenced by boxaGetNearestByDirection().

◆ boxHasOverlapInXorY()

static l_int32 boxHasOverlapInXorY ( l_int32  c1,
l_int32  s1,
l_int32  c2,
l_int32  s2 
)
static

boxHasOverlapInXorY()

Parameters
[in]c1left or top coordinate of box1
[in]s1width or height of box1
[in]c2left or top coordinate of box2
[in]s2width or height of box2
Returns
0 if no overlap; 1 if any overlap
Notes:
     (1) Like boxGetDistanceInXorY(), this is used for overlaps both in
         x (which projected vertically) and in y (projected horizontally)

Definition at line 1534 of file boxfunc1.c.

Referenced by boxaGetNearestByDirection().

◆ boxIntersectByLine()

l_ok boxIntersectByLine ( BOX box,
l_int32  x,
l_int32  y,
l_float32  slope,
l_int32 *  px1,
l_int32 *  py1,
l_int32 *  px2,
l_int32 *  py2,
l_int32 *  pn 
)

boxIntersectByLine()

Parameters
[in]box
[in]x,ypoint that line goes through
[in]slopeof line
[out]px1,py11st point of intersection with box
[out]px2,py22nd point of intersection with box
[out]pnnumber of points of intersection
Returns
0 if OK, 1 on error or if box is not valid
Notes:
     (1) If the intersection is at only one point (a corner), the
         coordinates are returned in (x1, y1).
     (2) Represent a vertical line by one with a large but finite slope.

Definition at line 1625 of file boxfunc1.c.

References boxGetGeometry(), ptaAddPt(), ptaCreate(), ptaDestroy(), ptaGetCount(), and ptaGetIPt().

Referenced by generatePtaHashBox().

◆ boxIntersects()

l_ok boxIntersects ( BOX box1,
BOX box2,
l_int32 *  presult 
)

boxIntersects()

Parameters
[in]box1,box2
[out]presult1 if any part of box2 is contained in box1; 0 otherwise
Returns
0 if OK, 1 on error

Definition at line 141 of file boxfunc1.c.

References boxGetGeometry(), and boxIsValid().

Referenced by boxaCombineOverlaps(), boxaCombineOverlapsInPair(), boxaIntersectsBox(), and boxaIntersectsBoxCount().

◆ boxOverlapArea()

l_ok boxOverlapArea ( BOX box1,
BOX box2,
l_int32 *  parea 
)

boxOverlapArea()

Parameters
[in]box1,box2
[out]pareathe number of pixels in the overlap
Returns
0 if OK, 1 on error.

Definition at line 850 of file boxfunc1.c.

References boxDestroy(), boxGetGeometry(), boxIsValid(), and boxOverlapRegion().

Referenced by boxaHandleOverlaps().

◆ boxOverlapDistance()

l_ok boxOverlapDistance ( BOX box1,
BOX box2,
l_int32 *  ph_ovl,
l_int32 *  pv_ovl 
)

boxOverlapDistance()

Parameters
[in]box1,box2two boxes, in any order
[out]ph_ovl[optional] horizontal overlap
[out]pv_ovl[optional] vertical overlap
Returns
0 if OK, 1 on error
Notes:
     (1) This measures horizontal and vertical overlap of the
         two boxes.  Horizontal and vertical overlap are measured
         independently.  We need to consider several cases to clarify.
     (2) A positive horizontal overlap means that there is at least
         one point on the the box1 boundary with the same x-component
         as some point on the box2 boundary.  Conversely, with a zero
         or negative horizontal overlap, there are no boundary pixels
         in box1 that share an x-component with a boundary pixel in box2.
     (3) For a zero or negative horizontal overlap, o <= 0, the minimum
         difference in the x-component between pixels on the boundaries
         of the two boxes is d = -o + 1.
     (4) Likewise for vertical overlaps.

Definition at line 1044 of file boxfunc1.c.

References boxGetGeometry(), and boxIsValid().

Referenced by boxSeparationDistance(), and recogExtractNumbers().

◆ boxOverlapFraction()

l_ok boxOverlapFraction ( BOX box1,
BOX box2,
l_float32 *  pfract 
)

boxOverlapFraction()

Parameters
[in]box1,box2
[out]pfractthe fraction of box2 overlapped by box1
Returns
0 if OK, 1 on error.
Notes:
     (1) The result depends on the order of the input boxes,
         because the overlap is taken as a fraction of box2.
     (2) If at least one box is not valid, there is no overlap.

Definition at line 810 of file boxfunc1.c.

References boxDestroy(), boxGetGeometry(), boxIsValid(), and boxOverlapRegion().

Referenced by boxaPruneSortedOnOverlap(), and boxCheckIfOverlapIsBig().

◆ boxOverlapRegion()

BOX* boxOverlapRegion ( BOX box1,
BOX box2 
)

boxOverlapRegion()

Parameters
[in]box1,box2
Returns
box of overlap region between input boxes; NULL if no overlap or on error
Notes:
     (1) This is the geometric intersection of the two rectangles.

Definition at line 710 of file boxfunc1.c.

References boxCreate(), boxGetGeometry(), and boxIsValid().

Referenced by boxaClipToBox(), boxOverlapArea(), and boxOverlapFraction().

◆ boxRelocateOneSide()

BOX* boxRelocateOneSide ( BOX boxd,
BOX boxs,
l_int32  loc,
l_int32  sideflag 
)

boxRelocateOneSide()

Parameters
[in]boxd[optional]; this can be null, equal to boxs, or different from boxs;
[in]boxsstarting box; to have one side relocated
[in]locnew location of the side that is changing
[in]sideflagL_FROM_LEFT, etc., indicating the side that moves
Returns
boxd, or NULL on error or if the computed boxd has width or height <= 0.
Notes:
     (1) Set boxd == NULL to get new box; boxd == boxs for in-place;
         or otherwise to resize existing boxd.
     (2) For usage, suggest one of these:
              boxd = boxRelocateOneSide(NULL, boxs, ...);   // new
              boxRelocateOneSide(boxs, boxs, ...);          // in-place
              boxRelocateOneSide(boxd, boxs, ...);          // other

Definition at line 1847 of file boxfunc1.c.

References boxCopy(), boxGetGeometry(), boxSetGeometry(), L_FROM_BOT, L_FROM_LEFT, L_FROM_RIGHT, and L_FROM_TOP.

◆ boxSeparationDistance()

l_ok boxSeparationDistance ( BOX box1,
BOX box2,
l_int32 *  ph_sep,
l_int32 *  pv_sep 
)

boxSeparationDistance()

Parameters
[in]box1,box2two boxes, in any order
[out]ph_sephorizontal separation
[out]pv_sepvertical separation
Returns
0 if OK, 1 on error
Notes:
     (1) This measures the Manhattan distance between the closest points
         on the boundaries of the two boxes.  When the boxes overlap
         (including touching along a line or at a corner), the
         horizontal and vertical distances are 0.
     (2) The distances represent the horizontal and vertical separation
         of the two boxes.  The boxes have a nonzero intersection when
         both the horizontal and vertical overlaps are positive, and
         for that case both horizontal and vertical separation
         distances are 0.
     (3) If the horizontal overlap of the boxes is positive, the
         horizontal separation between nearest points on respective
         boundaries is 0, and likewise for the vertical overlap.
     (4) If the horizontal overlap ho <= 0, the horizontal
         separation between nearest points is d = -ho + 1.
         Likewise, if the vertical overlap vo <= 0, the vertical
         separation between nearest points is d = -vo + 1.

Definition at line 1117 of file boxfunc1.c.

References boxIsValid(), and boxOverlapDistance().

◆ boxSetSide()

l_ok boxSetSide ( BOX boxs,
l_int32  side,
l_int32  val,
l_int32  thresh 
)

boxSetSide()

Parameters
[in]boxs
[in]sideL_SET_LEFT, L_SET_RIGHT, L_SET_TOP, L_SET_BOT
[in]vallocation to set for given side, for each box
[in]threshmin abs difference to cause resetting to val
Returns
0 if OK, 1 on error
Notes:
     (1) In-place operation.
     (2) Use thresh = 0 to definitely set the side to val.

Definition at line 2093 of file boxfunc1.c.

References boxGetGeometry(), boxSetGeometry(), L_SET_BOT, L_SET_LEFT, L_SET_RIGHT, and L_SET_TOP.

Referenced by boxaReconcileSizeByMedian(), and boxaSetSide().

◆ boxSimilar()

l_ok boxSimilar ( BOX box1,
BOX box2,
l_int32  leftdiff,
l_int32  rightdiff,
l_int32  topdiff,
l_int32  botdiff,
l_int32 *  psimilar 
)

boxSimilar()

Parameters
[in]box1
[in]box2
[in]leftdiff,rightdiff,topdiff,botdiff
[out]psimilar1 if similar; 0 otherwise
Returns
0 if OK, 1 on error
Notes:
     (1) The values of leftdiff (etc) are the maximum allowed deviations
         between the locations of the left (etc) sides.  If any side
         pairs differ by more than this amount, the boxes are not similar.

Definition at line 2404 of file boxfunc1.c.

References boxGetSideLocations(), and boxIsValid().

Referenced by boxaSimilar().