third-party/leptonica/src/dewarp.h
/*====================================================================*
- Copyright (C) 2001 Leptonica. All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
- 1. Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- 2. Redistributions in binary form must reproduce the above
- copyright notice, this list of conditions and the following
- disclaimer in the documentation and/or other materials
- provided with the distribution.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ANY
- CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
- EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
- PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
- OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*====================================================================*/
#ifndef LEPTONICA_DEWARP_H
#define LEPTONICA_DEWARP_H
/*
* dewarp.h
*
* Data structure to hold arrays and results for generating
* horizontal and vertical disparity arrays based on textlines.
* Each disparity array is two-dimensional. The vertical disparity
* array gives a vertical displacement, relative to the lowest point
* in the textlines. The horizontal disparty array gives a horizontal
* displacement, relative to the minimum values (for even pages)
* or maximum values (for odd pages) of the left and right ends of
* full textlines. Horizontal alignment always involves translations
* away from the book gutter.
*
* We have intentionally separated the process of building models
* from the rendering process that uses the models. For any page,
* the building operation either creates an actual model (that is,
* a model with at least the vertical disparity being computed, and
* for which the 'success' flag is set) or fails to create a model.
* However, at rendering time, a page can have one of two different
* types of models.
* (1) A valid model is an actual model that meets the rendering
* constraints, which are limits on model curvature parameters.
* See dewarpaTestForValidModel() for details.
* Valid models are identified by dewarpaInsertRefModels(),
* which sets the 'vvalid' and 'hvalid' fields. Only valid
* models are used for rendering.
* (2) A reference model is used by a page that doesn't have
* a valid model, but has a nearby valid model of the same
* parity (even/odd page) that it can use. The range in pages
* to search for a valid model is given by the 'maxdist' field.
*
* If a valid vertical disparity model (VDM) is not available,
* just use the input image. Otherwise, assuming the VDM is available:
* (a) with useboth == 0, we use only the VDM.
* (b) with useboth == 1, we require using the VDM and, if a valid
* horizontal disparity model (HDM) is available, we also use it.
*
* The 'maxdist' parameter is input when the dewarpa is created.
* The other rendering parameters have default values given in dewarp.c.
* All parameters used by rendering can be set (or reset) using accessors.
*
* After dewarping, use of the VDM will cause all points on each
* altered curve to have a y-value equal to the minimum. Use of
* the HDA will cause the left and right edges of the textlines
* to be vertically aligned if they had been typeset flush-left
* and flush-right, respectively.
*
* The sampled disparity arrays are expanded to full resolution,
* using linear interpolation, and this is further expanded
* by slope continuation to the right and below if the image
* is larger than the full resolution disparity arrays. Then
* the disparity correction can be applied to the input image.
* If the input pix are 2x reduced, the expansion from sampled
* to full res uses the product of (sampling) * (redfactor).
*
* The most accurate results are produced at full resolution, and
* this is generally recommended.
*/
/* Note on versioning of the serialization of this data structure:
* The dewarping utility and the stored data can be expected to change.
* In most situations, the serialized version is ephemeral -- it is
* not needed after being used. No functions will be provided to
* convert between different versions. */
#define DEWARP_VERSION_NUMBER 4
struct L_Dewarpa
{
l_int32 nalloc; /* size of dewarp ptr array */
l_int32 maxpage; /* maximum page number in array */
struct L_Dewarp **dewarp; /* array of ptrs to page dewarp */
struct L_Dewarp **dewarpcache; /* array of ptrs to cached dewarps */
struct Numa *namodels; /* list of page numbers for pages */
/* with page models */
struct Numa *napages; /* list of page numbers with either */
/* page models or ref page models */
l_int32 redfactor; /* reduction factor of input: 1 or 2 */
l_int32 sampling; /* disparity arrays sampling factor */
l_int32 minlines; /* min number of long lines required */
l_int32 maxdist; /* max distance for getting ref pages */
l_int32 max_linecurv; /* maximum abs line curvature, */
/* in micro-units */
l_int32 min_diff_linecurv; /* minimum abs diff line curvature */
/* in micro-units */
l_int32 max_diff_linecurv; /* maximum abs diff line curvature */
/* in micro-units */
l_int32 max_edgeslope; /* maximum abs left or right edge */
/* slope, in milli-units */
l_int32 max_edgecurv; /* maximum abs left or right edge */
/* curvature, in micro-units */
l_int32 max_diff_edgecurv; /* maximum abs diff left-right */
/* edge curvature, in micro-units */
l_int32 useboth; /* use both disparity arrays if */
/* available; just vertical otherwise */
l_int32 modelsready; /* invalid models have been removed */
/* and refs built against valid set */
};
typedef struct L_Dewarpa L_DEWARPA;
struct L_Dewarp
{
struct L_Dewarpa *dewa; /* ptr to parent (not owned) */
struct Pix *pixs; /* source pix, 1 bpp */
struct FPix *sampvdispar; /* sampled vert disparity array */
struct FPix *samphdispar; /* sampled horiz disparity array */
struct FPix *fullvdispar; /* full vert disparity array */
struct FPix *fullhdispar; /* full horiz disparity array */
struct Numa *namidys; /* sorted y val of midpoint each line */
struct Numa *nacurves; /* sorted curvature of each line */
l_int32 w; /* width of source image */
l_int32 h; /* height of source image */
l_int32 pageno; /* page number; important for reuse */
l_int32 sampling; /* sampling factor of disparity arrays */
l_int32 redfactor; /* reduction factor of pixs: 1 or 2 */
l_int32 minlines; /* min number of long lines required */
l_int32 nlines; /* number of long lines found */
l_int32 mincurv; /* min line curvature in micro-units */
l_int32 maxcurv; /* max line curvature in micro-units */
l_int32 leftslope; /* left edge slope in milli-units */
l_int32 rightslope; /* right edge slope in milli-units */
l_int32 leftcurv; /* left edge curvature in micro-units */
l_int32 rightcurv; /* right edge curvature in micro-units */
l_int32 nx; /* number of sampling pts in x-dir */
l_int32 ny; /* number of sampling pts in y-dir */
l_int32 hasref; /* 0 if normal; 1 if has a refpage */
l_int32 refpage; /* page with disparity model to use */
l_int32 vsuccess; /* sets to 1 if vert disparity builds */
l_int32 hsuccess; /* sets to 1 if horiz disparity builds */
l_int32 vvalid; /* sets to 1 if valid vert disparity */
l_int32 hvalid; /* sets to 1 if valid horiz disparity */
l_int32 debug; /* sets to 1 if debug output requested */
};
typedef struct L_Dewarp L_DEWARP;
#endif /* LEPTONICA_DEWARP_H */