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

Macros
#define	DEBUG_INVALID_MODELS 0 /* set this to 1 for debugging */

Functions
static l_int32	dewarpaTestForValidModel (L_DEWARPA dewa, L_DEWARP dew, l_int32 notests)

l_ok	dewarpSinglePage (PIX pixs, l_int32 thresh, l_int32 adaptive, l_int32 useboth, l_int32 check_columns, PIX ppixd, L_DEWARPA *pdewa, l_int32 debug)

l_ok	dewarpSinglePageInit (PIX pixs, l_int32 thresh, l_int32 adaptive, l_int32 useboth, l_int32 check_columns, PIX ppixb, L_DEWARPA *pdewa)

l_ok	dewarpSinglePageRun (PIX pixs, PIX pixb, L_DEWARPA dewa, PIX *ppixd, l_int32 debug)

l_ok	dewarpaListPages (L_DEWARPA *dewa)

l_ok	dewarpaSetValidModels (L_DEWARPA *dewa, l_int32 notests, l_int32 debug)

l_ok	dewarpaInsertRefModels (L_DEWARPA *dewa, l_int32 notests, l_int32 debug)

l_ok	dewarpaStripRefModels (L_DEWARPA *dewa)

l_ok	dewarpaRestoreModels (L_DEWARPA *dewa)

l_ok	dewarpaInfo (FILE fp, L_DEWARPA dewa)

l_ok	dewarpaModelStats (L_DEWARPA dewa, l_int32 pnnone, l_int32 pnvsuccess, l_int32 pnvvalid, l_int32 pnhsuccess, l_int32 pnhvalid, l_int32 *pnref)

l_ok	dewarpaShowArrays (L_DEWARPA *dewa, l_float32 scalefact, l_int32 first, l_int32 last)

l_ok	dewarpDebug (L_DEWARP dew, const char subdirs, l_int32 index)

l_ok	dewarpShowResults (L_DEWARPA dewa, SARRAY sa, BOXA boxa, l_int32 firstpage, l_int32 lastpage, const char pdfout)

Variables
static const l_int32	GrayInValue = 200

Detailed Description


   Single page dewarper

   Reference model (book-level, dewarpa) operations and debugging output

     Top-level single page dewarper
         l_int32            dewarpSinglePage()
         l_int32            dewarpSinglePageInit()
         l_int32            dewarpSinglePageRun()

     Operations on dewarpa
         l_int32            dewarpaListPages()
         l_int32            dewarpaSetValidModels()
         l_int32            dewarpaInsertRefModels()
         l_int32            dewarpaStripRefModels()
         l_int32            dewarpaRestoreModels()

     Dewarp debugging output
         l_int32            dewarpaInfo()
         l_int32            dewarpaModelStats()
         static l_int32     dewarpaTestForValidModel()
         l_int32            dewarpaShowArrays()
         l_int32            dewarpDebug()
         l_int32            dewarpShowResults()

Definition in file dewarp4.c.

Macro Definition Documentation

◆ DEBUG_INVALID_MODELS

#define DEBUG_INVALID_MODELS 0 /* set this to 1 for debugging */

Definition at line 68 of file dewarp4.c.

Function Documentation

◆ dewarpaInfo()

l_ok dewarpaInfo	(	FILE *	fp,
		L_DEWARPA *	dewa )

dewarpaInfo()

Parameters

[in]	fp
[in]	dewa

Returns: 0 if OK, 1 on error

Definition at line 655 of file dewarp4.c.

References dewarpaModelStats(), L_Dewarp::h, L_Dewarp::hasref, L_Dewarp::leftcurv, L_Dewarp::leftslope, L_Dewarp::maxcurv, L_Dewarpa::maxdist, L_Dewarpa::maxpage, L_Dewarp::mincurv, L_Dewarpa::minlines, L_Dewarpa::nalloc, L_Dewarpa::napages, L_Dewarp::nlines, L_Dewarp::nx, L_Dewarp::ny, L_Dewarp::pageno, L_Dewarpa::redfactor, L_Dewarp::refpage, L_Dewarp::rightcurv, L_Dewarp::rightslope, L_Dewarp::samphdispar, L_Dewarpa::sampling, L_Dewarp::sampvdispar, L_Dewarpa::useboth, and L_Dewarp::w.

◆ dewarpaInsertRefModels()

l_ok dewarpaInsertRefModels	(	L_DEWARPA *	dewa,
		l_int32	notests,
		l_int32	debug )

