third-party/leptonica/src/recog.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_RECOG_H
#define LEPTONICA_RECOG_H
/*
* recog.h
*
* A simple utility for training and recognizing individual
* machine-printed text characters. In an application, one can
* envision using a number of these, one for each trained set.
*
* In training mode, a set of labelled bitmaps is presented, either
* one at a time, or in a directory, or in a pixa. If in a directory,
* or a pixa, the labelling text string must be embedded in the
* text field of the image file.
*
* Any number of recognizers (L_Recog) can be trained and then used
* together in an array (L_Recoga). All these trained structures
* can be serialized to file and read back. The serialized version
* holds all the bitmaps used for training, plus, for arbitrary
* character sets, the UTF8 representation and the lookup table
* mapping from the character representation to index.
*
* There are three levels of "sets" here:
*
* (1) Example set: the examples representing a character that
* were printed in the same way, so that they can be combined
* without scaling to form an "average" template for the character.
* In the recognition phase, we use either this aligned average,
* or the individual bitmaps. All examples in the set are given
* the same character label. Example: the letter 'a' in the
* predominant font in a book.
*
* (2) Character set (represented by L_Recog, a single recognizer):
* The set of different characters, each of which is described
* by (1). Each element of the set has a different character
* label. Example: the digits '0' through '9' that are used for
* page numbering in a book.
*
* (3) Recognizer set (represented by L_Recoga, an array of recogs):
* A set of recognizers, each of which is described by (2).
* In general, we do not want to combine the character sets
* with the same labels within different recognizer sets,
* because the bitmaps can differ in font type, style or size.
* Example 1: the letter 'a' can be printed in two very different
* ways (either with a large loop or with a smaller loop in
* the lower half); both share the same label but need to be
* distinguished so that they are not mixed when averaging.
* Example 2: a recognizer trained for a book may be missing
* some characters, so we need to supplement it with another
* "generic" or "bootstrap" recognizer that has the additional
* characters from a variety of sources. Bootstrap recognizers
* must be run in a mode where all characters are scaled.
*
* In the recognition process, for each component in an input image,
* each recognizer (L_Recog) records the best match (highest
* correlation score). If there is more than one recognizer, these
* results are aggregated to find the best match for each character
* for all the recognizers, and this is stored in L_Recoga.
*/
#define RECOG_VERSION_NUMBER 1
struct L_Recoga {
l_int32 n; /* number of recogs */
l_int32 nalloc; /* number of recog ptrs allocated */
struct L_Recog **recog; /* recog ptr array */
struct L_Rcha *rcha; /* stores the array of best chars */
};
typedef struct L_Recoga L_RECOGA;
struct L_Recog {
l_int32 scalew; /* scale all examples to this width; */
/* use 0 prevent horizontal scaling */
l_int32 scaleh; /* scale all examples to this height; */
/* use 0 prevent vertical scaling */
l_int32 templ_type; /* template type: either an average of */
/* examples (L_USE_AVERAGE) or the set */
/* of all examples (L_USE_ALL) */
l_int32 maxarraysize; /* initialize container arrays to this */
l_int32 setsize; /* size of character set */
l_int32 threshold; /* for binarizing if depth > 1 */
l_int32 maxyshift; /* vertical jiggle on nominal centroid */
/* alignment; typically 0 or 1 */
l_float32 asperity_fr; /* +- allowed fractional asperity ratio */
l_int32 charset_type; /* one of L_ARABIC_NUMERALS, etc. */
l_int32 charset_size; /* expected number of classes in charset */
char *bootdir; /* dir with bootstrap pixa charsets */
char *bootpattern; /* file pattern for bootstrap pixa charsets */
char *bootpath; /* path for single bootstrap pixa charset */
l_int32 min_nopad; /* min number of samples without padding */
l_int32 max_afterpad; /* max number of samples after padding */
l_int32 samplenum; /* keep track of number of training samples */
l_int32 minwidth_u; /* min width of averaged unscaled templates */
l_int32 maxwidth_u; /* max width of averaged unscaled templates */
l_int32 minheight_u; /* min height of averaged unscaled templates */
l_int32 maxheight_u; /* max height of averaged unscaled templates */
l_int32 minwidth; /* min width of averaged scaled templates */
l_int32 maxwidth; /* max width of averaged scaled templates */
l_int32 ave_done; /* set to 1 when averaged bitmaps are made */
l_int32 train_done; /* set to 1 when training is complete or */
/* identification has started */
l_int32 min_splitw; /* min component width kept in splitting */
l_int32 min_splith; /* min component height kept in splitting */
l_int32 max_splith; /* max component height kept in splitting */
struct Sarray *sa_text; /* text array for arbitrary char set */
struct L_Dna *dna_tochar; /* index-to-char lut for arbitrary char set */
l_int32 *centtab; /* table for finding centroids */
l_int32 *sumtab; /* table for finding pixel sums */
char *fname; /* serialized filename (if read) */
struct Pixaa *pixaa_u; /* all unscaled bitmaps for each class */
struct Pixa *pixa_u; /* averaged unscaled bitmaps for each class */
struct Ptaa *ptaa_u; /* centroids of all unscaled bitmaps */
struct Pta *pta_u; /* centroids of unscaled averaged bitmaps */
struct Numaa *naasum_u; /* area of all unscaled bitmap examples */
struct Numa *nasum_u; /* area of unscaled averaged bitmaps */
struct Pixaa *pixaa; /* all bitmap examples for each class */
struct Pixa *pixa; /* averaged bitmaps for each class */
struct Ptaa *ptaa; /* centroids of all bitmap examples */
struct Pta *pta; /* centroids of averaged bitmaps */
struct Numaa *naasum; /* area of all bitmap examples */
struct Numa *nasum; /* area of averaged bitmaps */
struct Pixa *pixa_tr; /* input training images */
struct Pixa *pixadb_ave; /* unscaled and scaled averaged bitmaps */
struct Pixa *pixa_id; /* input images for identifying */
struct Pix *pixdb_ave; /* debug: best match of input against ave. */
struct Pix *pixdb_range; /* debug: best matches within range */
struct Pixa *pixadb_boot; /* debug: bootstrap training results */
struct Pixa *pixadb_split; /* debug: splitting results */
struct L_Bmf *bmf; /* bmf fonts */
l_int32 bmf_size; /* font size of bmf; default is 6 pt */
struct L_Rdid *did; /* temp data used for image decoding */
struct L_Rch *rch; /* temp data used for holding best char */
struct L_Rcha *rcha; /* temp data used for array of best chars */
l_int32 bootrecog; /* 1 if using bootstrap samples; else 0 */
l_int32 index; /* recog index in recoga; -1 if no parent */
struct L_Recoga *parent; /* ptr to parent array; can be null */
};
typedef struct L_Recog L_RECOG;
/*
* Data returned from correlation matching on a single character
*/
struct L_Rch {
l_int32 index; /* index of best template */
l_float32 score; /* correlation score of best template */
char *text; /* character string of best template */
l_int32 sample; /* index of best sample (within the best */
/* template class, if all samples are used) */
l_int32 xloc; /* x-location of template (delx + shiftx) */
l_int32 yloc; /* y-location of template (dely + shifty) */
l_int32 width; /* width of best template */
};
typedef struct L_Rch L_RCH;
/*
* Data returned from correlation matching on an array of characters
*/
struct L_Rcha {
struct Numa *naindex; /* indices of best templates */
struct Numa *nascore; /* correlation scores of best templates */
struct Sarray *satext; /* character strings of best templates */
struct Numa *nasample; /* indices of best samples */
struct Numa *naxloc; /* x-locations of templates (delx + shiftx) */
struct Numa *nayloc; /* y-locations of templates (dely + shifty) */
struct Numa *nawidth; /* widths of best templates */
};
typedef struct L_Rcha L_RCHA;
/*
* Data used for decoding a line of characters.
*/
struct L_Rdid {
struct Pix *pixs; /* clone of pix to be decoded */
l_int32 **counta; /* count array for each averaged template */
l_int32 **delya; /* best y-shift array per averaged template */
l_int32 narray; /* number of averaged templates */
l_int32 size; /* size of count array (width of pixs) */
l_int32 *setwidth; /* setwidths for each template */
struct Numa *nasum; /* pixel count in pixs by column */
struct Numa *namoment; /* first moment of pixels in pixs by column */
l_int32 fullarrays; /* 1 if full arrays are made; 0 otherwise */
l_float32 *beta; /* channel coeffs for template fg term */
l_float32 *gamma; /* channel coeffs for bit-and term */
l_float32 *trellisscore; /* score on trellis */
l_int32 *trellistempl; /* template on trellis (for backtrack) */
struct Numa *natempl; /* indices of best path templates */
struct Numa *naxloc; /* x locations of best path templates */
struct Numa *nadely; /* y locations of best path templates */
struct Numa *nawidth; /* widths of best path templates */
struct Numa *nascore; /* correlation scores: best path templates */
struct Numa *natempl_r; /* indices of best rescored templates */
struct Numa *naxloc_r; /* x locations of best rescoredtemplates */
struct Numa *nadely_r; /* y locations of best rescoredtemplates */
struct Numa *nawidth_r; /* widths of best rescoredtemplates */
struct Numa *nascore_r; /* correlation scores: rescored templates */
};
typedef struct L_Rdid L_RDID;
/*-------------------------------------------------------------------------*
* Flags for selecting processing *
*-------------------------------------------------------------------------*/
enum {
L_SELECT_UNSCALED = 0, /* select the unscaled bitmaps */
L_SELECT_SCALED = 1, /* select the scaled bitmaps */
L_SELECT_BOTH = 2 /* select both unscaled and scaled */
};
/*-------------------------------------------------------------------------*
* Flags for determining what to test against *
*-------------------------------------------------------------------------*/
enum {
L_USE_AVERAGE = 0, /* form template from class average */
L_USE_ALL = 1 /* match against all elements of each class */
};
/*-------------------------------------------------------------------------*
* Flags for describing limited character sets *
*-------------------------------------------------------------------------*/
enum {
L_UNKNOWN = 0, /* character set type is not specified */
L_ARABIC_NUMERALS = 1, /* 10 digits */
L_LC_ROMAN_NUMERALS = 2, /* 7 lower-case letters (i,v,x,l,c,d,m) */
L_UC_ROMAN_NUMERALS = 3, /* 7 upper-case letters (I,V,X,L,C,D,M) */
L_LC_ALPHA = 4, /* 26 lower-case letters */
L_UC_ALPHA = 5 /* 26 upper-case letters */
};
#endif /* LEPTONICA_RECOG_H */