#include <math.h>
#include "allheaders.h"
#include "pix_internal.h"

Functions
BOXA *	boxaSelectRange (BOXA *boxas, l_int32 first, l_int32 last, l_int32 copyflag)

BOXAA *	boxaaSelectRange (BOXAA *baas, l_int32 first, l_int32 last, l_int32 copyflag)

BOXA *	boxaSelectBySize (BOXA boxas, l_int32 width, l_int32 height, l_int32 type, l_int32 relation, l_int32 pchanged)

NUMA *	boxaMakeSizeIndicator (BOXA *boxa, l_int32 width, l_int32 height, l_int32 type, l_int32 relation)

BOXA *	boxaSelectByArea (BOXA boxas, l_int32 area, l_int32 relation, l_int32 pchanged)

NUMA *	boxaMakeAreaIndicator (BOXA *boxa, l_int32 area, l_int32 relation)

BOXA *	boxaSelectByWHRatio (BOXA boxas, l_float32 ratio, l_int32 relation, l_int32 pchanged)

NUMA *	boxaMakeWHRatioIndicator (BOXA *boxa, l_float32 ratio, l_int32 relation)

BOXA *	boxaSelectWithIndicator (BOXA boxas, NUMA na, l_int32 *pchanged)

BOXA *	boxaPermutePseudorandom (BOXA *boxas)

BOXA *	boxaPermuteRandom (BOXA boxad, BOXA boxas)

l_ok	boxaSwapBoxes (BOXA *boxa, l_int32 i, l_int32 j)

PTA *	boxaConvertToPta (BOXA *boxa, l_int32 ncorners)

BOXA *	ptaConvertToBoxa (PTA *pta, l_int32 ncorners)

PTA *	boxConvertToPta (BOX *box, l_int32 ncorners)

BOX *	ptaConvertToBox (PTA *pta)

l_ok	boxaGetExtent (BOXA boxa, l_int32 pw, l_int32 ph, BOX *pbox)

l_ok	boxaGetCoverage (BOXA boxa, l_int32 wc, l_int32 hc, l_int32 exactflag, l_float32 pfract)

l_ok	boxaaSizeRange (BOXAA baa, l_int32 pminw, l_int32 pminh, l_int32 pmaxw, l_int32 *pmaxh)

l_ok	boxaSizeRange (BOXA boxa, l_int32 pminw, l_int32 pminh, l_int32 pmaxw, l_int32 *pmaxh)

l_ok	boxaLocationRange (BOXA boxa, l_int32 pminx, l_int32 pminy, l_int32 pmaxx, l_int32 *pmaxy)

l_ok	boxaGetSizes (BOXA boxa, NUMA pnaw, NUMA *pnah)

l_ok	boxaGetArea (BOXA boxa, l_int32 parea)

PIX *	boxaDisplayTiled (BOXA boxas, PIXA pixa, l_int32 first, l_int32 last, l_int32 maxwidth, l_int32 linewidth, l_float32 scalefactor, l_int32 background, l_int32 spacing, l_int32 border)

Detailed Description


     Boxa and Boxaa range selection
          BOXA     *boxaSelectRange()
          BOXAA    *boxaaSelectRange()

     Boxa size selection
          BOXA     *boxaSelectBySize()
          NUMA     *boxaMakeSizeIndicator()
          BOXA     *boxaSelectByArea()
          NUMA     *boxaMakeAreaIndicator()
          BOXA     *boxaSelectByWHRatio()
          NUMA     *boxaMakeWHRatioIndicator()
          BOXA     *boxaSelectWithIndicator()

     Boxa permutation
          BOXA     *boxaPermutePseudorandom()
          BOXA     *boxaPermuteRandom()
          l_int32   boxaSwapBoxes()

     Boxa and box conversions
          PTA      *boxaConvertToPta()
          BOXA     *ptaConvertToBoxa()
          PTA      *boxConvertToPta()
          BOX      *ptaConvertToBox()

     Miscellaneous boxa functions
          l_int32   boxaGetExtent()
          l_int32   boxaGetCoverage()
          l_int32   boxaaSizeRange()
          l_int32   boxaSizeRange()
          l_int32   boxaLocationRange()
          NUMA     *boxaGetSizes()
          l_int32   boxaGetArea()
          PIX      *boxaDisplayTiled()