dewarpaInsertRefModels()

Parameters

[in]	dewa
[in]	notests	if 1, ignore curvature constraints on model
[in]	debug	1 to output information on invalid page models

Returns: 0 if OK, 1 on error

Notes:
     (1) This destroys all dewarp models that are invalid, and then
         inserts reference models where possible.
     (2) If notests == 1, this ignores the curvature constraints
         and assumes that all successfully built models are valid.
     (3) If useboth == 0, it uses the closest valid model within the
         distance and parity constraints.  If useboth == 1, it tries
         to use the closest allowed hvalid model; if it doesn't find
         an hvalid model, it uses the closest valid model.
     (4) For all pages without a model, this clears out any existing
         invalid and reference dewarps, finds the nearest valid model
         with the same parity, and inserts an empty dewarp with the
         reference page.
     (5) Then if it is requested to use both vertical and horizontal
         disparity arrays (useboth == 1), it tries to replace any
         hvalid == 0 model or reference with an hvalid == 1 reference.
     (6) The distance constraint is that any reference model must
         be within maxdist.  Note that with the parity constraint,
         no reference models will be used if maxdist < 2.
     (7) This function must be called, even if reference models will
         not be used.  It should be called after building models on all
         available pages, and after setting the rendering parameters.
     (8) If the dewa has been serialized, this function is called by
         dewarpaRead() when it is read back.  It is also called
         any time the rendering parameters are changed.
     (9) Note: if this has been called with useboth == 1, and useboth
         is reset to 0, you should first call dewarpaRestoreModels()
         to bring real models from the cache back to the primary array.

Definition at line 444 of file dewarp4.c.

References L_Dewarpa::dewarp, dewarpaRestoreModels(), dewarpaSetValidModels(), L_Dewarpa::dewarpcache, L_Dewarp::hasref, L_Dewarp::hvalid, L_Dewarpa::maxdist, L_Dewarpa::maxpage, L_Dewarpa::modelsready, L_Dewarpa::useboth, and L_Dewarp::vvalid.

◆ dewarpaListPages()

l_ok dewarpaListPages ( L_DEWARPA * dewa )

dewarpaListPages()

Parameters

[in] dewa populated with dewarp structs for pages

Returns: 0 if OK, 1 on error list of page numbers, or NULL on error

Notes:
     (1) This generates two numas, stored in the dewarpa, that give:
         (a) the page number for each dew that has a page model.
         (b) the page number for each dew that has either a page
             model or a reference model.
         It can be called at any time.
     (2) It is called by the dewarpa serializer before writing.

Definition at line 290 of file dewarp4.c.

References L_Dewarp::hasref, L_Dewarpa::maxpage, L_Dewarpa::namodels, L_Dewarpa::napages, and L_Dewarp::pageno.

Referenced by dewarpaModelStats(), dewarpaRestoreModels(), and dewarpaStripRefModels().

◆ dewarpaModelStats()

l_ok dewarpaModelStats	(	L_DEWARPA *	dewa,
		l_int32 *	pnnone,
		l_int32 *	pnvsuccess,
		l_int32 *	pnvvalid,
		l_int32 *	pnhsuccess,
		l_int32 *	pnhvalid,
		l_int32 *	pnref )

dewarpaModelStats()

Parameters

[in]	dewa
[out]	pnnone	[optional] number without any model
[out]	pnvsuccess	[optional] number with a vert model
[out]	pnvvalid	[optional] number with a valid vert model
[out]	pnhsuccess	[optional] number with both models
[out]	pnhvalid	[optional] number with both models valid
[out]	pnref	[optional] number with a reference model

Returns: 0 if OK, 1 on error

Notes:
     (1) A page without a model has no dew.  It most likely failed to
         generate a vertical model, and has not been assigned a ref
         model from a neighboring page with a valid vertical model.
     (2) A page has vsuccess == 1 if there is at least a model of the
         vertical disparity.  The model may be invalid, in which case
         dewarpaInsertRefModels() will stash it in the cache and
         attempt to replace it by a valid ref model.
     (3) A vvvalid model is a vertical disparity model whose parameters
         satisfy the constraints given in dewarpaSetValidModels().
     (4) A page has hsuccess == 1 if both the vertical and horizontal
         disparity arrays have been constructed.
     (5) An  hvalid model has vertical and horizontal disparity
         models whose parameters satisfy the constraints given
         in dewarpaSetValidModels().
     (6) A page has a ref model if it failed to generate a valid
         model but was assigned a vvalid or hvalid model on another
         page (within maxdist) by dewarpaInsertRefModel().
     (7) This calls dewarpaTestForValidModel(); it ignores the vvalid
         and hvalid fields.

