#include "allheaders.h"

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)

BOXA *	boxaContainedInBox (BOXA boxas, BOX box)

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

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

BOXA *	boxaIntersectsBox (BOXA boxas, BOX box)

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

BOXA *	boxaClipToBox (BOXA boxas, BOX box)

BOXA *	boxaCombineOverlaps (BOXA boxas, PIXA pixadb)

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

BOX *	boxOverlapRegion (BOX box1, BOX box2)

BOX *	boxBoundingRegion (BOX box1, BOX box2)

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

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

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

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)

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

BOX *	boxaGetNearestToLine (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)

BOX *	boxClipToRectangle (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)

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

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

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

BOXA *	boxaSetSide (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)

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

BOXA *	boxaAdjustHeightToTarget (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)

BOXA *	boxaMergeEvenOdd (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   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()
          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

◆ boxaAdjustHeightToTarget()

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

boxaAdjustHeightToTarget()

Parameters

[in]	boxad	use NULL to get a new one
[in]	boxas
[in]	sides	L_ADJUST_TOP, L_ADJUST_BOT, L_ADJUST_TOP_AND_BOT
[in]	target	target height if differs by more than thresh
[in]	thresh	min 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 2038 of file boxfunc1.c.

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

Referenced by boxaReconcileEvenOddHeight().

◆ 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,delbot	changes 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 1750 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]	boxad	use NULL to get a new one; same as boxas for in-place
[in]	boxas
[in]	sides	L_ADJUST_LEFT, L_ADJUST_RIGHT, L_ADJUST_LEFT_AND_RIGHT
[in]	target	target width if differs by more than thresh
[in]	thresh	min 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 1971 of file boxfunc1.c.

References boxaCopy(), boxaGetBox(), boxaGetCount(), 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]	baad	dest boxaa; add to this one
[in]	baas	source boxaa; add from this one
[in]	istart	starting index in baas
[in]	iend	ending 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 2400 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]	box	for 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 385 of file boxfunc1.c.

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

◆ boxaCombineOverlaps()

BOXA* boxaCombineOverlaps	(	BOXA *	boxas,
		PIXA *	pixadb
	)

boxaCombineOverlaps()

Parameters

[in]	boxas
[in,out]	pixadb	debug 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 441 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]	boxas1	input boxa1
[in]	boxas2	input boxa2
[out]	pboxad1	output boxa1
[out]	pboxad2	output boxa2
[in,out]	pixadb	debug 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 535 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]	box	for containment

Returns: boxad boxa with all boxes in boxas that are entirely contained in box, or NULL on error

Notes:
     (1) All boxes in boxa that are entirely outside box are removed.

Definition at line 173 of file boxfunc1.c.

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

◆ boxaContainedInBoxa()

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

boxaContainedInBoxa()

Parameters

[in]	boxa1,boxa2
[out]	pcontained	1 if every box in boxa2 is contained in some box in boxa1; 0 otherwise

Returns: 0 if OK, 1 on error

Definition at line 250 of file boxfunc1.c.

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

◆ boxaContainedInBoxCount()

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

boxaContainedInBoxCount()

Parameters

[in]	boxa
[in]	box	for selecting contained boxes in boxa
[out]	pcount	number of boxes intersecting the box

Returns: 0 if OK, 1 on error

Definition at line 211 of file boxfunc1.c.

References boxaGetBox(), boxaGetCount(), boxContains(), boxDestroy(), 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]	boxs	starting box; to have sides adjusted
[in]	delleft,delright,deltop,delbot	changes 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 1807 of file boxfunc1.c.

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