Definition in file boxfunc4.c.

Function Documentation

◆ boxaaSelectRange()

BOXAA * boxaaSelectRange	(	BOXAA *	baas,
		l_int32	first,
		l_int32	last,
		l_int32	copyflag )

boxaaSelectRange()

Parameters

[in]	baas
[in]	first	use 0 to select from the beginning
[in]	last	use -1 to select to the end
[in]	copyflag	L_COPY, L_CLONE

Returns: baad, or NULL on error

Notes:
     (1) The copyflag specifies what we do with each boxa from baas.
         Specifically, L_CLONE inserts a clone into baad of each
         selected boxa from baas.

Definition at line 151 of file boxfunc4.c.

References L_CLONE, L_COPY, and L_INSERT.

◆ boxaaSizeRange()

l_ok boxaaSizeRange	(	BOXAA *	baa,
		l_int32 *	pminw,
		l_int32 *	pminh,
		l_int32 *	pmaxw,
		l_int32 *	pmaxh )

boxaaSizeRange()

Parameters

[in]	baa
[out]	pminw	[optional] min width of all boxes
[out]	pmaxw	[optional] max width of all boxes
[out]	pminh	[optional] min height of all boxes
[out]	pmaxh	[optional] max height of all boxes

Returns: 0 if OK, 1 on error

Definition at line 1047 of file boxfunc4.c.

References boxaSizeRange(), and L_CLONE.

◆ boxaConvertToPta()

PTA * boxaConvertToPta	(	BOXA *	boxa,
		l_int32	ncorners )

boxaConvertToPta()

Parameters

[in]	boxa
[in]	ncorners	2 or 4 for the representation of each box

Returns: pta with ncorners points for each box in the boxa, or NULL on error

Notes:
     (1) If ncorners == 2, we select the UL and LR corners.
         Otherwise we save all 4 corners in this order: UL, UR, LL, LR.
     (2) Other boxa --> pta functions are:
         * boxaExtractAsPta(): allows extraction of any dimension
           and/or side location, with each in a separate pta.
         * boxaExtractCorners(): extracts any of the four corners as a pta.

Definition at line 738 of file boxfunc4.c.

References boxConvertToPta(), and L_COPY.

◆ boxaDisplayTiled()

PIX * boxaDisplayTiled	(	BOXA *	boxas,
		PIXA *	pixa,
		l_int32	first,
		l_int32	last,
		l_int32	maxwidth,
		l_int32	linewidth,
		l_float32	scalefactor,
		l_int32	background,
		l_int32	spacing,
		l_int32	border )

boxaDisplayTiled()

Parameters

[in]	boxas
[in]	pixa	[optional] background for each box
[in]	first	index of first box
[in]	last	index of last box; use -1 to go to end
[in]	maxwidth	of output image
[in]	linewidth	width of box outlines, before scaling
[in]	scalefactor	applied to every box; use 1.0 for no scaling
[in]	background	0 for white, 1 for black; this is the color of the spacing between the images
[in]	spacing	between images, and on outside
[in]	border	width of black border added to each image; use 0 for no border

Returns: pixd of tiled images of boxes, or NULL on error

Notes:
     (1) Displays each box separately in a tiled 32 bpp image.
     (2) If pixa is defined, it must have the same count as the boxa,
         and it will be a background over with each box is rendered.
         If pixa is not defined, the boxes will be rendered over
         blank images of identical size.
     (3) See pixaDisplayTiledInRows() for other parameters.

Definition at line 1294 of file boxfunc4.c.

References boxaGetExtent(), L_ADD_BELOW, L_CLONE, L_COPY, and L_INSERT.

◆ boxaGetArea()

l_ok boxaGetArea	(	BOXA *	boxa,
		l_int32 *	parea )

boxaGetArea()

Parameters

[in]	boxa
[out]	parea	total area of all boxes

Returns: 0 if OK, 1 on error