Definition at line 745 of file dewarp4.c.

References dewarpaListPages(), dewarpaTestForValidModel(), L_Dewarp::hasref, L_Dewarp::hsuccess, L_Dewarp::hvalid, L_Dewarpa::napages, L_Dewarp::vsuccess, and L_Dewarp::vvalid.

Referenced by dewarpaInfo().

◆ dewarpaRestoreModels()

l_ok dewarpaRestoreModels ( L_DEWARPA * dewa )

dewarpaRestoreModels()

Parameters

[in] dewa populated with dewarp structs for pages

Returns: 0 if OK, 1 on error

Notes:
     (1) This puts all real models (and only real models) in the
         primary dewarpa array.  First remove all dewarps that are
         only references to other page models.  Then move all models
         that had been cached back into the primary dewarp array.
     (2) After this is done, we still need to recompute and insert
         the reference models before dewa->modelsready is true.

Definition at line 612 of file dewarp4.c.

References L_Dewarpa::dewarp, dewarpaListPages(), dewarpaStripRefModels(), L_Dewarpa::dewarpcache, L_Dewarpa::maxpage, and L_Dewarpa::modelsready.

Referenced by dewarpaInsertRefModels().

◆ dewarpaSetValidModels()

l_ok dewarpaSetValidModels	(	L_DEWARPA *	dewa,
		l_int32	notests,
		l_int32	debug )

dewarpaSetValidModels()

Parameters

[in]	dewa
[in]	notests
[in]	debug	1 to output information on invalid page models

Returns: 0 if OK, 1 on error

Notes:
     (1) A valid model must meet the rendering requirements, which
         include whether or not a vertical disparity model exists
         and conditions on curvatures for vertical and horizontal
         disparity models.
     (2) If notests == 1, this ignores the curvature constraints
         and assumes that all successfully built models are valid.
     (3) This function does not need to be called by the application.
         It is called by dewarpaInsertRefModels(), which
         will destroy all invalid dewarps.  Consequently, to inspect
         an invalid dewarp model, it must be done before calling
         dewarpaInsertRefModels().

Definition at line 340 of file dewarp4.c.

References dewarpaTestForValidModel(), L_Dewarp::hasref, L_Dewarp::hsuccess, L_Dewarp::leftcurv, L_Dewarp::leftslope, L_Dewarpa::max_diff_edgecurv, L_Dewarpa::max_diff_linecurv, L_Dewarpa::max_edgecurv, L_Dewarpa::max_edgeslope, L_Dewarpa::max_linecurv, L_Dewarp::maxcurv, L_Dewarpa::maxpage, L_Dewarp::mincurv, L_Dewarp::rightcurv, L_Dewarp::rightslope, L_Dewarpa::useboth, and L_Dewarp::vsuccess.

Referenced by dewarpaInsertRefModels().

◆ dewarpaShowArrays()

l_ok dewarpaShowArrays	(	L_DEWARPA *	dewa,
		l_float32	scalefact,
		l_int32	first,
		l_int32	last )

dewarpaShowArrays()

Parameters

[in]	dewa
[in]	scalefact	on contour images; typ. 0.5
[in]	first	first page model to render
[in]	last	last page model to render; use 0 to go to end

Returns: 0 if OK, 1 on error

Notes:
     (1) Generates a pdf of contour plots of the disparity arrays.
     (2) This only shows actual models; not ref models

Definition at line 897 of file dewarp4.c.

References L_Dewarp::fullhdispar, L_Dewarp::fullvdispar, L_Dewarp::hasref, L_ADD_BELOW, L_FLATE_ENCODE, L_INSERT, L_Dewarpa::maxpage, L_Dewarp::samphdispar, and L_Dewarp::sampvdispar.

◆ dewarpaStripRefModels()

l_ok dewarpaStripRefModels ( L_DEWARPA * dewa )

dewarpaStripRefModels()

Parameters

[in] dewa populated with dewarp structs for pages

Returns: 0 if OK, 1 on error

Notes:
     (1) This examines each dew in a dewarpa, and removes
         all that don't have their own page model (i.e., all
         that have "references" to nearby pages with valid models).
         These references were generated by dewarpaInsertRefModels(dewa).