Referenced by boxaAdjustSides(), boxaConstrainSize(), pixaAddBorderGeneral(), 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]	psame	1 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 2143 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]	boxa	either unsorted, or 2D sorted in LR/TB scan order
[in]	dist_select	L_NON_NEGATIVE, L_ALL
[in]	range	search distance from box i; use 0 to search entire boxa (e.g., if it's not 2D sorted)
[out]	pnaaindex	for each box in boxa, contains a numa of 4 box indices (per direction) of the nearest box
[out]	pnaadist	for 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 1224 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]	boxa	either unsorted, or 2D sorted in LR/TB scan order
[in]	i	box we test against
[in]	dir	direction to look: L_FROM_LEFT, L_FROM_RIGHT, L_FROM_TOP, L_FROM_BOT
[in]	dist_select	L_NON_NEGATIVE, L_ALL
[in]	range	search distance from box i; use 0 to search entire boxa (e.g., if it's not 2D sorted)
[out]	pindex	index in boxa of nearest box with overlapping coordinates in the indicated direction; -1 if there is no box
[out]	pdist	distance 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 1305 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 1167 of file boxfunc1.c.

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

◆ boxaGetNearestToPt()

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

boxaGetNearestToPt()

Parameters

[in]	boxa
[in]	x,y	point

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 1115 of file boxfunc1.c.

References boxaGetBox(), boxaGetCount(), 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]	op	L_COMBINE, L_REMOVE_SMALL
[in]	range	forward distance over which overlaps are checked; > 0
[in]	min_overlap	minimum fraction of smaller box required for overlap to count; 0.0 to ignore
[in]	max_ratio	maximum 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 853 of file boxfunc1.c.

References boxaAddBox(), boxaCopy(), boxaCreate(), boxaDestroy(), boxaGetBox(), boxaGetCount(), 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]	box	for 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 303 of file boxfunc1.c.

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

◆ boxaIntersectsBoxCount()

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

boxaIntersectsBoxCount()

Parameters

[in]	boxa
[in]	box	for selecting intersecting boxes in boxa
[out]	pcount	number of boxes intersecting the box

Returns: 0 if OK, 1 on error

Definition at line 341 of file boxfunc1.c.

References boxaGetBox(), boxaGetCount(), boxDestroy(), boxIntersects(), and L_CLONE.

◆ boxaJoin()

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

boxaJoin()

Parameters

[in]	boxad	dest boxa; add to this one
[in]	boxas	source boxa; add from this one
[in]	istart	starting index in boxas
[in]	iend	ending 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 2351 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]	boxae	boxes to go in even positions in merged boxa
[in]	boxao	boxes to go in odd positions in merged boxa
[in]	fillflag	1 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 2514 of file boxfunc1.c.

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

Referenced by boxaFillSequence(), boxaReconcileEvenOddHeight(), boxaReconcilePairWidth(), boxaSmoothSequenceLS(), and boxaSmoothSequenceMedian().

◆ boxaSetSide()

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

boxaSetSide()

Parameters

[in]	boxad	use NULL to get a new one; same as boxas for in-place
[in]	boxas
[in]	side	L_SET_LEFT, L_SET_RIGHT, L_SET_TOP, L_SET_BOT
[in]	val	location to set for given side, for each box
[in]	thresh	min 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 1859 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]	debug	output details of non-similar boxes
[out]	psimilar	1 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 2277 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]	fillflag	1 to put invalid boxes in place; 0 to omit
[out]	pboxae,pboxao	save 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 2450 of file boxfunc1.c.

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

Referenced by boxaFillSequence(), boxaMedianDimensions(), boxaReconcileEvenOddHeight(), boxaReconcilePairWidth(), boxaSizeVariation(), boxaSmoothSequenceLS(), 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.

Definition at line 715 of file boxfunc1.c.

References boxCreate(), and boxGetGeometry().

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

◆ boxClipToRectangle()

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

boxClipToRectangle()

Parameters

[in]	box
[in]	wi,hi	rectangle 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 1587 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,h	clipping box size; typ. the size of an image
[out]	pxstart	start x coordinate
[out]	pystart	start y coordinate
[out]	pxend	one pixel beyond clipping box
[out]	pyend	one 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 1644 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]	type	L_SORT_BY_WIDTH, L_SORT_BY_HEIGHT, L_SORT_BY_MAX_DIMENSION, L_SORT_BY_PERIMETER, L_SORT_BY_AREA,
[out]	prel	1 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 1029 of file boxfunc1.c.

References boxGetGeometry(), 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]	presult	1 if box2 is entirely contained within box1; 0 otherwise

Returns: 0 if OK, 1 on error

Definition at line 100 of file boxfunc1.c.

References boxGetGeometry().

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,y	a point
[out]	pcontains	1 if box contains point; 0 otherwise

Returns: 0 if OK, 1 on error.

Definition at line 1080 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]	psame	1 if equal; 0 otherwise

Returns: 0 if OK, 1 on error

