#include "allheaders.h"
#include "pix_internal.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	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)

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 (const BOX box, l_float32 pcx, l_float32 *pcy)

l_ok	boxIntersectByLine (const 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)

l_ok	boxaAdjustBoxSides (BOXA *boxa, l_int32 index, 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   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,delbot	changes 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 1886 of file boxfunc1.c.

References boxAdjustSides(), and L_CLONE.

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

References 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,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 1838 of file boxfunc1.c.

References boxAdjustSides(), 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 2090 of file boxfunc1.c.

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

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

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

References boxBoundingRegion(), boxIntersects(), L_COPY, and L_INSERT.

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

References boxaCombineOverlaps(), boxBoundingRegion(), boxCompareSize(), boxIntersects(), L_COPY, L_INSERT, and L_SORT_BY_AREA.

◆ 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 boxas that are entirely outside box are removed.
     (2) If box is not valid, returns an empty boxa.

Definition at line 185 of file boxfunc1.c.

References boxContains(), 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 269 of file boxfunc1.c.

References boxContains(), 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

Notes:
     (1) If box is not valid, returns a zero count.

Definition at line 229 of file boxfunc1.c.

References boxContains(), 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 1932 of file boxfunc1.c.

Referenced by boxaAdjustBoxSides(), and boxaAdjustSides().

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

References boxEqual(), and L_CLONE.

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

References boxaGetNearestByDirection(), L_FROM_BOT, L_FROM_LEFT, L_FROM_RIGHT, L_FROM_TOP, and L_INSERT.

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

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

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

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

References boxBoundingRegion(), boxOverlapArea(), L_CLONE, L_COMBINE, L_COPY, L_INSERT, and L_REMOVE_SMALL.

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

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

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

References L_CLONE, and L_INSERT.

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

References L_COPY, and L_INSERT.

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

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

References boxSimilar(), and L_CLONE.

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

References L_COPY, and L_INSERT.

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

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

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

Referenced by boxClipToRectangleParams().

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

References boxClipToRectangle().

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

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

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

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

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

Referenced by boxaEqual().

◆ boxGetCenter()

l_ok boxGetCenter	(	const 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 or if box is not valid

Definition at line 1538 of file boxfunc1.c.

Referenced by boxaGetNearestToLine(), and boxaGetNearestToPt().

◆ 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 1515 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 1489 of file boxfunc1.c.

Referenced by boxaGetNearestByDirection().

◆ boxIntersectByLine()

l_ok boxIntersectByLine	(	const 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 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 1578 of file boxfunc1.c.

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

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

References boxOverlapRegion().

Referenced by boxaHandleOverlaps().

◆ boxOverlapDistance()

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

boxOverlapDistance()

Parameters

[in]	box1,box2	two 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 1015 of file boxfunc1.c.

Referenced by boxSeparationDistance().

◆ 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.
     (2) If at least one box is not valid, there is no overlap.

Definition at line 787 of file boxfunc1.c.

References boxOverlapRegion().

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

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

References 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	horizontal separation
[out]	pv_sep	vertical 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 1086 of file boxfunc1.c.

References boxOverlapDistance().

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

References L_SET_BOT, L_SET_LEFT, L_SET_RIGHT, and L_SET_TOP.

Referenced by 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 2331 of file boxfunc1.c.

Referenced by boxaSimilar().

Functions

Detailed Description

Function Documentation

◆ boxaAdjustBoxSides()

◆ 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()

◆ boxOverlapDistance()

◆ boxOverlapFraction()

◆ boxOverlapRegion()

◆ boxRelocateOneSide()

◆ boxSeparationDistance()

◆ boxSetSide()

◆ boxSimilar()