Definition at line 573 of file dewarp4.c.

References L_Dewarpa::dewarp, dewarpaListPages(), L_Dewarp::hasref, L_Dewarpa::maxpage, and L_Dewarpa::modelsready.

Referenced by dewarpaRestoreModels().

◆ dewarpaTestForValidModel()

static l_int32 dewarpaTestForValidModel	(	L_DEWARPA *	dewa,
		L_DEWARP *	dew,
		l_int32	notests )

static

dewarpaTestForValidModel()

Parameters

[in]	dewa
[in]	dew
[in]	notests

Returns: 0 if OK, 1 on error

Notes:
     (1) Computes validity of vertical (vvalid) model and both
         vertical and horizontal (hvalid) models.
     (2) If notests == 1, this ignores the curvature constraints
         and assumes that all successfully built models are valid.
     (3) This is just about the models, not the rendering process,
         so the value of useboth is not considered here.

Definition at line 811 of file dewarp4.c.

References L_Dewarp::hasref, L_Dewarp::hsuccess, L_Dewarp::hvalid, L_Dewarp::leftcurv, L_Dewarp::leftslope, L_Dewarpa::max_diff_edgecurv, L_Dewarpa::max_diff_linecurv, L_Dewarpa::max_edgecurv, L_Dewarpa::max_edgeslope, L_Dewarpa::max_linecurv, L_Dewarp::maxcurv, L_Dewarpa::min_diff_linecurv, L_Dewarp::mincurv, L_Dewarp::pageno, L_Dewarp::rightcurv, L_Dewarp::rightslope, L_Dewarp::vsuccess, and L_Dewarp::vvalid.

Referenced by dewarpaModelStats(), and dewarpaSetValidModels().

◆ dewarpDebug()

l_ok dewarpDebug	(	L_DEWARP *	dew,
		const char *	subdirs,
		l_int32	index )

dewarpDebug()

Parameters

[in]	dew
[in]	subdirs	one or more subdirectories of /tmp; e.g., "dew1"
[in]	index	to help label output images; e.g., the page number

Returns: 0 if OK, 1 on error

Notes:
     (1) Prints dewarp fields and generates disparity array contour images.
         The contour images are written to file:
               /tmp/[subdirs]/pixv_[index].png

Definition at line 991 of file dewarp4.c.

References L_Dewarp::fullhdispar, L_Dewarp::fullvdispar, L_Dewarp::h, L_Dewarp::hasref, L_Dewarp::leftcurv, L_Dewarp::leftslope, L_Dewarp::maxcurv, L_Dewarp::mincurv, L_Dewarp::minlines, L_Dewarp::nlines, L_Dewarp::nx, L_Dewarp::ny, L_Dewarp::pageno, L_Dewarp::redfactor, L_Dewarp::refpage, L_Dewarp::rightcurv, L_Dewarp::rightslope, L_Dewarp::samphdispar, L_Dewarp::sampling, L_Dewarp::sampvdispar, and L_Dewarp::w.

◆ dewarpShowResults()

l_ok dewarpShowResults	(	L_DEWARPA *	dewa,
		SARRAY *	sa,
		BOXA *	boxa,
		l_int32	firstpage,
		l_int32	lastpage,
		const char *	pdfout )

dewarpShowResults()

Parameters

[in]	dewa
[in]	sa	of indexed input images
[in]	boxa	crop boxes for input images; can be null
[in]	firstpage
[in]	lastpage
[in]	pdfout	filename

Returns: 0 if OK, 1 on error

Notes:
     (1) This generates a pdf of image pairs (before, after) for
         the designated set of input pages.
     (2) If the boxa exists, its elements are aligned with numbers
         in the filenames in sa.  It is used to crop the input images.
         It is assumed that the dewa was generated from the cropped
         images.  No undercropping is applied before rendering.

Definition at line 1076 of file dewarp4.c.

References L_Dewarp::hasref, L_ADD_BELOW, L_CLONE, L_INSERT, L_JPEG_ENCODE, L_Dewarp::pageno, and L_Dewarp::refpage.

◆ dewarpSinglePage()

l_ok dewarpSinglePage	(	PIX *	pixs,
		l_int32	thresh,
		l_int32	adaptive,
		l_int32	useboth,
		l_int32	check_columns,
		PIX **	ppixd,
		L_DEWARPA **	pdewa,
		l_int32	debug )