Notes:
     (1) Measures the total area of the boxes, without regard to overlaps.

Definition at line 1246 of file boxfunc4.c.

◆ boxaGetCoverage()

l_ok boxaGetCoverage	(	BOXA *	boxa,
		l_int32	wc,
		l_int32	hc,
		l_int32	exactflag,
		l_float32 *	pfract )

boxaGetCoverage()

Parameters

[in]	boxa
[in]	wc,hc	dimensions of overall clipping rectangle with UL corner at (0, 0 that is covered by the boxes.
[in]	exactflag	1 for guaranteeing an exact result; 0 for getting an exact result only if the boxes do not overlap
[out]	pfract	sum of box area as fraction of w * h

Returns: 0 if OK, 1 on error

Notes:
     (1) The boxes in boxa are clipped to the input rectangle.
     (2) * When exactflag == 1, we generate a 1 bpp pix of size
           wc x hc, paint all the boxes black, and count the fg pixels.
           This can take 1 msec on a large page with many boxes.
         * When exactflag == 0, we clip each box to the wc x hc region
           and sum the resulting areas.  This is faster.
         * The results are the same when none of the boxes overlap
           within the wc x hc region.

Definition at line 988 of file boxfunc4.c.

References L_CLONE, and PIX_SET.

◆ boxaGetExtent()

l_ok boxaGetExtent	(	BOXA *	boxa,
		l_int32 *	pw,
		l_int32 *	ph,
		BOX **	pbox )

boxaGetExtent()

Parameters

[in]	boxa
[out]	pw	[optional] width
[out]	ph	[optional] height
[out]	pbox	[optional] minimum box containing all boxes in boxa

Returns: 0 if OK, 1 on error

Notes:
     (1) This computes the minimum rectangular bounding region
         that contains all valid boxes in a boxa.
     (2) The returned w and h are the minimum size image
         that would contain all boxes untranslated.
     (3) If there are no valid boxes, returned w and h are 0 and
         all parameters in the returned box are 0.  This
         is not an error, because an empty boxa is valid and
         boxaGetExtent() is required for serialization.

Definition at line 924 of file boxfunc4.c.

Referenced by boxaDisplayTiled().

◆ boxaGetSizes()

l_ok boxaGetSizes	(	BOXA *	boxa,
		NUMA **	pnaw,
		NUMA **	pnah )

boxaGetSizes()

Parameters

[in]	boxa
[out]	pnaw	[optional] widths of valid boxes
[out]	pnah	[optional] heights of valid boxes

Returns: 0 if OK, 1 on error

Definition at line 1202 of file boxfunc4.c.

References L_COPY.

◆ boxaLocationRange()

l_ok boxaLocationRange	(	BOXA *	boxa,
		l_int32 *	pminx,
		l_int32 *	pminy,
		l_int32 *	pmaxx,
		l_int32 *	pmaxy )

boxaLocationRange()

Parameters

[in]	boxa
[out]	pminx	[optional] min (UL corner) x value of all boxes
[out]	pminy	[optional] min (UL corner) y value of all boxes
[out]	pmaxx	[optional] max (UL corner) x value of all boxes
[out]	pmaxy	[optional] max (UL corner) y value of all boxes

Returns: 0 if OK, 1 on error

Definition at line 1152 of file boxfunc4.c.

◆ boxaMakeAreaIndicator()

NUMA * boxaMakeAreaIndicator	(	BOXA *	boxa,
		l_int32	area,
		l_int32	relation )

boxaMakeAreaIndicator()

Parameters

[in]	boxa
[in]	area	threshold value of width * height
[in]	relation	L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE

Returns: na indicator array, or NULL on error

Notes:
     (1) To keep small components, use relation = L_SELECT_IF_LT or
         L_SELECT_IF_LTE.
         To keep large components, use relation = L_SELECT_IF_GT or
         L_SELECT_IF_GTE.

Definition at line 411 of file boxfunc4.c.

References L_SELECT_IF_GT, L_SELECT_IF_GTE, L_SELECT_IF_LT, and L_SELECT_IF_LTE.

Referenced by boxaSelectByArea().

◆ boxaMakeSizeIndicator()

NUMA * boxaMakeSizeIndicator	(	BOXA *	boxa,
		l_int32	width,
		l_int32	height,
		l_int32	type,
		l_int32	relation )

boxaMakeSizeIndicator()

Parameters

[in]	boxa
[in]	width,height	threshold dimensions
[in]	type	L_SELECT_WIDTH, L_SELECT_HEIGHT, L_SELECT_IF_EITHER, L_SELECT_IF_BOTH
[in]	relation	L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE

Returns: na indicator array, or NULL on error

Notes:
     (1) The args specify constraints on the size of the
         components that are kept.
     (2) If the selection type is L_SELECT_WIDTH, the input
         height is ignored, and v.v.
     (3) To keep small components, use relation = L_SELECT_IF_LT or
         L_SELECT_IF_LTE.
         To keep large components, use relation = L_SELECT_IF_GT or
         L_SELECT_IF_GTE.

Definition at line 278 of file boxfunc4.c.

References L_SELECT_HEIGHT, L_SELECT_IF_BOTH, L_SELECT_IF_EITHER, L_SELECT_IF_GT, L_SELECT_IF_GTE, L_SELECT_IF_LT, L_SELECT_IF_LTE, and L_SELECT_WIDTH.

Referenced by boxaSelectBySize().

◆ boxaMakeWHRatioIndicator()

NUMA * boxaMakeWHRatioIndicator	(	BOXA *	boxa,
		l_float32	ratio,
		l_int32	relation )

boxaMakeWHRatioIndicator()

Parameters

[in]	boxa
[in]	ratio	width/height threshold value
[in]	relation	L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE

Returns: na indicator array, or NULL on error

Notes:
     (1) To keep narrow components, use relation = L_SELECT_IF_LT or
         L_SELECT_IF_LTE.
         To keep wide components, use relation = L_SELECT_IF_GT or
         L_SELECT_IF_GTE.

Definition at line 511 of file boxfunc4.c.

References L_SELECT_IF_GT, L_SELECT_IF_GTE, L_SELECT_IF_LT, and L_SELECT_IF_LTE.

Referenced by boxaSelectByWHRatio().

◆ boxaPermutePseudorandom()

BOXA * boxaPermutePseudorandom ( BOXA * boxas )

boxaPermutePseudorandom()

Parameters

[in] boxas input boxa

Returns: boxad with boxes permuted, or NULL on error

Notes:
     (1) This does a pseudorandom in-place permutation of the boxes.
     (2) The result is guaranteed not to have any boxes in their
         original position, but it is not very random.  If you
         need randomness, use boxaPermuteRandom().

Definition at line 618 of file boxfunc4.c.

◆ boxaPermuteRandom()

BOXA * boxaPermuteRandom	(	BOXA *	boxad,
		BOXA *	boxas )

boxaPermuteRandom()

Parameters

[in]	boxad	[optional] can be null or equal to boxas
[in]	boxas	input boxa

Returns: boxad with boxes permuted, or NULL on error

Notes:
     (1) If boxad is null, make a copy of boxas and permute the copy.
         Otherwise, boxad must be equal to boxas, and the operation
         is done in-place.
     (2) If boxas is empty, return an empty boxad.
     (3) This does a random in-place permutation of the boxes,
         by swapping each box in turn with a random box.  The
         result is almost guaranteed not to have any boxes in their
         original position.
     (4) MSVC rand() has MAX_RAND = 2^15 - 1, so it will not do
         a proper permutation is the number of boxes exceeds this.

Definition at line 657 of file boxfunc4.c.

References boxaSwapBoxes(), and L_COPY.

◆ boxaSelectByArea()

BOXA * boxaSelectByArea	(	BOXA *	boxas,
		l_int32	area,
		l_int32	relation,
		l_int32 *	pchanged )

boxaSelectByArea()

Parameters

[in]	boxas
[in]	area	threshold value of width * height
[in]	relation	L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE
[out]	pchanged	[optional] 1 if changed; 0 if clone returned

Returns: boxad filtered set, or NULL on error

Notes:
     (1) Uses box copies in the new boxa.
     (2) To keep small components, use relation = L_SELECT_IF_LT or
         L_SELECT_IF_LTE.
         To keep large components, use relation = L_SELECT_IF_GT or
         L_SELECT_IF_GTE.

Definition at line 363 of file boxfunc4.c.

References boxaMakeAreaIndicator(), boxaSelectWithIndicator(), L_COPY, L_SELECT_IF_GT, L_SELECT_IF_GTE, L_SELECT_IF_LT, and L_SELECT_IF_LTE.

◆ boxaSelectBySize()

BOXA * boxaSelectBySize	(	BOXA *	boxas,
		l_int32	width,
		l_int32	height,
		l_int32	type,
		l_int32	relation,
		l_int32 *	pchanged )

boxaSelectBySize()

Parameters

[in]	boxas
[in]	width,height	threshold dimensions
[in]	type	L_SELECT_WIDTH, L_SELECT_HEIGHT, L_SELECT_IF_EITHER, L_SELECT_IF_BOTH
[in]	relation	L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE
[out]	pchanged	[optional] 1 if changed; 0 if clone returned

Returns: boxad filtered set, or NULL on error

Notes:
     (1) The args specify constraints on the size of the
         components that are kept.
     (2) Uses box copies in the new boxa.
     (3) If the selection type is L_SELECT_WIDTH, the input
         height is ignored, and v.v.
     (4) To keep small components, use relation = L_SELECT_IF_LT or
         L_SELECT_IF_LTE.
         To keep large components, use relation = L_SELECT_IF_GT or
         L_SELECT_IF_GTE.

Definition at line 217 of file boxfunc4.c.

References boxaMakeSizeIndicator(), boxaSelectWithIndicator(), L_COPY, L_SELECT_HEIGHT, L_SELECT_IF_BOTH, L_SELECT_IF_EITHER, L_SELECT_IF_GT, L_SELECT_IF_GTE, L_SELECT_IF_LT, L_SELECT_IF_LTE, and L_SELECT_WIDTH.

◆ boxaSelectByWHRatio()

BOXA * boxaSelectByWHRatio	(	BOXA *	boxas,
		l_float32	ratio,
		l_int32	relation,
		l_int32 *	pchanged )

boxaSelectByWHRatio()

Parameters

[in]	boxas
[in]	ratio	width/height threshold value
[in]	relation	L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE
[out]	pchanged	[optional] 1 if changed; 0 if clone returned

Returns: boxad filtered set, or NULL on error

Notes:
     (1) Uses box copies in the new boxa.
     (2) To keep narrow components, use relation = L_SELECT_IF_LT or
         L_SELECT_IF_LTE.
         To keep wide components, use relation = L_SELECT_IF_GT or
         L_SELECT_IF_GTE.

Definition at line 463 of file boxfunc4.c.

References boxaMakeWHRatioIndicator(), boxaSelectWithIndicator(), L_COPY, L_SELECT_IF_GT, L_SELECT_IF_GTE, L_SELECT_IF_LT, and L_SELECT_IF_LTE.

◆ boxaSelectRange()

BOXA * boxaSelectRange	(	BOXA *	boxas,
		l_int32	first,
		l_int32	last,
		l_int32	copyflag )

boxaSelectRange()

Parameters

[in]	boxas
[in]	first	use 0 to select from the beginning
[in]	last	use -1 to select to the end
[in]	copyflag	L_COPY, L_CLONE

Returns: boxad, or NULL on error

Notes:
     (1) The copyflag specifies what we do with each box from boxas.
         Specifically, L_CLONE inserts a clone into boxad of each
         selected box from boxas.

Definition at line 95 of file boxfunc4.c.

References L_CLONE, L_COPY, and L_INSERT.

◆ boxaSelectWithIndicator()

BOXA * boxaSelectWithIndicator	(	BOXA *	boxas,
		NUMA *	na,
		l_int32 *	pchanged )

boxaSelectWithIndicator()

Parameters

[in]	boxas
[in]	na	indicator numa
[out]	pchanged	[optional] 1 if changed; 0 if clone returned

Returns: boxad, or NULL on error

Notes:
     (1) Returns a copy of the boxa if no components are removed.
     (2) Uses box copies in the new boxa.
     (3) The indicator numa has values 0 (ignore) and 1 (accept).
     (4) If all indicator values are 0, the returned boxa is empty.

Definition at line 562 of file boxfunc4.c.

References L_COPY, and L_INSERT.

Referenced by boxaSelectByArea(), boxaSelectBySize(), and boxaSelectByWHRatio().

◆ boxaSizeRange()

l_ok boxaSizeRange	(	BOXA *	boxa,
		l_int32 *	pminw,
		l_int32 *	pminh,
		l_int32 *	pmaxw,
		l_int32 *	pmaxh )

boxaSizeRange()

Parameters

[in]	boxa
[out]	pminw	[optional] min width of all boxes
[out]	pmaxw	[optional] max width of all boxes
[out]	pminh	[optional] min height of all boxes
[out]	pmaxh	[optional] max height of all boxes

Returns: 0 if OK, 1 on error

Definition at line 1101 of file boxfunc4.c.

Referenced by boxaaSizeRange().

◆ boxaSwapBoxes()

l_ok boxaSwapBoxes	(	BOXA *	boxa,
		l_int32	i,
		l_int32	j )

boxaSwapBoxes()

Parameters

[in]	boxa
[in]	i,j	two indices of boxes, that are to be swapped

Returns: 0 if OK, 1 on error

Definition at line 692 of file boxfunc4.c.

References Boxa::box.

Referenced by boxaPermuteRandom().

◆ boxConvertToPta()

PTA * boxConvertToPta	(	BOX *	box,
		l_int32	ncorners )

boxConvertToPta()

Parameters

[in]	box
[in]	ncorners	2 or 4 for the representation of the box

Returns: pta with ncorners points, or NULL on error

Notes:
     (1) If ncorners == 2, we select the UL and LR corners.
         Otherwise we save all 4 corners in this order: UL, UR, LL, LR.

Definition at line 834 of file boxfunc4.c.

Referenced by boxaConvertToPta().

◆ ptaConvertToBox()

BOX * ptaConvertToBox ( PTA * pta )

ptaConvertToBox()

Parameters

[in] pta

Returns: box minimum containing all points in the pta, or NULL on error

Notes:
     (1) For 2 corners, the order of the 2 points is UL, LR.
         For 4 corners, the order of points is UL, UR, LL, LR.

Definition at line 874 of file boxfunc4.c.

◆ ptaConvertToBoxa()

BOXA * ptaConvertToBoxa	(	PTA *	pta,
		l_int32	ncorners )

ptaConvertToBoxa()

Parameters

[in]	pta
[in]	ncorners	2 or 4 for the representation of each box

Returns: boxa with one box for each 2 or 4 points in the pta, or NULL on error

Notes:
     (1) For 2 corners, the order of the 2 points is UL, LR.
         For 4 corners, the order of points is UL, UR, LL, LR.
     (2) Each derived box is the minimum size containing all corners.

Definition at line 781 of file boxfunc4.c.

References L_INSERT.

Functions

Detailed Description

Function Documentation

◆ boxaaSelectRange()

◆ boxaaSizeRange()

◆ boxaConvertToPta()

◆ boxaDisplayTiled()

◆ boxaGetArea()

◆ boxaGetCoverage()

◆ boxaGetExtent()

◆ boxaGetSizes()

◆ boxaLocationRange()

◆ boxaMakeAreaIndicator()

◆ boxaMakeSizeIndicator()

◆ boxaMakeWHRatioIndicator()

◆ boxaPermutePseudorandom()

◆ boxaPermuteRandom()

◆ boxaSelectByArea()

◆ boxaSelectBySize()

◆ boxaSelectByWHRatio()

◆ boxaSelectRange()

◆ boxaSelectWithIndicator()

◆ boxaSizeRange()

◆ boxaSwapBoxes()

◆ boxConvertToPta()

◆ ptaConvertToBox()

◆ ptaConvertToBoxa()