Leptonica
1.54
|
#define DEBUG_SHORT_LINES 0 /* ditto */ |
#define DEBUG_TEXTLINE_CENTERS 0 /* set this to 1 for debuging */ |
l_int32 dewarpaApplyDisparity | ( | L_DEWARPA * | dewa, |
l_int32 | pageno, | ||
PIX * | pixs, | ||
const char * | debugfile | ||
) |
Input: dewa pageno pixs (image to be modified; can be 1, 8 or 32 bpp) debugfile (use null to skip writing this) Return: 0 if OK, 1 on error (no models or ref models available)
Notes: (1) This applies the disparity arrays to the specified image. (2) If the models and ref models have not been validated, this will do so by calling dewarpaInsertRefModels(). (3) This works with both stripped and full resolution page models. If the full res disparity array(s) are missing, they are remade. (4) The caller must handle errors that are returned because there are no valid models or ref models for the page -- typically by using the input pixs. (5) If there is no model for , this will use the model for 'refpage' and put the result in the dew for . (6) This populates the full resolution disparity arrays if necessary. When applying to a number of images, after calling this function and saving the resulting pixd, you should call dewarpMinimize(dew) on the dew for . This will remove pixs and pixd (or their clones) stored in dew, as well as the full resolution disparity arrays. Together, these hold approximately 16 bytes for each pixel in pixs.
L_DEWARPA* dewarpaCreate | ( | l_int32 | nptrs, |
l_int32 | sampling, | ||
l_int32 | redfactor, | ||
l_int32 | minlines, | ||
l_int32 | maxdist | ||
) |
Input: nptrs (number of dewarp page ptrs; typically the number of pages) sampling (use -1 or 0 for default value; otherwise minimum of 5) redfactor (of input images: 1 is full resolution; 2 is 2x reduced) minlines (minimum number of lines to accept; e.g., 10) maxdist (for locating reference disparity; use -1 for default) Return: dewa (or null on error)
Notes: (1) The sampling, minlines and maxdist parameters will be applied to all images. (2) The sampling factor is used for generating the disparity arrays from the input image. For 2x reduced input, use a sampling factor that is half the sampling you want on the full resolution images. (3) Use = 1 for full resolution; 2 for 2x reduction. All input images must be at one of these two resolutions. (4) is the minimum number of nearly full-length lines required to generate a vertical disparity array. The default number is 15. Use a smaller number if you are willing to accept a questionable array, but not smaller than 4. (5) When a model can't be built for a page, it looks up to in either direction for a valid model with the same page parity. Use -1 for default value; use 0 to avoid using a ref model. (6) The ptr array is expanded as necessary to accommodate page images.
L_DEWARPA* dewarpaCreateFromPixacomp | ( | PIXAC * | pixac, |
l_int32 | sampling, | ||
l_int32 | minlines, | ||
l_int32 | maxdist | ||
) |
Input: pixac (pixacomp of G4, 1 bpp images; with 1x1x1 placeholders) sampling (use -1 or 0 for default value; otherwise minimum of 5) minlines (minimum number of lines to accept; e.g., 10) maxdist (for locating reference disparity; use -1 for default) Return: dewa (or null on error)
Notes: (1) The returned dewa has disparity arrays calculated and is ready for serialization or for use in dewarping. (2) The sampling, minlines and maxdist parameters are applied to all images. See notes in dewarpaCreate() for details. (3) The pixac is full. Placeholders, if any, are w=h=d=1 images, and the real input images are 1 bpp at full resolution. They are assumed to be cropped to the actual page regions, and may be arbitrarily sparse in the array. (4) The output dewarpa is indexed by the page number. The offset in the pixac gives the mapping between the array index in the pixac and the page number. (5) This adds the ref page models. (6) This can be used to make models for any desired set of pages. The direct models are only made for pages with images in the pixacomp; the ref models are made for pages of the same parity within of the nearest direct model.
void dewarpaDestroy | ( | L_DEWARPA ** | pdewa | ) |
Input: &dewa (<will be="" set="" to="" null="" before="" returning>="">) Return: void
l_int32 dewarpaDestroyDewarp | ( | L_DEWARPA * | dewa, |
l_int32 | pageno | ||
) |
Input: dewa pageno (of dew to be destroyed) Return: 0 if OK, 1 on error
l_int32 dewarpaExtendArrayToSize | ( | L_DEWARPA * | dewa, |
l_int32 | size | ||
) |
Input: dewa size (new size of dewarpa array) Return: 0 if OK; 1 on error
Notes: (1) If necessary, reallocs new dewarpa ptr array to .
L_DEWARP* dewarpaGetDewarp | ( | L_DEWARPA * | dewa, |
l_int32 | index | ||
) |
Input: dewa (populated with dewarp structs for pages) index (into dewa: this is the pageno) Return: dew (handle; still owned by dewa), or null on error
PIX* dewarpaGetResult | ( | L_DEWARPA * | dewa, |
l_int32 | index | ||
) |
Input: dewa (populated with dewarp structs for pages) index (into dewa: this is the pageno) Return: pixd (clone of the pix in dew), or null on error
l_int32 dewarpaInfo | ( | FILE * | fp, |
L_DEWARPA * | dewa | ||
) |
Input: fp dewa Return: 0 if OK, 1 on error
l_int32 dewarpaInsertDewarp | ( | L_DEWARPA * | dewa, |
L_DEWARP * | dew | ||
) |
Input: dewarpa dewarp (to be added) Return: 0 if OK, 1 on error
Notes: (1) This inserts the dewarp into the array, which now owns it. It also keeps track of the largest page number stored. (2) Note that this differs from the usual method of filling out arrays in leptonica, where the arrays are compact and new elements are typically added to the end. Here, the dewarp can be added anywhere, even beyond the initial allocation.
l_int32 dewarpaInsertRefModels | ( | L_DEWARPA * | dewa, |
l_int32 | debug | ||
) |
Input: dewa debug (1 to output information on invalid page models) Return: 0 if OK, 1 on error
Notes: (1) This destroys all dewarp models that are invalid, and then inserts reference models where possible. (2) For all pages without a model, this clears out any existing reference dewarps, finds the nearest valid model with the same parity, and inserts an empty dewarp with the reference page. (2) If the nearest page is greater than dewa->maxdist, it does not use it. As a consequence, there will be no model for that page. Note that if dewa->maxdist < 2, no reference models will be inserted. (3) Important: this function must be called, even if reference models will not be used! It is typically called after building models on all available pages, and after setting the rendering parameters. (4) 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.
l_int32 dewarpaListPages | ( | L_DEWARPA * | dewa | ) |
Input: dewa (populated with dewarp structs for pages) Return: 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.
l_int32 dewarpaModelStats | ( | L_DEWARPA * | dewa, |
l_int32 * | pnnone, | ||
l_int32 * | pnactual, | ||
l_int32 * | pnvalid, | ||
l_int32 * | pnref | ||
) |
Input: dewa &nnone (<optional return>=""> number without any model) &nactual (<optional return>=""> number with an actual model) &nvalid (<optional return>=""> number with a valid model) &nref (<optional return>=""> number with a reference model) Return: 0 if OK, 1 on error
Notes: (1) A page without a model has no dew. It most likely failed to generate an actual model, and has not been assigned a ref model from a neighboring page with a valid model. (2) An actual model has a computation of at least the vertical disparity, where the build resulted in 'success'. With further processing by dewarpaInsertRefModels(), it may be found to be invalid, in which case the dew will be destroyed and replaced by a ref model if possible. (3) A valid model is an actual model whose parameters satisfy the constraints given in dewarpaSetValidModels(). (4) A page has a ref model if it failed to generate a valid model but was assigned a valid model on another page (within maxdist) by dewarpaInsertRefModel(). (5) This evaluates the validity of each model internally, and does not use the 'valid' field in each dew.
L_DEWARPA* dewarpaRead | ( | const char * | filename | ) |
Input: filename Return: dewa, or null on error
L_DEWARPA* dewarpaReadStream | ( | FILE * | fp | ) |
Input: stream Return: dewa, or null on error
Notes: (1) The serialized dewarp contains a Numa that gives the (increasing) page number of the dewarp structs that are contained. (2) Reference pages are added in after readback.
l_int32 dewarpaSetCurvatures | ( | L_DEWARPA * | dewa, |
l_int32 | min_medcurv, | ||
l_int32 | max_medcurv, | ||
l_int32 | max_leftcurv, | ||
l_int32 | max_rightcurv | ||
) |
Input: dewa min_medcurv max_medcurv max_leftcurv max_rightcurv Return: 0 if OK, 1 on error
Notes: (1) This sets four curvature thresholds: * the minimum absolute value of the median for the vertical disparity line curvatures (Use a value of 0 to accept all models.) * the maximum absolute value of the median for the vertical disparity line curvatures * the maximum absolute value of the left edge for the horizontal disparity * the maximum absolute value of the right edge for the horizontal disparity all in micro-units, for dewarping to take place. Use -1 for default values. (2) An image with a median line curvature less than about 0.00001 has fairly straight textlines. This is 10 micro-units, and if == 11, this would prevent dewarping using the disparity arrays. (3) A model having median line curvature larger than about 200 micro-units should probably not be used. (4) A model having left or right curvature larger than about 100 micro-units should probably not be used.
l_int32 dewarpaSetMaxDistance | ( | L_DEWARPA * | dewa, |
l_int32 | maxdist | ||
) |
Input: dewa maxdist (for using ref models) Return: 0 if OK, 1 on error
Notes: (1) This sets the maxdist field.
l_int32 dewarpaSetValidModels | ( | L_DEWARPA * | dewa, |
l_int32 | debug | ||
) |
Input: dewa debug (1 to output information on invalid page models) Return: 0 if OK, 1 on error
Notes: (1) A valid model must meet the rendering requirements, which include whether or not a horizontal disparity model exists and conditions on curvatures for vertical and horizontal disparity models. (2) This function is called by dewarpaInsertRefModels(), which will destroy all invalid dewarps. It does not need to be called by the application. If you want to inspect an invalid dewarp model, you must do so before calling dewarpaInsertRefModels().
Input: dewa scalefact (on contour images; typ. 0.5) first (first page model to render) last (last page model to render; use 0 to go to end) Return: 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
l_int32 dewarpaStripRefModels | ( | L_DEWARPA * | dewa | ) |
Input: dewa (populated with dewarp structs for pages) Return: 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). (2) Note that even if dewa->fullmodel == 1 (i.e., a full model is required, with both vertical and horizontal disparity arrays), this function will leave it in. These "invalid" models will be removed by dewarpaInsertRefModels() and replaced by reference page models.
static l_int32 dewarpaTestForValidModel | ( | L_DEWARPA * | dewa, |
L_DEWARP * | dew | ||
) | [static] |
Input: dewa dew Return: valid (1 if true; 0 otherwise)
l_int32 dewarpaUseFullModel | ( | L_DEWARPA * | dewa, |
l_int32 | fullmodel | ||
) |
Input: dewa fullmodel (0 for false, 1 for true) Return: 0 if OK, 1 on error
Notes: (1) This sets the fullmodel field. If set, the fullmodel (both vertical and horizontal disparity) is used if available. Default is false, so a page model with only vertical disparity will be considered a valid model and will be used.
l_int32 dewarpaWrite | ( | const char * | filename, |
L_DEWARPA * | dewa | ||
) |
Input: filename dewa Return: 0 if OK, 1 on error
l_int32 dewarpaWriteStream | ( | FILE * | fp, |
L_DEWARPA * | dewa | ||
) |
Input: stream (opened for "wb") dewa Return: 0 if OK, 1 on error
l_int32 dewarpBuildModel | ( | L_DEWARP * | dew, |
const char * | debugfile | ||
) |
Input: dew debugfile (use null to skip writing this) Return: 0 if OK, 1 on error
Notes: (1) This is the basic function that builds the horizontal and vertical disparity arrays, which allow determination of the src pixel in the input image corresponding to each dest pixel in the dewarped image. (2) The method is as follows: (a) Estimate the points along the centers of all the long textlines. If there are too few lines, no disparity models are built. (b) From the vertical deviation of the lines, estimate the vertical disparity. (c) From the ends of the lines, estimate the horizontal disparity, assuming that the text is made of lines that are left and right justified. (d) One can also compute an additional contribution to the horizontal disparity, inferred from slopes of the top and bottom lines. We do not do this. (3) In more detail for the vertical disparity: (a) Fit a LS quadratic to center locations along each line. This smooths the curves. (b) Sample each curve at a regular interval, find the y-value of the flat point on each curve, and subtract the sampled curve value from this value. This is the vertical disparity at sampled points along each curve. (c) Fit a LS quadratic to each set of vertically aligned disparity samples. This smooths the disparity values in the vertical direction. Then resample at the same regular interval. We now have a regular grid of smoothed vertical disparity valuels. (4) Once the sampled vertical disparity array is found, it can be interpolated to get a full resolution vertical disparity map. This can be applied directly to the src image pixels to dewarp the image in the vertical direction, making all textlines horizontal. Likewise, the horizontal disparity array is used to left- and right-align the longest textlines.
L_DEWARP* dewarpCreate | ( | PIX * | pixs, |
l_int32 | pageno | ||
) |
Input: pixs (1 bpp) pageno (page number) Return: dew (or null on error)
Notes: (1) The input pixs is either full resolution or 2x reduced. (2) The page number is typically 0-based. If scanned from a book, the even pages are usually on the left. Disparity arrays built for even pages should only be applied to even pages.
L_DEWARP* dewarpCreateReference | ( | l_int32 | pageno, |
l_int32 | refpage | ||
) |
Input: pageno (this page number) refpage (page number of dewarp disparity arrays to be used) Return: dew (or null on error)
Notes: (1) This specifies which dewarp struct should be used for the given page. It is placed in dewarpa for pages for which no model can be built. (2) This page and the reference page have the same parity and the reference page is the closest page with a disparity model to this page.
l_int32 dewarpDebug | ( | L_DEWARP * | dew, |
const char * | subdir, | ||
l_int32 | index | ||
) |
Input: dew subdir (a subdirectory of /tmp; e.g., "dew1") index (to help label output images; e.g., the page number) Return: 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/[subdir]/pixv_[index].png
void dewarpDestroy | ( | L_DEWARP ** | pdew | ) |
Input: &dew (<will be="" set="" to="" null="" before="" returning>="">) Return: void
l_int32 dewarpFindHorizDisparity | ( | L_DEWARP * | dew, |
PTAA * | ptaa | ||
) |
Input: dew ptaa (unsmoothed lines, not vertically ordered) Return: 0 if OK, 1 on error
(1) This is not required for a successful model; only the vertical disparity is required. This will not be called if the function to build the vertical disparity fails. (2) Debug output goes to /tmp/dewhoriz/ for collection into a pdf.
static l_int32 dewarpFindLongLines | ( | PTA * | ptal, |
PTA * | ptar, | ||
PTA ** | pptald, | ||
PTA ** | pptard | ||
) | [static] |
Input: ptal (left end points of lines) ptar (right end points of lines) &ptald (<return> left end points of longest lines) &ptard (<return> right end points of longest lines) Return: 0 if OK, 1 on error or if there aren't enough long lines
Notes: (1) We do the following: (a) Sort the lines from top to bottom, and divide equally into Top and Bottom sets. (b) For each set, select the lines that are within 3% of the longest line in the set. (c) Accumulate the left and right end points from both sets into the two returned ptas.
l_int32 dewarpFindVertDisparity | ( | L_DEWARP * | dew, |
PTAA * | ptaa | ||
) |
Input: dew ptaa (unsmoothed lines, not vertically ordered) Return: 0 if OK, 1 on error
Notes: (1) This starts with points along the centers of textlines. It does quadratic fitting (and smoothing), first along the lines and then in the vertical direction, to generate the sampled vertical disparity map. This can then be interpolated to full resolution and used to remove the vertical line warping. (2) The model fails to build if the vertical disparity fails. This sets the success flag to 1 on success. (3) Pix debug output goes to /tmp/dewvert/ for collection into a pdf. Non-pix debug output goes to /tmp.
static l_int32 dewarpGetLineEndpoints | ( | l_int32 | h, |
PTAA * | ptaa, | ||
PTA ** | pptal, | ||
PTA ** | pptar | ||
) | [static] |
Input: h (height of pixs) ptaa (lines) &ptal (<return> left end points of each line) &ptar (<return> right end points of each line) Return: 0 if OK, 1 on error.
Notes: (1) We require that the set of end points extends over 45% of the height of the input image, to insure good coverage and avoid extrapolating too far. Large extrapolations are dangerous if used as a reference model. (2) For fitting the endpoints, x = f(y), we transpose x and y. Thus all these ptas have x and y swapped!
static PTA * dewarpGetMeanVerticals | ( | PIX * | pixs, |
l_int32 | x, | ||
l_int32 | y | ||
) | [static] |
Input: pixs (1 bpp, single c.c.) x,y (location of UL corner of pixs with respect to page image Return: pta (mean y-values in component for each x-value, both translated by (x,y)
PIX* dewarpGetResult | ( | L_DEWARP * | dew | ) |
Input: dew (after applying disparity correction) Return: pixd (clone of the pix in dew), or null on error
PTAA* dewarpGetTextlineCenters | ( | PIX * | pixs, |
l_int32 | debugflag | ||
) |
Input: pixs (1 bpp) debugflag (1 for debug output) Return: ptaa (of center values of textlines)
Notes: (1) This in general does not have a point for each value of x, because there will be gaps between words. It doesn't matter because we will fit a quadratic to the points that we do have.
l_int32 dewarpMinimize | ( | L_DEWARP * | dew | ) |
Input: dew Return: 0 if OK, 1 on error
Notes: (1) This removes all data that is not needed for serialization. It keeps the subsampled disparity array(s), so the full resolution arrays can be reconstructed.
l_int32 dewarpPopulateFullRes | ( | L_DEWARP * | dew, |
PIX * | pix | ||
) |
Input: dew pix (<optional>, to give size of actual image) Return: 0 if OK, 1 on error
Notes: (1) If the full resolution vertical and horizontal disparity arrays do not exist, they are built from the subsampled ones. (2) If pixs is not given, the size of the arrays is determined by the original image from which the sampled version was generated. (3) If pixs is given: (a) If the arrays do not exist, the size of pixs is used to determine the size of the full resolution arrays. (b) If the arrays exist and pixs is too large, the existing full res arrays are destroyed and new ones are made.
static l_int32 dewarpQuadraticLSF | ( | PTA * | ptad, |
l_float32 * | pa, | ||
l_float32 * | pb, | ||
l_float32 * | pc, | ||
l_float32 * | pmederr | ||
) | [static] |
Input: ptad (left or right end points of longest lines) &a (<return> coeff a of LSF: y = ax^2 + bx + c) &b (<return> coeff b of LSF: y = ax^2 + bx + c) &c (<return> coeff c of LSF: y = ax^2 + bx + c) &mederr (<optional return>=""> median error) Return: 0 if OK, 1 on error.
Notes: (1) This is used for finding the left or right sides of the text block, computed as a quadratic curve. Only the longest lines are input, so there are no outliers. (2) The ptas for the end points all have x and y swapped.
L_DEWARP* dewarpRead | ( | const char * | filename | ) |
Input: filename Return: dew, or null on error
L_DEWARP* dewarpReadStream | ( | FILE * | fp | ) |
Input: stream Return: dew, or null on error
Notes: (1) The dewarp struct is stored in minimized format, with only subsampled disparity arrays. (2) The sampling and extra horizontal disparity parameters are stored here. During generation of the dewarp struct, they are passed in from the dewarpa. In readback, it is assumed that they are (a) the same for each page and (b) the same as the values used to create the dewarpa.
Input: pixs (1 bpp) ptaas (input lines) fract (minimum fraction of longest line to keep) debugflag Return: ptaad (containing only lines of sufficient length), or null on error
l_int32 dewarpShowResults | ( | L_DEWARPA * | dewa, |
SARRAY * | sa, | ||
BOXA * | boxa, | ||
l_int32 | firstpage, | ||
l_int32 | lastpage, | ||
const char * | pdfout | ||
) |
Input: dewa sarray (of indexed input images) boxa (crop boxes for input images; can be null) firstpage, lastpage pdfout (filename) Return: 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
l_int32 dewarpWrite | ( | const char * | filename, |
L_DEWARP * | dew | ||
) |
Input: filename dew Return: 0 if OK, 1 on error
l_int32 dewarpWriteStream | ( | FILE * | fp, |
L_DEWARP * | dew | ||
) |
Input: stream (opened for "wb") dew Return: 0 if OK, 1 on error
Notes: (1) This should not be written if there is no sampled vertical disparity array, which means that no model has been built for this page.
static PIX * pixApplyHorizDisparity | ( | L_DEWARP * | dew, |
PIX * | pixs | ||
) | [static] |
Input: dew pixs (1, 8 or 32 bpp) Return: pixd (modified to remove horizontal disparity if possible), or null on error
Notes: (1) This applies the horizontal disparity array to the specified image. (2) The input pixs has already been corrected for vertical disparity. If the horizontal disparity array doesn't exist, this returns a clone of .
static PIX * pixApplyVertDisparity | ( | L_DEWARP * | dew, |
PIX * | pixs | ||
) | [static] |
Input: dew pixs (1, 8 or 32 bpp) Return: pixd (modified to remove vertical disparity), or null on error
Notes: (1) This applies the vertical disparity array to the specified image. For src pixels above the image, we use the pixels in the first raster line.
static l_int32 pixRenderFlats | ( | PIX * | pixs, |
NUMA * | naflats, | ||
l_int32 | linew | ||
) | [static] |
Input: pixs (32 bpp) naflats (y location of reference lines for vertical disparity) linew (width of rendered line; typ 2) Return: 0 if OK, 1 on error
static l_int32 pixRenderHorizEndPoints | ( | PIX * | pixs, |
PTA * | ptal, | ||
PTA * | ptar, | ||
l_uint32 | color | ||
) | [static] |
Input: pixs (32 bpp) ptal (left side line end points) ptar (right side line end points) color (0xrrggbb00) Return: 0 if OK, 1 on error
const l_int32 DEFAULT_ARRAY_SAMPLING = 30 [static] |
const l_int32 DEFAULT_MAX_LEFTCURV = 60 [static] |
const l_int32 DEFAULT_MAX_MEDCURV = 150 [static] |
const l_int32 DEFAULT_MAX_REF_DIST = 30 [static] |
const l_int32 DEFAULT_MAX_RIGHTCURV = 60 [static] |
const l_int32 DEFAULT_MIN_LINES = 15 [static] |
const l_int32 DEFAULT_MIN_MEDCURV = 0 [static] |
const l_float32 DEFAULT_SLOPE_FACTOR = 2000. [static] |
const l_int32 INITIAL_PTR_ARRAYSIZE = 20 [static] |
const l_int32 MAX_PTR_ARRAYSIZE = 10000 [static] |
const l_int32 MIN_ARRAY_SAMPLING = 8 [static] |
const l_float32 MIN_RATIO_LINES_TO_HEIGHT = 0.45 [static] |