dewarpSinglePage()

Parameters

[in]	pixs	with text, any depth
[in]	thresh	for global thresh to 1 bpp; ignore otherwise
[in]	adaptive	1 for adaptive thresh; 0 for global threshold
[in]	useboth	1 for both horiz and vert; 0 for vertical only
[in]	check_columns	1 to skip horizontal if multiple columns; 0 otherwise; default is to skip
[out]	ppixd	dewarped result
[out]	pdewa	[optional] dewa with single page; NULL to skip
[in]	debug	1 for debugging output, 0 otherwise

Returns: 0 if OK, 1 on error list of page numbers, or NULL on error

Notes:
     (1) Dewarps pixs and returns the result in &pixd.
     (2) This uses default values for all model parameters.
     (3) If pixs is 1 bpp, the parameters adaptive and thresh are ignored.
     (4) If it can't build a model, returns a copy of pixs in &pixd.

Definition at line 100 of file dewarp4.c.

References dewarpSinglePageInit(), and dewarpSinglePageRun().

◆ dewarpSinglePageInit()

l_ok dewarpSinglePageInit	(	PIX *	pixs,
		l_int32	thresh,
		l_int32	adaptive,
		l_int32	useboth,
		l_int32	check_columns,
		PIX **	ppixb,
		L_DEWARPA **	pdewa )

dewarpSinglePageInit()

Parameters

[in]	pixs	with text, any depth
[in]	thresh	for global thresh to 1 bpp; ignore otherwise
[in]	adaptive	1 for adaptive thresh; 0 for global threshold
[in]	useboth	1 for both horiz and vert; 0 for vertical only
[in]	check_columns	1 to skip horizontal if multiple columns; 0 otherwise; default is to skip
[out]	ppixb	1 bpp debug image
[out]	pdewa	initialized dewa

Returns: 0 if OK, 1 on error list of page numbers, or NULL on error

Notes:
     (1) This binarizes the input pixs if necessary, returning the
         binarized image.  It also initializes the dewa to default values
         for the model parameters.
     (2) If pixs is 1 bpp, the parameters adaptive and thresh are ignored.
     (3) To change the model parameters, call dewarpaSetCurvatures()
         before running dewarpSinglePageRun().  For example:
            dewarpSinglePageInit(pixs, 0, 1, 1, 1, &pixb, &dewa);
            dewarpaSetCurvatures(dewa, 250, -1, -1, 80, 70, 150);
            dewarpSinglePageRun(pixs, pixb, dewa, &pixd, 0);
            dewarpaDestroy(&dewa);
            pixDestroy(&pixb);

Definition at line 166 of file dewarp4.c.

Referenced by dewarpSinglePage().

◆ dewarpSinglePageRun()

l_ok dewarpSinglePageRun	(	PIX *	pixs,
		PIX *	pixb,
		L_DEWARPA *	dewa,
		PIX **	ppixd,
		l_int32	debug )

dewarpSinglePageRun()

Parameters

[in]	pixs	any depth
[in]	pixb	1 bpp
[in]	dewa	initialized
[out]	ppixd	dewarped result
[in]	debug	1 for debugging output, 0 otherwise

Returns: 0 if OK, 1 on error list of page numbers, or NULL on error

Notes:
     (1) Dewarps pixs and returns the result in &pixd.
     (2) The 1 bpp version pixb and dewa are conveniently generated by
         dewarpSinglePageInit().
     (3) Non-default model parameters must be set before calling this.
     (4) If a model cannot be built, this returns a copy of pixs in &pixd.

Definition at line 226 of file dewarp4.c.

Referenced by dewarpSinglePage().

Variable Documentation

◆ GrayInValue

const l_int32 GrayInValue = 200

static

Definition at line 72 of file dewarp4.c.

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ DEBUG_INVALID_MODELS

Function Documentation

◆ dewarpaInfo()

◆ dewarpaInsertRefModels()

◆ dewarpaListPages()

◆ dewarpaModelStats()

◆ dewarpaRestoreModels()

◆ dewarpaSetValidModels()

◆ dewarpaShowArrays()

◆ dewarpaStripRefModels()

◆ dewarpaTestForValidModel()

◆ dewarpDebug()

◆ dewarpShowResults()

◆ dewarpSinglePage()

◆ dewarpSinglePageInit()

◆ dewarpSinglePageRun()

Variable Documentation

◆ GrayInValue