Definition at line 2096 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,pcy	location of center of box

Returns: 0 if OK, 1 on error

Definition at line 1444 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]	c1	left or top coordinate of box1
[in]	s1	width or height of box1
[in]	c2	left or top coordinate of box2
[in]	s2	width or height of box2

Returns: distance between them (if < 0, box2 overlaps box1 in the dimension considered)

Definition at line 1421 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]	c1	left or top coordinate of box1
[in]	s1	width or height of box1
[in]	c2	left or top coordinate of box2
[in]	s2	width 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 1395 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,y	point that line goes through
[in]	slope	of line
[out]	px1,py1	1st point of intersection with box
[out]	px2,py2	2nd point of intersection with box
[out]	pn	number of points of intersection

Returns: 0 if OK, 1 on error

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 1485 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]	presult	1 if any part of box2 is contained in box1; 0 otherwise

Returns: 0 if OK, 1 on error

Definition at line 131 of file boxfunc1.c.

References boxGetGeometry().

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

◆ boxOverlapArea()

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

boxOverlapArea()

Parameters

[in]	box1,box2
[out]	parea	the number of pixels in the overlap

Returns: 0 if OK, 1 on error.

Definition at line 791 of file boxfunc1.c.

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

Referenced by boxaHandleOverlaps().

◆ boxOverlapFraction()

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

boxOverlapFraction()

Parameters

[in]	box1,box2
[out]	pfract	the 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.

Definition at line 755 of file boxfunc1.c.

References boxDestroy(), boxGetGeometry(), 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 673 of file boxfunc1.c.

References boxCreate(), and boxGetGeometry().

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]	boxs	starting box; to have one side relocated
[in]	loc	new location of the side that is changing
[in]	sideflag	L_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 1706 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,box2	two boxes, in any order
[out]	ph_sep	[optional] horizontal separation
[out]	pv_sep	[optional] vertical separation

Returns: 0 if OK, 1 on error

Notes:
     (1) This measures horizontal and vertical separation of the
         two boxes.  If the boxes are touching but have no pixels
         in common, the separation is 0.  If the boxes overlap by
         a distance d, the returned separation is -d.

Definition at line 973 of file boxfunc1.c.

References boxGetGeometry().

Referenced by recogExtractNumbers().

◆ boxSetSide()

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

boxSetSide()

Parameters

[in]	boxs
[in]	side	L_SET_LEFT, L_SET_RIGHT, L_SET_TOP, L_SET_BOT
[in]	val	location to set for given side, for each box
[in]	thresh	min 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 1909 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]	psimilar	1 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 2222 of file boxfunc1.c.

References boxGetSideLocations().

Referenced by boxaSimilar().

Functions

Detailed Description

Function Documentation

◆ boxaAdjustHeightToTarget()

◆ boxaAdjustSides()

◆ boxaAdjustWidthToTarget()

◆ boxaaJoin()

◆ boxaClipToBox()

◆ boxaCombineOverlaps()

◆ boxaCombineOverlapsInPair()

◆ boxaContainedInBox()

◆ boxaContainedInBoxa()

◆ boxaContainedInBoxCount()

◆ boxAdjustSides()

◆ boxaEqual()

◆ boxaFindNearestBoxes()

◆ boxaGetNearestByDirection()

◆ boxaGetNearestToLine()

◆ boxaGetNearestToPt()

◆ boxaHandleOverlaps()

◆ boxaIntersectsBox()

◆ boxaIntersectsBoxCount()

◆ boxaJoin()

◆ boxaMergeEvenOdd()

◆ boxaSetSide()

◆ boxaSimilar()

◆ boxaSplitEvenOdd()

◆ boxBoundingRegion()

◆ boxClipToRectangle()

◆ boxClipToRectangleParams()

◆ boxCompareSize()

◆ boxContains()

◆ boxContainsPt()

◆ boxEqual()

◆ boxGetCenter()

◆ boxGetDistanceInXorY()

◆ boxHasOverlapInXorY()

◆ boxIntersectByLine()

◆ boxIntersects()

◆ boxOverlapArea()

◆ boxOverlapFraction()

◆ boxOverlapRegion()

◆ boxRelocateOneSide()

◆ boxSeparationDistance()

◆ boxSetSide()

◆ boxSimilar()