Leptonica
1.54
|
#include "alltypes.h"
#define LIBLEPT_MAJOR_VERSION 1 |
#define LIBLEPT_MINOR_VERSION 69 |
LEPT_DLL void absDifferenceLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas1, | ||
l_uint32 * | datas2, | ||
l_int32 | d, | ||
l_int32 | wpls1, | ||
l_int32 | wpls2 | ||
) |
Finds the absolute value of the difference of each pixel, for 8 and 16 bpp gray and for 32 bpp rgb. For 32 bpp, the differences are found for each of the RGB components separately, and the LSB component is ignored. The results are written into datad.
LEPT_DLL l_int32 addColorizedGrayToCmap | ( | PIXCMAP * | cmap, |
l_int32 | type, | ||
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval, | ||
NUMA ** | pna | ||
) |
Input: cmap (from 2 or 4 bpp pix) type (L_PAINT_LIGHT, L_PAINT_DARK) rval, gval, bval (target color) &na (<optional return>=""> table for mapping new cmap entries) Return: 0 if OK; 1 on error; 2 if new colors will not fit in cmap.
Notes: (1) If type == L_PAINT_LIGHT, it colorizes non-black pixels, preserving antialiasing. If type == L_PAINT_DARK, it colorizes non-white pixels, preserving antialiasing. (2) This increases the colormap size by the number of different gray (non-black or non-white) colors in the input colormap. If there is not enough room in the colormap for this expansion, it returns 1 (treated as a warning); the caller should check the return value. (3) This can be used to determine if the new colors will fit in the cmap, using null for &na. Returns 0 if they fit; 2 if they don't fit. (4) The mapping table contains, for each gray color found, the index of the corresponding colorized pixel. Non-gray pixels are assigned the invalid index 256. (5) See pixColorGrayCmap() for usage.
LEPT_DLL l_int32 adjacentOnPixelInRaster | ( | PIX * | pixs, |
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 * | pxa, | ||
l_int32 * | pya | ||
) |
Input: pixs (1 bpp) x, y (current pixel) xa, ya (adjacent ON pixel, found by simple CCW search) Return: 1 if a pixel is found; 0 otherwise or on error
Notes: (1) Search is in 4-connected directions first; then on diagonals. This allows traversal along a 4-connected boundary.
LEPT_DLL l_int32 affineInvertXform | ( | l_float32 * | vc, |
l_float32 ** | pvci | ||
) |
Input: vc (vector of 6 coefficients) *vci (<return> inverted transform) Return: 0 if OK; 1 on error
Notes: (1) The 6 affine transform coefficients are the first two rows of a 3x3 matrix where the last row has only a 1 in the third column. We invert this using gaussjordan(), and select the first 2 rows as the coefficients of the inverse affine transform. (2) Alternatively, we can find the inverse transform coefficients by inverting the 2x2 submatrix, and treating the top 2 coefficients in the 3rd column as a RHS vector for that 2x2 submatrix. Then the 6 inverted transform coefficients are composed of the inverted 2x2 submatrix and the negative of the transformed RHS vector. Why is this so? We have Y = AX + R (2 equations in 6 unknowns) Then X = A'Y - A'R Gauss-jordan solves AF = R and puts the solution for F, which is A'R, into the input R vector.
LEPT_DLL l_int32 affineXformPt | ( | l_float32 * | vc, |
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 * | pxp, | ||
l_float32 * | pyp | ||
) |
Input: vc (vector of 6 coefficients) (x, y) (initial point) (&xp, &yp) (<return> transformed point) Return: 0 if OK; 1 on error
Notes: (1) This computes the floating point location of the transformed point. (2) It does not check ptrs for returned data!
LEPT_DLL l_int32 affineXformSampledPt | ( | l_float32 * | vc, |
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 * | pxp, | ||
l_int32 * | pyp | ||
) |
Input: vc (vector of 6 coefficients) (x, y) (initial point) (&xp, &yp) (<return> transformed point) Return: 0 if OK; 1 on error
Notes: (1) This finds the nearest pixel coordinates of the transformed point. (2) It does not check ptrs for returned data!
LEPT_DLL l_int32 applyCubicFit | ( | l_float32 | a, |
l_float32 | b, | ||
l_float32 | c, | ||
l_float32 | d, | ||
l_float32 | x, | ||
l_float32 * | py | ||
) |
Input: a, b, c, d (cubic fit coefficients) x &y (<return> y = a * x^3 + b * x^2 + c * x + d) Return: 0 if OK, 1 on error
Input: a, b (linear fit coefficients) x &y (<return> y = a * x + b) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 applyQuadraticFit | ( | l_float32 | a, |
l_float32 | b, | ||
l_float32 | c, | ||
l_float32 | x, | ||
l_float32 * | py | ||
) |
Input: a, b, c (quadratic fit coefficients) x &y (<return> y = a * x^2 + b * x + c) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 applyQuarticFit | ( | l_float32 | a, |
l_float32 | b, | ||
l_float32 | c, | ||
l_float32 | d, | ||
l_float32 | e, | ||
l_float32 | x, | ||
l_float32 * | py | ||
) |
Input: a, b, c, d, e (quartic fit coefficients) x &y (<return> y = a * x^4 + b * x^3 + c * x^2 + d * x + e) Return: 0 if OK, 1 on error
LEPT_DLL L_DNA* arrayFindEachSequence | ( | const l_uint8 * | data, |
l_int32 | datalen, | ||
const l_uint8 * | sequence, | ||
l_int32 | seqlen | ||
) |
Input: data (byte array) datalen (length of data, in bytes) sequence (subarray of bytes to find in data) seqlen (length of sequence, in bytes) Return: dna of offsets where the sequence is found, or null if none are found or on error
Notes: (1) The byte arrays and are not C strings, as they can contain null bytes. Therefore, for each we must give the length of the array. (2) This finds every occurrence in of .
LEPT_DLL l_int32 arrayFindSequence | ( | const l_uint8 * | data, |
l_int32 | datalen, | ||
const l_uint8 * | sequence, | ||
l_int32 | seqlen, | ||
l_int32 * | poffset, | ||
l_int32 * | pfound | ||
) |
Input: data (byte array) datalen (length of data, in bytes) sequence (subarray of bytes to find in data) seqlen (length of sequence, in bytes) &offset (return> offset from beginning of data where the sequence begins) &found (<optional return>=""> 1 if sequence is found; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) The byte arrays 'data' and 'sequence' are not C strings, as they can contain null bytes. Therefore, for each we must give the length of the array. (2) This searches for the first occurrence in of , which consists of bytes. The parameter must not exceed the actual length of the byte array. (3) If the sequence is not found, the offset will be set to -1.
Input: filename &nbytes (<return> number of bytes read) Return: array, or null on error
LEPT_DLL l_uint8* arrayReadStream | ( | FILE * | fp, |
l_int32 * | pnbytes | ||
) |
Input: stream &nbytes (<return> number of bytes read) Return: null-terminated array, or null on error (reading 0 bytes is not an error)
Notes: (1) N.B.: as a side effect, this always re-positions the stream ptr to the beginning of the file.
LEPT_DLL char* barcodeDispatchDecoder | ( | char * | barstr, |
l_int32 | format, | ||
l_int32 | debugflag | ||
) |
Input: barstr (string of integers in set {1,2,3,4} of bar widths) format (L_BF_ANY, L_BF_CODEI2OF5, L_BF_CODE93, ...) debugflag (use 1 to generate debug output) Return: data (string of decoded barcode data), or null on error
LEPT_DLL l_int32 barcodeFormatIsSupported | ( | l_int32 | format | ) |
Input: format Return: 1 if format is one of those supported; 0 otherwise
LEPT_DLL l_int32 bbufferBytesToWrite | ( | BBUFFER * | bb, |
size_t * | pnbytes | ||
) |
Input: bbuffer &nbytes (<return>) Return: 0 if OK; 1 on error
LEPT_DLL BBUFFER* bbufferCreate | ( | l_uint8 * | indata, |
l_int32 | nalloc | ||
) |
Input: buffer address in memory (<optional>) size of byte array to be alloc'd (0 for default) Return: bbuffer, or null on error
Notes: (1) If a buffer address is given, you should read all the data in. (2) Allocates a bbuffer with associated byte array of the given size. If a buffer address is given, it then reads the number of bytes into the byte array.
LEPT_DLL void bbufferDestroy | ( | BBUFFER ** | pbb | ) |
Input: &bbuffer (<to be="" nulled>="">) Return: void
Notes: (1) Destroys the byte array in the bbuffer and then the bbuffer; then nulls the contents of the input ptr.
LEPT_DLL l_uint8* bbufferDestroyAndSaveData | ( | BBUFFER ** | pbb, |
size_t * | pnbytes | ||
) |
Input: &bbuffer (<to be="" nulled>="">) &nbytes (<return> number of bytes saved in array) Return: barray (newly allocated array of data)
Notes: (1) Copies data to newly allocated array; then destroys the bbuffer.
LEPT_DLL l_int32 bbufferExtendArray | ( | BBUFFER * | bb, |
l_int32 | nbytes | ||
) |
Input: bbuffer nbytes (number of bytes to extend array size) Return: 0 if OK, 1 on error
Notes: (1) reallocNew() copies all bb->nalloc bytes, even though only bb->n are data.
Input: bbuffer src (source memory buffer from which bytes are read) nbytes (bytes to be read) Return: 0 if OK, 1 on error
Notes: (1) For a read after write, first remove the written bytes by shifting the unwritten bytes in the array, then check if there is enough room to add the new bytes. If not, realloc with bbufferExpandArray(), resulting in a second writing of the unwritten bytes. While less efficient, this is simpler than making a special case of reallocNew().
LEPT_DLL l_int32 bbufferReadStream | ( | BBUFFER * | bb, |
FILE * | fp, | ||
l_int32 | nbytes | ||
) |
Input: bbuffer fp (source stream from which bytes are read) nbytes (bytes to be read) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 bbufferWrite | ( | BBUFFER * | bb, |
l_uint8 * | dest, | ||
size_t | nbytes, | ||
size_t * | pnout | ||
) |
Input: bbuffer dest (dest memory buffer to which bytes are written) nbytes (bytes requested to be written) &nout (<return> bytes actually written) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 bbufferWriteStream | ( | BBUFFER * | bb, |
FILE * | fp, | ||
size_t | nbytes, | ||
size_t * | pnout | ||
) |
Input: bbuffer fp (dest stream to which bytes are written) nbytes (bytes requested to be written) &nout (<return> bytes actually written) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 bilinearXformPt | ( | l_float32 * | vc, |
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 * | pxp, | ||
l_float32 * | pyp | ||
) |
Input: vc (vector of 8 coefficients) (x, y) (initial point) (&xp, &yp) (<return> transformed point) Return: 0 if OK; 1 on error
Notes: (1) This computes the floating point location of the transformed point. (2) It does not check ptrs for returned data!
LEPT_DLL l_int32 bilinearXformSampledPt | ( | l_float32 * | vc, |
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 * | pxp, | ||
l_int32 * | pyp | ||
) |
Input: vc (vector of 8 coefficients) (x, y) (initial point) (&xp, &yp) (<return> transformed point) Return: 0 if OK; 1 on error
Notes: (1) This finds the nearest pixel coordinates of the transformed point. (2) It does not check ptrs for returned data!
LEPT_DLL void blockconvAccumLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | d, | ||
l_int32 | wpls | ||
) |
LEPT_DLL void blockconvLow | ( | l_uint32 * | data, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpl, | ||
l_uint32 * | dataa, | ||
l_int32 | wpla, | ||
l_int32 | wc, | ||
l_int32 | hc | ||
) |
Input: data (data of input image, to be convolved) w, h, wpl dataa (data of 32 bpp accumulator) wpla (accumulator) wc (convolution "half-width") hc (convolution "half-height") Return: void
Notes: (1) The full width and height of the convolution kernel are (2 * wc + 1) and (2 * hc + 1). (2) The lack of symmetry between the handling of the first (hc + 1) lines and the last (hc) lines, and similarly with the columns, is due to fact that for the pixel at (x,y), the accumulator values are taken at (x + wc, y + hc), (x - wc - 1, y + hc), (x + wc, y - hc - 1) and (x - wc - 1, y - hc - 1). (3) We compute sums, normalized as if there were no reduced area at the boundary. This under-estimates the value of the boundary pixels, so we multiply them by another normalization factor that is greater than 1. (4) This second normalization is done first for the first hc + 1 lines; then for the last hc lines; and finally for the first wc + 1 and last wc columns in the intermediate lines. (5) The caller should verify that wc < w and hc < h. Under those conditions, illegal reads and writes can occur. (6) Implementation note: to get the same results in the interior between this function and pixConvolve(), it is necessary to add 0.5 for roundoff in the main loop that runs over all pixels. However, if we do that and have white (255) pixels near the image boundary, some overflow occurs for pixels very close to the boundary. We can't fix this by subtracting from the normalized values for the boundary pixels, because this results in underflow if the boundary pixels are black (0). Empirically, adding 0.25 (instead of 0.5) before truncating in the main loop will not cause overflow, but this gives some off-by-1-level errors in interior pixel values. So we add 0.5 for roundoff in the main loop, and for pixels within a half filter width of the boundary, use a L_MIN of the computed value and 255 to avoid overflow during normalization.
LEPT_DLL void blocksumLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpl, | ||
l_uint32 * | dataa, | ||
l_int32 | wpla, | ||
l_int32 | wc, | ||
l_int32 | hc | ||
) |
Input: datad (of 8 bpp dest) w, h, wpl (of 8 bpp dest) dataa (of 32 bpp accum) wpla (of 32 bpp accum) wc, hc (convolution "half-width" and "half-height") Return: void
Notes: (1) The full width and height of the convolution kernel are (2 * wc + 1) and (2 * hc + 1). (2) The lack of symmetry between the handling of the first (hc + 1) lines and the last (hc) lines, and similarly with the columns, is due to fact that for the pixel at (x,y), the accumulator values are taken at (x + wc, y + hc), (x - wc - 1, y + hc), (x + wc, y - hc - 1) and (x - wc - 1, y - hc - 1). (3) Compute sums of ON pixels within the block filter size, normalized between 0 and 255, as if there were no reduced area at the boundary. This under-estimates the value of the boundary pixels, so we multiply them by another normalization factor that is greater than 1. (4) This second normalization is done first for the first hc + 1 lines; then for the last hc lines; and finally for the first wc + 1 and last wc columns in the intermediate lines. (5) The caller should verify that wc < w and hc < h. Under those conditions, illegal reads and writes can occur.
Input: dir (directory holding pixa of character set) size (4, 6, 8, ... , 20) Return: bmf (holding the bitmap font and associated information)
Notes: (1) This first tries to read a pre-computed pixa file with the 95 ascii chars in it. If the file is not found, it creates the pixa from the raw image. It then generates all associated data required to use the bmf.
LEPT_DLL void bmfDestroy | ( | L_BMF ** | pbmf | ) |
Input: &bmf (<set to="" null>="">) Return: void
LEPT_DLL l_int32 bmfGetBaseline | ( | L_BMF * | bmf, |
char | chr, | ||
l_int32 * | pbaseline | ||
) |
Input: bmf chr (should be one of the 95 supported bitmaps) &baseline (<return>; distance below UL corner of bitmap char) Return: 0 if OK, 1 on error
LEPT_DLL SARRAY* bmfGetLineStrings | ( | L_BMF * | bmf, |
const char * | textstr, | ||
l_int32 | maxw, | ||
l_int32 | firstindent, | ||
l_int32 * | ph | ||
) |
Input: bmf textstr maxw (max width of a text line in pixels) firstindent (indentation of first line, in x-widths) &h (<return> height required to hold text bitmap) Return: sarray of text strings for each line, or null on error
Notes: (1) Divides the input text string into an array of text strings, each of which will fit within maxw bits of width.
Input: bmf chr (should be one of the 95 supported printable bitmaps) Return: pix (clone of pix in bmf), or null on error
LEPT_DLL l_int32 bmfGetStringWidth | ( | L_BMF * | bmf, |
const char * | textstr, | ||
l_int32 * | pw | ||
) |
Input: bmf textstr &w (<return> width of text string, in pixels for the font represented by the bmf) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 bmfGetWidth | ( | L_BMF * | bmf, |
char | chr, | ||
l_int32 * | pw | ||
) |
Input: bmf chr (should be one of the 95 supported bitmaps) &w (<return> character width; -1 if not printable) Return: 0 if OK, 1 on error
LEPT_DLL NUMA* bmfGetWordWidths | ( | L_BMF * | bmf, |
const char * | textstr, | ||
SARRAY * | sa | ||
) |
Input: bmf textstr sa (of individual words) Return: numa (of word lengths in pixels for the font represented by the bmf), or null on error
Input: boxaa index (of boxa with boxaa) box (to be added) accessflag (L_INSERT, L_COPY or L_CLONE) Return: 0 if OK, 1 on error
Notes: (1) Adds to an existing boxa only.
Input: boxaa boxa (to be added) copyflag (L_INSERT, L_COPY, L_CLONE) Return: 0 if OK, 1 on error
Input: boxaa box (to be aligned with the last of one of the boxa in boxaa, if possible) delta (amount by which consecutive components can miss in overlap and still be included in the array) &index (of boxa with best overlap, or if none match, this is the index of the next boxa to be generated) Return: 0 if OK, 1 on error
Notes: (1) This is not greedy; it finds the boxa whose last box has the biggest overlap with the input box.
Input: baas (input boxaa to be copied) copyflag (L_COPY, L_CLONE) Return: baad (new boxaa, composed of copies or clones of the boxa in baas), or null on error
Notes: (1) L_COPY makes a copy of each boxa in baas. L_CLONE makes a clone of each boxa in baas.
LEPT_DLL BOXAA* boxaaCreate | ( | l_int32 | n | ) |
Input: size of boxa ptr array to be alloc'd (0 for default) Return: baa, or null on error
Input: boxa box (to be added) copyflag (L_INSERT, L_COPY, L_CLONE) Return: 0 if OK, 1 on error
LEPT_DLL void boxaaDestroy | ( | BOXAA ** | pbaa | ) |
Input: &boxaa (<will be="" set="" to="" null="" before="" returning>="">) Return: void
LEPT_DLL PIX* boxaaDisplay | ( | BOXAA * | boxaa, |
l_int32 | linewba, | ||
l_int32 | linewb, | ||
l_uint32 | colorba, | ||
l_uint32 | colorb, | ||
l_int32 | w, | ||
l_int32 | h | ||
) |
Input: boxaa linewba (line width to display boxa) linewb (line width to display box) colorba (color to display boxa) colorb (color to display box) w (of pix; use 0 if determined by boxaa) h (of pix; use 0 if determined by boxaa) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 boxaaExtendArray | ( | BOXAA * | baa | ) |
Input: boxaa Return: 0 if OK, 1 on error
LEPT_DLL l_int32 boxaaExtendArrayToSize | ( | BOXAA * | baa, |
l_int32 | size | ||
) |
Input: boxaa size (new size of boxa array) Return: 0 if OK; 1 on error
Notes: (1) If necessary, reallocs the boxa ptr array to .
Input: boxaa maxindex boxa (to be replicated into the extended ptr array) Return: 0 if OK, 1 on error
Notes: (1) This should be used on an existing boxaa that has been fully loaded with boxa. It then extends the boxaa, loading all the additional ptrs with copies of boxa. Typically, boxa will be empty.
LEPT_DLL BOXA* boxaAffineTransform | ( | BOXA * | boxas, |
l_float32 * | mat | ||
) |
Input: boxas mat (3x3 transform matrix; canonical form) Return: boxad (transformed boxas), or null on error
Input: boxaa num (number extracted from each) copyflag (L_COPY or L_CLONE) Return: boxa, or null on error
Notes: (1) This 'flattens' the boxaa to a boxa, taking the first boxes from each boxa. (2) If less than boxes are in a boxa, we add invalid placeholder boxes to preserve the alignment between the input boxaa and the output boxa.
Input: boxaa &naindex (<optional return>=""> the boxa index in the boxaa) copyflag (L_COPY or L_CLONE) Return: boxa, or null on error
Notes: (1) This 'flattens' the boxaa to a boxa, taking the boxes in order in the first boxa, then the second, etc. (2) If a boxa is empty, we generate an invalid, placeholder box of zero size. This is useful when converting from a boxaa where each boxa has either 0 or 1 boxes, and it is necessary to maintain a 1:1 correspondence between the initial boxa array and the resulting box array. (3) If &naindex is defined, we generate a Numa that gives, for each box in the boxaa, the index of the boxa to which it belongs.
Input: baa iboxa (index into the boxa array in the boxaa) ibox (index into the box array in the boxa) accessflag (L_COPY or L_CLONE) Return: box, or null on error
Input: boxaa index (to the index-th boxa) accessflag (L_COPY or L_CLONE) Return: boxa, or null on error
LEPT_DLL l_int32 boxaaGetBoxCount | ( | BOXAA * | baa | ) |
Input: boxaa Return: count (number of boxes), or 0 if no boxes or on error
LEPT_DLL l_int32 boxaaGetCount | ( | BOXAA * | baa | ) |
Input: boxaa Return: count (number of boxa), or 0 if no boxa or on error
Input: boxaa &w (<optional return>=""> width) &h (<optional return>=""> height) &box (<optional return>="">, minimum box containing all boxa in boxaa) Return: 0 if OK, 1 on error
Notes: (1) The returned w and h are the minimum size image that would contain all boxes untranslated.
LEPT_DLL l_int32 boxaaInitFull | ( | BOXAA * | baa, |
BOXA * | boxa | ||
) |
Input: boxaa (typically empty) boxa (to be replicated into the entire ptr array) Return: 0 if OK, 1 on error
Notes: (1) This initializes a boxaa by filling up the entire boxa ptr array with copies of . Any existing boxa are destroyed. After this operation, the number of boxa is equal to the number of allocated ptrs. (2) Note that we use boxaaReplaceBox() instead of boxaInsertBox(). They both have the same effect when inserting into a NULL ptr in the boxa ptr array (3) Example usage. This function is useful to prepare for a random insertion (or replacement) of boxa into a boxaa. To randomly insert boxa into a boxaa, up to some index "max": Boxaa *baa = boxaaCreate(max); // initialize the boxa Boxa *boxa = boxaCreate(...); ... [optionally fix with boxes] boxaaInitFull(baa, boxa); A typical use is to initialize the array with empty boxa, and to replace only a subset that must be aligned with something else, such as a pixa.
Input: boxaa index (location in boxaa to insert new boxa) boxa (new boxa to be inserted) Return: 0 if OK, 1 on error
Notes: (1) This shifts boxa[i] --> boxa[i + 1] for all i >= index, and then inserts boxa as boxa[index]. (2) To insert at the beginning of the array, set index = 0. (3) To append to the array, it's easier to use boxaaAddBoxa(). (4) This should not be used repeatedly to insert into large arrays, because the function is O(n).
Input: w, h (of pix that is being quadtree-ized) nlevels (in quadtree) Return: baa (for quadtree regions at each level), or null on error
Notes: (1) The returned boxaa has of boxa, each containing the set of rectangles at that level. The rectangle at level 0 is the entire region; at level 1 the region is divided into 4 rectangles, and at level n there are n^4 rectangles. (2) At each level, the rectangles in the boxa are in "raster" order, with LR (fast scan) and TB (slow scan).
Input: filename Return: boxaa, or null on error
LEPT_DLL BOXAA* boxaaReadStream | ( | FILE * | fp | ) |
Input: stream Return: boxaa, or null on error
LEPT_DLL l_int32 boxaaRemoveBoxa | ( | BOXAA * | baa, |
l_int32 | index | ||
) |
Input: boxaa index (of the boxa to be removed) Return: 0 if OK, 1 on error
Notes: (1) This removes boxa[index] and then shifts boxa[i] --> boxa[i - 1] for all i > index. (2) The removed boxaa is destroyed. (2) This should not be used repeatedly on large arrays, because the function is O(n).
Input: boxaa index (to the index-th boxa) boxa (insert and replace any existing one) Return: 0 if OK, 1 on error
Notes: (1) Any existing boxa is destroyed, and the input one is inserted in its place. (2) If the index is invalid, return 1 (error)
LEPT_DLL l_int32 boxaaWrite | ( | const char * | filename, |
BOXAA * | baa | ||
) |
Input: filename boxaa Return: 0 if OK, 1 on error
LEPT_DLL l_int32 boxaaWriteStream | ( | FILE * | fp, |
BOXAA * | baa | ||
) |
Input: stream boxaa Return: 0 if OK, 1 on error
Input: boxa sorttype (L_SORT_BY_X, L_SORT_BY_Y, L_SORT_BY_WIDTH, L_SORT_BY_HEIGHT, L_SORT_BY_PERIMETER) sortorder (L_SORT_INCREASING, L_SORT_DECREASING) &naindex (<optional return>=""> index of sorted order into original array) Return: boxad (sorted version of boxas), or null on error
Notes: (1) For a large number of boxes (say, greater than 1000), this O(n) binsort is much faster than the O(nlogn) shellsort. For 5000 components, this is over 20x faster than boxaSort(). (2) Consequently, boxaSort() calls this function if it will likely go much faster.
Input: boxa Return: 0 if OK, 1 on error
Notes: (1) This destroys all boxes in the boxa, setting the ptrs to null. The number of allocated boxes, n, is set to 0.
LEPT_DLL BOXA* boxaClipToBox | ( | BOXA * | boxas, |
BOX * | box | ||
) |
Input: boxas box (for clipping) Return boxad (boxa with boxes in boxas clipped to box), or null on error
Notes: (1) All boxes in boxa not intersecting with box are removed, and the remaining boxes are clipped to box.
LEPT_DLL BOXA* boxaCombineOverlaps | ( | BOXA * | boxas | ) |
Input: boxas Return: boxad (where each set of boxes in boxas that overlap are combined into a single bounding box in boxad), or null on error.
Notes: (1) If there are no overlapping boxes, it simply returns a copy of . (2) The alternative method of painting each rectanle and finding the 4-connected components gives the wrong result, because two non-overlapping rectangles, when rendered, can still be 4-connected, and hence they will be joined. (3) A bad case is to have n boxes, none of which overlap. Then you have one iteration with O(n^2) compares. This is still faster than painting each rectangle and finding the connected components, even for thousands of rectangles.
LEPT_DLL BOXA* boxaConstrainSize | ( | BOXA * | boxas, |
l_int32 | width, | ||
l_int32 | widthflag, | ||
l_int32 | height, | ||
l_int32 | heightflag | ||
) |
Input: boxas width (force width of all boxes to this size; input 0 to use the median width) widthflag (L_ADJUST_LEFT, L_ADJUST_RIGHT, or L_ADJUST_LEFT_AND_RIGHT) height (force height of all boxes to this size; input 0 to use the median height) heightflag (L_ADJUST_TOP, L_ADJUST_BOT, or L_ADJUST_TOP_AND_BOT) Return: boxad (adjusted so all boxes are the same size)
Notes: (1) Typical input might be the output of boxaLinearFit(), where each side has been fit. This alters the width and height to the given value, moving the sides either in or out. (2) All input boxes should be valid. Median values will be used with invalid boxes.
LEPT_DLL BOXA* boxaContainedInBox | ( | BOXA * | boxas, |
BOX * | box | ||
) |
Input: boxas box (for containment) Return: boxad (boxa with all boxes in boxas that are entirely contained in box), or null on error
Notes: (1) All boxes in boxa that are entirely outside box are removed.
LEPT_DLL PTA* boxaConvertToPta | ( | BOXA * | boxa, |
l_int32 | ncorners | ||
) |
Input: boxa ncorners (2 or 4 for the representation of each box) Return: pta (with 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.
Input: boxa copyflag (L_COPY, L_CLONE, L_COPY_CLONE) Return: new boxa, or null on error
Notes: (1) See pix.h for description of the copyflag. (2) The copy-clone makes a new boxa that holds clones of each box.
LEPT_DLL BOXA* boxaCreate | ( | l_int32 | n | ) |
Input: n (initial number of ptrs) Return: boxa, or null on error
LEPT_DLL void boxaDestroy | ( | BOXA ** | pboxa | ) |
Input: &boxa (<will be="" set="" to="" null="" before="" returning>="">) Return: void
Note:
LEPT_DLL BOX* boxAdjustSides | ( | BOX * | boxd, |
BOX * | boxs, | ||
l_int32 | delleft, | ||
l_int32 | delright, | ||
l_int32 | deltop, | ||
l_int32 | delbot | ||
) |
Input: boxd (<optional>; this can be null, equal to boxs, or different from boxs) boxs (starting box; to have sides adjusted) delleft, delright, deltop, delbot (changes in location of each side) Return: boxd, or null on error or if the computed boxd has width or height <= 0.
Notes: (1) Set boxd == NULL to get new box; boxd == boxs for in-place; or otherwise to resize existing boxd. (2) For usage, suggest one of these: boxd = boxAdjustSides(NULL, boxs, ...); // new boxAdjustSides(boxs, boxs, ...); // in-place boxAdjustSides(boxd, boxs, ...); // other (1) New box dimensions are cropped at left and top to x >= 0 and y >= 0. (2) For example, to expand in-place by 20 pixels on each side, use boxAdjustSides(box, box, -20, 20, -20, 20);
Input: boxa num (number put into each boxa in the baa) copyflag (L_COPY or L_CLONE) Return: boxaa, or null on error
Notes: (1) This puts boxes from the input into each of a set of boxa within an output boxaa. (2) This assumes that the boxes in are in sets of each.
LEPT_DLL l_int32 boxaEqual | ( | BOXA * | boxa1, |
BOXA * | boxa2, | ||
l_int32 | maxdist, | ||
NUMA ** | pnaindex, | ||
l_int32 * | psame | ||
) |
Input: boxa1 boxa2 maxdist &naindex (<optional return>=""> index array of correspondences &same (<return> 1 if equal; 0 otherwise) Return 0 if OK, 1 on error
Notes: (1) The two boxa are the "same" if they contain the same boxes and each box is within of its counterpart in their positions within the boxa. This allows for small rearrangements. Use 0 for maxdist if the boxa must be identical. (2) This applies only to geometry and ordering; refcounts are not considered. (3) allows some latitude in the ordering of the boxes. For the boxa to be the "same", corresponding boxes must be within of each other. Note that for large , we should use a hash function for efficiency. (4) naindex[i] gives the position of the box in boxa2 that corresponds to box i in boxa1. It is only returned if the boxa are equal.
LEPT_DLL l_int32 boxaExtendArray | ( | BOXA * | boxa | ) |
Input: boxa Return: 0 if OK; 1 on error
Notes: (1) Reallocs with doubled size of ptr array.
LEPT_DLL l_int32 boxaExtendArrayToSize | ( | BOXA * | boxa, |
l_int32 | size | ||
) |
Input: boxa size (new size of boxa array) Return: 0 if OK; 1 on error
Notes: (1) If necessary, reallocs new boxa ptr array to .
LEPT_DLL l_int32 boxaExtractAsNuma | ( | BOXA * | boxa, |
NUMA ** | pnax, | ||
NUMA ** | pnay, | ||
NUMA ** | pnaw, | ||
NUMA ** | pnah, | ||
l_int32 | keepinvalid | ||
) |
Input: boxa &nax (<optional return>=""> array of x locations) &nay (<optional return>=""> array of y locations) &naw (<optional return>=""> array of w locations) &nah (<optional return>=""> array of h locations) keepinvalid (1 to keep invalid boxes; 0 to remove them) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 boxaExtractAsPta | ( | BOXA * | boxa, |
PTA ** | pptal, | ||
PTA ** | pptat, | ||
PTA ** | pptar, | ||
PTA ** | pptab, | ||
l_int32 | keepinvalid | ||
) |
Input: boxa &ptal (<optional return>=""> array of left locations vs. index) &ptat (<optional return>=""> array of top locations vs. index) &ptar (<optional return>=""> array of right locations vs. index) &ptab (<optional return>=""> array of bottom locations vs. index) keepinvalid (1 to keep invalid boxes; 0 to remove them) Return: 0 if OK, 1 on error
LEPT_DLL NUMAA* boxaExtractSortedPattern | ( | BOXA * | boxa, |
NUMA * | na | ||
) |
Input: boxa (typ. of word bounding boxes, in textline order) numa (index of textline for each box in boxa) Return: naa (numaa, where each numa represents one textline), or null on error
Notes: (1) The input is expected to come from pixGetWordBoxesInTextlines(). (2) Each numa in the output consists of an average y coordinate of the first box in the textline, followed by pairs of x coordinates representing the left and right edges of each of the boxes in the textline.
Input: boxa index (to the index-th box) accessflag (L_COPY or L_CLONE) Return: box, or null on error
LEPT_DLL l_int32 boxaGetBoxGeometry | ( | BOXA * | boxa, |
l_int32 | index, | ||
l_int32 * | px, | ||
l_int32 * | py, | ||
l_int32 * | pw, | ||
l_int32 * | ph | ||
) |
Input: boxa index (to the index-th box) &x, &y, &w, &h (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 boxaGetCount | ( | BOXA * | boxa | ) |
Input: boxa Return: count (of all boxes); 0 if no boxes or on error
LEPT_DLL l_int32 boxaGetCoverage | ( | BOXA * | boxa, |
l_int32 | wc, | ||
l_int32 | hc, | ||
l_int32 | exactflag, | ||
l_float32 * | pfract | ||
) |
Input: boxa wc, hc (dimensions of overall clipping rectangle with UL corner at (0, 0) that is covered by the boxes. exactflag (1 for guaranteeing an exact result; 0 for getting an exact result only if the boxes do not overlap) &fract (<return> sum of box area as fraction of w * h) Return: 0 if OK, 1 on error
Notes: (1) The boxes in boxa are clipped to the input rectangle. (2) * When == 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 == 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.
Input: boxa &w (<optional return>=""> width) &h (<optional return>=""> height) &box (<optional return>="">, minimum box containing all boxes in boxa) Return: 0 if OK, 1 on error
Notes: (1) The returned w and h are the minimum size image that would contain all boxes untranslated. (2) If there are no 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.
LEPT_DLL BOX* boxaGetMedian | ( | BOXA * | boxa | ) |
Input: boxa Return: box (with median values for x, y, w, h), or null on error or if the boxa is empty.
Notes: (1) See boxaGetRankSize()
Input: boxa x, y (point) Return box (box with centroid closest to the given point [x,y]), or NULL if no boxes in boxa)
Notes: (1) Uses euclidean distance between centroid and point.
LEPT_DLL BOX* boxaGetRankSize | ( | BOXA * | boxa, |
l_float32 | fract | ||
) |
Input: boxa fract (use 0.0 for smallest, 1.0 for largest) Return: box (with rank values for x, y, w, h), or null on error or if the boxa is empty (has no valid boxes)
Notes: (1) This function does not assume that all boxes in the boxa are valid (2) The four box parameters are sorted independently. For rank order, the width and height are sorted in increasing order. But what does it mean to sort x and y in "rank order"? If the boxes are of comparable size and somewhat aligned (e.g., from multiple images), it makes some sense to give a "rank order" for x and y by sorting them in decreasing order. But in general, the interpretation of a rank order on x and y is highly application dependent. In summary:
Input: boxa index (to the index-th box) accessflag (L_COPY or L_CLONE) Return: box, or null if box is not valid or on error
Notes: (1) This returns NULL for an invalid box in a boxa. For a box to be valid, both the width and height must be > 0. (2) We allow invalid boxes, with w = 0 or h = 0, as placeholders in boxa for which the index of the box in the boxa is important. This is an atypical situation; usually you want to put only valid boxes in a boxa.
LEPT_DLL l_int32 boxaGetValidCount | ( | BOXA * | boxa | ) |
Input: boxa Return: count (of valid boxes); 0 if no valid boxes or on error
LEPT_DLL BOXA* boxaGetWhiteblocks | ( | BOXA * | boxas, |
BOX * | box, | ||
l_int32 | sortflag, | ||
l_int32 | maxboxes, | ||
l_float32 | maxoverlap, | ||
l_int32 | maxperim, | ||
l_float32 | fract, | ||
l_int32 | maxpops | ||
) |
Input: boxas (typically, a set of bounding boxes of fg components) box (initial region; typically including all boxes in boxas; if null, it computes the region to include all boxes in boxas) sortflag (L_SORT_BY_WIDTH, L_SORT_BY_HEIGHT, L_SORT_BY_MIN_DIMENSION, L_SORT_BY_MAX_DIMENSION, L_SORT_BY_PERIMETER, L_SORT_BY_AREA) maxboxes (maximum number of output whitespace boxes; e.g., 100) maxoverlap (maximum fractional overlap of a box by any of the larger boxes; e.g., 0.2) maxperim (maximum half-perimeter, in pixels, for which pivot is selected by proximity to box centroid; e.g., 200) fract (fraction of box diagonal that is an acceptable distance from the box centroid to select the pivot; e.g., 0.2) maxpops (maximum number of pops from the heap; use 0 as default) Return: boxa (of sorted whitespace boxes), or null on error
Notes: (1) This uses the elegant Breuel algorithm, found in "Two Geometric Algorithms for Layout Analysis", 2002, url: "citeseer.ist.psu.edu/breuel02two.html". It starts with the bounding boxes (b.b.) of the connected components (c.c.) in a region, along with the rectangle representing that region. It repeatedly divides the rectangle into four maximal rectangles that exclude a pivot rectangle, sorting them in a priority queue according to one of the six sort flags. It returns a boxa of the "largest" set that have no intersection with boxes from the input boxas. (2) If box == NULL, the initial region is the minimal region that includes the origin and every box in boxas. (3) maxboxes is the maximum number of whitespace boxes that will be returned. The actual number will depend on the image and the values chosen for maxoverlap and maxpops. In many cases, the actual number will be 'maxboxes'. (4) maxoverlap allows pruning of whitespace boxes depending on the overlap. To avoid all pruning, use maxoverlap = 1.0. To select only boxes that have no overlap with each other (maximal pruning), choose maxoverlap = 0.0. Otherwise, no box can have more than the 'maxoverlap' fraction of its area overlapped by any larger (in the sense of the sortflag) box. (5) Choose maxperim (actually, maximum half-perimeter) to represent a c.c. that is small enough so that you don't care about the white space that could be inside of it. For all such c.c., the pivot for 'quadfurcation' of a rectangle is selected as having a reasonable proximity to the rectangle centroid. (6) Use fract in the range [0.0 ... 1.0]. Set fract = 0.0 to choose the small box nearest the centroid as the pivot. If you choose fract > 0.0, it is suggested that you call boxaPermuteRandom() first, to permute the boxes (see usage below). This should reduce the search time for each of the pivot boxes. (7) Choose maxpops to be the maximum number of rectangles that are popped from the heap. This is an indirect way to limit the execution time. Use 0 for default (a fairly large number). At any time, you can expect the heap to contain about 2.5 times as many boxes as have been popped off. (8) The output result is a sorted set of overlapping boxes, constrained by 'maxboxes', 'maxoverlap' and 'maxpops'. (9) The main defect of the method is that it abstracts out the actual components, retaining only the b.b. for analysis. Consider a component with a large b.b. If this is chosen as a pivot, all white space inside is immediately taken out of consideration. Furthermore, even if it is never chosen as a pivot, as the partitioning continues, at no time will any of the whitespace inside this component be part of a rectangle with zero overlapping boxes. Thus, the interiors of all boxes are necessarily excluded from the union of the returned whitespace boxes. (10) USAGE: One way to accommodate to this weakness is to remove such large b.b. before starting the computation. For example, if 'box' is an input image region containing 'boxa' b.b. of c.c.:
// Faster pivot choosing boxaPermuteRandom(boxa, boxa);
// Remove anything either large width or height boxat = boxaSelectBySize(boxa, maxwidth, maxheight, L_SELECT_IF_BOTH, L_SELECT_IF_LT, NULL);
boxad = boxaGetWhiteblocks(boxat, box, type, maxboxes, maxoverlap, maxperim, fract, maxpops);
The result will be rectangular regions of "white space" that extend into (and often through) the excluded components. (11) As a simple example, suppose you wish to find the columns on a page. First exclude large c.c. that may block the columns, and then call:
boxad = boxaGetWhiteblocks(boxa, box, L_SORT_BY_HEIGHT, 20, 0.15, 200, 0.2, 2000);
to get the 20 tallest boxes with no more than 0.15 overlap between a box and any of the taller ones, and avoiding the use of any c.c. with a b.b. half perimeter greater than 200 as a pivot.
LEPT_DLL l_int32 boxaInitFull | ( | BOXA * | boxa, |
BOX * | box | ||
) |
Input: boxa (typically empty) box (to be replicated into the entire ptr array) Return: 0 if OK, 1 on error
Notes: (1) This initializes a boxa by filling up the entire box ptr array with copies of . Any existing boxes are destroyed. After this oepration, the number of boxes is equal to the number of allocated ptrs. (2) Note that we use boxaReplaceBox() instead of boxaInsertBox(). They both have the same effect when inserting into a NULL ptr in the boxa ptr array: (3) Example usage. This function is useful to prepare for a random insertion (or replacement) of boxes into a boxa. To randomly insert boxes into a boxa, up to some index "max": Boxa *boxa = boxaCreate(max); Box *box = boxCreate(...); boxaInitFull(boxa, box); If we have an existing boxa with a smaller ptr array, it can be reused: boxaExtendArrayToSize(boxa, max); Box *box = boxCreate(...); boxaInitFull(boxa, box); The initialization allows the boxa to always be properly filled, even if all the boxes are not later replaced. If you want to know which boxes have been replaced, you can initialize the array with invalid boxes that have w = 0 and/or h = 0. Then boxaGetValidBox() will return NULL for the invalid boxes.
Input: boxa index (location in boxa to insert new value) box (new box to be inserted) Return: 0 if OK, 1 on error
Notes: (1) This shifts box[i] --> box[i + 1] for all i >= index, and then inserts box as box[index]. (2) To insert at the beginning of the array, set index = 0. (3) To append to the array, it's easier to use boxaAddBox(). (4) This should not be used repeatedly to insert into large arrays, because the function is O(n).
LEPT_DLL BOXA* boxaIntersectsBox | ( | BOXA * | boxas, |
BOX * | box | ||
) |
Input: boxas box (for intersecting) Return boxad (boxa with all boxes in boxas that intersect box), or null on error
Notes: (1) All boxes in boxa that intersect with box (i.e., are completely or partially contained in box) are retained.
Input: boxad (dest boxa; add to this one) boxas (source boxa; add from this one) istart (starting index in nas) iend (ending index in nas; use 0 to cat all) Return: 0 if OK, 1 on error
Notes: (1) This appends a clone of each indicated box in boxas to boxad (2) istart < 0 is taken to mean 'read from the start' (istart = 0) (3) iend <= 0 means 'read to the end'
Input: boxas (source boxa) factor (reject outliers with error greater than this number of median errors; typically ~3) max_error (maximum difference in pixels between fitted and original location to allow using the original value instead of the fitted value) debug (1 for debug output) Return: boxad (fitted boxa), or null on error
Notes: (1) Suppose you have a boxa where the box edges are expected to vary slowly and linearly across the set. These could be, for example, noisy measurements of similar regions on successive scanned pages. (2) Method: there are 2 basic steps: (a) Find outliers, separately based on the deviation from the median of the width and height of the box. After the width- and height-based outliers are removed, do a linear LSF for each of the four sides. Use to specify tolerance to outliers; use a very large value of to avoid rejecting points. (b) Using the LSF of (a), make the final determination of the four edge locations. See (3) for details. (3) The parameter makes the input values somewhat sticky. Use the fitted values only when the difference between input and fitted value is greater than . Two special cases: (a) set == 0 to use only fitted values in boxad. (b) set == 10000 to ignore all fitted values; then boxad will be the same as boxas. (4) Invalid input boxes are not used in computation of the LSF, and the output boxes are found from the LSF. (5) To enforce additional constraints on the size of each box, follow this operation with boxaConstrainSize(), taking boxad as input.
LEPT_DLL l_int32 boxaLocationRange | ( | BOXA * | boxa, |
l_int32 * | pminx, | ||
l_int32 * | pminy, | ||
l_int32 * | pmaxx, | ||
l_int32 * | pmaxy | ||
) |
Input: boxa &minx, &miny, &maxx, &maxy (<optional return>=""> range of UL corner positions) Return: 0 if OK, 1 on error
LEPT_DLL NUMA* boxaMakeSizeIndicator | ( | BOXA * | boxa, |
l_int32 | width, | ||
l_int32 | height, | ||
l_int32 | type, | ||
l_int32 | relation | ||
) |
Input: boxa width, height (threshold dimensions) type (L_SELECT_WIDTH, L_SELECT_HEIGHT, L_SELECT_IF_EITHER, L_SELECT_IF_BOTH) relation (L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE) Return: 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.
LEPT_DLL BOXA* boxaMergeEvenOdd | ( | BOXA * | boxae, |
BOXA * | boxao | ||
) |
Input: boxae (boxes to go in even positions in merged boxa) boxao (boxes to go in odd positions in merged boxa) Return: boxad (merged), or null on error
Notes: (1) Boxes are alternatingly selected from boxae and boxao. Both boxae and boxao are of the same size.
LEPT_DLL BOXA* boxaPermutePseudorandom | ( | BOXA * | boxas | ) |
Input: boxas (input boxa) Return: 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().
LEPT_DLL BOXA* boxaPermuteRandom | ( | BOXA * | boxad, |
BOXA * | boxas | ||
) |
Input: boxad (<optional> can be null or equal to boxas) boxas (input boxa) Return: 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) 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. (3) MSVC rand() has MAX_RAND = 2^15 - 1, so it will not do a proper permutation is the number of boxes exceeds this.
LEPT_DLL l_int32 boxaPlotSides | ( | BOXA * | boxa, |
const char * | plotname, | ||
NUMA ** | pnal, | ||
NUMA ** | pnat, | ||
NUMA ** | pnar, | ||
NUMA ** | pnab, | ||
l_int32 | outformat | ||
) |
Input: boxas (source boxa) plotname (<optional>, can be NULL) &nal (<optional return>=""> na of left sides) &nat (<optional return>=""> na of top sides) &nar (<optional return>=""> na of right sides) &nab (<optional return>=""> na of bottom sides) outformat (GPLOT_NONE for no output; GPLOT_PNG for png, etc) ut Return: 0 if OK, 1 on error
Notes: (1) This is a debugging function to show the progression of the four sides in the boxes. There must be at least 2 boxes. (2) One of three conditions holds: (a) only the even indices have valid boxes (b) only the odd indices have valid boxes (c) all indices have valid boxes This condition is determined by looking at the first 2 boxes. (3) The plotfiles are put in /tmp, and are named either with or, if NULL, a default name.
LEPT_DLL BOXA* boxaPruneSortedOnOverlap | ( | BOXA * | boxas, |
l_float32 | maxoverlap | ||
) |
Input: boxas (sorted by size in decreasing order) maxoverlap (maximum fractional overlap of a box by any of the larger boxes) Return: boxad (pruned), or null on error
Notes: (1) This selectively removes smaller boxes when they are overlapped by any larger box by more than the input 'maxoverlap' fraction. (2) To avoid all pruning, use maxoverlap = 1.0. To select only boxes that have no overlap with each other (maximal pruning), set maxoverlap = 0.0. (3) If there are no boxes in boxas, returns an empty boxa.
Input: filename Return: boxa, or null on error
LEPT_DLL BOXA* boxaReadStream | ( | FILE * | fp | ) |
Input: stream Return: boxa, or null on error
LEPT_DLL l_int32 boxaRemoveBox | ( | BOXA * | boxa, |
l_int32 | index | ||
) |
Input: boxa index (of box to be removed) Return: 0 if OK, 1 on error
Notes: (1) This removes box[index] and then shifts box[i] --> box[i - 1] for all i > index. (2) It should not be used repeatedly to remove boxes from large arrays, because the function is O(n).
Input: boxa index (to the index-th box) box (insert to replace existing one) Return: 0 if OK, 1 on error
Notes: (1) In-place replacement of one box. (2) The previous box at that location, if any, is destroyed.
Input: boxas (xc, yc) (location of center of rotation) angle (rotation in radians; clockwise is positive) Return: boxad (scaled boxas), or null on error
Notes; (1) See createMatrix2dRotate() for details of transform.
Input: boxa w, h (of image in which the boxa is embedded) rotation (0 = noop, 1 = 90 deg, 2 = 180 deg, 3 = 270 deg; all rotations are clockwise) Return: boxad, or null on error
Notes: (1) See boxRotateOrth() for details.
Input: boxas scalex (horizontal scale factor) scaley (vertical scale factor) Return: boxad (scaled boxas), or null on error
Notes; (1) See createMatrix2dScale() for details of transform.
LEPT_DLL BOXA* boxaSelectBySize | ( | BOXA * | boxas, |
l_int32 | width, | ||
l_int32 | height, | ||
l_int32 | type, | ||
l_int32 | relation, | ||
l_int32 * | pchanged | ||
) |
Input: boxas width, height (threshold dimensions) type (L_SELECT_WIDTH, L_SELECT_HEIGHT, L_SELECT_IF_EITHER, L_SELECT_IF_BOTH) relation (L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE) &changed (<optional return>=""> 1 if changed; 0 if clone returned) Return: 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 clones 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.
Input: boxas na (indicator numa) &changed (<optional return>=""> 1 if changed; 0 if clone returned) Return: boxad, or null on error
Notes: (1) Returns a boxa clone if no components are removed. (2) Uses box clones in the new boxa. (3) The indicator numa has values 0 (ignore) and 1 (accept).
LEPT_DLL l_int32 boxaSizeRange | ( | BOXA * | boxa, |
l_int32 * | pminw, | ||
l_int32 * | pminh, | ||
l_int32 * | pmaxw, | ||
l_int32 * | pmaxh | ||
) |
Input: boxa &minw, &minh, &maxw, &maxh (<optional return>=""> range of dimensions of box in the array) Return: 0 if OK, 1 on error
LEPT_DLL BOXA* boxaSmoothSequence | ( | BOXA * | boxas, |
l_float32 | factor, | ||
l_int32 | max_error, | ||
l_int32 | debug | ||
) |
Input: boxas (source boxa) factor (reject outliers with error greater than this number of median errors; typically ~3) max_error (maximum difference in pixels between fitted and original location to allow using the original value instead of the fitted value) debug (1 for debug output) Return: boxad (fitted boxa), or null on error
Notes: (1) This does linear fitting separately to the sequences of even and odd boxes. It is assumed that in both the even and odd sets, the box edges vary slowly and linearly across each set.
Input: boxa sorttype (L_SORT_BY_X, L_SORT_BY_Y, L_SORT_BY_WIDTH, L_SORT_BY_HEIGHT, L_SORT_BY_MIN_DIMENSION, L_SORT_BY_MAX_DIMENSION, L_SORT_BY_PERIMETER, L_SORT_BY_AREA, L_SORT_BY_ASPECT_RATIO) sortorder (L_SORT_INCREASING, L_SORT_DECREASING) &naindex (<optional return>=""> index of sorted order into original array) Return: boxad (sorted version of boxas), or null on error
LEPT_DLL BOXAA* boxaSort2d | ( | BOXA * | boxas, |
NUMAA ** | pnaad, | ||
l_int32 | delta1, | ||
l_int32 | delta2, | ||
l_int32 | minh1 | ||
) |
Input: boxas &naa (<optional return>=""> numaa with sorted indices whose values are the indices of the input array) delta1 (min overlap that permits aggregation of a box onto a boxa of horizontally-aligned boxes; pass 1) delta2 (min overlap that permits aggregation of a box onto a boxa of horizontally-aligned boxes; pass 2) minh1 (components less than this height either join an existing boxa or are set aside for pass 2) Return: boxaa (2d sorted version of boxa), or null on error
Notes: (1) The final result is a sort where the 'fast scan' direction is left to right, and the 'slow scan' direction is from top to bottom. Each boxa in the boxaa represents a sorted set of boxes from left to right. (2) Two passes are used to aggregate the boxas, which can corresond to characters or words in a line of text. In pass 1, only taller components, which correspond to xheight or larger, are permitted to start a new boxa, whereas in pass 2, the remaining vertically-challenged components are allowed to join an existing boxa or start a new one. (3) If delta1 < 0, the first pass allows aggregation when boxes in the same boxa do not overlap vertically. The distance by which they can miss and still be aggregated is the absolute value |delta1|. Similar for delta2 on the second pass. (4) On the first pass, any component of height less than minh1 cannot start a new boxa; it's put aside for later insertion. (5) On the second pass, any small component that doesn't align with an existing boxa can start a new one. (6) This can be used to identify lines of text from character or word bounding boxes.
LEPT_DLL BOXAA* boxaSort2dByIndex | ( | BOXA * | boxas, |
NUMAA * | naa | ||
) |
Input: boxas naa (numaa that maps from the new baa to the input boxa) Return: baa (sorted boxaa), or null on error
LEPT_DLL BOXA* boxaSortByIndex | ( | BOXA * | boxas, |
NUMA * | naindex | ||
) |
Input: boxas naindex (na that maps from the new boxa to the input boxa) Return: boxad (sorted), or null on error
Input: boxa &boxae, &boxao (<return> save even and odd boxes in their separate boxa, setting the other type to invalid boxes.) Return: 0 if OK, 1 on error
Notes: (1) For example, boxae copies of the even boxes, in their original location, that are in boxa. Invalid boxes are placed in the odd array locations.
Input: boxa i, j (two indices of boxes, that are to be swapped) Return: 0 if OK, 1 on error
LEPT_DLL BOXA* boxaTransform | ( | BOXA * | boxas, |
l_int32 | shiftx, | ||
l_int32 | shifty, | ||
l_float32 | scalex, | ||
l_float32 | scaley | ||
) |
Input: boxa shiftx, shifty scalex, scaley Return: boxad, or null on error
Notes: (1) This is a very simple function that first shifts, then scales.
LEPT_DLL BOXA* boxaTransformOrdered | ( | BOXA * | boxas, |
l_int32 | shiftx, | ||
l_int32 | shifty, | ||
l_float32 | scalex, | ||
l_float32 | scaley, | ||
l_int32 | xcen, | ||
l_int32 | ycen, | ||
l_float32 | angle, | ||
l_int32 | order | ||
) |
Input: boxa shiftx, shifty scalex, scaley xcen, ycen (center of rotation) angle (in radians; clockwise is positive) order (one of 6 combinations: L_TR_SC_RO, ...) Return: boxd, or null on error
Notes: (1) This allows a sequence of linear transforms on each box. the transforms are from the affine set, composed of shift, scaling and rotation, and the order of the transforms is specified. (2) Although these operations appear to be on an infinite 2D plane, in practice the region of interest is clipped to a finite image. The center of rotation is usually taken with respect to the image (either the UL corner or the center). A translation can have two very different effects: (a) Moves the boxes across the fixed image region. (b) Moves the image origin, causing a change in the image region and an opposite effective translation of the boxes. This function should only be used for (a), where the image region is fixed on translation. If the image region is changed by the translation, use instead the functions in affinecompose.c, where the image region and rotation center can be computed from the actual clipping due to translation of the image origin. (3) See boxTransformOrdered() for usage and implementation details.
Input: boxas transx (x component of translation wrt. the origin) transy (y component of translation wrt. the origin) Return: boxad (translated boxas), or null on error
Notes; (1) See createMatrix2dTranslate() for details of transform.
Input: filename boxa Return: 0 if OK, 1 on error
LEPT_DLL l_int32 boxaWriteStream | ( | FILE * | fp, |
BOXA * | boxa | ||
) |
Input: stream boxa Return: 0 if OK, 1 on error
LEPT_DLL BOX* boxBoundingRegion | ( | BOX * | box1, |
BOX * | box2 | ||
) |
Input: box1, box2 (two boxes) Return: box (of bounding region containing the input boxes), or null on error
LEPT_DLL l_int32 boxChangeRefcount | ( | BOX * | box, |
l_int32 | delta | ||
) |
Input: box wi, hi (rectangle representing image) Return: part of box within given rectangle, or NULL on error or if box is entirely outside the rectangle
Notes: (1) This can be used to clip a rectangle to an image. The clipping rectangle is assumed to have a UL corner at (0, 0), and a LR corner at (wi - 1, hi - 1).
Input: box Return: ptr to same box, or null on error
Input: box1, box2 &result (<return> 1 if box2 is entirely contained within box1, and 0 otherwise) Return: 0 if OK, 1 on error
Input: box x, y (a point) &contains (<return> 1 if box contains point; 0 otherwise) Return: 0 if OK, 1 on error.
Input: x, y, w, h Return: box, or null on error
Notes: (1) This clips the box to the +quad. If no part of the box is in the +quad, this returns NULL. (2) We allow you to make a box with w = 0 and/or h = 0. This does not represent a valid region, but it is useful as a placeholder in a boxa for which the index of the box in the boxa is important. This is an atypical situation; usually you want to put only valid boxes with nonzero width and height in a boxa. If you have a boxa with invalid boxes, the accessor boxaGetValidBox() will return NULL on each invalid box. (3) If you want to create only valid boxes, use boxCreateValid(), which returns NULL if either w or h is 0.
Input: x, y, w, h Return: box, or null on error
Notes: (1) This returns NULL if either w = 0 or h = 0.
LEPT_DLL void boxDestroy | ( | BOX ** | pbox | ) |
Input: &box (<will be="" set="" to="" null="" before="" returning>="">) Return: void
Notes: (1) Decrements the ref count and, if 0, destroys the box. (2) Always nulls the input ptr.
Input: box1 box2 &same (<return> 1 if equal; 0 otherwise) Return 0 if OK, 1 on error
Input: box &cx, &cy (<return> location of center of box) Return 0 if OK, 1 on error
LEPT_DLL l_int32 boxGetGeometry | ( | BOX * | box, |
l_int32 * | px, | ||
l_int32 * | py, | ||
l_int32 * | pw, | ||
l_int32 * | ph | ||
) |
Input: box &x, &y, &w, &h (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 boxGetRefcount | ( | BOX * | box | ) |
LEPT_DLL l_int32 boxIntersectByLine | ( | BOX * | box, |
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 | slope, | ||
l_int32 * | px1, | ||
l_int32 * | py1, | ||
l_int32 * | px2, | ||
l_int32 * | py2, | ||
l_int32 * | pn | ||
) |
Input: box x, y (point that line goes through) slope (of line) (&x1, &y1) (<return> 1st point of intersection with box) (&x2, &y2) (<return> 2nd point of intersection with box) &n (<return> number of points of intersection) Return: 0 if OK, 1 on error
Notes: (1) If the intersection is at only one point (a corner), the coordinates are returned in (x1, y1). (2) Represent a vertical line by one with a large but finite slope.
Input: box1, box2 &result (<return> 1 if any part of box2 is contained in box1, and 0 otherwise) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 boxIsValid | ( | BOX * | box, |
l_int32 * | pvalid | ||
) |
Input: box &valid (<return> 1 if valid; 0 otherwise) Return: 0 if OK, 1 on error
Input: box1, box2 (two boxes) &fract (<return> the fraction of box2 overlapped by box1) Return: 0 if OK, 1 on error.
Notes: (1) The result depends on the order of the input boxes, because the overlap is taken as a fraction of box2.
LEPT_DLL BOX* boxOverlapRegion | ( | BOX * | box1, |
BOX * | box2 | ||
) |
Input: box1, box2 (two boxes) Return: box (of overlap region between input boxes), or null if no overlap or on error
LEPT_DLL l_int32 boxPrintStreamInfo | ( | FILE * | fp, |
BOX * | box | ||
) |
Input: stream box Return: 0 if OK, 1 on error
Notes: (1) This outputs information about the box, for debugging. (2) Use serialization functions to write to file if you want to read the data back.
Input: boxd (<optional>; this can be null, equal to boxs, or different from boxs); boxs (starting box; to have one side relocated) loc (new location of the side that is changing) sideflag (L_FROM_LEFT, etc., indicating the side that moves) Return: boxd, or null on error or if the computed boxd has width or height <= 0.
Notes: (1) Set boxd == NULL to get new box; boxd == boxs for in-place; or otherwise to resize existing boxd. (2) For usage, suggest one of these: boxd = boxRelocateOneSide(NULL, boxs, ...); // new boxRelocateOneSide(boxs, boxs, ...); // in-place boxRelocateOneSide(boxd, boxs, ...); // other
Input: box w, h (of image in which the box is embedded) rotation (0 = noop, 1 = 90 deg, 2 = 180 deg, 3 = 270 deg; all rotations are clockwise) Return: boxd, or null on error
Notes: (1) Rotate the image with the embedded box by the specified amount. (2) After rotation, the rotated box is always measured with respect to the UL corner of the image.
Input: box x, y, w, h (use -1 to leave unchanged) Return: 0 if OK, 1 on error
LEPT_DLL BOX* boxTransform | ( | BOX * | box, |
l_int32 | shiftx, | ||
l_int32 | shifty, | ||
l_float32 | scalex, | ||
l_float32 | scaley | ||
) |
Input: box shiftx, shifty scalex, scaley Return: boxd, or null on error
Notes: (1) This is a very simple function that first shifts, then scales. (2) If the box is invalid, a new invalid box is returned.
LEPT_DLL BOX* boxTransformOrdered | ( | BOX * | boxs, |
l_int32 | shiftx, | ||
l_int32 | shifty, | ||
l_float32 | scalex, | ||
l_float32 | scaley, | ||
l_int32 | xcen, | ||
l_int32 | ycen, | ||
l_float32 | angle, | ||
l_int32 | order | ||
) |
Input: boxs shiftx, shifty scalex, scaley xcen, ycen (center of rotation) angle (in radians; clockwise is positive) order (one of 6 combinations: L_TR_SC_RO, ...) Return: boxd, or null on error
Notes: (1) This allows a sequence of linear transforms, composed of shift, scaling and rotation, where the order of the transforms is specified. (2) The rotation is taken about a point specified by (xcen, ycen). Let the components of the vector from the center of rotation to the box center be (xdif, ydif): xdif = (bx + 0.5 * bw) - xcen ydif = (by + 0.5 * bh) - ycen Then the box center after rotation has new components: bxcen = xcen + xdif * cosa + ydif * sina bycen = ycen + ydif * cosa - xdif * sina where cosa and sina are the cos and sin of the angle, and the enclosing box for the rotated box has size: rw = |bw * cosa| + |bh * sina| rh = |bh * cosa| + |bw * sina| where bw and bh are the unrotated width and height. Then the box UL corner (rx, ry) is rx = bxcen - 0.5 * rw ry = bycen - 0.5 * rh (3) The center of rotation specified by args and is the point BEFORE any translation or scaling. If the rotation is not the first operation, this function finds the actual center at the time of rotation. It does this by making the following assumptions: (1) Any scaling is with respect to the UL corner, so that the center location scales accordingly. (2) A translation does not affect the center of the image; it just moves the boxes. We always use assumption (1). However, assumption (2) will be incorrect if the apparent translation is due to a clipping operation that, in effect, moves the origin of the image. In that case, you should NOT use these simple functions. Instead, use the functions in affinecompose.c, where the rotation center can be computed from the actual clipping due to translation of the image origin.
LEPT_DLL l_int32 ccbaAddCcb | ( | CCBORDA * | ccba, |
CCBORD * | ccb | ||
) |
Input: ccba ccb (to be added by insertion) Return: 0 if OK; 1 on error
LEPT_DLL CCBORDA* ccbaCreate | ( | PIX * | pixs, |
l_int32 | n | ||
) |
Input: pixs (binary image; can be null) n (initial number of ptrs) Return: ccba, or null on error
LEPT_DLL void ccbaDestroy | ( | CCBORDA ** | pccba | ) |
Input: &ccba (<to be="" nulled>="">) Return: void
LEPT_DLL PIX* ccbaDisplayBorder | ( | CCBORDA * | ccba | ) |
Input: ccba Return: pix of border pixels, or null on error
Notes: (1) Uses global ptaa, which gives each border pixel in global coordinates, and must be computed in advance by calling ccbaGenerateGlobalLocs().
LEPT_DLL PIX* ccbaDisplayImage1 | ( | CCBORDA * | ccba | ) |
Input: ccborda Return: pix of image, or null on error
Notes: (1) Uses local ptaa, which gives each border pixel in local coordinates, so the actual pixel positions must be computed using all offsets. (2) For the holes, use coordinates relative to the c.c. (3) This is slower than Method 2. (4) This uses topological properties (Method 1) to do scan conversion to raster
This algorithm deserves some commentary.
I first tried the following:
x x x x x x x x x x x x x x x o x x x x x x x x x
if you 4-fill from the outside, the pixel 'o' will not be filled! XORing with the border leaves it OFF. Inverting then gives a single bad ON pixel that is not actually part of the hole.
So what you must do instead is 4-fill the holes from inside. You can do this from a seedfill, using a pix with the hole border as the filling mask. But you need to start with a pixel inside the hole. How is this determined? The best way is from the contour. We have a right-hand shoulder rule for inside (i.e., the filled region). Take the first 2 pixels of the hole border, and compute dx and dy (second coord minus first coord: dx = sx - fx, dy = sy - fy). There are 8 possibilities, depending on the values of dx and dy (which can each be -1, 0, and +1, but not both 0). These 8 cases can be broken into 4; see the simple algorithm below. Once you have an interior seed pixel, you fill from the seed, clipping with the hole border pix by filling into its invert.
You then successively XOR these interior filled components, in any order.
LEPT_DLL PIX* ccbaDisplayImage2 | ( | CCBORDA * | ccba | ) |
Input: ccborda Return: pix of image, or null on error
Notes: (1) Uses local chain ptaa, which gives each border pixel in local coordinates, so the actual pixel positions must be computed using all offsets. (2) Treats exterior and hole borders on equivalent footing, and does all calculations on a pix that spans the c.c. with a 1 pixel added boundary. (3) This uses topological properties (Method 2) to do scan conversion to raster (4) The algorithm is described at the top of this file (Method 2). It is preferred to Method 1 because it is between 1.2x and 2x faster than Method 1.
LEPT_DLL PIX* ccbaDisplaySPBorder | ( | CCBORDA * | ccba | ) |
Input: ccba Return: pix of border pixels, or null on error
Notes: (1) Uses spglobal pta, which gives each border pixel in global coordinates, one path per c.c., and must be computed in advance by calling ccbaGenerateSPGlobalLocs().
LEPT_DLL l_int32 ccbaExtendArray | ( | CCBORDA * | ccba | ) |
Input: ccba Return: 0 if OK; 1 on error
LEPT_DLL l_int32 ccbaGenerateGlobalLocs | ( | CCBORDA * | ccba | ) |
Input: ccba (with local chain ptaa of borders computed) Return: 0 if OK, 1 on error
Action: this uses the pixel locs in the local ptaa, which are all relative to each c.c., to find the global pixel locations, and stores them in the global ptaa.
LEPT_DLL l_int32 ccbaGenerateSinglePath | ( | CCBORDA * | ccba | ) |
Input: ccba Return: 0 if OK, 1 on error
Notes: (1) Generates a single border in local pixel coordinates. For each c.c., if there is just an outer border, copy it. If there are also hole borders, for each hole border, determine the smallest horizontal or vertical distance from the border to the outside of the c.c., and find a path through the c.c. for this cut. We do this in a way that guarantees a pixel from the hole border is the starting point of the path, and we must verify that the path intersects the outer border (if it intersects it, then it ends on it). One can imagine pathological cases, but they may not occur in images of text characters and un-textured line graphics. (2) Once it is verified that the path through the c.c. intersects both the hole and outer borders, we generate the full single path for all borders in the c.c. Starting at the start point on the outer border, when we hit a line on a cut, we take the cut, do the hold border, and return on the cut to the outer border. We compose a pta of the outer border pts that are on cut paths, and for every point on the outer border (as we go around), we check against this pta. When we find a matching point in the pta, we do its cut path and hole border. The single path is saved in the ccb.
LEPT_DLL l_int32 ccbaGenerateSPGlobalLocs | ( | CCBORDA * | ccba, |
l_int32 | ptsflag | ||
) |
Input: ccba ptsflag (CCB_SAVE_ALL_PTS or CCB_SAVE_TURNING_PTS) Return: 0 if OK, 1 on error
Notes: (1) This calculates the splocal rep if not yet made. (2) It uses the local pixel values in splocal, the single path pta, which are all relative to each c.c., to find the corresponding global pixel locations, and stores them in the spglobal pta. (3) This lists only the turning points: it both makes a valid svg file and is typically about half the size when all border points are listed.
LEPT_DLL l_int32 ccbaGenerateStepChains | ( | CCBORDA * | ccba | ) |
Input: ccba (with local chain ptaa of borders computed) Return: 0 if OK, 1 on error
Notes: (1) This uses the pixel locs in the local ptaa, which are all relative to each c.c., to find the step directions for successive pixels in the chain, and stores them in the step numaa. (2) To get the step direction, use 1 2 3 0 P 4 7 6 5 where P is the previous pixel at (px, py). The step direction is the number (from 0 through 7) for each relative location of the current pixel at (cx, cy). It is easily found by indexing into a 2-d 3x3 array (dirtab).
LEPT_DLL CCBORD* ccbaGetCcb | ( | CCBORDA * | ccba, |
l_int32 | index | ||
) |
Input: ccba Return: ccb, or null on error
LEPT_DLL l_int32 ccbaGetCount | ( | CCBORDA * | ccba | ) |
Input: ccba Return: count, with 0 on error
Input: filename Return: ccba, or null on error
LEPT_DLL CCBORDA* ccbaReadStream | ( | FILE * | fp | ) |
Input: stream Return: ccba, or null on error
Format: ccba: %7d cc
(num. c.c.) (ascii) (17B) pix width (4B) pix height (4B) [for i = 1, ncc] ulx (4B) uly (4B) w (4B) -- not req'd for reconstruction h (4B) -- not req'd for reconstruction number of borders (4B) [for j = 1, nb] startx (4B) starty (4B) [for k = 1, nb] 2 steps (1B) end in z8 or 88 (1B)
LEPT_DLL l_int32 ccbaStepChainsToPixCoords | ( | CCBORDA * | ccba, |
l_int32 | coordtype | ||
) |
Input: ccba (with step chains numaa of borders) coordtype (CCB_GLOBAL_COORDS or CCB_LOCAL_COORDS) Return: 0 if OK, 1 on error
Notes: (1) This uses the step chain data in each ccb to determine the pixel locations, either global or local, and stores them in the appropriate ptaa, either global or local. For the latter, the pixel locations are relative to the c.c.
Input: filename ccba Return: 0 if OK, 1 on error
LEPT_DLL l_int32 ccbaWriteStream | ( | FILE * | fp, |
CCBORDA * | ccba | ||
) |
Input: stream ccba Return: 0 if OK; 1 on error
Format: ccba: %7d cc
(num. c.c.) (ascii) (18B) pix width (4B) pix height (4B) [for i = 1, ncc] ulx (4B) uly (4B) w (4B) -- not req'd for reconstruction h (4B) -- not req'd for reconstruction number of borders (4B) [for j = 1, nb] startx (4B) starty (4B) [for k = 1, nb] 2 steps (1B) end in z8 or 88 (1B)
LEPT_DLL l_int32 ccbaWriteSVG | ( | const char * | filename, |
CCBORDA * | ccba | ||
) |
Input: filename ccba Return: 0 if OK, 1 on error
LEPT_DLL char* ccbaWriteSVGString | ( | const char * | filename, |
CCBORDA * | ccba | ||
) |
Input: filename ccba Return: string in svg-formatted, that can be written to file, or null on error.
Input: pixs (<optional>) Return: ccb or null on error
LEPT_DLL void ccbDestroy | ( | CCBORD ** | pccb | ) |
Input: &ccb (<to be="" nulled>="">) Return: void
Input: rval, gval, bval &rgbpixel (<return> 32-bit pixel) Return: 0 if OK; 1 on error
Notes: (1) A slower implementation uses macros: SET_DATA_BYTE(ppixel, COLOR_RED, rval); SET_DATA_BYTE(ppixel, COLOR_GREEN, gval); SET_DATA_BYTE(ppixel, COLOR_BLUE, bval);
LEPT_DLL void compressed_dataDestroy | ( | L_COMPRESSED_DATA ** | pcid | ) |
Input: &cid (<will be="" set="" to="" null="" before="" returning>="">) Return: void
LEPT_DLL l_int32 concatenatePdf | ( | const char * | dirname, |
const char * | substr, | ||
const char * | fileout | ||
) |
Input: directory name (containing single-page pdf files) substr (<optional> substring filter on filenames; can be NULL) fileout (concatenated pdf file) Return: 0 if OK, 1 on error
Notes: (1) This only works with leptonica-formatted single-page pdf files. (2) If is not NULL, only filenames that contain the substring can be returned. If == NULL, none of the filenames are filtered out. (3) The files in the directory, after optional filtering by the substring, are lexically sorted in increasing order before concatenation.
LEPT_DLL l_int32 concatenatePdfToData | ( | const char * | dirname, |
const char * | substr, | ||
l_uint8 ** | pdata, | ||
size_t * | pnbytes | ||
) |
Input: directory name (containing single-page pdf files) substr (<optional> substring filter on filenames; can be NULL) &data (<return> concatenated pdf data in memory) &nbytes (<return> number of bytes in pdf data) Return: 0 if OK, 1 on error
Notes: (1) This only works with leptonica-formatted single-page pdf files. (2) If is not NULL, only filenames that contain the substring can be returned. If == NULL, none of the filenames are filtered out. (3) The files in the directory, after optional filtering by the substring, are lexically sorted in increasing order before concatenation.
LEPT_DLL void convertByteToHexAscii | ( | l_uint8 | byteval, |
char * | pnib1, | ||
char * | pnib2 | ||
) |
Input: byteval (input byte) &nib1, &nib2 (<return> two hex ascii characters) Return: void
LEPT_DLL l_int32 convertFilesFittedToPS | ( | const char * | dirin, |
const char * | substr, | ||
l_float32 | xpts, | ||
l_float32 | ypts, | ||
const char * | fileout | ||
) |
LEPT_DLL l_int32 convertFilesTo1bpp | ( | const char * | dirin, |
const char * | substr, | ||
l_int32 | upscaling, | ||
l_int32 | thresh, | ||
l_int32 | firstpage, | ||
l_int32 | npages, | ||
const char * | dirout, | ||
l_int32 | outformat | ||
) |
Input: dirin substr (<optional> substring filter on filenames; can be NULL) upscaling (1, 2 or 4; only for input color or grayscale) thresh (global threshold for binarization; use 0 for default) firstpage npages (use 0 to do all from to the end) dirout outformat (IFF_PNG, IFF_TIFF_G4) Return: 0 if OK, 1 on error
Notes: (1) Images are sorted lexicographically, and the names in the output directory are retained except for the extension.
LEPT_DLL l_int32 convertFilesToPdf | ( | const char * | dirname, |
const char * | substr, | ||
l_int32 | res, | ||
l_float32 | scalefactor, | ||
l_int32 | type, | ||
l_int32 | quality, | ||
const char * | title, | ||
const char * | fileout | ||
) |
Input: directory name (containing images) substr (<optional> substring filter on filenames; can be NULL) res (input resolution of all images) scalefactor (scaling factor applied to each image; > 0.0) type (encoding type (L_JPEG_ENCODE, L_G4_ENCODE, L_FLATE_ENCODE, or 0 for default) quality (used for JPEG only; 0 for default (75)) title (<optional> pdf title; if null, taken from the first image filename) fileout (pdf file of all images) Return: 0 if OK, 1 on error
Notes: (1) If is not NULL, only image filenames that contain the substring can be used. If == NULL, all files in the directory are used. (2) The files in the directory, after optional filtering by the substring, are lexically sorted in increasing order before concatenation. (3) The scalefactor is applied to each image before encoding. If you enter a value <= 0.0, it will be set to 1.0. (4) Specifying one of the three encoding types for forces all images to be compressed with that type. Use 0 to have the type determined for each image based on depth and whether or not it has a colormap.
LEPT_DLL l_int32 convertFilesToPS | ( | const char * | dirin, |
const char * | substr, | ||
l_int32 | res, | ||
const char * | fileout | ||
) |
LEPT_DLL l_int32 convertFlateToPS | ( | const char * | filein, |
const char * | fileout, | ||
const char * | operation, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | res, | ||
l_float32 | scale, | ||
l_int32 | pageno, | ||
l_int32 | endpage | ||
) |
Input: filein (input file -- any format) fileout (output ps file) operation ("w" for write; "a" for append) x, y (location of LL corner of image, in pixels, relative to the PostScript origin (0,0) at the LL corner of the page) res (resolution of the input image, in ppi; use 0 for default) scale (scaling by printer; use 0.0 or 1.0 for no scaling) pageno (page number; must start with 1; you can use 0 if there is only one page.) endpage (boolean: use TRUE if this is the last image to be added to the page; FALSE otherwise) Return: 0 if OK, 1 on error
Notes: (1) This outputs level 3 PS as flate compressed (overlaid with ascii85 encoding). (2) An output file can contain multiple pages, each with multiple images. The arguments to convertFlateToPS() allow you to control placement of png images on multiple pages within a PostScript file. (3) For the first image written to a file, use "w", which opens for write and clears the file. For all subsequent images written to that file, use "a". (4) The (x, y) parameters give the LL corner of the image relative to the LL corner of the page. They are in units of pixels if scale = 1.0. If you use (e.g.) scale = 2.0, the image is placed at (2x, 2y) on the page, and the image dimensions are also doubled. (5) Display vs printed resolution: * If your display is 75 ppi and your image was created at a resolution of 300 ppi, you can get the image to print at the same size as it appears on your display by either setting scale = 4.0 or by setting res = 75. Both tell the printer to make a 4x enlarged image. * If your image is generated at 150 ppi and you use scale = 1, it will be rendered such that 150 pixels correspond to 72 pts (1 inch on the printer). This function does the conversion from pixels (with or without scaling) to pts, which are the units that the printer uses. * The printer will choose its own resolution to use in rendering the image, which will not affect the size of the rendered image. That is because the output PostScript file describes the geometry in terms of pts, which are defined to be 1/72 inch. The printer will only see the size of the image in pts, through the scale and translate parameters and the affine transform (the ImageMatrix) of the image. (6) To render multiple images on the same page, set endpage = FALSE for each image until you get to the last, for which you set endpage = TRUE. This causes the "showpage" command to be invoked. Showpage outputs the entire page and clears the raster buffer for the next page to be added. Without a "showpage", subsequent images from the next page will overlay those previously put down. (7) For multiple pages, increment the page number, starting with page 1. This allows PostScript (and PDF) to build a page directory, which viewers use for navigation.
LEPT_DLL l_int32 convertFlateToPSEmbed | ( | const char * | filein, |
const char * | fileout | ||
) |
Input: filein (input file -- any format) fileout (output ps file) Return: 0 if OK, 1 on error
Notes: (1) This function takes any image file as input and generates a flate-compressed, ascii85 encoded PS file, with a bounding box. (2) The bounding box is required when a program such as TeX (through epsf) places and rescales the image. (3) The bounding box is sized for fitting the image to an 8.5 x 11.0 inch page.
LEPT_DLL l_int32 convertFlateToPSString | ( | const char * | filein, |
char ** | poutstr, | ||
l_int32 * | pnbytes, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | res, | ||
l_float32 | scale, | ||
l_int32 | pageno, | ||
l_int32 | endpage | ||
) |
Generates level 3 PS string in flate compressed format.
Input: filein (input image file) &poutstr (<return> PS string) &nbytes (<return> number of bytes in PS string) x, y (location of LL corner of image, in pixels, relative to the PostScript origin (0,0) at the LL corner of the page) res (resolution of the input image, in ppi; use 0 for default) scale (scaling by printer; use 0.0 or 1.0 for no scaling) pageno (page number; must start with 1; you can use 0 if there is only one page.) endpage (boolean: use TRUE if this is the last image to be added to the page; FALSE otherwise) Return: 0 if OK, 1 on error
Notes: (1) The returned PS character array is a null-terminated ascii string. All the raster data is ascii85 encoded, so there are no null bytes embedded in it. (2) The raster encoding is made with gzip, the same as that in a png file that is compressed without prediction. The raster data itself is 25% larger than that in the binary form, due to the ascii85 encoding.
Usage: See convertFlateToPS()
LEPT_DLL l_int32 convertG4ToPS | ( | const char * | filein, |
const char * | fileout, | ||
const char * | operation, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | res, | ||
l_float32 | scale, | ||
l_int32 | pageno, | ||
l_int32 | maskflag, | ||
l_int32 | endpage | ||
) |
Input: filein (input tiff g4 file) fileout (output ps file) operation ("w" for write; "a" for append) x, y (location of LL corner of image, in pixels, relative to the PostScript origin (0,0) at the LL corner of the page) res (resolution of the input image, in ppi; typ. values are 300 and 600; use 0 for automatic determination based on image size) scale (scaling by printer; use 0.0 or 1.0 for no scaling) pageno (page number; must start with 1; you can use 0 if there is only one page.) maskflag (boolean: use TRUE if just painting through fg; FALSE if painting both fg and bg. endpage (boolean: use TRUE if this is the last image to be added to the page; FALSE otherwise) Return: 0 if OK, 1 on error
Notes: (1) See the usage comments in convertJpegToPS(), some of which are repeated here. (2) This is a wrapper for tiff g4. The PostScript that is generated is expanded by about 5/4 (due to the ascii85 encoding. If you convert to pdf (ps2pdf), the ascii85 decoder is automatically invoked, so that the pdf wrapped g4 file is essentially the same size as the original g4 file. It's useful to have the PS file ascii85 encoded, because many printers will not print binary PS files. (3) For the first image written to a file, use "w", which opens for write and clears the file. For all subsequent images written to that file, use "a". (4) To render multiple images on the same page, set endpage = FALSE for each image until you get to the last, for which you set endpage = TRUE. This causes the "showpage" command to be invoked. Showpage outputs the entire page and clears the raster buffer for the next page to be added. Without a "showpage", subsequent images from the next page will overlay those previously put down. (5) For multiple images to the same page, where you are writing both jpeg and tiff-g4, you have two options: (a) write the g4 first, as either image (maskflag == FALSE) or imagemask (maskflag == TRUE), and then write the jpeg over it. (b) write the jpeg first and as the last item, write the g4 as an imagemask (maskflag == TRUE), to paint through the foreground only. We have this flexibility with the tiff-g4 because it is 1 bpp. (6) For multiple pages, increment the page number, starting with page 1. This allows PostScript (and PDF) to build a page directory, which viewers use for navigation.
LEPT_DLL l_int32 convertG4ToPSEmbed | ( | const char * | filein, |
const char * | fileout | ||
) |
Input: filein (input tiff file) fileout (output ps file) Return: 0 if OK, 1 on error
Notes: (1) This function takes a g4 compressed tif file as input and generates a g4 compressed, ascii85 encoded PS file, with a bounding box. (2) The bounding box is required when a program such as TeX (through epsf) places and rescales the image. (3) The bounding box is sized for fitting the image to an 8.5 x 11.0 inch page. (4) We paint this through a mask, over whatever is below.
LEPT_DLL l_int32 convertG4ToPSString | ( | const char * | filein, |
char ** | poutstr, | ||
l_int32 * | pnbytes, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | res, | ||
l_float32 | scale, | ||
l_int32 | pageno, | ||
l_int32 | maskflag, | ||
l_int32 | endpage | ||
) |
Input: filein (input tiff g4 file) &poutstr (<return> PS string) &nbytes (<return> number of bytes in PS string) x, y (location of LL corner of image, in pixels, relative to the PostScript origin (0,0) at the LL corner of the page) res (resolution of the input image, in ppi; typ. values are 300 and 600; use 0 for automatic determination based on image size) scale (scaling by printer; use 0.0 or 1.0 for no scaling) pageno (page number; must start with 1; you can use 0 if there is only one page.) maskflag (boolean: use TRUE if just painting through fg; FALSE if painting both fg and bg. endpage (boolean: use TRUE if this is the last image to be added to the page; FALSE otherwise) Return: 0 if OK, 1 on error
Notes: (1) Generates PS string in G4 compressed tiff format from G4 tiff file. (2) For usage, see convertG4ToPS().
LEPT_DLL l_int32 convertHSVToRGB | ( | l_int32 | hval, |
l_int32 | sval, | ||
l_int32 | vval, | ||
l_int32 * | prval, | ||
l_int32 * | pgval, | ||
l_int32 * | pbval | ||
) |
Input: hval, sval, vval &rval, &gval, &bval (<return> RGB values) Return: 0 if OK, 1 on error
Notes: (1) See convertRGBToHSV() for valid input range of HSV values and their interpretation in color space.
LEPT_DLL l_int32 convertImageDataToPdf | ( | l_uint8 * | imdata, |
size_t | size, | ||
l_int32 | type, | ||
l_int32 | quality, | ||
const char * | fileout, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | res, | ||
L_PDF_DATA ** | plpd, | ||
l_int32 | position, | ||
const char * | title | ||
) |
Input: imdata (array of formatted image data; e.g., png, jpeg) size (size of image data) type (L_G4_ENCODE, L_JPEG_ENCODE, L_FLATE_ENCODE) quality (used for JPEG only; 0 for default (75)) fileout (output pdf file; only required on last image on page) x, y (location of lower-left corner of image, in pixels, relative to the PostScript origin (0,0) at the lower-left corner of the page) res (override the resolution of the input image, in ppi; use 0 to respect the resolution embedded in the input) &lpd (ptr to lpd, which is created on the first invocation and returned until last image is processed, at which time it is destroyed) position (in image sequence: L_FIRST_IMAGE, L_NEXT_IMAGE, L_LAST_IMAGE) title (<optional> pdf title; taken from the first image placed on a page; e.g., an input image filename) Return: 0 if OK, 1 on error
Notes: (1) If == 0 and the input resolution field is 0, this will use DEFAULT_INPUT_RES. (2) See comments in convertToPdf().
LEPT_DLL l_int32 convertImageDataToPdfData | ( | l_uint8 * | imdata, |
size_t | size, | ||
l_int32 | type, | ||
l_int32 | quality, | ||
l_uint8 ** | pdata, | ||
size_t * | pnbytes, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | res, | ||
L_PDF_DATA ** | plpd, | ||
l_int32 | position, | ||
const char * | title | ||
) |
Input: imdata (array of formatted image data; e.g., png, jpeg) size (size of image data) type (L_G4_ENCODE, L_JPEG_ENCODE, L_FLATE_ENCODE) quality (used for JPEG only; 0 for default (75)) &data (<return> pdf data in memory) &nbytes (<return> number of bytes in pdf data) x, y (location of lower-left corner of image, in pixels, relative to the PostScript origin (0,0) at the lower-left corner of the page) res (override the resolution of the input image, in ppi; use 0 to respect the resolution embedded in the input) &lpd (ptr to lpd, which is created on the first invocation and returned until last image is processed, at which time it is destroyed) position (in image sequence: L_FIRST_IMAGE, L_NEXT_IMAGE, L_LAST_IMAGE) title (<optional> pdf title; taken from the first image placed on a page; e.g., an input image filename) Return: 0 if OK, 1 on error
Notes: (1) If == 0 and the input resolution field is 0, this will use DEFAULT_INPUT_RES. (2) See comments in convertToPdf().
LEPT_DLL l_int32 convertJpegToPS | ( | const char * | filein, |
const char * | fileout, | ||
const char * | operation, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | res, | ||
l_float32 | scale, | ||
l_int32 | pageno, | ||
l_int32 | endpage | ||
) |
Input: filein (input jpeg file) fileout (output ps file) operation ("w" for write; "a" for append) x, y (location of LL corner of image, in pixels, relative to the PostScript origin (0,0) at the LL corner of the page) res (resolution of the input image, in ppi; use 0 for default) scale (scaling by printer; use 0.0 or 1.0 for no scaling) pageno (page number; must start with 1; you can use 0 if there is only one page) endpage (boolean: use TRUE if this is the last image to be added to the page; FALSE otherwise) Return: 0 if OK, 1 on error
Notes: (1) This is simpler to use than pixWriteStringPS(), and it outputs in level 2 PS as compressed DCT (overlaid with ascii85 encoding). (2) An output file can contain multiple pages, each with multiple images. The arguments to convertJpegToPS() allow you to control placement of jpeg images on multiple pages within a PostScript file. (3) For the first image written to a file, use "w", which opens for write and clears the file. For all subsequent images written to that file, use "a". (4) The (x, y) parameters give the LL corner of the image relative to the LL corner of the page. They are in units of pixels if scale = 1.0. If you use (e.g.) scale = 2.0, the image is placed at (2x, 2y) on the page, and the image dimensions are also doubled. (5) Display vs printed resolution: * If your display is 75 ppi and your image was created at a resolution of 300 ppi, you can get the image to print at the same size as it appears on your display by either setting scale = 4.0 or by setting res = 75. Both tell the printer to make a 4x enlarged image. * If your image is generated at 150 ppi and you use scale = 1, it will be rendered such that 150 pixels correspond to 72 pts (1 inch on the printer). This function does the conversion from pixels (with or without scaling) to pts, which are the units that the printer uses. * The printer will choose its own resolution to use in rendering the image, which will not affect the size of the rendered image. That is because the output PostScript file describes the geometry in terms of pts, which are defined to be 1/72 inch. The printer will only see the size of the image in pts, through the scale and translate parameters and the affine transform (the ImageMatrix) of the image. (6) To render multiple images on the same page, set endpage = FALSE for each image until you get to the last, for which you set endpage = TRUE. This causes the "showpage" command to be invoked. Showpage outputs the entire page and clears the raster buffer for the next page to be added. Without a "showpage", subsequent images from the next page will overlay those previously put down. (7) For multiple pages, increment the page number, starting with page 1. This allows PostScript (and PDF) to build a page directory, which viewers use for navigation.
LEPT_DLL l_int32 convertJpegToPSEmbed | ( | const char * | filein, |
const char * | fileout | ||
) |
Input: filein (input jpeg file) fileout (output ps file) Return: 0 if OK, 1 on error
Notes: (1) This function takes a jpeg file as input and generates a DCT compressed, ascii85 encoded PS file, with a bounding box. (2) The bounding box is required when a program such as TeX (through epsf) places and rescales the image. (3) The bounding box is sized for fitting the image to an 8.5 x 11.0 inch page.
LEPT_DLL l_int32 convertJpegToPSString | ( | const char * | filein, |
char ** | poutstr, | ||
l_int32 * | pnbytes, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | res, | ||
l_float32 | scale, | ||
l_int32 | pageno, | ||
l_int32 | endpage | ||
) |
Generates PS string in jpeg format from jpeg file
Input: filein (input jpeg file) &poutstr (<return> PS string) &nbytes (<return> number of bytes in PS string) x, y (location of LL corner of image, in pixels, relative to the PostScript origin (0,0) at the LL corner of the page) res (resolution of the input image, in ppi; use 0 for default) scale (scaling by printer; use 0.0 or 1.0 for no scaling) pageno (page number; must start with 1; you can use 0 if there is only one page) endpage (boolean: use TRUE if this is the last image to be added to the page; FALSE otherwise) Return: 0 if OK, 1 on error
Notes: (1) For usage, see convertJpegToPS()
LEPT_DLL BOXAA* convertNumberedMasksToBoxaa | ( | const char * | dirname, |
const char * | substr, | ||
l_int32 | numpre, | ||
l_int32 | numpost | ||
) |
Input: directory name (containing mask images) substr (<optional> substring filter on filenames; can be NULL) numpre (number of characters in name before number) numpost (number of characters in name after number, up to a dot before an extension) including an extension and the dot separator) Return: boxaa of mask regions, or null on error
Notes: (1) This is conveniently used to generate the input boxaa for convertSegmentedFilesToPdf(). It guarantees that the boxa will be aligned with the page images, even if some of the boxa are empty.
LEPT_DLL l_uint16 convertOnBigEnd16 | ( | l_uint16 | shortin | ) |
LEPT_DLL l_uint32 convertOnBigEnd32 | ( | l_uint32 | wordin | ) |
LEPT_DLL l_uint16 convertOnLittleEnd16 | ( | l_uint16 | shortin | ) |
LEPT_DLL l_uint32 convertOnLittleEnd32 | ( | l_uint32 | wordin | ) |
LEPT_DLL l_int32 convertRGBToHSV | ( | l_int32 | rval, |
l_int32 | gval, | ||
l_int32 | bval, | ||
l_int32 * | phval, | ||
l_int32 * | psval, | ||
l_int32 * | pvval | ||
) |
Input: rval, gval, bval (RGB input) &hval, &sval, &vval (<return> HSV values) Return: 0 if OK, 1 on error
Notes: (1) The range of returned values is: h [0 ... 239] s [0 ... 255] v [0 ... 255] (2) If r = g = b, the pixel is gray (s = 0), and we define h = 0. (3) h wraps around, so that h = 0 and h = 240 are equivalent in hue space. (4) h has the following correspondence to color: h = 0 magenta h = 40 red h = 80 yellow h = 120 green h = 160 cyan h = 200 blue
LEPT_DLL l_int32 convertRGBToYUV | ( | l_int32 | rval, |
l_int32 | gval, | ||
l_int32 | bval, | ||
l_int32 * | pyval, | ||
l_int32 * | puval, | ||
l_int32 * | pvval | ||
) |
Input: rval, gval, bval (RGB input) &yval, &uval, &vval (<return> YUV values) Return: 0 if OK, 1 on error
Notes: (1) The range of returned values is: Y [16 ... 235] U [16 ... 240] V [16 ... 240]
LEPT_DLL l_int32 convertSegmentedFilesToPdf | ( | const char * | dirname, |
const char * | substr, | ||
l_int32 | res, | ||
l_int32 | type, | ||
l_int32 | thresh, | ||
BOXAA * | baa, | ||
l_int32 | quality, | ||
l_float32 | scalefactor, | ||
const char * | title, | ||
const char * | fileout | ||
) |
Input: directory name (containing images) substr (<optional> substring filter on filenames; can be NULL) res (input resolution of all images) type (compression type for non-image regions; the image regions are always compressed with L_JPEG_ENCODE) thresh (used for converting gray --> 1 bpp with L_G4_ENCODE) boxaa (<optional> of image regions) quality (used for JPEG only; 0 for default (75)) scalefactor (scaling factor applied to each image region) title (<optional> pdf title; if null, taken from the first image filename) fileout (pdf file of all images) Return: 0 if OK, 1 on error
Notes: (1) If is not NULL, only image filenames that contain the substring can be used. If == NULL, all files in the directory are used. (2) The files in the directory, after optional filtering by the substring, are lexically sorted in increasing order before concatenation. (3) The images are encoded with G4 if 1 bpp; JPEG if 8 bpp without colormap and many colors, or 32 bpp; FLATE for anything else. (4) The boxaa, if it exists, contains one boxa of "image regions" for each image file. The boxa must be aligned with the sorted set of images. (5) The scalefactor is applied to each image region. It is typically < 1.0, to save bytes in the final pdf, because the resolution is often not critical in non-text regions. (6) If the non-image regions have pixel depth > 1 and the encoding type is G4, they are automatically scaled up by 2x and thresholded. Otherwise, no scaling is performed on them. (7) Note that this function can be used to generate multipage G4 compressed pdf from any input, by using == NULL and == L_G4_ENCODE.
LEPT_DLL l_int32 convertSegmentedPagesToPS | ( | const char * | pagedir, |
const char * | pagestr, | ||
const char * | maskdir, | ||
const char * | maskstr, | ||
l_int32 | numpre, | ||
l_int32 | numpost, | ||
l_int32 | maxnum, | ||
l_float32 | textscale, | ||
l_float32 | imagescale, | ||
l_int32 | threshold, | ||
const char * | fileout | ||
) |
LEPT_DLL SARRAY* convertSortedToNumberedPathnames | ( | SARRAY * | sa, |
l_int32 | numpre, | ||
l_int32 | numpost, | ||
l_int32 | maxnum | ||
) |
convertSortedToNumberedPathnames()
Input: sorted pathnames (including zero-padded integers) numpre (number of characters in name before number) numpost (number of characters in name after the number, up to a dot before an extension) maxnum (only consider page numbers up to this value) Return: sarray of numbered pathnames, or NULL on error
Notes: (1) Typically, numpre = numpost = 0; e.g., when the filename just has a number followed by an optional extension.
LEPT_DLL l_int32 convertTiffMultipageToPS | ( | const char * | filein, |
const char * | fileout, | ||
const char * | tempfile, | ||
l_float32 | fillfract | ||
) |
Input: filein (input tiff multipage file) fileout (output ps file) tempfile (<optional> for temporary g4 tiffs; use NULL for default) factor (for filling 8.5 x 11 inch page; use 0.0 for DEFAULT_FILL_FRACTION) Return: 0 if OK, 1 on error
Notes: (1) This converts a multipage tiff file of binary page images into a ccitt g4 compressed PS file. (2) If the images are generated from a standard resolution fax, the vertical resolution is doubled to give a normal-looking aspect ratio.
LEPT_DLL l_int32 convertToPdf | ( | const char * | filein, |
l_int32 | type, | ||
l_int32 | quality, | ||
const char * | fileout, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | res, | ||
L_PDF_DATA ** | plpd, | ||
l_int32 | position, | ||
const char * | title | ||
) |
Input: filein (input image file -- any format) type (L_G4_ENCODE, L_JPEG_ENCODE, L_FLATE_ENCODE) quality (used for JPEG only; 0 for default (75)) fileout (output pdf file; only required on last image on page) x, y (location of lower-left corner of image, in pixels, relative to the PostScript origin (0,0) at the lower-left corner of the page) res (override the resolution of the input image, in ppi; use 0 to respect the resolution embedded in the input) &lpd (ptr to lpd, which is created on the first invocation and returned until last image is processed, at which time it is destroyed) position (in image sequence: L_FIRST_IMAGE, L_NEXT_IMAGE, L_LAST_IMAGE) title (<optional> pdf title; if null, taken from the first image placed on a page; e.g., an input image filename) Return: 0 if OK, 1 on error
Notes: (1) To wrap only one image in pdf, input = NULL, and the value of will be ignored: convertToPdf(... type, quality, x, y, res, NULL, 0); (2) To wrap multiple images on a single pdf page, this is called once for each successive image. Do it this way: L_PDF_DATA *lpd; convertToPdf(... type, quality, x, y, res, &lpd, L_FIRST_IMAGE); convertToPdf(... type, quality, x, y, res, &lpd, L_NEXT_IMAGE); ... convertToPdf(... type, quality, x, y, res, &lpd, L_LAST_IMAGE); This will write the result to the value of specified in the first call; succeeding values of are ignored. On the last call: the pdf data bytes are computed and written to , lpd is destroyed internally, and the returned value of lpd is null. So the client has nothing to clean up. (3) (a) Set == 0 to respect the resolution embedded in the image file. If no resolution is embedded, it will be set to the default value. (b) Set to some other value to override the file resolution. (4) (a) If the input and the resolution of the output device are equal, the image will be "displayed" at the same size as the original. (b) If the input is 72, the output device will render the image at 1 pt/pixel. (c) Some possible choices for the default input pix resolution are: 72 ppi Render pix on any output device at one pt/pixel 96 ppi Windows default for generated display images 300 ppi Typical default for scanned images. We choose 300, which is sensible for rendering page images. However, images come from a variety of sources, and some are explicitly created for viewing on a display.
LEPT_DLL l_int32 convertToPdfData | ( | const char * | filein, |
l_int32 | type, | ||
l_int32 | quality, | ||
l_uint8 ** | pdata, | ||
size_t * | pnbytes, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | res, | ||
L_PDF_DATA ** | plpd, | ||
l_int32 | position, | ||
const char * | title | ||
) |
Input: filein (input image file -- any format) type (L_G4_ENCODE, L_JPEG_ENCODE, L_FLATE_ENCODE) quality (used for JPEG only; 0 for default (75)) &data (<return> pdf data in memory) &nbytes (<return> number of bytes in pdf data) x, y (location of lower-left corner of image, in pixels, relative to the PostScript origin (0,0) at the lower-left corner of the page) res (override the resolution of the input image, in ppi; use 0 to respect the resolution embedded in the input) &lpd (ptr to lpd, which is created on the first invocation and returned until last image is processed, at which time it is destroyed) position (in image sequence: L_FIRST_IMAGE, L_NEXT_IMAGE, L_LAST_IMAGE) title (<optional> pdf title; taken from the first image placed on a page; e.g., an input image filename) Return: 0 if OK, 1 on error
Notes: (1) If == 0 and the input resolution field is 0, this will use DEFAULT_INPUT_RES. (2) See comments in convertToPdf().
LEPT_DLL l_int32 convertToPdfDataSegmented | ( | const char * | filein, |
l_int32 | res, | ||
l_int32 | type, | ||
l_int32 | thresh, | ||
BOXA * | boxa, | ||
l_int32 | quality, | ||
l_float32 | scalefactor, | ||
l_uint8 ** | pdata, | ||
size_t * | pnbytes | ||
) |
Input: filein (input image file -- any format) res (input image resolution; typ. 300 ppi; use 0 for default) type (compression type for non-image regions; the image regions are always compressed with L_JPEG_ENCODE) thresh (used for converting gray --> 1 bpp with L_G4_ENCODE) boxa (<optional> image regions; can be null) quality (used for jpeg image regions; 0 for default) scalefactor (used for jpeg regions; must be <= 1.0) &data (<return> pdf data in memory) &nbytes (<return> number of bytes in pdf data) Return: 0 if OK, 1 on error
Notes: (1) If there are no image regions, set == NULL; and are ignored. (2) Typically, is < 1.0. The image regions are
LEPT_DLL l_int32 convertToPdfSegmented | ( | const char * | filein, |
l_int32 | res, | ||
l_int32 | type, | ||
l_int32 | thresh, | ||
BOXA * | boxa, | ||
l_int32 | quality, | ||
l_float32 | scalefactor, | ||
const char * | fileout | ||
) |
Input: filein (input image file -- any format) res (input image resolution; typ. 300 ppi; use 0 for default) type (compression type for non-image regions; the image regions are always compressed with L_JPEG_ENCODE) thresh (used for converting gray --> 1 bpp with L_G4_ENCODE) boxa (<optional> of image regions; can be null) quality (used for jpeg image regions; 0 for default) scalefactor (used for jpeg regions; must be <= 1.0) fileout (output pdf file) Return: 0 if OK, 1 on error
Notes: (1) If there are no image regions, set == NULL; and are ignored. (2) Typically, is < 1.0, because the image regions can be rendered at a lower resolution (for better compression) than the text regions. If == 0, we use 1.0. If the input image is 1 bpp and scalefactor < 1.0, we use scaleToGray() to downsample the image regions to gray before compressing them. (3) If the compression type for non-image regions is L_G4_ENCODE and bpp > 1, the image is upscaled 2x and thresholded to 1 bpp. That is the only situation where is used. (4) The parameter is only used for image regions. If == L_JPEG_ENCODE, default jpeg quality (75) is used for the non-image regions. (5) Processing matrix for non-image regions.
Input G4 JPEG FLATE ----------|--------------------------------------------------- 1 bpp | 1x, 1 bpp 1x flate, 1 bpp 1x, 1 bpp | cmap | 2x, 1 bpp 1x flate, cmap 1x, cmap | 2,4 bpp | 2x, 1 bpp 1x flate 1x, 2,4 bpp no cmap | 2,4 bpp | 8,32 bpp | 2x, 1 bpp 1x (jpeg) 1x, 8,32 bpp no cmap | 8,32 bpp
Summary: (a) if G4 is requested, G4 is used, with 2x upscaling for all cases except 1 bpp. (b) if JPEG is requested, use flate encoding for all cases except 8 bpp without cmap and 32 bpp (rgb). (c) if FLATE is requested, use flate with no transformation of the raster data. (6) Calling options/sequence for these functions: file --> file (convertToPdfSegmented) pix --> file (pixConvertToPdfSegmented) pix --> data (pixConvertToPdfDataSegmented) file --> data (convertToPdfDataSegmented) pix --> data (pixConvertToPdfDataSegmented)
LEPT_DLL l_int32 convertToPSEmbed | ( | const char * | filein, |
const char * | fileout, | ||
l_int32 | level | ||
) |
LEPT_DLL l_int32 convertYUVToRGB | ( | l_int32 | yval, |
l_int32 | uval, | ||
l_int32 | vval, | ||
l_int32 * | prval, | ||
l_int32 * | pgval, | ||
l_int32 * | pbval | ||
) |
Input: yval, uval, vval &rval, &gval, &bval (<return> RGB values) Return: 0 if OK, 1 on error
Notes: (1) The range of valid input values is: Y [16 ... 235] U [16 ... 240] V [16 ... 240] (2) Conversion of RGB --> YUV --> RGB leaves the image unchanged. (3) The YUV gamut is larger than the RBG gamut; many YUV values will result in an invalid RGB value. We clip individual r,g,b components to the range [0, 255], and do not test input.
LEPT_DLL l_float32** create2dFloatArray | ( | l_int32 | sy, |
l_int32 | sx | ||
) |
Input: sy (rows == height) sx (columns == width) Return: doubly indexed array (i.e., an array of sy row pointers, each of which points to an array of sx floats)
Notes: (1) The array[sy][sx] is indexed in standard "matrix notation", with the row index first.
LEPT_DLL l_int32** create2dIntArray | ( | l_int32 | sy, |
l_int32 | sx | ||
) |
Input: sy (rows == height) sx (columns == width) Return: doubly indexed array (i.e., an array of sy row pointers, each of which points to an array of sx ints)
Notes: (1) The array[sy][sx] is indexed in standard "matrix notation", with the row index first.
Input: xc, yc (location of center of rotation) angle (rotation in radians; clockwise is positive) Return: 3x3 transform matrix, or null on error
Notes; (1) The rotation is equivalent to: v' = Av where v and v' are 1x3 column vectors in the form v = [x, y, 1]^ (^ denotes transpose) and the affine rotation matrix is A = [ cosa -sina xc*(1-cosa) + yc*sina sina cosa yc*(1-cosa) - xc*sina 0 0 1 ]
If the rotation is about the origin, (xc, yc) = (0, 0) and this simplifies to A = [ cosa -sina 0 sina cosa 0 0 0 1 ]
These relations follow from the following equations, which you can convince yourself are correct as follows. Draw a circle centered on (xc,yc) and passing through (x,y), with (x',y') on the arc at an angle 'a' clockwise from (x,y). [ Hint: cos(a + b) = cosa * cosb - sina * sinb sin(a + b) = sina * cosb + cosa * sinb ]
x' - xc = (x - xc) * cosa - (y - yc) * sina y' - yc = (x - xc) * sina + (y - yc) * cosa
LEPT_DLL l_float32* createMatrix2dScale | ( | l_float32 | scalex, |
l_float32 | scaley | ||
) |
Input: scalex (horizontal scale factor) scaley (vertical scale factor) Return: 3x3 transform matrix, or null on error
Notes; (1) The scaling is equivalent to: v' = Av where v and v' are 1x3 column vectors in the form v = [x, y, 1]^ (^ denotes transpose) and the affine scaling matrix is A = [ sx 0 0 0 sy 0 0 0 1 ]
(2) We consider scaling as with respect to a fixed origin. In other words, the origin is the only point that doesn't move in the scaling transform.
LEPT_DLL l_float32* createMatrix2dTranslate | ( | l_float32 | transx, |
l_float32 | transy | ||
) |
Input: transx (x component of translation wrt. the origin) transy (y component of translation wrt. the origin) Return: 3x3 transform matrix, or null on error
Notes; (1) The translation is equivalent to: v' = Av where v and v' are 1x3 column vectors in the form v = [x, y, 1]^ (^ denotes transpose) and the affine tranlation matrix is A = [ 1 0 tx 0 1 ty 0 0 1 ]
(2) We consider translation as with respect to a fixed origin. In a clipping operation, the origin moves and the points are fixed, and you use (-tx, -ty) where (tx, ty) is the translation vector of the origin.
LEPT_DLL l_uint8* decodeAscii85 | ( | char * | ina, |
l_int32 | insize, | ||
l_int32 * | poutsize | ||
) |
Input: inarray (ascii85 input data) insize (number of bytes in input array) &outsize (<return> number of bytes in output l_uint8 array) Return: outarray (binary)
Notes: (1) We assume the data is properly encoded, so we do not check for invalid characters or the final '>' character. (2) We permit whitespace to be added to the encoding in an arbitrary way.
LEPT_DLL 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.
LEPT_DLL 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.
LEPT_DLL 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.
LEPT_DLL void dewarpaDestroy | ( | L_DEWARPA ** | pdewa | ) |
Input: &dewa (<will be="" set="" to="" null="" before="" returning>="">) Return: void
LEPT_DLL l_int32 dewarpaDestroyDewarp | ( | L_DEWARPA * | dewa, |
l_int32 | pageno | ||
) |
Input: dewa pageno (of dew to be destroyed) Return: 0 if OK, 1 on error
LEPT_DLL 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 .
LEPT_DLL 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
LEPT_DLL 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
LEPT_DLL l_int32 dewarpaInfo | ( | FILE * | fp, |
L_DEWARPA * | dewa | ||
) |
Input: fp dewa Return: 0 if OK, 1 on error
LEPT_DLL 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.
LEPT_DLL 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.
LEPT_DLL 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.
LEPT_DLL 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.
LEPT_DLL L_DEWARPA* dewarpaRead | ( | const char * | filename | ) |
Input: filename Return: dewa, or null on error
LEPT_DLL 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.
LEPT_DLL 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.
LEPT_DLL 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.
LEPT_DLL 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().
LEPT_DLL l_int32 dewarpaShowArrays | ( | L_DEWARPA * | dewa, |
l_float32 | scalefact, | ||
l_int32 | first, | ||
l_int32 | last | ||
) |
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
LEPT_DLL 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.
LEPT_DLL 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.
LEPT_DLL l_int32 dewarpaWrite | ( | const char * | filename, |
L_DEWARPA * | dewa | ||
) |
Input: filename dewa Return: 0 if OK, 1 on error
LEPT_DLL l_int32 dewarpaWriteStream | ( | FILE * | fp, |
L_DEWARPA * | dewa | ||
) |
Input: stream (opened for "wb") dewa Return: 0 if OK, 1 on error
LEPT_DLL 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.
LEPT_DLL 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.
LEPT_DLL 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.
LEPT_DLL 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
LEPT_DLL void dewarpDestroy | ( | L_DEWARP ** | pdew | ) |
Input: &dew (<will be="" set="" to="" null="" before="" returning>="">) Return: void
LEPT_DLL 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.
LEPT_DLL 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.
LEPT_DLL PIX* dewarpGetResult | ( | L_DEWARP * | dew | ) |
Input: dew (after applying disparity correction) Return: pixd (clone of the pix in dew), or null on error
LEPT_DLL 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.
LEPT_DLL 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.
LEPT_DLL 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.
LEPT_DLL L_DEWARP* dewarpRead | ( | const char * | filename | ) |
Input: filename Return: dew, or null on error
LEPT_DLL 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.
LEPT_DLL PTAA* dewarpRemoveShortLines | ( | PIX * | pixs, |
PTAA * | ptaas, | ||
l_float32 | fract, | ||
l_int32 | debugflag | ||
) |
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
LEPT_DLL 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
LEPT_DLL l_int32 dewarpWrite | ( | const char * | filename, |
L_DEWARP * | dew | ||
) |
Input: filename dew Return: 0 if OK, 1 on error
LEPT_DLL 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.
LEPT_DLL void dilateGrayLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_int32 | size, | ||
l_int32 | direction, | ||
l_uint8 * | buffer, | ||
l_uint8 * | maxarray | ||
) |
Input: datad, w, h, wpld (8 bpp image) datas, wpls (8 bpp image, of same dimensions) size (full length of SEL; restricted to odd numbers) direction (L_HORIZ or L_VERT) buffer (holds full line or column of src image pixels) maxarray (array of dimension 2*size+1) Return: void
Note: To eliminate border effects on the actual image, these images are prepared with an additional border of dimensions: leftpix = 0.5 * size rightpix = 1.5 * size toppix = 0.5 * size bottompix = 1.5 * size and we initialize the src border pixels to 0. This allows full processing over the actual image; at the end the border is removed.
Method: Algorithm by van Herk and Gil and Werman
LEPT_DLL PIX* displayHSVColorRange | ( | l_int32 | hval, |
l_int32 | sval, | ||
l_int32 | vval, | ||
l_int32 | huehw, | ||
l_int32 | sathw, | ||
l_int32 | nsamp, | ||
l_int32 | factor | ||
) |
Input: hval (hue center value; in range [0 ... 240] sval (saturation center value; in range [0 ... 255] vval (max intensity value; in range [0 ... 255] huehw (half-width of hue range; > 0) sathw (half-width of saturation range; > 0) nsamp (number of samplings in each half-width in hue and sat) factor (linear size of each color square, in pixels; > 3) Return: pixd (32 bpp set of color squares over input range), or null on error
Notes: (1) The total number of color samplings in each of the hue and saturation directions is 2 * nsamp + 1.
LEPT_DLL void ditherTo2bppLineLow | ( | l_uint32 * | lined, |
l_int32 | w, | ||
l_uint32 * | bufs1, | ||
l_uint32 * | bufs2, | ||
l_int32 * | tabval, | ||
l_int32 * | tab38, | ||
l_int32 * | tab14, | ||
l_int32 | lastlineflag | ||
) |
LEPT_DLL void ditherTo2bppLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_uint32 * | bufs1, | ||
l_uint32 * | bufs2, | ||
l_int32 * | tabval, | ||
l_int32 * | tab38, | ||
l_int32 * | tab14 | ||
) |
LEPT_DLL void ditherToBinaryLineLow | ( | l_uint32 * | lined, |
l_int32 | w, | ||
l_uint32 * | bufs1, | ||
l_uint32 * | bufs2, | ||
l_int32 | lowerclip, | ||
l_int32 | upperclip, | ||
l_int32 | lastlineflag | ||
) |
LEPT_DLL void ditherToBinaryLineLUTLow | ( | l_uint32 * | lined, |
l_int32 | w, | ||
l_uint32 * | bufs1, | ||
l_uint32 * | bufs2, | ||
l_int32 * | tabval, | ||
l_int32 * | tab38, | ||
l_int32 * | tab14, | ||
l_int32 | lastlineflag | ||
) |
Input: lined (ptr to beginning of dest line w (width of image in pixels) bufs1 (buffer of current source line) bufs2 (buffer of next source line) tabval (value to assign for current pixel) tab38 (excess value to give to neighboring 3/8 pixels) tab14 (excess value to give to neighboring 1/4 pixel) lastlineflag (0 if not last dest line, 1 if last dest line) Return: void
LEPT_DLL void ditherToBinaryLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_uint32 * | bufs1, | ||
l_uint32 * | bufs2, | ||
l_int32 | lowerclip, | ||
l_int32 | upperclip | ||
) |
LEPT_DLL void ditherToBinaryLUTLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_uint32 * | bufs1, | ||
l_uint32 * | bufs2, | ||
l_int32 * | tabval, | ||
l_int32 * | tab38, | ||
l_int32 * | tab14 | ||
) |
Low-level function for doing Floyd-Steinberg error diffusion dithering from 8 bpp (datas) to 1 bpp (datad). Two source line buffers, bufs1 and bufs2, are provided, along with three 256-entry lookup tables: tabval gives the output pixel value, tab38 gives the extra (plus or minus) transferred to the pixels directly to the left and below, and tab14 gives the extra transferred to the diagonal below. The choice of 3/8 and 1/4 is traditional but arbitrary when you use a lookup table; the only constraint is that the sum is 1. See other comments below.
Input: dpix addc (use 0.0 to skip the operation) multc (use 1.0 to skip the operation) Return: 0 if OK, 1 on error
Notes: (1) This is an in-place operation. (2) It can be used to multiply each pixel by a constant, and also to add a constant to each pixel. Multiplication is done first.
LEPT_DLL l_int32 dpixChangeRefcount | ( | DPIX * | dpix, |
l_int32 | delta | ||
) |
Input: dpix Return: same dpix (ptr), or null on error
Notes: (1) See pixClone() for definition and usage.
LEPT_DLL FPIX* dpixConvertToFPix | ( | DPIX * | dpix | ) |
Input: dpix Return: fpix, or null on error
LEPT_DLL PIX* dpixConvertToPix | ( | DPIX * | dpixs, |
l_int32 | outdepth, | ||
l_int32 | negvals, | ||
l_int32 | errorflag | ||
) |
Input: dpixs outdepth (0, 8, 16 or 32 bpp) negvals (L_CLIP_TO_ZERO, L_TAKE_ABSVAL) errorflag (1 to output error stats; 0 otherwise) Return: pixd, or null on error
Notes: (1) Use = 0 to programmatically determine the output depth. If no values are greater than 255, it will set outdepth = 8; otherwise to 16 or 32. (2) Because we are converting a float to an unsigned int with a specified dynamic range (8, 16 or 32 bits), errors can occur. If errorflag == TRUE, output the number of values out of range, both negative and positive. (3) If a pixel value is positive and out of range, clip to the maximum value represented at the outdepth of 8, 16 or 32 bits.
Input: dpixd (<optional>; can be null, or equal to dpixs, or different from dpixs) dpixs Return: dpixd, or null on error
Notes: (1) There are three cases: (a) dpixd == null (makes a new dpix; refcount = 1) (b) dpixd == dpixs (no-op) (c) dpixd != dpixs (data copy; no change in refcount) If the refcount of dpixd > 1, case (c) will side-effect these handles. (2) The general pattern of use is: dpixd = dpixCopy(dpixd, dpixs); This will work for all three cases. For clarity when the case is known, you can use: (a) dpixd = dpixCopy(NULL, dpixs); (c) dpixCopy(dpixd, dpixs); (3) For case (c), we check if dpixs and dpixd are the same size. If so, the data is copied directly. Otherwise, the data is reallocated to the correct size and the copy proceeds. The refcount of dpixd is unchanged. (4) This operation, like all others that may involve a pre-existing dpixd, will side-effect any existing clones of dpixd.
LEPT_DLL l_int32 dpixCopyResolution | ( | DPIX * | dpixd, |
DPIX * | dpixs | ||
) |
LEPT_DLL DPIX* dpixCreate | ( | l_int32 | width, |
l_int32 | height | ||
) |
Input: width, height Return: dpix (with data allocated and initialized to 0), or null on error
Notes: (1) Makes a DPix of specified size, with the data array allocated and initialized to 0.
LEPT_DLL DPIX* dpixCreateTemplate | ( | DPIX * | dpixs | ) |
LEPT_DLL void dpixDestroy | ( | DPIX ** | pdpix | ) |
Input: &dpix <will be="" nulled>=""> Return: void
Notes: (1) Decrements the ref count and, if 0, destroys the dpix. (2) Always nulls the input ptr.
LEPT_DLL DPIX* dpixEndianByteSwap | ( | DPIX * | dpixd, |
DPIX * | dpixs | ||
) |
Input: dpixd (can be equal to dpixs or NULL) dpixs Return: dpixd always
Notes: (1) On big-endian hardware, this does byte-swapping on each of the 4-byte words in the dpix data. On little-endians, the data is unchanged. This is used for serialization of dpix; the data is serialized in little-endian byte order because most hardware is little-endian. (2) The operation can be either in-place or, if dpixd == NULL, a new dpix is made. If not in-place, caller must catch the returned pointer.
LEPT_DLL l_float64* dpixGetData | ( | DPIX * | dpix | ) |
Input: dpix &w, &h (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 dpixGetMax | ( | DPIX * | dpix, |
l_float64 * | pmaxval, | ||
l_int32 * | pxmaxloc, | ||
l_int32 * | pymaxloc | ||
) |
Input: dpix &maxval (<optional return>=""> max value) &xmaxloc (<optional return>=""> x location of max) &ymaxloc (<optional return>=""> y location of max) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 dpixGetMin | ( | DPIX * | dpix, |
l_float64 * | pminval, | ||
l_int32 * | pxminloc, | ||
l_int32 * | pyminloc | ||
) |
Input: dpix &minval (<optional return>=""> min value) &xminloc (<optional return>=""> x location of min) &yminloc (<optional return>=""> y location of min) Return: 0 if OK; 1 on error
Input: dpix (x,y) pixel coords &val (<return> pixel value) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 dpixGetRefcount | ( | DPIX * | dpix | ) |
LEPT_DLL l_int32 dpixGetWpl | ( | DPIX * | dpix | ) |
LEPT_DLL DPIX* dpixLinearCombination | ( | DPIX * | dpixd, |
DPIX * | dpixs1, | ||
DPIX * | dpixs2, | ||
l_float32 | a, | ||
l_float32 | b | ||
) |
Input: dpixd (<optional>; this can be null, equal to dpixs1, or different from dpixs1) dpixs1 (can be == to dpixd) dpixs2 Return: dpixd always
Notes: (1) Computes pixelwise linear combination: a * src1 + b * src2 (2) Alignment is to UL corner. (3) There are 3 cases. The result can go to a new dest, in-place to dpixs1, or to an existing input dest: * dpixd == null: (src1 + src2) --> new dpixd * dpixd == dpixs1: (src1 + src2) --> src1 (in-place) * dpixd != dpixs1: (src1 + src2) --> input dpixd (4) dpixs2 must be different from both dpixd and dpixs1.
Input: filename Return: dpix, or null on error
LEPT_DLL DPIX* dpixReadStream | ( | FILE * | fp | ) |
Input: stream Return: dpix, or null on error
LEPT_DLL l_int32 dpixResizeImageData | ( | DPIX * | dpixd, |
DPIX * | dpixs | ||
) |
Input: dpixd, dpixs Return: 0 if OK, 1 on error
LEPT_DLL DPIX* dpixScaleByInteger | ( | DPIX * | dpixs, |
l_int32 | factor | ||
) |
Input: dpixs (low resolution, subsampled) factor (scaling factor) Return: dpixd (interpolated result), or null on error
Notes: (1) The width wd of dpixd is related to ws of dpixs by: wd = factor * (ws - 1) + 1 (and ditto for the height) We avoid special-casing boundary pixels in the interpolation by constructing fpixd by inserting (factor - 1) interpolated pixels between each pixel in fpixs. Then wd = ws + (ws - 1) * (factor - 1) (same as above) This also has the advantage that if we subsample by , throwing out all the interpolated pixels, we regain the original low resolution dpix.
LEPT_DLL l_int32 dpixSetAllArbitrary | ( | DPIX * | dpix, |
l_float64 | inval | ||
) |
Input: dpix val (to set at each pixel) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 dpixSetData | ( | DPIX * | dpix, |
l_float64 * | data | ||
) |
Input: dpix w, h Return: 0 if OK, 1 on error
Input: dpix (x,y) pixel coords val (pixel value) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 dpixSetWpl | ( | DPIX * | dpix, |
l_int32 | wpl | ||
) |
Input: filename dpix Return: 0 if OK, 1 on error
LEPT_DLL l_int32 dpixWriteStream | ( | FILE * | fp, |
DPIX * | dpix | ||
) |
Input: stream (opened for "wb") dpix Return: 0 if OK, 1 on error
LEPT_DLL char* encodeAscii85 | ( | l_uint8 * | inarray, |
l_int32 | insize, | ||
l_int32 * | poutsize | ||
) |
Input: inarray (input data) insize (number of bytes in input array) &outsize (<return> number of bytes in output char array) Return: chara (with 64 characters +
in each line)
Notes: (1) Ghostscript has a stack break if the last line of data only has a '>', so we avoid the problem by always putting '~>' on the last line.
LEPT_DLL void erodeGrayLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_int32 | size, | ||
l_int32 | direction, | ||
l_uint8 * | buffer, | ||
l_uint8 * | minarray | ||
) |
Input: datad, w, h, wpld (8 bpp image) datas, wpls (8 bpp image, of same dimensions) size (full length of SEL; restricted to odd numbers) direction (L_HORIZ or L_VERT) buffer (holds full line or column of src image pixels) minarray (array of dimension 2*size+1) Return: void
Note: To eliminate border effects on the actual image, these images are prepared with an additional border of dimensions: leftpix = 0.5 * size rightpix = 1.5 * size toppix = 0.5 * size bottompix = 1.5 * size and we initialize the src border pixels to 255. This allows full processing over the actual image; at the end the border is removed.
Method: Algorithm by van Herk and Gil and Werman
LEPT_DLL l_int32 extractG4DataFromFile | ( | const char * | filein, |
l_uint8 ** | pdata, | ||
size_t * | pnbytes, | ||
l_int32 * | pw, | ||
l_int32 * | ph, | ||
l_int32 * | pminisblack | ||
) |
Input: filein &data (<return> binary data of ccitt g4 encoded stream) &nbytes (<return> size of binary data) &w (<return optional>=""> image width) &h (<return optional>=""> image height) &minisblack (<return optional>=""> boolean) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 extractJpegDataFromArray | ( | const void * | data, |
size_t | nbytes, | ||
l_int32 * | pw, | ||
l_int32 * | ph, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp | ||
) |
Input: data (binary data consisting of the entire jpeg file) nbytes (size of binary data) &w (<optional return>=""> image width) &h (<optional return>=""> image height) &bps (<optional return>=""> bits/sample; should be 8) &spp (<optional return>=""> samples/pixel; should be 1, 3 or 4) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 extractJpegDataFromFile | ( | const char * | filein, |
l_uint8 ** | pdata, | ||
size_t * | pnbytes, | ||
l_int32 * | pw, | ||
l_int32 * | ph, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp | ||
) |
Input: filein &data (<return> binary data consisting of the entire jpeg file) &nbytes (<return> size of binary data) &w (<optional return>=""> image width) &h (<optional return>=""> image height) &bps (<optional return>=""> bits/sample; should be 8) &spp (<optional return>=""> samples/pixel; should be 1 or 3) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 extractMinMaxComponent | ( | l_uint32 | pixel, |
l_int32 | type | ||
) |
Input: pixel (32 bpp RGB) type (L_CHOOSE_MIN or L_CHOOSE_MAX) Return: componet (in range [0 ... 255], or null on error
LEPT_DLL l_int32 extractNumberFromFilename | ( | const char * | fname, |
l_int32 | numpre, | ||
l_int32 | numpost | ||
) |
Input: fname numpre (number of characters before the digits to be found) numpost (number of characters after the digits to be found) Return: num (number embedded in the filename); -1 on error or if not found
Notes: (1) Use unix-style pathname separators ('/'). (2) The number is to be found in the basename, which is the filename without either the directory or the last extension. (3) When a number is found, it is non-negative. If no number is found, this returns -1, without an error message. The caller needs to check.
LEPT_DLL void extractRGBValues | ( | l_uint32 | pixel, |
l_int32 * | prval, | ||
l_int32 * | pgval, | ||
l_int32 * | pbval | ||
) |
Input: pixel (32 bit) &rval (<optional return>=""> red component) &gval (<optional return>=""> green component) &bval (<optional return>=""> blue component) Return: void
Notes: (1) A slower implementation uses macros: *prval = GET_DATA_BYTE(&pixel, COLOR_RED); *pgval = GET_DATA_BYTE(&pixel, COLOR_GREEN); *pbval = GET_DATA_BYTE(&pixel, COLOR_BLUE);
LEPT_DLL l_int32 fgetJpegResolution | ( | FILE * | fp, |
l_int32 * | pxres, | ||
l_int32 * | pyres | ||
) |
LEPT_DLL l_int32 fgetPngResolution | ( | FILE * | fp, |
l_int32 * | pxres, | ||
l_int32 * | pyres | ||
) |
LEPT_DLL l_int32 fhmtautogen | ( | SELA * | sela, |
l_int32 | fileindex, | ||
const char * | filename | ||
) |
Input: sela fileindex filename (<optional>; can be null) Return: 0 if OK; 1 on error
Notes: (1) This function generates all the code for implementing dwa morphological operations using all the sels in the sela. (2) See fhmtautogen1() and fhmtautogen2() for details.
LEPT_DLL l_int32 fhmtautogen1 | ( | SELA * | sela, |
l_int32 | fileindex, | ||
const char * | filename | ||
) |
Input: sel array fileindex filename (<optional>; can be null) Return: 0 if OK; 1 on error
Notes: (1) This function uses hmttemplate1.txt to create a top-level file that contains two functions that carry out the hit-miss transform for any of the sels in the input sela. (2) The fileindex parameter is inserted into the output filename, as described below. (3) If filename == NULL, the output file is fhmtgen.<n>.c, where <n> is equal to the 'fileindex' parameter. (4) If filename != NULL, the output file is <filename>.<n>.c. (5) Each sel must have at least one hit. A sel with only misses generates code that will abort the operation if it is called.
LEPT_DLL l_int32 fhmtautogen2 | ( | SELA * | sela, |
l_int32 | fileindex, | ||
const char * | filename | ||
) |
Input: sel array fileindex filename (<optional>; can be null) Return: 0 if OK; 1 on error
Notes: (1) This function uses hmttemplate2.txt to create a low-level file that contains the low-level functions for implementing the hit-miss transform for every sel in the input sela. (2) The fileindex parameter is inserted into the output filename, as described below. (3) If filename == NULL, the output file is fhmtgenlow.<n>.c, where <n> is equal to the 'fileindex' parameter. (4) If filename != NULL, the output file is <filename>low.<n>.c.
LEPT_DLL l_int32 fhmtgen_low_1 | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_int32 | index | ||
) |
a dispatcher to appropriate low-level code
LEPT_DLL l_int32 fileAppendString | ( | const char * | filename, |
const char * | str | ||
) |
Input: filename str (string to append to file) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 fileConcatenate | ( | const char * | srcfile, |
const char * | destfile | ||
) |
Input: srcfile (file to append) destfile (file to add to) Return: 0 if OK, 1 on error
Input: srcfile (copy this file) newfile (to this file) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 fileFormatIsTiff | ( | FILE * | fp | ) |
Input: fp (file stream) Return: 1 if file is tiff; 0 otherwise or on error
LEPT_DLL l_int32 filesAreIdentical | ( | const char * | fname1, |
const char * | fname2, | ||
l_int32 * | psame | ||
) |
Input: fname1 fname2 &same (<return> 1 if identical; 0 if different) Return: 0 if OK, 1 on error
LEPT_DLL void finalAccumulateThreshLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_uint32 | offset, | ||
l_uint32 | threshold | ||
) |
LEPT_DLL l_int32 findFileFormat | ( | const char * | filename, |
l_int32 * | pformat | ||
) |
Input: filename &format (<return>) Return: 0 if OK, 1 on error or if format is not recognized
LEPT_DLL l_int32 findFileFormatBuffer | ( | const l_uint8 * | buf, |
l_int32 * | pformat | ||
) |
Input: byte buffer (at least 12 bytes in size; we can't check) &format (<return>) Return: 0 if OK, 1 on error or if format is not recognized
Notes: (1) This determines the file format from the first 12 bytes in the compressed data stream, which are stored in memory. (2) For tiff files, this returns IFF_TIFF. The specific tiff compression is then determined using findTiffCompression().
LEPT_DLL l_int32 findFileFormatStream | ( | FILE * | fp, |
l_int32 * | pformat | ||
) |
Input: fp (file stream) &format (<return>) Return: 0 if OK, 1 on error or if format is not recognized
Notes: (1) Important: Side effect -- this resets fp to BOF.
LEPT_DLL l_int32 findNextBorderPixel | ( | l_int32 | w, |
l_int32 | h, | ||
l_uint32 * | data, | ||
l_int32 | wpl, | ||
l_int32 | px, | ||
l_int32 | py, | ||
l_int32 * | pqpos, | ||
l_int32 * | pnpx, | ||
l_int32 * | pnpy | ||
) |
Input: w, h, data, wpl (px, py), (current P) &qpos (input current Q; <return> new Q) (&npx, &npy) (<return> new P) Return: 0 if next pixel found; 1 otherwise
Notes: (1) qpos increases clockwise from 0 to 7, with 0 at location with Q to left of P: Q P (2) this is a low-level function that does not check input parameters. All calling functions should check them.
LEPT_DLL l_int32 findTiffCompression | ( | FILE * | fp, |
l_int32 * | pcomptype | ||
) |
Input: stream (must be rewound to BOF) &comptype (<return> compression type) Return: 0 if OK, 1 on error
Notes: (1) The returned compression type is that defined in the enum in imageio.h. It is not the tiff flag value. (2) The compression type is initialized to IFF_UNKNOWN. If it is not one of the specified types, the returned type is IFF_TIFF, which indicates no compression. (3) When this function is called, the stream must be at BOF. If the opened stream is to be used again to read the file, it must be rewound to BOF after calling this function.
LEPT_DLL void flipLRLow | ( | l_uint32 * | data, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | d, | ||
l_int32 | wpl, | ||
l_uint8 * | tab, | ||
l_uint32 * | buffer | ||
) |
Notes: (1) The pixel access routines allow a trivial implementation. However, for d < 8, it is more efficient to right-justify each line to a 32-bit boundary and then extract bytes and do pixel reversing. In those cases, as in the 180 degree rotation, we right-shift the data (if necessary) to right-justify on the 32 bit boundary, and then read the bytes off each raster line in reverse order, reversing the pixels in each byte using a table. These functions for 1, 2 and 4 bpp were tested against the "trivial" version (shown here for 4 bpp): for (i = 0; i < h; i++) { line = data + i * wpl; memcpy(buffer, line, bpl); for (j = 0; j < w; j++) { val = GET_DATA_QBIT(buffer, w - 1 - j); SET_DATA_QBIT(line, j, val); } } (2) This operation is in-place.
Notes: (1) This is simple and fast. We use the memcpy function to do all the work on aligned data, regardless of pixel depth. (2) This operation is in-place.
LEPT_DLL l_int32 fmorphautogen | ( | SELA * | sela, |
l_int32 | fileindex, | ||
const char * | filename | ||
) |
Input: sela fileindex filename (<optional>; can be null) Return: 0 if OK; 1 on error
Notes: (1) This function generates all the code for implementing dwa morphological operations using all the sels in the sela. (2) See fmorphautogen1() and fmorphautogen2() for details.
LEPT_DLL l_int32 fmorphautogen1 | ( | SELA * | sela, |
l_int32 | fileindex, | ||
const char * | filename | ||
) |
Input: sela fileindex filename (<optional>; can be null) Return: 0 if OK; 1 on error
Notes: (1) This function uses morphtemplate1.txt to create a top-level file that contains two functions. These functions will carry out dilation, erosion, opening or closing for any of the sels in the input sela. (2) The fileindex parameter is inserted into the output filename, as described below. (3) If filename == NULL, the output file is fmorphgen.<n>.c, where <n> is equal to the 'fileindex' parameter. (4) If filename != NULL, the output file is <filename>.<n>.c.
LEPT_DLL l_int32 fmorphautogen2 | ( | SELA * | sela, |
l_int32 | fileindex, | ||
const char * | filename | ||
) |
LEPT_DLL l_int32 fmorphopgen_low_1 | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_int32 | index | ||
) |
a dispatcher to appropriate low-level code
LEPT_DLL l_int32 fmorphopgen_low_2 | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_int32 | index | ||
) |
a dispatcher to appropriate low-level code
LEPT_DLL size_t fnbytesInFile | ( | FILE * | fp | ) |
Input: file stream Return: nbytes in file; 0 on error
LEPT_DLL FILE* fopenReadStream | ( | const char * | filename | ) |
Input: filename Return: stream, or null on error
Notes: (1) This wrapper also handles pathname conversions for Windows. It should be used whenever you want to run fopen() to read from a stream.
LEPT_DLL FILE* fopenWriteStream | ( | const char * | filename, |
const char * | modestring | ||
) |
Input: filename modestring Return: stream, or null on error
Notes: (1) This wrapper also handles pathname conversions for Windows. It should be used whenever you want to run fopen() to write or append to a stream.
Input: fpixa fpix (to be added) copyflag (L_INSERT, L_COPY, L_CLONE) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 fpixaChangeRefcount | ( | FPIXA * | fpixa, |
l_int32 | delta | ||
) |
Input: fpixa Return: 0 if OK, 1 on error
Input: fpixas copyflag: L_COPY makes a new fpixa and copies each fpix L_CLONE gives a new ref-counted handle to the input fpixa L_COPY_CLONE makes a new fpixa with clones of all fpix Return: new fpixa, or null on error
LEPT_DLL FPIXA* fpixaCreate | ( | l_int32 | n | ) |
Input: n (initial number of ptrs) Return: fpixa, or null on error
LEPT_DLL FPIX* fpixAddBorder | ( | FPIX * | fpixs, |
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot | ||
) |
Input: fpixs left, right, top, bot (pixels on each side to be added) Return: fpixd, or null on error
Notes: (1) Adds border of '0' 32-bit pixels
LEPT_DLL FPIX* fpixAddContinuedBorder | ( | FPIX * | fpixs, |
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot | ||
) |
Input: fpixs left, right, top, bot (pixels on each side to be added) Return: fpixd, or null on error
Notes: (1) This adds pixels on each side whose values are equal to the value on the closest boundary pixel.
LEPT_DLL FPIX* fpixAddMirroredBorder | ( | FPIX * | fpixs, |
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot | ||
) |
Input: fpixs left, right, top, bot (pixels on each side to be added) Return: fpixd, or null on error
Notes: (1) See pixAddMirroredBorder() for situations of usage.
Input: fpix addc (use 0.0 to skip the operation) multc (use 1.0 to skip the operation) Return: 0 if OK, 1 on error
Notes: (1) This is an in-place operation. (2) It can be used to multiply each pixel by a constant, and also to add a constant to each pixel. Multiplication is done first.
LEPT_DLL FPIX* fpixAddSlopeBorder | ( | FPIX * | fpixs, |
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot | ||
) |
Input: fpixs left, right, top, bot (pixels on each side to be added) Return: fpixd, or null on error
Notes: (1) This adds pixels on each side whose values have a normal derivative equal to the normal derivative at the boundary of fpixs.
LEPT_DLL void fpixaDestroy | ( | FPIXA ** | pfpixa | ) |
Input: &fpixa (<can be="" nulled>="">) Return: void
Notes: (1) Decrements the ref count and, if 0, destroys the fpixa. (2) Always nulls the input ptr.
LEPT_DLL PIX* fpixaDisplayQuadtree | ( | FPIXA * | fpixa, |
l_int32 | factor | ||
) |
Input: fpixa (mean, variance or root variance) factor (replication factor at lowest level) Return: pixd (8 bpp, mosaic of quadtree images), or null on error
Notes: (1) The mean and root variance fall naturally in the 8 bpp range, but the variance is typically outside the range. This function displays 8 bpp pix clipped to 255, so the image pixels will mostly be 255 (white).
LEPT_DLL l_int32 fpixaExtendArray | ( | FPIXA * | fpixa | ) |
Input: fpixa Return: 0 if OK; 1 on error
Notes: (1) Doubles the size of the fpixa ptr array.
LEPT_DLL l_int32 fpixaExtendArrayToSize | ( | FPIXA * | fpixa, |
l_int32 | size | ||
) |
Input: fpixa Return: 0 if OK; 1 on error
Notes: (1) If necessary, reallocs new fpixa ptrs array to .
Input: fpixs (8 bpp) vc (vector of 8 coefficients for projective transformation) inval (value brought in; typ. 0) Return: fpixd, or null on error
LEPT_DLL FPIX* fpixAffinePta | ( | FPIX * | fpixs, |
PTA * | ptad, | ||
PTA * | ptas, | ||
l_int32 | border, | ||
l_float32 | inval | ||
) |
Input: fpixs (8 bpp) ptad (4 pts of final coordinate space) ptas (4 pts of initial coordinate space) border (size of extension with constant normal derivative) inval (value brought in; typ. 0) Return: fpixd, or null on error
Notes: (1) If > 0, all four sides are extended by that distance, and removed after the transformation is finished. Pixels that would be brought in to the trimmed result from outside the extended region are assigned . The purpose of extending the image is to avoid such assignments. (2) On the other hand, you may want to give all pixels that are brought in from outside fpixs a specific value. In that case, set == 0.
LEPT_DLL l_int32 fpixaGetCount | ( | FPIXA * | fpixa | ) |
Input: fpixa Return: count, or 0 if no pixa
Input: fpixa index (to the index-th fpix) accesstype (L_COPY or L_CLONE) Return: fpix, or null on error
LEPT_DLL l_int32 fpixaGetFPixDimensions | ( | FPIXA * | fpixa, |
l_int32 | index, | ||
l_int32 * | pw, | ||
l_int32 * | ph | ||
) |
Input: fpixa index (to the index-th box) &w, &h (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 fpixaGetPixel | ( | FPIXA * | fpixa, |
l_int32 | index, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 * | pval | ||
) |
Input: fpixa index (into fpixa array) (x,y) pixel coords &val (<return> pixel value) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 fpixaSetPixel | ( | FPIXA * | fpixa, |
l_int32 | index, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 | val | ||
) |
Input: fpixa index (into fpixa array) (x,y) pixel coords val (pixel value) Return: 0 if OK; 1 on error
LEPT_DLL PIX* fpixAutoRenderContours | ( | FPIX * | fpix, |
l_int32 | ncontours | ||
) |
Input: pixs (8 or 16 bpp; no colormap) ncontours (> 1, < 500, typ. about 50) Return: pixd (8 bpp), or null on error
Notes: (1) The increment is set to get approximately . (2) The proximity to the target value for contour display is set at 0.1 * increment. (3) Negative contours are rendered in red; 0 or positive contours are rendered in black.
LEPT_DLL l_int32 fpixChangeRefcount | ( | FPIX * | fpix, |
l_int32 | delta | ||
) |
Input: fpix Return: same fpix (ptr), or null on error
Notes: (1) See pixClone() for definition and usage.
LEPT_DLL DPIX* fpixConvertToDPix | ( | FPIX * | fpix | ) |
Input: fpix Return: dpix, or null on error
LEPT_DLL PIX* fpixConvertToPix | ( | FPIX * | fpixs, |
l_int32 | outdepth, | ||
l_int32 | negvals, | ||
l_int32 | errorflag | ||
) |
Input: fpixs outdepth (0, 8, 16 or 32 bpp) negvals (L_CLIP_TO_ZERO, L_TAKE_ABSVAL) errorflag (1 to output error stats; 0 otherwise) Return: pixd, or null on error
Notes: (1) Use = 0 to programmatically determine the output depth. If no values are greater than 255, it will set outdepth = 8; otherwise to 16 or 32. (2) Because we are converting a float to an unsigned int with a specified dynamic range (8, 16 or 32 bits), errors can occur. If errorflag == TRUE, output the number of values out of range, both negative and positive. (3) If a pixel value is positive and out of range, clip to the maximum value represented at the outdepth of 8, 16 or 32 bits.
Input: fpixs (32 bit float array) kernel normflag (1 to normalize kernel to unit sum; 0 otherwise) Return: fpixd (32 bit float array)
Notes: (1) This gives a float convolution with an arbitrary kernel. (2) If normflag == 1, the result is normalized by scaling all kernel values for a unit sum. Do not normalize if the kernel has null sum, such as a DoG. (3) With the FPix, there are no issues about negative array or kernel values. The convolution is performed with single precision arithmetic. (4) To get a subsampled output, call l_setConvolveSampling(). The time to make a subsampled output is reduced by the product of the sampling factors. (5) This uses a mirrored border to avoid special casing on the boundaries.
Input: fpixs (32 bit float array) kelx (x-dependent kernel) kely (y-dependent kernel) normflag (1 to normalize kernel to unit sum; 0 otherwise) Return: fpixd (32 bit float array)
Notes: (1) This does a convolution with a separable kernel that is is a sequence of convolutions in x and y. The two one-dimensional kernel components must be input separately; the full kernel is the product of these components. The support for the full kernel is thus a rectangular region. (2) The normflag parameter is used as in fpixConvolve(). (3) Warning: if you use l_setConvolveSampling() to get a subsampled output, and the sampling factor is larger than the kernel half-width, it is faster to use the non-separable version pixConvolve(). This is because the first convolution here must be done on every raster line, regardless of the vertical sampling factor. If the sampling factor is smaller than kernel half-width, it's faster to use the separable convolution. (4) This uses mirrored borders to avoid special casing on the boundaries.
Input: fpixd (<optional>; can be null, or equal to fpixs, or different from fpixs) fpixs Return: fpixd, or null on error
Notes: (1) There are three cases: (a) fpixd == null (makes a new fpix; refcount = 1) (b) fpixd == fpixs (no-op) (c) fpixd != fpixs (data copy; no change in refcount) If the refcount of fpixd > 1, case (c) will side-effect these handles. (2) The general pattern of use is: fpixd = fpixCopy(fpixd, fpixs); This will work for all three cases. For clarity when the case is known, you can use: (a) fpixd = fpixCopy(NULL, fpixs); (c) fpixCopy(fpixd, fpixs); (3) For case (c), we check if fpixs and fpixd are the same size. If so, the data is copied directly. Otherwise, the data is reallocated to the correct size and the copy proceeds. The refcount of fpixd is unchanged. (4) This operation, like all others that may involve a pre-existing fpixd, will side-effect any existing clones of fpixd.
LEPT_DLL l_int32 fpixCopyResolution | ( | FPIX * | fpixd, |
FPIX * | fpixs | ||
) |
LEPT_DLL FPIX* fpixCreate | ( | l_int32 | width, |
l_int32 | height | ||
) |
Input: width, height Return: fpixd (with data allocated and initialized to 0), or null on error
Notes: (1) Makes a FPix of specified size, with the data array allocated and initialized to 0.
LEPT_DLL FPIX* fpixCreateTemplate | ( | FPIX * | fpixs | ) |
LEPT_DLL void fpixDestroy | ( | FPIX ** | pfpix | ) |
Input: &fpix <will be="" nulled>=""> Return: void
Notes: (1) Decrements the ref count and, if 0, destroys the fpix. (2) Always nulls the input ptr.
LEPT_DLL PIX* fpixDisplayMaxDynamicRange | ( | FPIX * | fpixs | ) |
Input: fpixs Return: pixd (8 bpp), or null on error
LEPT_DLL FPIX* fpixEndianByteSwap | ( | FPIX * | fpixd, |
FPIX * | fpixs | ||
) |
Input: fpixd (can be equal to fpixs or NULL) fpixs Return: fpixd always
Notes: (1) On big-endian hardware, this does byte-swapping on each of the 4-byte floats in the fpix data. On little-endians, the data is unchanged. This is used for serialization of fpix; the data is serialized in little-endian byte order because most hardware is little-endian. (2) The operation can be either in-place or, if fpixd == NULL, a new fpix is made. If not in-place, caller must catch the returned pointer.
LEPT_DLL l_float32* fpixGetData | ( | FPIX * | fpix | ) |
Input: fpix &w, &h (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 fpixGetMax | ( | FPIX * | fpix, |
l_float32 * | pmaxval, | ||
l_int32 * | pxmaxloc, | ||
l_int32 * | pymaxloc | ||
) |
Input: fpix &maxval (<optional return>=""> max value) &xmaxloc (<optional return>=""> x location of max) &ymaxloc (<optional return>=""> y location of max) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 fpixGetMin | ( | FPIX * | fpix, |
l_float32 * | pminval, | ||
l_int32 * | pxminloc, | ||
l_int32 * | pyminloc | ||
) |
Input: fpix &minval (<optional return>=""> min value) &xminloc (<optional return>=""> x location of min) &yminloc (<optional return>=""> y location of min) Return: 0 if OK; 1 on error
Input: fpix (x,y) pixel coords &val (<return> pixel value) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 fpixGetRefcount | ( | FPIX * | fpix | ) |
LEPT_DLL l_int32 fpixGetWpl | ( | FPIX * | fpix | ) |
LEPT_DLL FPIX* fpixLinearCombination | ( | FPIX * | fpixd, |
FPIX * | fpixs1, | ||
FPIX * | fpixs2, | ||
l_float32 | a, | ||
l_float32 | b | ||
) |
Input: fpixd (<optional>; this can be null, equal to fpixs1, or different from fpixs1) fpixs1 (can be == to fpixd) fpixs2 Return: fpixd always
Notes: (1) Computes pixelwise linear combination: a * src1 + b * src2 (2) Alignment is to UL corner. (3) There are 3 cases. The result can go to a new dest, in-place to fpixs1, or to an existing input dest: * fpixd == null: (src1 + src2) --> new fpixd * fpixd == fpixs1: (src1 + src2) --> src1 (in-place) * fpixd != fpixs1: (src1 + src2) --> input fpixd (4) fpixs2 must be different from both fpixd and fpixs1.
LEPT_DLL l_int32 fpixPrintStream | ( | FILE * | fp, |
FPIX * | fpix, | ||
l_int32 | factor | ||
) |
Input: stream fpix factor (subsampled) Return: 0 if OK, 1 on error
Notes: (1) Subsampled printout of fpix for debugging.
Input: fpixs (8 bpp) vc (vector of 8 coefficients for projective transformation) inval (value brought in; typ. 0) Return: fpixd, or null on error
LEPT_DLL FPIX* fpixProjectivePta | ( | FPIX * | fpixs, |
PTA * | ptad, | ||
PTA * | ptas, | ||
l_int32 | border, | ||
l_float32 | inval | ||
) |
Input: fpixs (8 bpp) ptad (4 pts of final coordinate space) ptas (4 pts of initial coordinate space) border (size of extension with constant normal derivative) inval (value brought in; typ. 0) Return: fpixd, or null on error
Notes: (1) If > 0, all four sides are extended by that distance, and removed after the transformation is finished. Pixels that would be brought in to the trimmed result from outside the extended region are assigned . The purpose of extending the image is to avoid such assignments. (2) On the other hand, you may want to give all pixels that are brought in from outside fpixs a specific value. In that case, set == 0.
LEPT_DLL l_int32 fpixRasterop | ( | FPIX * | fpixd, |
l_int32 | dx, | ||
l_int32 | dy, | ||
l_int32 | dw, | ||
l_int32 | dh, | ||
FPIX * | fpixs, | ||
l_int32 | sx, | ||
l_int32 | sy | ||
) |
Input: fpixd (dest fpix) dx (x val of UL corner of dest rectangle) dy (y val of UL corner of dest rectangle) dw (width of dest rectangle) dh (height of dest rectangle) fpixs (src fpix) sx (x val of UL corner of src rectangle) sy (y val of UL corner of src rectangle) Return: 0 if OK; 1 on error.
Notes: (1) This is similiar in structure to pixRasterop(), except it only allows copying from the source into the destination. For that reason, no op code is necessary. Additionally, all pixels are 32 bit words (float values), which makes the copy very simple. (2) Clipping of both src and dest fpix are done automatically. (3) This allows in-place copying, without checking to see if the result is valid: use for in-place with caution!
Input: filename Return: fpix, or null on error
LEPT_DLL FPIX* fpixReadStream | ( | FILE * | fp | ) |
Input: stream Return: fpix, or null on error
LEPT_DLL FPIX* fpixRemoveBorder | ( | FPIX * | fpixs, |
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot | ||
) |
Input: fpixs left, right, top, bot (pixels on each side to be removed) Return: fpixd, or null on error
Input: fpixs incr (increment between contours; must be > 0.0) proxim (required proximity to target value; typ. 0.1 * incr) Return: pixd (8 bpp), or null on error
Notes: (1) Values are displayed when val/incr is close to an integer. (2) Negative contours are rendered in red; 0 or positive contours are rendered in black.
LEPT_DLL l_int32 fpixResizeImageData | ( | FPIX * | fpixd, |
FPIX * | fpixs | ||
) |
Input: fpixd, fpixs Return: 0 if OK, 1 on error
Notes: (1) If the data sizes differ, this destroys the existing data in fpixd and allocates a new, uninitialized, data array of the same size as the data in fpixs. Otherwise, this doesn't do anything.
LEPT_DLL FPIX* fpixScaleByInteger | ( | FPIX * | fpixs, |
l_int32 | factor | ||
) |
Input: fpixs (low resolution, subsampled) factor (scaling factor) Return: fpixd (interpolated result), or null on error
Notes: (1) The width wd of fpixd is related to ws of fpixs by: wd = factor * (ws - 1) + 1 (and ditto for the height) We avoid special-casing boundary pixels in the interpolation by constructing fpixd by inserting (factor - 1) interpolated pixels between each pixel in fpixs. Then wd = ws + (ws - 1) * (factor - 1) (same as above) This also has the advantage that if we subsample by , throwing out all the interpolated pixels, we regain the original low resolution fpix.
LEPT_DLL l_int32 fpixSetAllArbitrary | ( | FPIX * | fpix, |
l_float32 | inval | ||
) |
Input: fpix val (to set at each pixel) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 fpixSetData | ( | FPIX * | fpix, |
l_float32 * | data | ||
) |
Input: fpix w, h Return: 0 if OK, 1 on error
Input: fpix (x,y) pixel coords val (pixel value) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 fpixSetWpl | ( | FPIX * | fpix, |
l_int32 | wpl | ||
) |
Input: filename fpix Return: 0 if OK, 1 on error
LEPT_DLL l_int32 fpixWriteStream | ( | FILE * | fp, |
FPIX * | fpix | ||
) |
Input: stream (opened for "wb") fpix Return: 0 if OK, 1 on error
LEPT_DLL l_int32 fprintTiffInfo | ( | FILE * | fpout, |
const char * | tiffile | ||
) |
LEPT_DLL l_int32 freadHeaderJpeg | ( | FILE * | fp, |
l_int32 * | pw, | ||
l_int32 * | ph, | ||
l_int32 * | pspp, | ||
l_int32 * | pycck, | ||
l_int32 * | pcmyk | ||
) |
Input: stream &w (<optional return>="">) &h (<optional return>="">) &spp (<optional return>="">, samples/pixel) &ycck (<optional return>="">, 1 if ycck color space; 0 otherwise) &cmyk (<optional return>="">, 1 if cmyk color space; 0 otherwise) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 freadHeaderPng | ( | FILE * | fp, |
l_int32 * | pwidth, | ||
l_int32 * | pheight, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp, | ||
l_int32 * | piscmap | ||
) |
Input: stream &width (<return>) &height (<return>) &bps (<return>, bits/sample) &spp (<return>, samples/pixel) &iscmap (<optional return>="">; input NULL to ignore) Return: 0 if OK, 1 on error
Notes: (1) If there is a colormap, iscmap is returned as 1; else 0.
LEPT_DLL l_int32 freadHeaderPnm | ( | FILE * | fp, |
PIX ** | ppix, | ||
l_int32 * | pwidth, | ||
l_int32 * | pheight, | ||
l_int32 * | pdepth, | ||
l_int32 * | ptype, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp | ||
) |
Input: stream opened for read &pix (<optional return>=""> use null to return only header data) &width (<return>) &height (<return>) &depth (<return>) &type (<return> pnm type) &bps (<optional return>="">, bits/sample) &spp (<optional return>="">, samples/pixel) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 freadHeaderSpix | ( | FILE * | fp, |
l_int32 * | pwidth, | ||
l_int32 * | pheight, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp, | ||
l_int32 * | piscmap | ||
) |
Input: stream &width (<return>) &height (<return>) &bps (<return>, bits/sample) &spp (<return>, samples/pixel) &iscmap (<optional return>="">; input NULL to ignore) Return: 0 if OK, 1 on error
Notes: (1) If there is a colormap, iscmap is returned as 1; else 0.
LEPT_DLL l_int32 freadHeaderTiff | ( | FILE * | fp, |
l_int32 | n, | ||
l_int32 * | pwidth, | ||
l_int32 * | pheight, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp, | ||
l_int32 * | pres, | ||
l_int32 * | pcmap, | ||
l_int32 * | pformat | ||
) |
Input: stream n (page image number: 0-based) &width (<return>) &height (<return>) &bps (<return> bits per sample -- 1, 2, 4 or 8) &spp (<return>; samples per pixel -- 1 or 3) &res (<optional return>="">; resolution in x dir; NULL to ignore) &cmap (<optional return>="">; colormap exists; input NULL to ignore) &format (<optional return>="">; tiff format; input NULL to ignore) Return: 0 if OK, 1 on error
Notes: (1) If there is a colormap, cmap is returned as 1; else 0. (2) If
is equal to or greater than the number of images, returns 1.
Input: a (n x n matrix) b (rhs column vector) n (dimension) Return: 0 if ok, 1 on error
Note side effects: (1) the matrix a is transformed to its inverse (2) the vector b is transformed to the solution X to the linear equation AX = B
Adapted from "Numerical Recipes in C, Second Edition", 1992 pp. 36-41 (gauss-jordan elimination)
LEPT_DLL PIX* generateBinaryMaze | ( | l_int32 | w, |
l_int32 | h, | ||
l_int32 | xi, | ||
l_int32 | yi, | ||
l_float32 | wallps, | ||
l_float32 | ranis | ||
) |
Input: w, h (size of maze) xi, yi (initial location) wallps (probability that a pixel to the side is ON) ranis (ratio of prob that pixel in forward direction is a wall to the probability that pixel in side directions is a wall) Return: pix, or null on error
Notes: (1) We have two input probability factors that determine the density of walls and average length of straight passages. When ranis < 1.0, you are more likely to generate a wall to the side than going forward. Enter 0.0 for either if you want to use the default values. (2) This is a type of percolation problem, and exhibits different phases for different parameters wallps and ranis. For larger values of these parameters, regions in the maze are not explored because the maze generator walls them off and cannot get through. The boundary between the two phases in this two-dimensional parameter space goes near these values: wallps ranis 0.35 1.00 0.40 0.85 0.45 0.70 0.50 0.50 0.55 0.40 0.60 0.30 0.65 0.25 0.70 0.19 0.75 0.15 0.80 0.11 (3) Because here is a considerable amount of overhead in calling pixGetPixel() and pixSetPixel(), this function can be sped up with little effort using raster line pointers and the GET_DATA* and SET_DATA* macros.
LEPT_DLL char* generateFlatePS | ( | const char * | filein, |
L_COMPRESSED_DATA * | cid, | ||
l_float32 | xpt, | ||
l_float32 | ypt, | ||
l_float32 | wpt, | ||
l_float32 | hpt, | ||
l_int32 | pageno, | ||
l_int32 | endpage | ||
) |
Input: filein (<optional> input filename; can be null) cid (flate compressed image data) xpt, ypt (location of LL corner of image, in pts, relative to the PostScript origin (0,0) at the LL corner of the page) wpt, hpt (rendered image size in pts) pageno (page number; must start with 1; you can use 0 if there is only one page) endpage (boolean: use TRUE if this is the last image to be added to the page; FALSE otherwise) Return: PS string, or null on error
LEPT_DLL char* generateG4PS | ( | const char * | filein, |
L_COMPRESSED_DATA * | cid, | ||
l_float32 | xpt, | ||
l_float32 | ypt, | ||
l_float32 | wpt, | ||
l_float32 | hpt, | ||
l_int32 | maskflag, | ||
l_int32 | pageno, | ||
l_int32 | endpage | ||
) |
Input: filein (<optional> input tiff g4 file; can be null) cid (g4 compressed image data) xpt, ypt (location of LL corner of image, in pts, relative to the PostScript origin (0,0) at the LL corner of the page) wpt, hpt (rendered image size in pts) maskflag (boolean: use TRUE if just painting through fg; FALSE if painting both fg and bg. pageno (page number; must start with 1; you can use 0 if there is only one page.) endpage (boolean: use TRUE if this is the last image to be added to the page; FALSE otherwise) Return: PS string, or null on error
Notes: (1) Low-level function.
LEPT_DLL char* generateJpegPS | ( | const char * | filein, |
L_COMPRESSED_DATA * | cid, | ||
l_float32 | xpt, | ||
l_float32 | ypt, | ||
l_float32 | wpt, | ||
l_float32 | hpt, | ||
l_int32 | pageno, | ||
l_int32 | endpage | ||
) |
Input: filein (<optional> input jpeg filename; can be null) cid (jpeg compressed image data) xpt, ypt (location of LL corner of image, in pts, relative to the PostScript origin (0,0) at the LL corner of the page) wpt, hpt (rendered image size in pts) pageno (page number; must start with 1; you can use 0 if there is only one page.) endpage (boolean: use TRUE if this is the last image to be added to the page; FALSE otherwise) Return: PS string, or null on error
Notes: (1) Low-level function.
LEPT_DLL PTAA* generatePtaaBoxa | ( | BOXA * | boxa | ) |
Input: boxa Return: ptaa, or null on error
Notes: (1) This generates a pta of the four corners for each box in the boxa. (2) Each of these pta can be rendered onto a pix with random colors, by using pixRenderRandomCmapPtaa() with closeflag = 1.
LEPT_DLL PTAA* generatePtaaHashBoxa | ( | BOXA * | boxa, |
l_int32 | spacing, | ||
l_int32 | width, | ||
l_int32 | orient, | ||
l_int32 | outline | ||
) |
Input: boxa spacing (spacing between hash lines; must be > 1) width (hash line width) orient (orientation of lines: L_HORIZONTAL_LINE, ...) outline (0 to skip drawing box outline) Return: ptaa, or null on error
Notes: (1) The orientation takes on one of 4 orientations (horiz, vertical, slope +1, slope -1). (2) The full outline is also drawn if = 1. (3) Each of these pta can be rendered onto a pix with random colors, by using pixRenderRandomCmapPtaa() with closeflag = 1.
LEPT_DLL PTA* generatePtaBox | ( | BOX * | box, |
l_int32 | width | ||
) |
Input: box width (of line) Return: ptad, or null on error
Notes: (1) Because the box is constructed so that we don't have any overlapping lines, there is no need to remove duplicates.
Input: boxa width removedups (1 to remove, 0 to leave) Return: ptad, or null on error
Notes: (1) If the boxa has overlapping boxes, and if blending will be used to give a transparent effect, transparency artifacts at line intersections can be removed using removedups = 1.
LEPT_DLL PTA* generatePtaFilledCircle | ( | l_int32 | radius | ) |
Input: radius Return: pta, or null on error
Notes: (1) The circle is has diameter = 2 * radius + 1. (2) It is located with the center of the circle at the point (radius, radius). (3) Consequently, it typically must be translated if it is to represent a set of pixels in an image.
LEPT_DLL PTA* generatePtaHashBox | ( | BOX * | box, |
l_int32 | spacing, | ||
l_int32 | width, | ||
l_int32 | orient, | ||
l_int32 | outline | ||
) |
Input: box spacing (spacing between lines; must be > 1) width (of line) orient (orientation of lines: L_HORIZONTAL_LINE, ...) outline (0 to skip drawing box outline) Return: ptad, or null on error
Notes: (1) The orientation takes on one of 4 orientations (horiz, vertical, slope +1, slope -1). (2) The full outline is also drawn if = 1.
Input: x1, y1 (end point 1) x2, y2 (end point 2) Return: pta, or null on error
Input: x, y (point of origination) length (of line, including starting point) radang (angle in radians, CW from horizontal) Return: pta, or null on error
Notes: (1) The of the line is 1 greater than the distance used in locatePtRadially(). Example: a distance of 1 gives rise to a length of 2.
LEPT_DLL PTA* generatePtaPolyline | ( | PTA * | ptas, |
l_int32 | width, | ||
l_int32 | closeflag, | ||
l_int32 | removedups | ||
) |
Input: pta (vertices of polyline) width closeflag (1 to close the contour; 0 otherwise) removedups (1 to remove, 0 to leave) Return: ptad, or null on error
Notes: (1) If the boxa has overlapping boxes, and if blending will be used to give a transparent effect, transparency artifacts at line intersections can be removed using removedups = 1.
Input: x1, y1 (end point 1) x2, y2 (end point 2) width Return: ptaj, or null on error
LEPT_DLL char* generateUncompressedPS | ( | char * | hexdata, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | d, | ||
l_int32 | psbpl, | ||
l_int32 | bps, | ||
l_float32 | xpt, | ||
l_float32 | ypt, | ||
l_float32 | wpt, | ||
l_float32 | hpt, | ||
l_int32 | boxflag | ||
) |
Input: hexdata w, h (raster image size in pixels) d (image depth in bpp; rgb is 32) psbpl (raster bytes/line, when packed to the byte boundary) bps (bits/sample: either 1 or 8) xpt, ypt (location of LL corner of image, in pts, relative to the PostScript origin (0,0) at the LL corner of the page) wpt, hpt (rendered image size in pts) boxflag (1 to print out bounding box hint; 0 to skip) Return: PS string, or null on error
Notes: (1) Low-level function.
LEPT_DLL char* genPathname | ( | const char * | dir, |
const char * | fname | ||
) |
Input: range (size of range; must be >= 2) seed (use 0 to skip; otherwise call srand) val (<return> random integer in range {0 ... range-1} Return: 0 if OK, 1 on error
Notes: (1) For example, to choose a rand integer between 0 and 99, use = 100.
LEPT_DLL char* genTempFilename | ( | const char * | dir, |
const char * | tail, | ||
l_int32 | usetime, | ||
l_int32 | usepid | ||
) |
Input: ptas (source 3 points; unprimed) ptad (transformed 3 points; primed) &vc (<return> vector of coefficients of transform) Return: 0 if OK; 1 on error
We have a set of six equations, describing the affine transformation that takes 3 points (ptas) into 3 other points (ptad). These equations are:
x1' = c[0]*x1 + c[1]*y1 + c[2] y1' = c[3]*x1 + c[4]*y1 + c[5] x2' = c[0]*x2 + c[1]*y2 + c[2] y2' = c[3]*x2 + c[4]*y2 + c[5] x3' = c[0]*x3 + c[1]*y3 + c[2] y3' = c[3]*x3 + c[4]*y3 + c[5]
This can be represented as
AC = B
where B and C are column vectors
B = [ x1' y1' x2' y2' x3' y3' ] C = [ c[0] c[1] c[2] c[3] c[4] c[5] c[6] ]
and A is the 6x6 matrix
x1 y1 1 0 0 0 0 0 0 x1 y1 1 x2 y2 1 0 0 0 0 0 0 x2 y2 1 x3 y3 1 0 0 0 0 0 0 x3 y3 1
These six equations are solved here for the coefficients C.
These six coefficients can then be used to find the dest point (x',y') corresponding to any src point (x,y), according to the equations
x' = c[0]x + c[1]y + c[2] y' = c[3]x + c[4]y + c[5]
that are implemented in affineXformPt().
!!!!!!!!!!!!!!!!!! Very important !!!!!!!!!!!!!!!!!!!!!!
When the affine transform is composed from a set of simple operations such as translation, scaling and rotation, it is built in a form to convert from the un-transformed src point to the transformed dest point. However, when an affine transform is used on images, it is used in an inverted way: it converts from the transformed dest point to the un-transformed src point. So, for example, if you transform a boxa using transform A, to transform an image in the same way you must use the inverse of A.
For example, if you transform a boxa with a 3x3 affine matrix 'mat', the analogous image transformation must use 'matinv':
boxad = boxaAffineTransform(boxas, mat); affineInvertXform(mat, &matinv); pixd = pixAffine(pixs, matinv, L_BRING_IN_WHITE);
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Input: ptas (source 4 points; unprimed) ptad (transformed 4 points; primed) &vc (<return> vector of coefficients of transform) Return: 0 if OK; 1 on error
We have a set of 8 equations, describing the bilinear transformation that takes 4 points (ptas) into 4 other points (ptad). These equations are:
x1' = c[0]*x1 + c[1]*y1 + c[2]*x1*y1 + c[3] y1' = c[4]*x1 + c[5]*y1 + c[6]*x1*y1 + c[7] x2' = c[0]*x2 + c[1]*y2 + c[2]*x2*y2 + c[3] y2' = c[4]*x2 + c[5]*y2 + c[6]*x2*y2 + c[7] x3' = c[0]*x3 + c[1]*y3 + c[2]*x3*y3 + c[3] y3' = c[4]*x3 + c[5]*y3 + c[6]*x3*y3 + c[7] x4' = c[0]*x4 + c[1]*y4 + c[2]*x4*y4 + c[3] y4' = c[4]*x4 + c[5]*y4 + c[6]*x4*y4 + c[7]
This can be represented as
AC = B
where B and C are column vectors
B = [ x1' y1' x2' y2' x3' y3' x4' y4' ] C = [ c[0] c[1] c[2] c[3] c[4] c[5] c[6] c[7] ]
and A is the 8x8 matrix
x1 y1 x1*y1 1 0 0 0 0 0 0 0 0 x1 y1 x1*y1 1 x2 y2 x2*y2 1 0 0 0 0 0 0 0 0 x2 y2 x2*y2 1 x3 y3 x3*y3 1 0 0 0 0 0 0 0 0 x3 y3 x3*y3 1 x4 y4 x4*y4 1 0 0 0 0 0 0 0 0 x4 y4 x4*y4 1
These eight equations are solved here for the coefficients C.
These eight coefficients can then be used to find the mapping (x,y) --> (x',y'):
x' = c[0]x + c[1]y + c[2]xy + c[3] y' = c[4]x + c[5]y + c[6]xy + c[7]
that are implemented in bilinearXformSampledPt() and bilinearXFormPt().
LEPT_DLL l_int32 getCompositeParameters | ( | l_int32 | size, |
l_int32 * | psize1, | ||
l_int32 * | psize2, | ||
char ** | pnameh1, | ||
char ** | pnameh2, | ||
char ** | pnamev1, | ||
char ** | pnamev2 | ||
) |
Input: size &size1 (<optional return>=""> brick factor size) &size2 (<optional return>=""> comb factor size) &nameh1 (<optional return>=""> name of horiz brick) &nameh2 (<optional return>=""> name of horiz comb) &namev1 (<optional return>=""> name of vert brick) &namev2 (<optional return>=""> name of vert comb) Return: 0 if OK, 1 on error
Notes: (1) This uses the big lookup table at the top of this file. (2) All returned strings are copies that must be freed.
LEPT_DLL PTA* getCutPathForHole | ( | PIX * | pix, |
PTA * | pta, | ||
BOX * | boxinner, | ||
l_int32 * | pdir, | ||
l_int32 * | plen | ||
) |
Input: pix (of c.c.) pta (of outer border) boxinner (b.b. of hole path) &dir (direction (0-3), returned; only needed for debug) &len (length of path, returned) Return: pta of pts on cut path from the hole border to the outer border, including end points on both borders; or null on error
Notes: (1) If we don't find a path, we return a pta with no pts in it and len = 0. (2) The goal is to get a reasonably short path between the inner and outer borders, that goes entirely within the fg of the pix. This function is cheap-and-dirty, may fail for some holes in complex topologies such as those you might find in a moderately dark scanned halftone. If it fails to find a path to any particular hole, it gives a warning, and because that hole path is not included, the hole will not be rendered.
LEPT_DLL l_int32 getExtendedCompositeParameters | ( | l_int32 | size, |
l_int32 * | pn, | ||
l_int32 * | pextra, | ||
l_int32 * | pactualsize | ||
) |
getExtendedCompositeParameters()
Input: size (of linear Sel) &pn (<return> number of 63 wide convolutions) &pextra (<return> size of extra Sel) &actualsize (<optional return>=""> actual size used in operation) Return: 0 if OK, 1 on error
Notes: (1) The DWA implementation allows Sels to be used with hits up to 31 pixels from the origin, either horizontally or vertically. Larger Sels can be used if decomposed into a set of operations with Sels not exceeding 63 pixels in either width or height (and with the origin as close to the center of the Sel as possible). (2) This returns the decomposition of a linear Sel of length into a set of
Sels of length 63 plus an extra Sel of length . (3) For notation, let w == , n ==
, and e == . We have 1 < e < 63.
Then if w < 64, we have n = 0 and e = w. The general formula for w > 63 is: w = 63 + (n - 1) * 62 + (e - 1)
Where did this come from? Each successive convolution with a Sel of length L adds a total length (L - 1) to w. This accounts for using 62 for each additional Sel of size 63, and using (e - 1) for the additional Sel of size e.
Solving for n and e for w > 63: n = 1 + Int((w - 63) / 62) e = w - 63 - (n - 1) * 62 + 1
The extra part is decomposed into two factors f1 and f2, and the actual size of the extra part is e' = f1 * f2 Then the actual width is: w' = 63 + (n - 1) * 62 + f1 * f2 - 1
LEPT_DLL SARRAY* getFilenamesInDirectory | ( | const char * | dirname | ) |
Input: directory name Return: sarray of file names, or NULL on error
Notes: (1) The versions compiled under unix and cygwin use the POSIX C library commands for handling directories. For windows, there is a separate implementation. (2) It returns an array of filename tails; i.e., only the part of the path after the last slash. (3) Use of the d_type field of dirent is not portable: "According to POSIX, the dirent structure contains a field char d_name[] of unspecified size, with at most NAME_MAX characters preceding the terminating null character. Use of other fields will harm the portability of your programs." (4) As a consequence of (3), we note several things:
LEPT_DLL const char* getFormatExtension | ( | l_int32 | format | ) |
Input: format (integer) Return: extension (string), or null if format is out of range
Notes: (1) This string is NOT owned by the caller; it is just a pointer to a global string. Do not free it.
LEPT_DLL char* getImagelibVersions | ( | ) |
Return: string of version numbers (e.g., libgif 4.1.6 libjpeg 8b libpng 1.4.3 libtiff 3.9.4 zlib 1.2.5
Notes: (1) The caller has responsibility to free the memory.
LEPT_DLL l_int32 getImpliedFileFormat | ( | const char * | filename | ) |
Input: filename Return: output format, or IFF_UNKNOWN on error or invalid extension.
Notes: (1) This determines the output file format from the extension of the input filename.
LEPT_DLL char* getLeptonicaVersion | ( | ) |
Return: string of version number (e.g., 'leptonica-1.68')
Notes: (1) The caller has responsibility to free the memory.
LEPT_DLL l_float32 getLogBase2 | ( | l_int32 | val, |
l_float32 * | logtab | ||
) |
LEPT_DLL l_uint32 getMorphBorderPixelColor | ( | l_int32 | type, |
l_int32 | depth | ||
) |
Input: type (L_MORPH_DILATE, L_MORPH_ERODE) depth (of pix) Return: color of border pixels for this operation
LEPT_DLL SARRAY* getNumberedPathnamesInDirectory | ( | const char * | dirname, |
const char * | substr, | ||
l_int32 | numpre, | ||
l_int32 | numpost, | ||
l_int32 | maxnum | ||
) |
getNumberedPathnamesInDirectory()
Input: directory name substr (<optional> substring filter on filenames; can be NULL) numpre (number of characters in name before number) numpost (number of characters in name after the number, up to a dot before an extension) maxnum (only consider page numbers up to this value) Return: sarray of numbered pathnames, or NULL on error
Notes: (1) Returns the full pathnames of the numbered filenames in the directory. The number in the filename is the index into the sarray. For indices for which there are no filenames, an empty string ("") is placed into the sarray. This makes reading numbered files very simple. For example, the image whose filename includes number N can be retrieved using pixReadIndexed(sa, N); (2) If is not NULL, only filenames that contain the substring can be included. If is NULL, all matching filenames are used. (3) If no numbered files are found, it returns an empty sarray, with no initialized strings. (4) It is assumed that the page number is contained within the basename (the filename without directory or extension). is the number of characters in the basename preceeding the actual page number; is the number following the page number, up to either the end of the basename or a ".", whichever comes first. (5) This is useful when all filenames contain numbers that are not necessarily consecutive. 0-padding is not required. (6) To use a O(n) matching algorithm, the largest page number is found and two internal arrays of this size are created. This maximum is constrained not to exceed , to make sure that an unrealistically large number is not accidentally used to determine the array sizes.
LEPT_DLL void getOctcubeIndexFromRGB | ( | l_int32 | rval, |
l_int32 | gval, | ||
l_int32 | bval, | ||
l_uint32 * | rtab, | ||
l_uint32 * | gtab, | ||
l_uint32 * | btab, | ||
l_uint32 * | pindex | ||
) |
Input: rval, gval, bval rtab, gtab, btab (generated with makeRGBToIndexTables()) &index (<return>) Return: void
Note: no error checking!
Input: ptas (source 4 points; unprimed) ptad (transformed 4 points; primed) &vc (<return> vector of coefficients of transform) Return: 0 if OK; 1 on error
We have a set of 8 equations, describing the projective transformation that takes 4 points (ptas) into 4 other points (ptad). These equations are:
x1' = (c[0]*x1 + c[1]*y1 + c[2]) / (c[6]*x1 + c[7]*y1 + 1) y1' = (c[3]*x1 + c[4]*y1 + c[5]) / (c[6]*x1 + c[7]*y1 + 1) x2' = (c[0]*x2 + c[1]*y2 + c[2]) / (c[6]*x2 + c[7]*y2 + 1) y2' = (c[3]*x2 + c[4]*y2 + c[5]) / (c[6]*x2 + c[7]*y2 + 1) x3' = (c[0]*x3 + c[1]*y3 + c[2]) / (c[6]*x3 + c[7]*y3 + 1) y3' = (c[3]*x3 + c[4]*y3 + c[5]) / (c[6]*x3 + c[7]*y3 + 1) x4' = (c[0]*x4 + c[1]*y4 + c[2]) / (c[6]*x4 + c[7]*y4 + 1) y4' = (c[3]*x4 + c[4]*y4 + c[5]) / (c[6]*x4 + c[7]*y4 + 1)
Multiplying both sides of each eqn by the denominator, we get
AC = B
where B and C are column vectors
B = [ x1' y1' x2' y2' x3' y3' x4' y4' ] C = [ c[0] c[1] c[2] c[3] c[4] c[5] c[6] c[7] ]
and A is the 8x8 matrix
x1 y1 1 0 0 0 -x1*x1' -y1*x1' 0 0 0 x1 y1 1 -x1*y1' -y1*y1' x2 y2 1 0 0 0 -x2*x2' -y2*x2' 0 0 0 x2 y2 1 -x2*y2' -y2*y2' x3 y3 1 0 0 0 -x3*x3' -y3*x3' 0 0 0 x3 y3 1 -x3*y3' -y3*y3' x4 y4 1 0 0 0 -x4*x4' -y4*x4' 0 0 0 x4 y4 1 -x4*y4' -y4*y4'
These eight equations are solved here for the coefficients C.
These eight coefficients can then be used to find the mapping (x,y) --> (x',y'):
x' = (c[0]x + c[1]y + c[2]) / (c[6]x + c[7]y + 1) y' = (c[3]x + c[4]y + c[5]) / (c[6]x + c[7]y + 1)
that is implemented in projectiveXformSampled() and projectiveXFormInterpolated().
Input: w (image width, pixels) h (image height, pixels) fillfract (fraction in linear dimension of full page, not to be exceeded; use 0 for default) Return: 0 if OK, 1 on error
Input: w (image width, pixels) h (image height, pixels) fillfract (fraction in linear dimension of full page, not to be exceeded; use 0 for default) Return: 0 if OK, 1 on error
LEPT_DLL void getScaledParametersPS | ( | BOX * | box, |
l_int32 | wpix, | ||
l_int32 | hpix, | ||
l_int32 | res, | ||
l_float32 | scale, | ||
l_float32 * | pxpt, | ||
l_float32 * | pypt, | ||
l_float32 * | pwpt, | ||
l_float32 * | phpt | ||
) |
Input: box (<optional> location of image in mils; with (x,y) being the LL corner) wpix (pix width in pixels) hpix (pix height in pixels) res (of printer; use 0 for default) scale (use 1.0 or 0.0 for no scaling) &xpt (location of llx in pts) &ypt (location of lly in pts) &wpt (image width in pts) &hpt (image height in pts) Return: void (no arg checking)
Notes: (1) The image is always scaled, depending on res and scale. (2) If no box, the image is centered on the page. (3) If there is a box, the image is placed within it.
LEPT_DLL SARRAY* getSortedPathnamesInDirectory | ( | const char * | dirname, |
const char * | substr, | ||
l_int32 | firstpage, | ||
l_int32 | npages | ||
) |
getSortedPathnamesInDirectory()
Input: directory name substr (<optional> substring filter on filenames; can be NULL) firstpage (0-based) npages (use 0 for all to the end) Return: sarray of sorted pathnames, or NULL on error
Notes: (1) If is not NULL, only filenames that contain the substring can be returned. If == NULL, none of the filenames are filtered out. (2) The files in the directory, after optional filtering by the substring, are lexically sorted in increasing order. The full pathnames are returned for the requested sequence. If no files are found after filtering, returns an empty sarray.
LEPT_DLL l_int32 getTiffResolution | ( | FILE * | fp, |
l_int32 * | pxres, | ||
l_int32 * | pyres | ||
) |
LEPT_DLL l_int32 gplotAddPlot | ( | GPLOT * | gplot, |
NUMA * | nax, | ||
NUMA * | nay, | ||
l_int32 | plotstyle, | ||
const char * | plottitle | ||
) |
Input: gplot nax (<optional> numa: set to null for Y_VS_I; required for Y_VS_X) nay (numa: required for both Y_VS_I and Y_VS_X) plotstyle (GPLOT_LINES, GPLOT_POINTS, GPLOT_IMPULSES, GPLOT_LINESPOINTS, GPLOT_DOTS) plottitle (<optional> title for individual plot) Return: 0 if OK, 1 on error
Notes: (1) There are 2 options for (x,y) values: o To plot an array vs the index, set nax = NULL. o To plot one array vs another, use both nax and nay. (2) If nax is defined, it must be the same size as nay. (3) The 'plottitle' string can have spaces, double quotes and backquotes, but not single quotes.
LEPT_DLL GPLOT* gplotCreate | ( | const char * | rootname, |
l_int32 | outformat, | ||
const char * | title, | ||
const char * | xlabel, | ||
const char * | ylabel | ||
) |
Input: rootname (root for all output files) outformat (GPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_X11, GPLOT_LATEX) title (<optional> overall title) xlabel (<optional> x axis label) ylabel (<optional> y axis label) Return: gplot, or null on error
Notes: (1) This initializes the plot. (2) The 'title', 'xlabel' and 'ylabel' strings can have spaces, double quotes and backquotes, but not single quotes.
LEPT_DLL void gplotDestroy | ( | GPLOT ** | pgplot | ) |
Input: &gplot (<to be="" nulled>="">) Return: void
LEPT_DLL l_int32 gplotGenCommandFile | ( | GPLOT * | gplot | ) |
Input: gplot Return: 0 if OK, 1 on error
LEPT_DLL l_int32 gplotGenDataFiles | ( | GPLOT * | gplot | ) |
Input: gplot Return: 0 if OK, 1 on error
LEPT_DLL l_int32 gplotMakeOutput | ( | GPLOT * | gplot | ) |
Input: gplot Return: 0 if OK; 1 on error
Notes: (1) This uses gplot and the new arrays to add a plot to the output, by writing a new data file and appending the appropriate plot commands to the command file. (2) The gnuplot program for windows is wgnuplot.exe. The standard gp426win32 distribution does not have a X11 terminal.
Input: filename Return: gplot, or NULL on error
LEPT_DLL l_int32 gplotSetScaling | ( | GPLOT * | gplot, |
l_int32 | scaling | ||
) |
Input: gplot scaling (GPLOT_LINEAR_SCALE, GPLOT_LOG_SCALE_X, GPLOT_LOG_SCALE_Y, GPLOT_LOG_SCALE_X_Y) Return: 0 if OK; 1 on error
Notes: (1) By default, the x and y axis scaling is linear. (2) Call this function to set semi-log or log-log scaling.
LEPT_DLL l_int32 gplotSimple1 | ( | NUMA * | na, |
l_int32 | outformat, | ||
const char * | outroot, | ||
const char * | title | ||
) |
Input: na (numa; plot Y_VS_I) outformat (GPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_X11, GPLOT_LATEX) outroot (root of output files) title (<optional>, can be NULL) Return: 0 if OK, 1 on error
Notes: (1) This gives a line plot of a numa, where the array value is plotted vs the array index. The plot is generated in the specified output format; the title is optional. (2) When calling this function more than once, be sure the outroot strings are different; otherwise, you will overwrite the output files.
LEPT_DLL l_int32 gplotSimple2 | ( | NUMA * | na1, |
NUMA * | na2, | ||
l_int32 | outformat, | ||
const char * | outroot, | ||
const char * | title | ||
) |
Input: na1 (numa; we plot Y_VS_I) na2 (ditto) outformat (GPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_X11, GPLOT_LATEX) outroot (root of output files) title (<optional>) Return: 0 if OK, 1 on error
Notes: (1) This gives a line plot of two numa, where the array values are each plotted vs the array index. The plot is generated in the specified output format; the title is optional. (2) When calling this function more than once, be sure the outroot strings are different; otherwise, you will overwrite the output files.
LEPT_DLL l_int32 gplotSimpleN | ( | NUMAA * | naa, |
l_int32 | outformat, | ||
const char * | outroot, | ||
const char * | title | ||
) |
Input: naa (numaa; we plot Y_VS_I for each numa) outformat (GPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_X11, GPLOT_LATEX) outroot (root of output files) title (<optional>) Return: 0 if OK, 1 on error
Notes: (1) This gives a line plot of all numas in a numaa (array of numa), where the array values are each plotted vs the array index. The plot is generated in the specified output format; the title is optional. (2) When calling this function more than once, be sure the outroot strings are different; otherwise, you will overwrite the output files.
LEPT_DLL l_int32 gplotWrite | ( | const char * | filename, |
GPLOT * | gplot | ||
) |
Input: filename gplot Return: 0 if OK; 1 on error
LEPT_DLL l_int32 ioFormatTest | ( | const char * | filename | ) |
Input: filename (input file) Return: 0 if OK; 1 on error or if the test fails
Notes: (1) This writes and reads a set of output files losslessly in different formats to /tmp, and tests that the result before and after is unchanged. (2) This should work properly on input images of any depth, with and without colormaps. (3) All supported formats are tested for bmp, png, tiff and non-ascii pnm. Ascii pnm also works (but who'd ever want to use it?) We allow 2 bpp bmp, although it's not supported elsewhere. And we don't support reading 16 bpp png, although this can be turned on in pngio.c. (4) This silently skips png or tiff testing if HAVE_LIBPNG or HAVE_LIBTIFF are 0, respectively.
Input: pixaa (one pixa for each class) &pna (<return> number of samples used to build each composite) &ptat (<return> centroids of bordered composites) Return: pixad (accumulated sum of samples in each class), or null on error
Input: jbclasser pixs (of input page) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 jbAddPageComponents | ( | JBCLASSER * | classer, |
PIX * | pixs, | ||
BOXA * | boxas, | ||
PIXA * | pixas | ||
) |
Input: jbclasser pixs (of input page) boxas (b.b. of components for this page) pixas (components for this page) Return: 0 if OK; 1 on error
Notes: (1) If there are no components on the page, we don't require input of empty boxas or pixas, although that's the typical situation.
LEPT_DLL l_int32 jbAddPages | ( | JBCLASSER * | classer, |
SARRAY * | safiles | ||
) |
Input: jbclasser safiles (of page image file names) Return: 0 if OK; 1 on error
Note: (1) jbclasser makes a copy of the array of file names. (2) The caller is still responsible for destroying the input array.
LEPT_DLL JBCLASSER* jbClasserCreate | ( | l_int32 | method, |
l_int32 | components | ||
) |
Input: method (JB_RANKHAUS, JB_CORRELATION) components (JB_CONN_COMPS, JB_CHARACTERS, JB_WORDS) Return: jbclasser, or null on error
LEPT_DLL void jbClasserDestroy | ( | JBCLASSER ** | pclasser | ) |
Input: jbclasser boxa (of new components for classification) pixas (of new components for classification) Return: 0 if OK; 1 on error
Input: jbclasser boxa (of new components for classification) pixas (of new components for classification) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 jbCorrelation | ( | const char * | dirin, |
l_float32 | thresh, | ||
l_float32 | weight, | ||
l_int32 | components, | ||
const char * | rootname, | ||
l_int32 | firstpage, | ||
l_int32 | npages, | ||
l_int32 | renderflag | ||
) |
Input: dirin (directory of input images) thresh (typically ~0.8) weight (typically ~0.6) components (JB_CONN_COMPS, JB_CHARACTERS, JB_WORDS) rootname (for output files) firstpage (0-based) npages (use 0 for all pages in dirin) renderflag (1 to render from templates; 0 to skip) Return: 0 if OK, 1 on error
Notes: (1) The images must be 1 bpp. If they are not, you can convert them using convertFilesTo1bpp(). (2) See prog/jbcorrelation for generating more output (e.g., for debugging)
LEPT_DLL JBCLASSER* jbCorrelationInit | ( | l_int32 | components, |
l_int32 | maxwidth, | ||
l_int32 | maxheight, | ||
l_float32 | thresh, | ||
l_float32 | weightfactor | ||
) |
Input: components (JB_CONN_COMPS, JB_CHARACTERS, JB_WORDS) maxwidth (of component; use 0 for default) maxheight (of component; use 0 for default) thresh (value for correlation score: in [0.4 - 0.98]) weightfactor (corrects thresh for thick characters [0.0 - 1.0]) Return: jbclasser if OK; NULL on error
Notes: (1) For scanned text, suggested input values are: thresh ~ [0.8 - 0.85] weightfactor ~ [0.5 - 0.6] (2) For electronically generated fonts (e.g., rasterized pdf), a very high thresh (e.g., 0.95) will not cause a significant increase in the number of classes.
LEPT_DLL JBCLASSER* jbCorrelationInitWithoutComponents | ( | l_int32 | components, |
l_int32 | maxwidth, | ||
l_int32 | maxheight, | ||
l_float32 | thresh, | ||
l_float32 | weightfactor | ||
) |
jbCorrelationInitWithoutComponents()
Input: same as jbCorrelationInit Output: same as jbCorrelationInit
Note: acts the same as jbCorrelationInit(), but the resulting object doesn't keep a list of all the components.
LEPT_DLL void jbDataDestroy | ( | JBDATA ** | pdata | ) |
LEPT_DLL JBDATA* jbDataRead | ( | const char * | rootname | ) |
Input: rootname (for template and data files) Return: jbdata, or NULL on error
LEPT_DLL PIXA* jbDataRender | ( | JBDATA * | data, |
l_int32 | debugflag | ||
) |
Input: jbdata debugflag (if TRUE, writes into 2 bpp pix and adds component outlines in color) Return: pixa (reconstruction of original images, using templates) or null on error
LEPT_DLL JBDATA* jbDataSave | ( | JBCLASSER * | classer | ) |
Input: jbclasser latticew, latticeh (cell size used to store each connected component in the composite) Return: jbdata, or null on error
Notes: (1) This routine stores the jbig2-type data required for generating a lossy jbig2 version of the image. It can be losslessly written to (and read from) two files. (2) It generates and stores the mosaic of templates. (3) It clones the Numa and Pta arrays, so these must all be destroyed by the caller. (4) Input 0 to use the default values for latticew and/or latticeh,
LEPT_DLL l_int32 jbDataWrite | ( | const char * | rootout, |
JBDATA * | jbdata | ||
) |
Input: rootname (for output files; everything but the extension) jbdata Return: 0 if OK, 1 on error
Notes: (1) Serialization function that writes data in jbdata to file.
LEPT_DLL l_int32 jbGetComponents | ( | PIX * | pixs, |
l_int32 | components, | ||
l_int32 | maxwidth, | ||
l_int32 | maxheight, | ||
BOXA ** | pboxad, | ||
PIXA ** | ppixad | ||
) |
Input: pixs (1 bpp) components (JB_CONN_COMPS, JB_CHARACTERS, JB_WORDS) maxwidth, maxheight (of saved components; larger are discarded) &pboxa (<return> b.b. of component items) &ppixa (<return> component items) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 jbGetLLCorners | ( | JBCLASSER * | classer | ) |
Input: jbclasser Return: 0 if OK, 1 on error
Notes: (1) This computes the ptall field, which has the global LL corners, adjusted for each specific component, so that each component can be replaced by the template for its class and have the centroid in the template in the same position as the centroid of the original connected component. It is important that this be done properly to avoid a wavy baseline in the result. (2) It is computed here from the corresponding UL corners, where the input templates and stored instances are all bordered. This should be done after all pages have been processed. (3) For proper substitution, the templates whose LL corners are placed in these locations must be UN-bordered. This is available for a realistic jbig2 encoder, which would (1) encode each template without a border, and (2) encode the position using the LL corner (rather than the UL corner) because the difference between y-values of successive instances is typically close to zero.
Input: jbclasser pixs (full res image) boxa (of c.c. bounding rectangles for this page) Return: 0 if OK, 1 on error
Notes: (1) This computes the ptaul field, which has the global UL corners, adjusted for each specific component, so that each component can be replaced by the template for its class and have the centroid in the template in the same position as the centroid of the original connected component. It is important that this be done properly to avoid a wavy baseline in the result. (2) The array fields ptac and ptact give the centroids of those components relative to the UL corner of each component. Here, we compute the difference in each component, round to nearest integer, and correct the box->x and box->y by the appropriate integral difference. (3) The templates and stored instances are all bordered.
LEPT_DLL l_int32 jbRankHaus | ( | const char * | dirin, |
l_int32 | size, | ||
l_float32 | rank, | ||
l_int32 | components, | ||
const char * | rootname, | ||
l_int32 | firstpage, | ||
l_int32 | npages, | ||
l_int32 | renderflag | ||
) |
Input: dirin (directory of input images) size (of Sel used for dilation; typ. 2) rank (rank value of match; typ. 0.97) components (JB_CONN_COMPS, JB_CHARACTERS, JB_WORDS) rootname (for output files) firstpage (0-based) npages (use 0 for all pages in dirin) renderflag (1 to render from templates; 0 to skip) Return: 0 if OK, 1 on error
Notes: (1) See prog/jbrankhaus for generating more output (e.g., for debugging)
LEPT_DLL JBCLASSER* jbRankHausInit | ( | l_int32 | components, |
l_int32 | maxwidth, | ||
l_int32 | maxheight, | ||
l_int32 | size, | ||
l_float32 | rank | ||
) |
Input: components (JB_CONN_COMPS, JB_CHARACTERS, JB_WORDS) maxwidth (of component; use 0 for default) maxheight (of component; use 0 for default) size (of square structuring element; 2, representing 2x2 sel, is necessary for reasonable accuracy of small components; combine this with rank ~ 0.97 to avoid undue class expansion) rank (rank val of match, each way; in [0.5 - 1.0]; when using size = 2, 0.97 is a reasonable value) Return: jbclasser if OK; NULL on error
LEPT_DLL PIXA* jbTemplatesFromComposites | ( | PIXA * | pixac, |
NUMA * | na | ||
) |
Input: pixac (one pix of composites for each class) na (number of samples used for each class composite) Return: pixad (8 bpp templates for each class), or null on error
LEPT_DLL JBCLASSER* jbWordsInTextlines | ( | const char * | dirin, |
l_int32 | reduction, | ||
l_int32 | maxwidth, | ||
l_int32 | maxheight, | ||
l_float32 | thresh, | ||
l_float32 | weight, | ||
NUMA ** | pnatl, | ||
l_int32 | firstpage, | ||
l_int32 | npages | ||
) |
Input: dirin (directory of input pages) reduction (1 for full res; 2 for half-res) maxwidth (of word mask components, to be kept) maxheight (of word mask components, to be kept) thresh (on correlation; 0.80 is reasonable) weight (for handling thick text; 0.6 is reasonable) natl (<return> numa with textline index for each component) firstpage (0-based) npages (use 0 for all pages in dirin) Return: classer (for the set of pages)
Notes: (1) This is a high-level function. See prog/jbwords for example of usage. (2) Typically, words can be found reasonably well at a resolution of about 150 ppi. For highest accuracy, you should use 300 ppi. Assuming that the input images are 300 ppi, use reduction = 1 for finding words at full res, and reduction = 2 for finding them at 150 ppi.
LEPT_DLL L_KERNEL* kernelCopy | ( | L_KERNEL * | kels | ) |
Input: kels (source kernel) Return: keld (copy of kels), or null on error
LEPT_DLL L_KERNEL* kernelCreate | ( | l_int32 | height, |
l_int32 | width | ||
) |
Input: height, width Return: kernel, or null on error
Notes: (1) kernelCreate() initializes all values to 0. (2) After this call, (cy,cx) and nonzero data values must be assigned.
LEPT_DLL L_KERNEL* kernelCreateFromFile | ( | const char * | filename | ) |
Input: filename Return: kernel, or null on error
Notes: (1) The file contains, in the following order:
Input: pix cy, cx (origin of kernel) Return: kernel, or null on error
Notes: (1) The origin must be positive and within the dimensions of the pix.
LEPT_DLL L_KERNEL* kernelCreateFromString | ( | l_int32 | h, |
l_int32 | w, | ||
l_int32 | cy, | ||
l_int32 | cx, | ||
const char * | kdata | ||
) |
Input: height, width cy, cx (origin) kdata Return: kernel of the given size, or null on error
Notes: (1) The data is an array of chars, in row-major order, giving space separated integers in the range [-255 ... 255]. (2) The only other formatting limitation is that you must leave space between the last number in each row and the double-quote. If possible, it's also nice to have each line in the string represent a line in the kernel; e.g., static const char *kdata = " 20 50 20 " " 70 140 70 " " 20 50 20 ";
LEPT_DLL void kernelDestroy | ( | L_KERNEL ** | pkel | ) |
Input: &kel (<to be="" nulled>="">) Return: void
Input: kernel size (of grid interiors; odd; minimum size of 17 is enforced) gthick (grid thickness; minimum size of 2 is enforced) Return: pix (display of kernel), or null on error
Notes: (1) This gives a visual representation of a kernel. (2) The origin is outlined in red.
Input: kel row col &val Return: 0 if OK; 1 on error
Input: kernel &min (<optional return>=""> minimum value) &max (<optional return>=""> maximum value) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 kernelGetParameters | ( | L_KERNEL * | kel, |
l_int32 * | psy, | ||
l_int32 * | psx, | ||
l_int32 * | pcy, | ||
l_int32 * | pcx | ||
) |
Input: kernel &sy, &sx, &cy, &cx (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 kernelGetSum | ( | L_KERNEL * | kel, |
l_float32 * | psum | ||
) |
Input: kernel &sum (<return> sum of all kernel values) Return: 0 if OK, 1 on error
LEPT_DLL L_KERNEL* kernelInvert | ( | L_KERNEL * | kels | ) |
Input: kels (source kel, to be inverted) Return: keld (spatially inverted, about the origin), or null on error
Notes: (1) For convolution, the kernel is spatially inverted before a "correlation" operation is done between the kernel and the image.
LEPT_DLL L_KERNEL* kernelNormalize | ( | L_KERNEL * | kels, |
l_float32 | normsum | ||
) |
Input: kels (source kel, to be normalized) normsum (desired sum of elements in keld) Return: keld (normalized version of kels), or null on error or if sum of elements is very close to 0)
Notes: (1) If the sum of kernel elements is close to 0, do not try to calculate the normalized kernel. Instead, return a copy of the input kernel, with an error message.
LEPT_DLL L_KERNEL* kernelRead | ( | const char * | fname | ) |
Input: filename Return: kernel, or null on error
LEPT_DLL L_KERNEL* kernelReadStream | ( | FILE * | fp | ) |
Input: stream Return: kernel, or null on error
Input: kernel row col val Return: 0 if OK; 1 on error
Input: kernel cy, cx Return: 0 if OK; 1 on error
LEPT_DLL l_int32 kernelWrite | ( | const char * | fname, |
L_KERNEL * | kel | ||
) |
Input: fname (output file) kernel Return: 0 if OK, 1 on error
LEPT_DLL l_int32 kernelWriteStream | ( | FILE * | fp, |
L_KERNEL * | kel | ||
) |
Input: stream kel Return: 0 if OK, 1 on error
LEPT_DLL l_uint8* l_binaryCopy | ( | l_uint8 * | datas, |
size_t | size | ||
) |
Input: datas size (of data array) Return: datad (on heap), or null on error
Notes: (1) We add 4 bytes to the zeroed output because in some cases (e.g., string handling) it is important to have the data be null terminated. This guarantees that after the memcpy, the result is automatically null terminated.
LEPT_DLL l_uint8* l_binaryRead | ( | const char * | filename, |
size_t * | pnbytes | ||
) |
Input: filename &nbytes (<return> number of bytes read) Return: data, or null on error
LEPT_DLL l_uint8* l_binaryReadStream | ( | FILE * | fp, |
size_t * | pnbytes | ||
) |
Input: stream &nbytes (<return> number of bytes read) Return: null-terminated array, or null on error (reading 0 bytes is not an error)
Notes: (1) The returned array is terminated with a null byte so that it can be used to read ascii data into a proper C string. (2) Side effect: this re-positions the stream ptr to the beginning of the file.
LEPT_DLL l_int32 l_binaryWrite | ( | const char * | filename, |
const char * | operation, | ||
void * | data, | ||
size_t | nbytes | ||
) |
Input: filename (output) operation ("w" for write; "a" for append) data (binary data to be written) nbytes (size of data array) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 l_byteaAppendData | ( | L_BYTEA * | ba, |
l_uint8 * | newdata, | ||
size_t | newbytes | ||
) |
Input: ba newdata (byte array to be appended) size (size of data array) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 l_byteaAppendString | ( | L_BYTEA * | ba, |
char * | str | ||
) |
Input: ba str (null-terminated string to be appended) Return: 0 if OK, 1 on error
LEPT_DLL L_BYTEA* l_byteaCopy | ( | L_BYTEA * | bas, |
l_int32 | copyflag | ||
) |
Input: bas (source lba) copyflag (L_COPY, L_CLONE) Return: clone or copy of bas, or null on error
Notes: (1) If cloning, up the refcount and return a ptr to .
LEPT_DLL l_uint8* l_byteaCopyData | ( | L_BYTEA * | ba, |
size_t * | psize | ||
) |
Input: ba &size (<returned> size of data in lba) Return: copy of data in use in the data array, or null on error.
Notes: (1) The returned data is owned by the caller. The input still owns the original data array.
LEPT_DLL L_BYTEA* l_byteaCreate | ( | size_t | nbytes | ) |
Input: n (determines initial size of data array) Return: l_bytea, or null on error
Notes: (1) The allocated array is n + 1 bytes. This allows room for null termination.
LEPT_DLL void l_byteaDestroy | ( | L_BYTEA ** | pba | ) |
Input: &ba (<will be="" set="" to="" null="" before="" returning>="">) Return: void
Notes: (1) Decrements the ref count and, if 0, destroys the lba. (2) Always nulls the input ptr. (3) If the data has been previously removed, the lba will have been nulled, so this will do nothing.
LEPT_DLL l_int32 l_byteaExtendArrayToSize | ( | L_BYTEA * | ba, |
size_t | size | ||
) |
Input: ba size (new size of lba data array) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 l_byteaFindEachSequence | ( | L_BYTEA * | ba, |
l_uint8 * | sequence, | ||
l_int32 | seqlen, | ||
L_DNA ** | pda | ||
) |
Input: ba sequence (subarray of bytes to find in data) seqlen (length of sequence, in bytes) &da (<return> byte positions of each occurrence of ) Return: 0 if OK, 1 on error
LEPT_DLL l_uint8* l_byteaGetData | ( | L_BYTEA * | ba, |
size_t * | psize | ||
) |
Input: ba &size (<returned> size of data in lba) Return: ptr to existing data array, or NULL on error
Notes: (1) The returned ptr is owned by . Do not free it!
LEPT_DLL size_t l_byteaGetSize | ( | L_BYTEA * | ba | ) |
Input: ba Return: size of stored byte array, or 0 on error
LEPT_DLL L_BYTEA* l_byteaInitFromFile | ( | const char * | fname | ) |
Input: fname Return: l_bytea, or null on error
LEPT_DLL L_BYTEA* l_byteaInitFromMem | ( | l_uint8 * | data, |
size_t | size | ||
) |
Input: data (to be copied to the array) size (amount of data) Return: l_bytea, or null on error
LEPT_DLL L_BYTEA* l_byteaInitFromStream | ( | FILE * | fp | ) |
Input: stream Return: l_bytea, or null on error
LEPT_DLL l_int32 l_byteaJoin | ( | L_BYTEA * | ba1, |
L_BYTEA ** | pba2 | ||
) |
Input: ba1 &ba2 (data array is added to the one in ba1, and then ba2 is destroyed) Return: 0 if OK, 1 on error
Notes: (1) It is a no-op, not an error, for to be null.
LEPT_DLL l_int32 l_byteaSplit | ( | L_BYTEA * | ba1, |
size_t | splitloc, | ||
L_BYTEA ** | pba2 | ||
) |
Input: ba1 (lba to split; array bytes nulled beyond the split loc) splitloc (location in ba1 to split; ba2 begins there) &ba2 (<return> with data starting at splitloc) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 l_byteaWrite | ( | const char * | fname, |
L_BYTEA * | ba, | ||
size_t | startloc, | ||
size_t | endloc | ||
) |
Input: fname (output file) ba startloc (first byte to output) endloc (last byte to output; use 0 to write to the end of the data array) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 l_byteaWriteStream | ( | FILE * | fp, |
L_BYTEA * | ba, | ||
size_t | startloc, | ||
size_t | endloc | ||
) |
Input: stream (opened for binary write) ba startloc (first byte to output) endloc (last byte to output; use 0 to write to the end of the data array) Return: 0 if OK, 1 on error
LEPT_DLL void l_chooseDisplayProg | ( | l_int32 | selection | ) |
LEPT_DLL void l_clearDataBit | ( | void * | line, |
l_int32 | n | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) Return: void
Action: sets the (1-bit) pixel to 0
LEPT_DLL void l_clearDataDibit | ( | void * | line, |
l_int32 | n | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) Return: void
Action: sets the (2-bit) pixel to 0
LEPT_DLL void l_clearDataQbit | ( | void * | line, |
l_int32 | n | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) Return: void
Action: sets the (4-bit) pixel to 0
Input: daa da (to be added) copyflag (L_INSERT, L_COPY, L_CLONE) Return: 0 if OK, 1 on error
Input: daa index (of l_dna within l_dnaa) val (number to be added; stored as a double) Return: 0 if OK, 1 on error
Notes: (1) Adds to an existing l_dna only.
LEPT_DLL L_DNAA* l_dnaaCreate | ( | l_int32 | n | ) |
Input: size of l_dna ptr array to be alloc'd (0 for default) Return: daa, or null on error
LEPT_DLL l_int32 l_dnaAddNumber | ( | L_DNA * | da, |
l_float64 | val | ||
) |
Input: da val (float or int to be added; stored as a float) Return: 0 if OK, 1 on error
LEPT_DLL void l_dnaaDestroy | ( | L_DNAA ** | pdaa | ) |
Input: &dnaa <to be="" nulled="" if="" it="" exists>=""> Return: void
LEPT_DLL l_int32 l_dnaaExtendArray | ( | L_DNAA * | daa | ) |
Input: daa Return: 0 if OK, 1 on error
LEPT_DLL l_int32 l_dnaaGetCount | ( | L_DNAA * | daa | ) |
Input: daa Return: count (number of l_dna), or 0 if no l_dna or on error
Input: daa index (to the index-th l_dna) accessflag (L_COPY or L_CLONE) Return: l_dna, or null on error
LEPT_DLL l_int32 l_dnaaGetDnaCount | ( | L_DNAA * | daa, |
l_int32 | index | ||
) |
Input: daa index (of l_dna in daa) Return: count of numbers in the referenced l_dna, or 0 on error.
LEPT_DLL l_int32 l_dnaaGetNumberCount | ( | L_DNAA * | daa | ) |
Input: daa Return: count (total number of numbers in the l_dnaa), or 0 if no numbers or on error
Input: daa i (index of l_dna within l_dnaa) j (index into l_dna) val (<return> double value) Return: 0 if OK, 1 on error
LEPT_DLL L_DNAA* l_dnaaRead | ( | const char * | filename | ) |
Input: filename Return: daa, or null on error
LEPT_DLL L_DNAA* l_dnaaReadStream | ( | FILE * | fp | ) |
Input: stream Return: daa, or null on error
Input: daa index (to the index-th l_dna) l_dna (insert and replace any existing one) Return: 0 if OK, 1 on error
Notes: (1) Any existing l_dna is destroyed, and the input one is inserted in its place. (2) If the index is invalid, return 1 (error)
LEPT_DLL l_int32 l_dnaaWrite | ( | const char * | filename, |
L_DNAA * | daa | ||
) |
Input: filename, daa Return: 0 if OK, 1 on error
LEPT_DLL l_int32 l_dnaaWriteStream | ( | FILE * | fp, |
L_DNAA * | daa | ||
) |
Input: stream, daa Return: 0 if OK, 1 on error
LEPT_DLL l_int32 l_dnaChangeRefcount | ( | L_DNA * | da, |
l_int32 | delta | ||
) |
l_dnaChangeRefCount()
Input: da delta (change to be applied) Return: 0 if OK, 1 on error
LEPT_DLL L_DNA* l_dnaClone | ( | L_DNA * | da | ) |
Input: da Return: ptr to same l_dna, or null on error
LEPT_DLL NUMA* l_dnaConvertToNuma | ( | L_DNA * | da | ) |
Input: da Return: na, or null on error
Input: da Return: copy of l_dna, or null on error
LEPT_DLL l_int32 l_dnaCopyXParameters | ( | L_DNA * | dad, |
L_DNA * | das | ||
) |
Input: dad (destination DNuma) das (source DNuma) Return: 0 if OK, 1 on error
LEPT_DLL L_DNA* l_dnaCreate | ( | l_int32 | n | ) |
Input: size of number array to be alloc'd (0 for default) Return: da, or null on error
Input: da (float) size (of the array) copyflag (L_INSERT or L_COPY) Return: da, or null on error
Notes: (1) With L_INSERT, ownership of the input array is transferred to the returned l_dna, and all elements are considered to be valid.
LEPT_DLL L_DNA* l_dnaCreateFromIArray | ( | l_int32 * | iarray, |
l_int32 | size | ||
) |
Input: iarray (integer) size (of the array) Return: da, or null on error
Notes: (1) We can't insert this int array into the l_dna, because a l_dna takes a double array. So this just copies the data from the input array into the l_dna. The input array continues to be owned by the caller.
LEPT_DLL void l_dnaDestroy | ( | L_DNA ** | pda | ) |
Input: &da (<to be="" nulled="" if="" it="" exists>="">) Return: void
Notes: (1) Decrements the ref count and, if 0, destroys the l_dna. (2) Always nulls the input ptr.
LEPT_DLL l_int32 l_dnaEmpty | ( | L_DNA * | da | ) |
Input: da Return: 0 if OK; 1 on error
Notes: (1) This does not change the allocation of the array. It just clears the number of stored numbers, so that the array appears to be empty.
LEPT_DLL l_int32 l_dnaExtendArray | ( | L_DNA * | da | ) |
Input: da Return: 0 if OK, 1 on error
LEPT_DLL l_int32 l_dnaGetCount | ( | L_DNA * | da | ) |
Input: da Return: count, or 0 if no numbers or on error
LEPT_DLL l_float64* l_dnaGetDArray | ( | L_DNA * | da, |
l_int32 | copyflag | ||
) |
Input: da copyflag (L_NOCOPY or L_COPY) Return: either the bare internal array or a copy of it, or null on error
Notes: (1) If copyflag == L_COPY, it makes a copy which the caller is responsible for freeing. Otherwise, it operates directly on the bare array of the l_dna. (2) Very important: for L_NOCOPY, any writes to the array will be in the l_dna. Do not write beyond the size of the count field, because it will not be accessable from the l_dna! If necessary, be sure to set the count field to a larger number (such as the alloc size) BEFORE calling this function. Creating with l_dnaMakeConstant() is another way to insure full initialization.
Input: da index (into l_dna) &val (<return> double value; 0.0 on error) Return: 0 if OK; 1 on error
Notes: (1) Caller may need to check the function return value to decide if a 0.0 in the returned ival is valid.
LEPT_DLL l_int32* l_dnaGetIArray | ( | L_DNA * | da | ) |
Input: da Return: a copy of the bare internal array, integerized by rounding, or null on error Notes: (1) A copy of the array is made, because we need to generate an integer array from the bare double array. The caller is responsible for freeing the array. (2) The array size is determined by the number of stored numbers, not by the size of the allocated array in the l_dna. (3) This function is provided to simplify calculations using the bare internal array, rather than continually calling accessors on the l_dna. It is typically used on an array of size 256.
Input: da index (into l_dna) &ival (<return> integer value; 0 on error) Return: 0 if OK; 1 on error
Notes: (1) Caller may need to check the function return value to decide if a 0 in the returned ival is valid.
LEPT_DLL l_int32 l_dnaGetRefcount | ( | L_DNA * | da | ) |
l_dnaGetRefCount()
Input: da Return: refcount, or UNDEF on error
Input: da &startx (<optional return>=""> startx) &delx (<optional return>=""> delx) Return: 0 if OK, 1 on error
Input: da index (location in da to insert new value) val (float64 or integer to be added) Return: 0 if OK, 1 on error
Notes: (1) This shifts da[i] --> da[i + 1] for all i >= index, and then inserts val as da[index]. (2) It should not be used repeatedly on large arrays, because the function is O(n).
LEPT_DLL L_DNA* l_dnaMakeDelta | ( | L_DNA * | das | ) |
Input: das (input l_dna) Return: dad (of difference values val[i+1] - val[i]), or null on error
Input: startval increment size (of sequence) Return: l_dna of sequence of evenly spaced values, or null on error
Input: filename Return: da, or null on error
LEPT_DLL L_DNA* l_dnaReadStream | ( | FILE * | fp | ) |
Input: stream Return: da, or null on error
LEPT_DLL l_int32 l_dnaRemoveNumber | ( | L_DNA * | da, |
l_int32 | index | ||
) |
Input: da index (element to be removed) Return: 0 if OK, 1 on error
Notes: (1) This shifts da[i] --> da[i - 1] for all i > index. (2) It should not be used repeatedly on large arrays, because the function is O(n).
Input: da index (element to be replaced) val (new value to replace old one) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 l_dnaSetCount | ( | L_DNA * | da, |
l_int32 | newcount | ||
) |
Input: da newcount Return: 0 if OK, 1 on error
Notes: (1) If newcount <= da->nalloc, this resets da->n. Using newcount = 0 is equivalent to l_dnaEmpty(). (2) If newcount > da->nalloc, this causes a realloc to a size da->nalloc = newcount. (3) All the previously unused values in da are set to 0.0.
Input: da index (to element to be set) val (to set element) Return: 0 if OK; 1 on error
Input: da startx (x value corresponding to da[0]) delx (difference in x values for the situation where the elements of da correspond to the evaulation of a function at equal intervals of size ) Return: 0 if OK, 1 on error
Input: da index (to element to change relative to the current value) diff (increment if diff > 0 or decrement if diff < 0) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 l_dnaWrite | ( | const char * | filename, |
L_DNA * | da | ||
) |
Input: filename, da Return: 0 if OK, 1 on error
LEPT_DLL l_int32 l_dnaWriteStream | ( | FILE * | fp, |
L_DNA * | da | ||
) |
Input: stream, da Return: 0 if OK, 1 on error
Input: msg (error message) procname
LEPT_DLL void l_errorFloat | ( | const char * | msg, |
const char * | procname, | ||
l_float32 | fval | ||
) |
Input: msg (error message; must include 'f') procname fval (embedded in error message via f)
LEPT_DLL void l_errorInt | ( | const char * | msg, |
const char * | procname, | ||
l_int32 | ival | ||
) |
Input: msg (error message; must include 'd') procname ival (embedded in error message via d)
LEPT_DLL void l_errorString | ( | const char * | msg, |
const char * | procname, | ||
const char * | str | ||
) |
Input: msg (error message; must include 's') procname str (embedded in error message via s)
LEPT_DLL L_COMPRESSED_DATA* l_generateFlateData | ( | const char * | fname, |
l_int32 | ascii85flag | ||
) |
Input: fname ascii85flag (0 for gzipped; 1 for ascii85-encoded gzipped) Return: cid (flate compressed image data), or null on error
Notes: (1) The input image is converted to one of these 4 types:
LEPT_DLL L_COMPRESSED_DATA* l_generateG4Data | ( | const char * | fname, |
l_int32 | ascii85flag | ||
) |
Input: fname (of g4 compressed file) ascii85flag (0 for g4 compressed; 1 for ascii85-encoded g4) Return: cid (g4 compressed image data), or null on error
Notes: (1) Set ascii85flag:
LEPT_DLL L_COMPRESSED_DATA* l_generateJpegData | ( | const char * | fname, |
l_int32 | ascii85flag | ||
) |
Input: fname (of jpeg file) ascii85flag (0 for jpeg; 1 for ascii85-encoded jpeg) Return: cid (containing jpeg data), or null on error
Notes: (1) Set ascii85flag:
LEPT_DLL void l_getCurrentTime | ( | l_int32 * | sec, |
l_int32 * | usec | ||
) |
Input: &sec (<optional return>=""> in seconds since birth of Unix) &usec (<optional return>=""> in microseconds since birth of Unix) Return: void
LEPT_DLL l_int32 l_getDataBit | ( | void * | line, |
l_int32 | n | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) Return: val of the nth (1-bit) pixel.
LEPT_DLL l_int32 l_getDataByte | ( | void * | line, |
l_int32 | n | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) Return: value of the n-th (byte) pixel
LEPT_DLL l_int32 l_getDataDibit | ( | void * | line, |
l_int32 | n | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) Return: val of the nth (2-bit) pixel.
LEPT_DLL l_int32 l_getDataFourBytes | ( | void * | line, |
l_int32 | n | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) Return: value of the n-th (4-byte) pixel
LEPT_DLL l_int32 l_getDataQbit | ( | void * | line, |
l_int32 | n | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) Return: val of the nth (4-bit) pixel.
LEPT_DLL l_int32 l_getDataTwoBytes | ( | void * | line, |
l_int32 | n | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) Return: value of the n-th (2-byte) pixel
LEPT_DLL char* l_getFormattedDate | ( | ) |
Input: (none) Return: formatted date string, or null on error
Input: msg (info message) procname
LEPT_DLL void l_infoFloat | ( | const char * | msg, |
const char * | procname, | ||
l_float32 | fval | ||
) |
Input: msg (info message; must include 'f') procname fval (embedded in info message via f)
LEPT_DLL void l_infoFloat2 | ( | const char * | msg, |
const char * | procname, | ||
l_float32 | fval1, | ||
l_float32 | fval2 | ||
) |
Input: msg (info message; must include two 'f') procname fval1, fval2 (two args, embedded in info message via f)
Input: msg (info message; must include 'd') procname ival (embedded in info message via d)
LEPT_DLL void l_infoInt2 | ( | const char * | msg, |
const char * | procname, | ||
l_int32 | ival1, | ||
l_int32 | ival2 | ||
) |
Input: msg (info message; must include two 'd') procname ival1, ival2 (two args, embedded in info message via d)
LEPT_DLL void l_infoString | ( | const char * | msg, |
const char * | procname, | ||
const char * | str | ||
) |
Input: msg (info message; must include 's') procname str (embedded in warning message via s)
LEPT_DLL void l_jpegSetNoChromaSampling | ( | l_int32 | flag | ) |
Input: flag (0 for standard 2x2 chroma subsampling) 1 for no chroma subsampling (high quality)) Return: void
LEPT_DLL void l_pdfSetDateAndVersion | ( | l_int32 | flag | ) |
Input: flag (1 for writing date/time and leptonica version; 0 for omitting this from the metadata) Return: void
Notes: (1) The default is for writing this data. For regression tests that compare output against golden files, it is useful to omit.
LEPT_DLL void l_pdfSetG4ImageMask | ( | l_int32 | flag | ) |
Input: flag (1 for writing g4 data as fg only through a mask; 0 for writing fg and bg) Return: void
Notes: (1) The default is for writing only the fg (through the mask). That way when you write a 1 bpp image, the bg is transparent, so any previously written image remains visible behind it.
LEPT_DLL void l_pngSetStrip16To8 | ( | l_int32 | flag | ) |
Input: flag (1 for stripping 16 bpp to 8 bpp; 0 for leaving 16 bpp) Return: void
LEPT_DLL void l_pngSetStripAlpha | ( | l_int32 | flag | ) |
Input: flag (1 for stripping alpha channel on read; 0 for leaving it) Return: void
LEPT_DLL void l_pngSetWriteAlpha | ( | l_int32 | flag | ) |
Input: flag (1 for writing alpha channel; 0 for just writing rgb) Return: void
LEPT_DLL void l_pngSetZlibCompression | ( | l_int32 | val | ) |
Input: val (zlib compression value) Return: void
Notes: (1) Valid zlib compression values are in the interval [0 ... 9], where, as defined in zlib.h: 0 Z_NO_COMPRESSION 1 Z_BEST_SPEED (poorest compression) 9 Z_BEST_COMPRESSION For the default value, use either of these: 6 Z_DEFAULT_COMPRESSION -1 (resolves to Z_DEFAULT_COMPRESSION) (2) If you use the defined constants in zlib.h instead of the compression integers given above, you must include zlib.h.
LEPT_DLL l_int32 l_productMat2 | ( | l_float32 * | mat1, |
l_float32 * | mat2, | ||
l_float32 * | matd, | ||
l_int32 | size | ||
) |
Input: mat1 (square matrix, as a 1-dimensional size^2 array) mat2 (square matrix, as a 1-dimensional size^2 array) matd (square matrix; product stored here) size (of matrices) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 l_productMat3 | ( | l_float32 * | mat1, |
l_float32 * | mat2, | ||
l_float32 * | mat3, | ||
l_float32 * | matd, | ||
l_int32 | size | ||
) |
Input: mat1 (square matrix, as a 1-dimensional size^2 array) mat2 (square matrix, as a 1-dimensional size^2 array) mat3 (square matrix, as a 1-dimensional size^2 array) matd (square matrix; product stored here) size (of matrices) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 l_productMat4 | ( | l_float32 * | mat1, |
l_float32 * | mat2, | ||
l_float32 * | mat3, | ||
l_float32 * | mat4, | ||
l_float32 * | matd, | ||
l_int32 | size | ||
) |
Input: mat1 (square matrix, as a 1-dimensional size^2 array) mat2 (square matrix, as a 1-dimensional size^2 array) mat3 (square matrix, as a 1-dimensional size^2 array) mat4 (square matrix, as a 1-dimensional size^2 array) matd (square matrix; product stored here) size (of matrices) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 l_productMatVec | ( | l_float32 * | mat, |
l_float32 * | vecs, | ||
l_float32 * | vecd, | ||
l_int32 | size | ||
) |
Input: mat (square matrix, as a 1-dimensional ^2 array) vecs (input column vector of length ) vecd (result column vector) size (matrix is x ; vectors are length ) Return: 0 if OK, 1 on error
LEPT_DLL void l_psWriteBoundingBox | ( | l_int32 | flag | ) |
LEPT_DLL void l_setAlphaMaskBorder | ( | l_float32 | val1, |
l_float32 | val2 | ||
) |
Input: val1, val2 (in [0.0 ... 1.0]) Return: void
Notes: (1) This sets the opacity values used to generate the two outer boundary rings in the alpha mask associated with geometric transforms such as pixRotateWithAlpha(). (2) The default values are val1 = 0.0 (completely transparent in the outermost ring) and val2 = 0.5 (half transparent in the second ring). When the image is blended, this completely removes the outer ring (shrinking the image by 2 in each direction), and alpha-blends with 0.5 the second ring. (3) The actual mask values are found by multiplying these normalized opacity values by 255.
LEPT_DLL void l_setConvolveSampling | ( | l_int32 | xfact, |
l_int32 | yfact | ||
) |
Input: xfact, yfact (integer >= 1) Return: void
Notes: (1) This sets the x and y output subsampling factors for generic pix and fpix convolution. The default values are 1 (no subsampling).
LEPT_DLL void l_setDataBit | ( | void * | line, |
l_int32 | n | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) Return: void
Action: sets the pixel to 1
LEPT_DLL void l_setDataBitVal | ( | void * | line, |
l_int32 | n, | ||
l_int32 | val | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) val (val to be inserted: 0 or 1) Return: void
Notes: (1) This is an accessor for a 1 bpp pix. (2) It is actually a little slower than using: if (val == 0) l_ClearDataBit(line, n); else l_SetDataBit(line, n);
LEPT_DLL void l_setDataByte | ( | void * | line, |
l_int32 | n, | ||
l_int32 | val | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) val (val to be inserted: 0 - 0xff) Return: void
LEPT_DLL void l_setDataDibit | ( | void * | line, |
l_int32 | n, | ||
l_int32 | val | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) val (val to be inserted: 0 - 3) Return: void
LEPT_DLL void l_setDataFourBytes | ( | void * | line, |
l_int32 | n, | ||
l_int32 | val | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) val (val to be inserted: 0 - 0xffffffff) Return: void
LEPT_DLL void l_setDataQbit | ( | void * | line, |
l_int32 | n, | ||
l_int32 | val | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) val (val to be inserted: 0 - 0xf) Return: void
LEPT_DLL void l_setDataTwoBytes | ( | void * | line, |
l_int32 | n, | ||
l_int32 | val | ||
) |
Input: line (ptr to beginning of data line) n (pixel index) val (val to be inserted: 0 - 0xffff) Return: void
Input: msg (warning message) procname
LEPT_DLL void l_warningFloat | ( | const char * | msg, |
const char * | procname, | ||
l_float32 | fval | ||
) |
Input: msg (warning message; must include 'f') procname fval (embedded in warning message via f)
LEPT_DLL void l_warningFloat2 | ( | const char * | msg, |
const char * | procname, | ||
l_float32 | fval1, | ||
l_float32 | fval2 | ||
) |
Input: msg (warning message; must include 'f') procname fval1, fval2 (two args, embedded in message via f)
LEPT_DLL void l_warningInt | ( | const char * | msg, |
const char * | procname, | ||
l_int32 | ival | ||
) |
Input: msg (warning message; must include 'd') procname ival (embedded in warning message via d)
LEPT_DLL void l_warningInt2 | ( | const char * | msg, |
const char * | procname, | ||
l_int32 | ival1, | ||
l_int32 | ival2 | ||
) |
Input: msg (warning message; must include 'd') procname ival1, ival2 (two args, embedded in message via d)
LEPT_DLL void l_warningString | ( | const char * | msg, |
const char * | procname, | ||
const char * | str | ||
) |
Input: msg (warning message; must include 's') procname str (embedded in warning message via s)
LEPT_DLL void* lept_calloc | ( | size_t | nmemb, |
size_t | size | ||
) |
Input: nmemb (number of members) size (of each member) Return: void ptr, or null on error
Notes: (1) For safety with windows DLLs, this can be used in conjunction with lept_free() to avoid C-runtime boundary problems. Just use these two functions throughout your application.
Input: srcfile newfile Return: 0 on success, non-zero on failure
Notes: (1) This copies a file to /tmp or a subdirectory of /tmp. (2) The input srcfile name is the complete pathname. The input newfile is either in /tmp or a subdirectory of /tmp, and newfile can be specified either as the full path or without the leading '/tmp'. (3) Use unix pathname separators. (4) On Windows, the source and target filename are altered internally if necessary to conform to the Windows temp file. (5) Alternatively, you can use fileCopy(). This avoids forking a new process and has no restrictions on the destination directory.
LEPT_DLL void lept_direxists | ( | const char * | dirname, |
l_int32 * | pexists | ||
) |
Input: dirname &exists (<return> 1 on success, 0 on failure) Return: void
Notes: (1) For Windows, use windows pathname separators.
LEPT_DLL l_int32 lept_fclose | ( | FILE * | fp | ) |
Input: fp (stream handle) Return: 0 if OK, 1 on error
Notes: (1) This should be used by any application that accepts a file handle generated by a leptonica Windows DLL.
LEPT_DLL FILE* lept_fopen | ( | const char * | filename, |
const char * | mode | ||
) |
Input: filename mode (same as for fopen(); e.g., "rb") Return: stream or null on error
Notes: (1) This must be used by any application that passes a file handle to a leptonica Windows DLL.
Input: void ptr Return: 0 if OK, 1 on error
Notes: (1) This should be used by any application that accepts heap data allocated by a leptonica Windows DLL.
LEPT_DLL l_int32 lept_mkdir | ( | const char * | subdir | ) |
Input: subdir Return: 0 on success, non-zero on failure
Notes: (1) This makes a subdirectory of /tmp/. (2) Use unix pathname separators. (3) On Windows, it makes a subdirectory of <Temp>/leptonica, where <Temp> is the Windows temp dir. The name translation is: /tmp --> <Temp>/leptonica
Input: srcfile, newfile Return: 0 on success, non-zero on failure
Notes: (1) This moves a srcfile to /tmp or to a subdirectory of /tmp. (2) The input srcfile name is the complete pathname. The input newfile is either in /tmp or a subdirectory of /tmp, and newfile can be specified either as the full path or without the leading '/tmp'. (3) Use unix pathname separators. (4) On Windows, the source and target filename are altered internally if necessary to conform to the Windows temp file. The name translation is: /tmp --> <Temp>/leptonica
Input: subdir (can be NULL, in which case the removed file is in /tmp) filename (without the directory) Return: 0 on success, non-zero on failure
Notes: (1) This removes the named file in /tmp or a subdirectory of /tmp. If the file is in /tmp, use NULL for the subdir. (2) Use unix pathname separators. (3) On Windows, the file is in either <Temp>/leptonica, or a subdirectory of this, where <Temp> is the Windows temp dir. The name translation is: /tmp --> <Temp>/leptonica
LEPT_DLL l_int32 lept_rmdir | ( | const char * | subdir | ) |
Input: subdir (of /tmp or its equivalent on Windows) Return: 0 on success, non-zero on failure
Notes: (1) On unix, this removes all the files in the named subdirectory of /tmp. It then removes the subdirectory. (2) Use unix pathname separators. (3) On Windows, the affected directory is a subdirectory of <Temp>/leptonica, where <Temp> is the Windows temp dir.
LEPT_DLL l_int32 lept_roundftoi | ( | l_float32 | fval | ) |
Input: fval Return: value rounded to int
Notes: (1) For fval >= 0, fval --> round(fval) == floor(fval + 0.5) For fval < 0, fval --> -round(-fval)) This is symmetric around 0. e.g., for fval in (-0.5 ... 0.5), fval --> 0
Input: lheap item to be added to the tail of the heap Return: 0 if OK, 1 on error
LEPT_DLL L_HEAP* lheapCreate | ( | l_int32 | nalloc, |
l_int32 | direction | ||
) |
Input: size of ptr array to be alloc'd (0 for default) direction (L_SORT_INCREASING, L_SORT_DECREASING) Return: lheap, or null on error
LEPT_DLL void lheapDestroy | ( | L_HEAP ** | plh, |
l_int32 | freeflag | ||
) |
Input: &lheap (<to be="" nulled>="">) freeflag (TRUE to free each remaining struct in the array) Return: void
Notes: (1) Use freeflag == TRUE when the items in the array can be simply destroyed using free. If those items require their own destroy function, they must be destroyed before calling this function, and then this function is called with freeflag == FALSE. (2) To destroy the lheap, we destroy the ptr array, then the lheap, and then null the contents of the input ptr.
LEPT_DLL l_int32 lheapExtendArray | ( | L_HEAP * | lh | ) |
Input: lheap Return: 0 if OK, 1 on error
LEPT_DLL l_int32 lheapGetCount | ( | L_HEAP * | lh | ) |
Input: lheap Return: count, or 0 on error
LEPT_DLL l_int32 lheapPrint | ( | FILE * | fp, |
L_HEAP * | lh | ||
) |
Input: stream lheap Return: 0 if OK; 1 on error
LEPT_DLL void* lheapRemove | ( | L_HEAP * | lh | ) |
Input: lheap Return: ptr to item popped from the root of the heap, or null if the heap is empty or on error
Input: lh (heap, with internal array) Return: 0 if OK, 1 on error
Notes: (1) This sorts an array into heap order. If the heap is already in heap order for the direction given, this has no effect.
LEPT_DLL l_int32 lheapSortStrictOrder | ( | L_HEAP * | lh | ) |
Input: lh (heap, with internal array) Return: 0 if OK, 1 on error
Notes: (1) This sorts a heap into strict order. (2) For each element, starting at the end of the array and working forward, the element is swapped with the head element and then allowed to swap down onto a heap of size reduced by one. The result is that the heap is reversed but in strict order. The array elements are then reversed to put it in the original order.
LEPT_DLL l_int32 lheapSwapDown | ( | L_HEAP * | lh | ) |
Input: lh (heap) Return: 0 if OK, 1 on error
Notes: (1) This is called after an item has been popped off the root of the heap, and the last item in the heap has been placed at the root. (2) To regain the heap order, we let it bubble down, iteratively swapping with one of its children. For a decreasing sort, it swaps with the largest child; for an increasing sort, the smallest. This continues until it either reaches the lowest level in the heap, or the parent finds that neither child should swap with it (e.g., for a decreasing heap, the parent is larger than or equal to both children).
LEPT_DLL l_int32 lheapSwapUp | ( | L_HEAP * | lh, |
l_int32 | index | ||
) |
Input: lh (heap) index (of array corresponding to node to be swapped up) Return: 0 if OK, 1 on error
Notes: (1) This is called after a new item is put on the heap, at the bottom of a complete tree. (2) To regain the heap order, we let it bubble up, iteratively swapping with its parent, until it either reaches the root of the heap or it finds a parent that is in the correct position already vis-a-vis the child.
LEPT_DLL l_int32 linearInterpolatePixelColor | ( | l_uint32 * | datas, |
l_int32 | wpls, | ||
l_int32 | w, | ||
l_int32 | h, | ||
l_float32 | x, | ||
l_float32 | y, | ||
l_uint32 | colorval, | ||
l_uint32 * | pval | ||
) |
Input: datas (ptr to beginning of image data) wpls (32-bit word/line for this data array) w, h (of image) x, y (floating pt location for evaluation) colorval (color brought in from the outside when the input x,y location is outside the image; in 0xrrggbb00 format)) &val (<return> interpolated color value) Return: 0 if OK, 1 on error
Notes: (1) This is a standard linear interpolation function. It is equivalent to area weighting on each component, and avoids "jaggies" when rendering sharp edges.
LEPT_DLL l_int32 linearInterpolatePixelFloat | ( | l_float32 * | datas, |
l_int32 | w, | ||
l_int32 | h, | ||
l_float32 | x, | ||
l_float32 | y, | ||
l_float32 | inval, | ||
l_float32 * | pval | ||
) |
Input: datas (ptr to beginning of float image data) wpls (32-bit word/line for this data array) w, h (of image) x, y (floating pt location for evaluation) inval (float value brought in from the outside when the input x,y location is outside the image) &val (<return> interpolated float value) Return: 0 if OK, 1 on error
Notes: (1) This is a standard linear interpolation function. It is equivalent to area weighting on each component, and avoids "jaggies" when rendering sharp edges.
LEPT_DLL l_int32 linearInterpolatePixelGray | ( | l_uint32 * | datas, |
l_int32 | wpls, | ||
l_int32 | w, | ||
l_int32 | h, | ||
l_float32 | x, | ||
l_float32 | y, | ||
l_int32 | grayval, | ||
l_int32 * | pval | ||
) |
Input: datas (ptr to beginning of image data) wpls (32-bit word/line for this data array) w, h (of image) x, y (floating pt location for evaluation) grayval (color brought in from the outside when the input x,y location is outside the image) &val (<return> interpolated gray value) Return: 0 if OK, 1 on error
Notes: (1) This is a standard linear interpolation function. It is equivalent to area weighting on each component, and avoids "jaggies" when rendering sharp edges.
Input datad (dest byte array data, reordered on little-endians) datas (a src line of pix data) wpl (number of 32 bit words in the line) Return: 0 if OK, 1 on error
Notes: (1) This is used on little-endian platforms to swap the bytes within each word in the line of image data. Bytes 0 <==> 3 and 1 <==> 2 are swapped in the dest byte array data8d, relative to the pix data in datas. (2) The bytes represent 8 bit pixel values. They are swapped for little endians so that when the dest array (char *)datad is addressed by bytes, the pixels are chosen sequentially from left to right in the image.
LEPT_DLL l_int32 listAddToHead | ( | DLLIST ** | phead, |
void * | data | ||
) |
Input: &head (<optional> input head) data (void* ptr, to be added) Return: 0 if OK; 1 on error
Notes: (1) This makes a new cell, attaches the data, and adds the cell to the head of the list. (2) When consing from NULL, be sure to initialize head to NULL before calling this function.
LEPT_DLL l_int32 listAddToTail | ( | DLLIST ** | phead, |
DLLIST ** | ptail, | ||
void * | data | ||
) |
Input: &head (<may be="" updated>="">, head can be null) &tail (<updated>, tail can be null) data (void* ptr, to be hung on tail cons cell) Return: 0 if OK; 1 on error
Notes: (1) This makes a new cell, attaches the data, and adds the cell to the tail of the list. (2) &head is input to allow the list to be "cons'd" up from NULL. (3) &tail is input to allow the tail to be updated for efficient sequential operation with this function. (4) We assume that if *phead and/or *ptail are not NULL, then they are valid addresses. Therefore: (a) when consing from NULL, be sure to initialize both head and tail to NULL. (b) when tail == NULL for an existing list, the tail will be found and updated.
LEPT_DLL void listDestroy | ( | DLLIST ** | phead | ) |
Input: &head (<to be="" nulled>=""> head of list) Return: void
Notes: (1) This only destroys the cons cells. Before destroying the list, it is necessary to remove all data and set the data pointers in each cons cell to NULL. (2) listDestroy() will give a warning message for each data ptr that is not NULL.
LEPT_DLL DLLIST* listFindElement | ( | DLLIST * | head, |
void * | data | ||
) |
Input: head (list head) data (void* address, to be searched for) Return: cell (the containing cell, or null if not found or on error)
Notes: (1) This returns a ptr to the cell, which is still embedded in the list. (2) This handle and the attached data have not been copied or reference counted, so they must not be destroyed. This violates our basic rule that every handle returned from a function is owned by that function and must be destroyed, but if rules aren't there to be broken, why have them?
LEPT_DLL DLLIST* listFindTail | ( | DLLIST * | head | ) |
Input: head Return: tail, or null on error
LEPT_DLL l_int32 listGetCount | ( | DLLIST * | head | ) |
Input: head (of list) Return: number of elements; 0 if no list or on error
LEPT_DLL l_int32 listInsertAfter | ( | DLLIST ** | phead, |
DLLIST * | elem, | ||
void * | data | ||
) |
Input: &head (<optional> input head) elem (list element to be inserted after; must be null if head is null) data (void* ptr, to be added) Return: 0 if OK; 1 on error
Notes: (1) This can be called on a null list, in which case both head and elem must be null. The head is included in the call to allow "consing" up from NULL. (2) If you are searching through a list, looking for a condition to add an element, you can do something like this: L_BEGIN_LIST_FORWARD(head, elem) <identify an="" elem="" to="" insert="" after>=""> listInsertAfter(&head, elem, data); L_END_LIST
LEPT_DLL l_int32 listInsertBefore | ( | DLLIST ** | phead, |
DLLIST * | elem, | ||
void * | data | ||
) |
Input: &head (<optional> input head) elem (list element to be inserted in front of; must be null if head is null) data (void* address, to be added) Return: 0 if OK; 1 on error
Notes: (1) This can be called on a null list, in which case both head and elem must be null. (2) If you are searching through a list, looking for a condition to add an element, you can do something like this: L_BEGIN_LIST_FORWARD(head, elem) <identify an="" elem="" to="" insert="" before>=""> listInsertBefore(&head, elem, data); L_END_LIST
Input: &head1 (<may be="" changed>=""> head of first list) &head2 (<to be="" nulled>=""> head of second list) Return: 0 if OK, 1 on error
Notes: (1) The concatenated list is returned with head1 as the new head. (2) Both input ptrs must exist, though either can have the value NULL.
LEPT_DLL void* listRemoveElement | ( | DLLIST ** | phead, |
DLLIST * | elem | ||
) |
Input: &head (<can be="" changed>=""> input head) elem (list element to be removed) Return: data (void* struct on cell)
Notes: (1) in ANSI C, it is not necessary to cast return to actual type; e.g., pix = listRemoveElement(&head, elem); but in ANSI C++, it is necessary to do the cast: pix = (Pix *)listRemoveElement(&head, elem);
LEPT_DLL void* listRemoveFromHead | ( | DLLIST ** | phead | ) |
Input: &head (<to be="" updated>=""> head of list) Return: data (void* struct on cell), or null on error
Notes: (1) in ANSI C, it is not necessary to cast return to actual type; e.g., pix = listRemoveFromHead(&head); but in ANSI C++, it is necessary to do the cast; e.g., pix = (Pix *)listRemoveFromHead(&head);
LEPT_DLL void* listRemoveFromTail | ( | DLLIST ** | phead, |
DLLIST ** | ptail | ||
) |
Input: &head (<may be="" changed>="">, head must NOT be null) &tail (<always updated>="">, tail may be null) Return: data (void* struct on cell) or null on error
Notes: (1) We include &head so that it can be set to NULL if if the only element in the list is removed. (2) The function is relying on the fact that if tail is not NULL, then is is a valid address. You can use this function with tail == NULL for an existing list, in which case the tail is found and updated, and the removed element is returned. (3) In ANSI C, it is not necessary to cast return to actual type; e.g., pix = listRemoveFromTail(&head, &tail); but in ANSI C++, it is necessary to do the cast; e.g., pix = (Pix *)listRemoveFromTail(&head, &tail);
LEPT_DLL l_int32 listReverse | ( | DLLIST ** | phead | ) |
Input: &head (<may be="" changed>=""> list head) Return: 0 if OK, 1 on error
Notes: (1) This reverses the list in-place.
LEPT_DLL void locateOutsideSeedPixel | ( | l_int32 | fpx, |
l_int32 | fpy, | ||
l_int32 | spx, | ||
l_int32 | spy, | ||
l_int32 * | pxs, | ||
l_int32 * | pys | ||
) |
Input: fpx, fpy (location of first pixel) spx, spy (location of second pixel) &xs, &xy (seed pixel to be returned)
Notes: (1) the first and second pixels must be 8-adjacent, so |dx| <= 1 and |dy| <= 1 and both dx and dy cannot be 0. There are 8 possible cases. (2) the seed pixel is OUTSIDE the foreground of the c.c. (3) these rules are for the situation where the INSIDE of the c.c. is on the right as you follow the border: cw for an exterior border and ccw for a hole border.
LEPT_DLL l_int32 locatePtRadially | ( | l_int32 | xr, |
l_int32 | yr, | ||
l_float64 | dist, | ||
l_float64 | radang, | ||
l_float64 * | px, | ||
l_float64 * | py | ||
) |
Input: xr, yr (reference point) radang (angle in radians, CW from horizontal) dist (distance of point from reference point along line given by the specified angle) &x, &y (<return> location of point) Return: 0 if OK, 1 on error
Input: lqueue item to be added to the tail of the queue Return: 0 if OK, 1 on error
Notes: (1) The algorithm is as follows. If the queue is populated to the end of the allocated array, shift all ptrs toward the beginning of the array, so that the head of the queue is at the beginning of the array. Then, if the array is more than 0.75 full, realloc with double the array size. Finally, add the item to the tail of the queue.
LEPT_DLL L_QUEUE* lqueueCreate | ( | l_int32 | nalloc | ) |
Input: size of ptr array to be alloc'd (0 for default) Return: lqueue, or null on error
Notes: (1) Allocates a ptr array of given size, and initializes counters.
LEPT_DLL void lqueueDestroy | ( | L_QUEUE ** | plq, |
l_int32 | freeflag | ||
) |
Input: &lqueue (<to be="" nulled>="">) freeflag (TRUE to free each remaining struct in the array) Return: void
Notes: (1) If freeflag is TRUE, frees each struct in the array. (2) If freeflag is FALSE but there are elements on the array, gives a warning and destroys the array. This will cause a memory leak of all the items that were on the queue. So if the items require their own destroy function, they must be destroyed before the queue. The same applies to the auxiliary stack, if it is used. (3) To destroy the L_Queue, we destroy the ptr array, then the lqueue, and then null the contents of the input ptr.
LEPT_DLL l_int32 lqueueExtendArray | ( | L_QUEUE * | lq | ) |
Input: lqueue Return: 0 if OK, 1 on error
LEPT_DLL l_int32 lqueueGetCount | ( | L_QUEUE * | lq | ) |
Input: lqueue Return: count, or 0 on error
LEPT_DLL l_int32 lqueuePrint | ( | FILE * | fp, |
L_QUEUE * | lq | ||
) |
Input: stream lqueue Return: 0 if OK; 1 on error
LEPT_DLL void* lqueueRemove | ( | L_QUEUE * | lq | ) |
Input: lqueue Return: ptr to item popped from the head of the queue, or null if the queue is empty or on error
Notes: (1) If this is the last item on the queue, so that the queue becomes empty, nhead is reset to the beginning of the array.
Input: lstack item to be added to the lstack Return: 0 if OK; 1 on error.
LEPT_DLL L_STACK* lstackCreate | ( | l_int32 | nalloc | ) |
Input: nalloc (initial ptr array size; use 0 for default) Return: lstack, or null on error
LEPT_DLL void lstackDestroy | ( | L_STACK ** | plstack, |
l_int32 | freeflag | ||
) |
Input: &lstack (<to be="" nulled>="">) freeflag (TRUE to free each remaining struct in the array) Return: void
Notes: (1) If freeflag is TRUE, frees each struct in the array. (2) If freeflag is FALSE but there are elements on the array, gives a warning and destroys the array. This will cause a memory leak of all the items that were on the lstack. So if the items require their own destroy function, they must be destroyed before the lstack. (3) To destroy the lstack, we destroy the ptr array, then the lstack, and then null the contents of the input ptr.
LEPT_DLL l_int32 lstackExtendArray | ( | L_STACK * | lstack | ) |
Input: lstack Return: 0 if OK; 1 on error
LEPT_DLL l_int32 lstackGetCount | ( | L_STACK * | lstack | ) |
Input: lstack Return: count, or 0 on error
LEPT_DLL l_int32 lstackPrint | ( | FILE * | fp, |
L_STACK * | lstack | ||
) |
Input: stream lstack Return: 0 if OK; 1 on error
LEPT_DLL void* lstackRemove | ( | L_STACK * | lstack | ) |
Input: lstack Return: ptr to item popped from the top of the lstack, or null if the lstack is empty or on error
LEPT_DLL l_int32 make8To1DitherTables | ( | l_int32 ** | ptabval, |
l_int32 ** | ptab38, | ||
l_int32 ** | ptab14, | ||
l_int32 | lowerclip, | ||
l_int32 | upperclip | ||
) |
Input: &tabval (value assigned to output pixel; 0 or 1) &tab38 (amount propagated to pixels left and below) &tab14 (amount propagated to pixel to left and down) lowerclip (values near 0 where the excess is not propagated) upperclip (values near 255 where the deficit is not propagated)
Return: 0 if OK, 1 on error
LEPT_DLL l_int32 make8To2DitherTables | ( | l_int32 ** | ptabval, |
l_int32 ** | ptab38, | ||
l_int32 ** | ptab14, | ||
l_int32 | cliptoblack, | ||
l_int32 | cliptowhite | ||
) |
Input: &tabval (value assigned to output pixel; 0, 1, 2 or 3) &tab38 (amount propagated to pixels left and below) &tab14 (amount propagated to pixel to left and down) cliptoblack (values near 0 where the excess is not propagated) cliptowhite (values near 255 where the deficit is not propagated)
Return: 0 if OK, 1 on error
LEPT_DLL L_KERNEL* makeDoGKernel | ( | l_int32 | halfheight, |
l_int32 | halfwidth, | ||
l_float32 | stdev, | ||
l_float32 | ratio | ||
) |
Input: halfheight, halfwidth (sx = 2 * halfwidth + 1, etc) stdev (standard deviation) ratio (of stdev for wide filter to stdev for narrow one) Return: kernel, or null on error
Notes: (1) The DoG (difference of gaussians) is a wavelet mother function with null total sum. By subtracting two blurred versions of the image, it acts as a bandpass filter for frequencies passed by the narrow gaussian but stopped by the wide one.See: http://en.wikipedia.org/wiki/Difference_of_Gaussians (2) The kernel size (sx, sy) = (2 * halfwidth + 1, 2 * halfheight + 1). (3) The kernel center (cx, cy) = (halfwidth, halfheight). (4) The halfwidth and halfheight are typically equal, and are typically several times larger than the standard deviation. (5) The ratio is the ratio of standard deviations of the wide to narrow gaussian. It must be >= 1.0; 1.0 is a no-op. (6) Because the kernel is a null sum, it must be invoked without normalization in pixConvolve().
LEPT_DLL l_uint16* makeExpandTab2x | ( | void | ) |
LEPT_DLL l_uint32* makeExpandTab4x | ( | void | ) |
LEPT_DLL l_uint32* makeExpandTab8x | ( | void | ) |
Input: height, width cy, cx (origin of kernel) Return: kernel, or null on error
Notes: (1) This is the same low-pass filtering kernel that is used in the block convolution functions. (2) The kernel origin (, ) is typically placed as near the center of the kernel as possible. If height and width are odd, then using cy = (height - 1) / 2 and cx = (width - 1) / 2 places the origin at the exact center. (3) This returns a normalized kernel.
LEPT_DLL L_KERNEL* makeGaussianKernel | ( | l_int32 | halfheight, |
l_int32 | halfwidth, | ||
l_float32 | stdev, | ||
l_float32 | max | ||
) |
Input: halfheight, halfwidth (sx = 2 * halfwidth + 1, etc) stdev (standard deviation) max (value at (cx,cy)) Return: kernel, or null on error
Notes: (1) The kernel size (sx, sy) = (2 * halfwidth + 1, 2 * halfheight + 1). (2) The kernel center (cx, cy) = (halfwidth, halfheight). (3) The halfwidth and halfheight are typically equal, and are typically several times larger than the standard deviation. (4) If pixConvolve() is invoked with normalization (the sum of kernel elements = 1.0), use 1.0 for max (or any number that's not too small or too large).
LEPT_DLL l_int32 makeGaussianKernelSep | ( | l_int32 | halfheight, |
l_int32 | halfwidth, | ||
l_float32 | stdev, | ||
l_float32 | max, | ||
L_KERNEL ** | pkelx, | ||
L_KERNEL ** | pkely | ||
) |
Input: halfheight, halfwidth (sx = 2 * halfwidth + 1, etc) stdev (standard deviation) max (value at (cx,cy)) &kelx (<return> x part of kernel) &kely (<return> y part of kernel) Return: 0 if OK, 1 on error
Notes: (1) See makeGaussianKernel() for description of input parameters. (2) These kernels are constructed so that the result of both normalized and un-normalized convolution will be the same as when convolving with pixConvolve() using the full kernel. (3) The trick for the un-normalized convolution is to have the product of the two kernel elemets at (cx,cy) be equal to max, not max**2. That's why the max for kely is 1.0. If instead we use sqrt(max) for both, the results are slightly less accurate, when compared to using the full kernel in makeGaussianKernel().
LEPT_DLL l_int32 makeGrayQuantColormapArb | ( | PIX * | pixs, |
l_int32 * | tab, | ||
l_int32 | outdepth, | ||
PIXCMAP ** | pcmap | ||
) |
Input: pixs (8 bpp) tab (table mapping input gray level to cmap index) outdepth (of colormap: 1, 2, 4 or 8) &cmap (<return> colormap) Return: 0 if OK, 1 on error
Notes: (1) The table is a 256-entry inverse colormap: it maps input gray level to colormap index (the bin number). It is computed using makeGrayQuantTableArb(). (2) The colormap generated here has quantized values at the average gray value of the pixels that are in each bin. (3) Returns an error if there are not enough levels in the output colormap for the number of bins. The number of bins must not exceed 2^outdepth.
LEPT_DLL l_int32* makeGrayQuantIndexTable | ( | l_int32 | nlevels | ) |
Input: nlevels (number of output levels) Return: table (maps input gray level to colormap index, or null on error) Notes: (1) 'nlevels' is some number between 2 and 256 (typically 8 or less). (2) The table is typically used for quantizing 2, 4 and 8 bpp grayscale src pix, and generating a colormapped dest pix.
LEPT_DLL l_int32 makeGrayQuantTableArb | ( | NUMA * | na, |
l_int32 | outdepth, | ||
l_int32 ** | ptab, | ||
PIXCMAP ** | pcmap | ||
) |
Input: na (numa of bin boundaries) outdepth (of colormap: 1, 2, 4 or 8) &tab (<return> table mapping input gray level to cmap index) &cmap (<return> colormap) Return: 0 if OK, 1 on error
Notes: (1) The number of bins is the count of + 1. (2) The bin boundaries in na must be sorted in increasing order. (3) The table is an inverse colormap: it maps input gray level to colormap index (the bin number). (4) The colormap generated here has quantized values at the center of each bin. If you want to use the average gray value of pixels within the bin, discard the colormap and compute it using makeGrayQuantColormapArb(). (5) Returns an error if there are not enough levels in the output colormap for the number of bins. The number of bins must not exceed 2^outdepth.
LEPT_DLL l_int32* makeGrayQuantTargetTable | ( | l_int32 | nlevels, |
l_int32 | depth | ||
) |
Input: nlevels (number of output levels) depth (of dest pix, in bpp; 2, 4 or 8 bpp) Return: table (maps input gray level to thresholded gray level, or null on error)
Notes: (1) nlevels is some number between 2 and 2^(depth) (2) The table is used in two similar ways:
LEPT_DLL l_float32* makeLogBase2Tab | ( | void | ) |
LEPT_DLL l_int32* makeMSBitLocTab | ( | l_int32 | bitval | ) |
Input: bitval (either 0 or 1) Return: table (giving, for an input byte, the MS bit location, starting at 0 with the MSBit in the byte), or null on error.
Notes: (1) If bitval == 1, it finds the leftmost ON pixel in a byte; otherwise if bitval == 0, it finds the leftmost OFF pixel. (2) If there are no pixels of the indicated color in the byte, this returns 8.
LEPT_DLL l_int32 makeOrientDecision | ( | l_float32 | upconf, |
l_float32 | leftconf, | ||
l_float32 | minupconf, | ||
l_float32 | minratio, | ||
l_int32 * | porient, | ||
l_int32 | debug | ||
) |
Input: upconf (nonzero) leftconf (nonzero) minupconf (minimum value for which a decision can be made) minratio (minimum conf ratio required for a decision) &orient (<return> text orientation enum {0,1,2,3,4}) debug (1 for debug output; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) This can be run after pixOrientDetect() (2) Both upconf and leftconf must be nonzero; otherwise the orientation cannot be determined. (3) The abs values of the input confidences are compared to minupconf. (4) The abs value of the largest of (upconf/leftconf) and (leftconf/upconf) is compared with minratio. (5) Input 0.0 for the default values for minupconf and minratio. (6) The return value of orient is interpreted thus: L_TEXT_ORIENT_UNKNOWN: not enough evidence to determine L_TEXT_ORIENT_UP: text rightside-up L_TEXT_ORIENT_LEFT: landscape, text up facing left L_TEXT_ORIENT_DOWN: text upside-down L_TEXT_ORIENT_RIGHT: landscape, text up facing right
LEPT_DLL l_int32* makePixelCentroidTab8 | ( | void | ) |
Input: void Return: table of 256 l_int32, or null on error
Notes: (1) This table of integers gives the centroid weight of the 1 bits in the 8 bit index. In other words, if sumtab is obtained by makePixelSumTab8, and centroidtab is obtained by makePixelCentroidTab8, then, for 1 <= i <= 255, centroidtab[i] / (float)sumtab[i] is the centroid of the 1 bits in the 8-bit index i, where the MSB is considered to have position 0 and the LSB is considered to have position 7.
LEPT_DLL l_int32* makePixelSumTab8 | ( | void | ) |
Input: void Return: table of 256 l_int32, or null on error
Notes: (1) This table of integers gives the number of 1 bits in the 8 bit index.
LEPT_DLL l_uint8* makeReverseByteTab1 | ( | void | ) |
Notes: (1) This generates an 8 bit lookup table for reversing the order of eight 1-bit pixels.
LEPT_DLL l_uint8* makeReverseByteTab2 | ( | void | ) |
Notes: (1) This generates an 8 bit lookup table for reversing the order of four 2-bit pixels.
LEPT_DLL l_uint8* makeReverseByteTab4 | ( | void | ) |
Notes: (1) This generates an 8 bit lookup table for reversing the order of two 4-bit pixels.
LEPT_DLL l_int32 makeRGBToIndexTables | ( | l_uint32 ** | prtab, |
l_uint32 ** | pgtab, | ||
l_uint32 ** | pbtab, | ||
l_int32 | cqlevels | ||
) |
Input: &rtab, >ab, &btab (<return> tables) cqlevels (can be 1, 2, 3, 4, 5 or 6) Return: 0 if OK; 1 on error
Set up tables. e.g., for cqlevels = 5, we need an integer 0 < i < 2^15: rtab = (0 i7 0 0 i6 0 0 i5 0 0 i4 0 0 i3 0 0) gtab = (0 0 i7 0 0 i6 0 0 i5 0 0 i4 0 0 i3 0) btab = (0 0 0 i7 0 0 i6 0 0 i5 0 0 i4 0 0 i3)
The tables are then used to map from rbg --> index as follows: index = (0 r7 g7 b7 r6 g6 b6 r5 g5 b5 r4 g4 b4 r3 g3 b3)
e.g., for cqlevels = 4, we map to index = (0 0 0 0 r7 g7 b7 r6 g6 b6 r5 g5 b5 r4 g4 b4)
This may look a bit strange. The notation 'r7' means the MSBit of the r value (which has 8 bits, going down from r7 to r0). Keep in mind that r7 is actually the r component bit for level 1 of the octtree. Level 1 is composed of 8 octcubes, represented by the bits (r7 g7 b7), which divide the entire color space into 8 cubes. At level 2, each of these 8 octcubes is further divided into 8 cubes, each labeled by the second most significant bits (r6 g6 b6) of the rgb color.
LEPT_DLL l_uint8* makeSubsampleTab2x | ( | void | ) |
This table permutes the bits in a byte, from 0 4 1 5 2 6 3 7 to 0 1 2 3 4 5 6 7
LEPT_DLL l_uint32* makeSumTabSG2 | ( | void | ) |
Returns a table of 256 l_uint32s, giving the four output 8-bit grayscale sums corresponding to 8 input bits of a binary image, for a 2x scale-to-gray op. The sums from two adjacent scanlines are then added and transformed to output four 8 bpp pixel values, using makeValTabSG2().
LEPT_DLL l_uint32* makeSumTabSG3 | ( | void | ) |
Returns a table of 64 l_uint32s, giving the two output 8-bit grayscale sums corresponding to 6 input bits of a binary image, for a 3x scale-to-gray op. In practice, this would be used three times (on adjacent scanlines), and the sums would be added and then transformed to output 8 bpp pixel values, using makeValTabSG3().
LEPT_DLL l_uint32* makeSumTabSG4 | ( | void | ) |
Returns a table of 256 l_uint32s, giving the two output 8-bit grayscale sums corresponding to 8 input bits of a binary image, for a 4x scale-to-gray op. The sums from four adjacent scanlines are then added and transformed to output 8 bpp pixel values, using makeValTabSG4().
LEPT_DLL l_uint8* makeValTabSG2 | ( | void | ) |
Returns an 8 bit value for the sum of ON pixels in a 2x2 square, according to
val = 255 - (255 * sum)/4
where sum is in set {0,1,2,3,4}
LEPT_DLL l_uint8* makeValTabSG3 | ( | void | ) |
Returns an 8 bit value for the sum of ON pixels in a 3x3 square, according to val = 255 - (255 * sum)/9 where sum is in set {0, ... ,9}
LEPT_DLL l_uint8* makeValTabSG4 | ( | void | ) |
Returns an 8 bit value for the sum of ON pixels in a 4x4 square, according to
val = 255 - (255 * sum)/16
where sum is in set {0, ... ,16}
LEPT_DLL l_uint8* makeValTabSG6 | ( | void | ) |
Returns an 8 bit value for the sum of ON pixels in a 6x6 square, according to val = 255 - (255 * sum)/36 where sum is in set {0, ... ,36}
LEPT_DLL l_uint8* makeValTabSG8 | ( | void | ) |
Returns an 8 bit value for the sum of ON pixels in an 8x8 square, according to val = 255 - (255 * sum)/64 where sum is in set {0, ... ,64}
LEPT_DLL l_int32 morphSequenceVerify | ( | SARRAY * | sa | ) |
Input: sarray (of operation sequence) Return: TRUE if valid; FALSE otherwise or on error
Notes: (1) This does verification of valid binary morphological operation sequences. (2) See pixMorphSequence() for notes on valid operations in the sequence.
LEPT_DLL size_t nbytesInFile | ( | const char * | filename | ) |
Input: filename Return: nbytes in file; 0 on error
LEPT_DLL l_int32 nextOnPixelInRaster | ( | PIX * | pixs, |
l_int32 | xstart, | ||
l_int32 | ystart, | ||
l_int32 * | px, | ||
l_int32 * | py | ||
) |
Input: pixs (1 bpp) xstart, ystart (starting point for search) &x, &y (<return> coord value of next ON pixel) Return: 1 if a pixel is found; 0 otherwise or on error
LEPT_DLL l_int32 nextOnPixelInRasterLow | ( | l_uint32 * | data, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpl, | ||
l_int32 | xstart, | ||
l_int32 | ystart, | ||
l_int32 * | px, | ||
l_int32 * | py | ||
) |
Input: na2d row of 2d array col of 2d array val (float or int to be added; stored as a float) Return: 0 if OK, 1 on error
Input: nrows (of 2d array) ncols (of 2d array) initsize (initial size of each allocated numa) Return: numa2d, or null on error
Notes: (1) The numa2d holds a doubly-indexed array of numa. (2) The numa ptr array is initialized with all ptrs set to NULL. (3) The numas are created only when a number is to be stored at an index (i,j) for which a numa has not yet been made.
LEPT_DLL void numa2dDestroy | ( | NUMA2D ** | pna2d | ) |
Input: &numa2d (<to be="" nulled="" if="" it="" exists>="">) Return: void
Input: na2d row of 2d array col of 2d array Return: size of numa at [row][col], or 0 if the numa doesn't exist or on error
LEPT_DLL l_int32 numa2dGetFValue | ( | NUMA2D * | na2d, |
l_int32 | row, | ||
l_int32 | col, | ||
l_int32 | index, | ||
l_float32 * | pval | ||
) |
Input: na2d row of 2d array col of 2d array index (into numa) &val (<return> float value) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 numa2dGetIValue | ( | NUMA2D * | na2d, |
l_int32 | row, | ||
l_int32 | col, | ||
l_int32 | index, | ||
l_int32 * | pval | ||
) |
Input: na2d row of 2d array col of 2d array index (into numa) &val (<return> integer value) Return: 0 if OK, 1 on error
Input: na2d row of 2d array col of 2d array Return: na (a clone of the numa if it exists) or null if it doesn't
Notes: (1) This does not give an error if the index is out of bounds.
Input: naa na (to be added) copyflag (L_INSERT, L_COPY, L_CLONE) Return: 0 if OK, 1 on error
Input: naa index (of numa within numaa) val (float or int to be added; stored as a float) Return: 0 if OK, 1 on error
Notes: (1) Adds to an existing numa only.
LEPT_DLL l_int32 numaaCompareImagesByBoxes | ( | NUMAA * | naa1, |
NUMAA * | naa2, | ||
l_int32 | nperline, | ||
l_int32 | nreq, | ||
l_int32 | maxshiftx, | ||
l_int32 | maxshifty, | ||
l_int32 | delx, | ||
l_int32 | dely, | ||
l_int32 * | psame, | ||
l_int32 | debugflag | ||
) |
Input: naa1 (for image 1, formatted by boxaExtractSortedPattern()) naa2 (ditto; for image 2) nperline (number of box regions to be used in each textline) nreq (number of complete row matches required) maxshiftx (max allowed x shift between two patterns, in pixels) maxshifty (max allowed y shift between two patterns, in pixels) delx (max allowed difference in x data, after alignment) dely (max allowed difference in y data, after alignment) &same (<return> 1 if row matches are found; 0 otherwise) debugflag (1 for debug output) Return: 0 if OK, 1 on error
Notes: (1) Each input numaa describes a set of sorted bounding boxes (sorted by textline and, within each textline, from left to right) in the images from which they are derived. See boxaExtractSortedPattern() for a description of the data format in each of the input numaa. (2) This function does an alignment between the input descriptions of bounding boxes for two images. The input parameter specifies the number of boxes to consider in each line when testing for a match, and is the required number of lines that must be well-aligned to get a match. (3) Testing by alignment has 3 steps: (a) Generating the location of word bounding boxes from the images (prior to calling this function). (b) Listing all possible pairs of aligned rows, based on tolerances in horizontal and vertical positions of the boxes. Specifically, all pairs of rows are enumerated whose first boxes can be brought into close alignment, based on the delx parameter for boxes in the line and within the overall the and constraints. (c) Each pair, starting with the first, is used to search for a set of - 1 other pairs that can all be aligned with a difference in global translation of not more than (, ).
LEPT_DLL NUMAA* numaaCreate | ( | l_int32 | n | ) |
Input: size of numa ptr array to be alloc'd (0 for default) Return: naa, or null on error
Input: nas left, right (number of elements to add on each side) val (initialize border elements) Return: nad (with added elements at left and right), or null on error
LEPT_DLL l_int32 numaAddNumber | ( | NUMA * | na, |
l_float32 | val | ||
) |
Input: na val (float or int to be added; stored as a float) Return: 0 if OK, 1 on error
Input: nas left, right (number of elements to add on each side) type (L_CONTINUED_BORDER, L_MIRRORED_BORDER) Return: nad (with added elements at left and right), or null on error
LEPT_DLL void numaaDestroy | ( | NUMAA ** | pnaa | ) |
Input: &numaa <to be="" nulled="" if="" it="" exists>=""> Return: void
LEPT_DLL l_int32 numaaExtendArray | ( | NUMAA * | naa | ) |
Input: naa Return: 0 if OK, 1 on error
LEPT_DLL NUMA* numaaFlattenToNuma | ( | NUMAA * | naa | ) |
LEPT_DLL l_int32 numaaGetCount | ( | NUMAA * | naa | ) |
Input: naa Return: count (number of numa), or 0 if no numa or on error
Input: naa index (to the index-th numa) accessflag (L_COPY or L_CLONE) Return: numa, or null on error
LEPT_DLL l_int32 numaaGetNumaCount | ( | NUMAA * | naa, |
l_int32 | index | ||
) |
Input: naa index (of numa in naa) Return: count of numbers in the referenced numa, or 0 on error.
LEPT_DLL l_int32 numaaGetNumberCount | ( | NUMAA * | naa | ) |
Input: naa Return: count (total number of numbers in the numaa), or 0 if no numbers or on error
LEPT_DLL NUMA** numaaGetPtrArray | ( | NUMAA * | naa | ) |
Input: naa Return: the internal array of ptrs to Numa, or null on error
Notes: (1) This function is convenient for doing direct manipulation on a fixed size array of Numas. To do this, it sets the count to the full size of the allocated array of Numa ptrs. The originating Numaa owns this array: DO NOT free it! (2) Intended usage: Numaa *naa = numaaCreate(n); Numa **array = numaaGetPtrArray(naa); ... [manipulate Numas directly on the array] numaaDestroy(&naa); (3) Cautions:
Input: naa i (index of numa within numaa) j (index into numa) val (<return> float value) Return: 0 if OK, 1 on error
Input: filename Return: naa, or null on error
LEPT_DLL NUMAA* numaaReadStream | ( | FILE * | fp | ) |
Input: stream Return: naa, or null on error
Input: naa index (to the index-th numa) numa (insert and replace any existing one) Return: 0 if OK, 1 on error
Notes: (1) Any existing numa is destroyed, and the input one is inserted in its place. (2) If the index is invalid, return 1 (error)
Input: nad (<optional> can be null or equal to na1 (in-place) na1 na2 op (L_ARITH_ADD, L_ARITH_SUBTRACT, L_ARITH_MULTIPLY, L_ARITH_DIVIDE) Return: nad (always: operation applied to na1 and na2)
Notes: (1) The sizes of na1 and na2 must be equal. (2) nad can only null or equal to na1. (3) To add a constant to a numa, or to multipy a numa by a constant, use numaTransform().
LEPT_DLL l_int32 numaaWrite | ( | const char * | filename, |
NUMAA * | naa | ||
) |
Input: filename, naa Return: 0 if OK, 1 on error
LEPT_DLL l_int32 numaaWriteStream | ( | FILE * | fp, |
NUMAA * | naa | ||
) |
Input: stream, naa Return: 0 if OK, 1 on error
LEPT_DLL NUMA* numaBinSort | ( | NUMA * | nas, |
l_int32 | sortorder | ||
) |
Input: nas (of non-negative integers with a max that is typically less than 50,000) sortorder (L_SORT_INCREASING or L_SORT_DECREASING) Return: na (sorted), or null on error
Notes: (1) Because this uses a bin sort with buckets of size 1, it is not appropriate for sorting either small arrays or arrays containing very large integer values. For such arrays, use a standard general sort function like numaSort().
LEPT_DLL l_int32 numaChangeRefcount | ( | NUMA * | na, |
l_int32 | delta | ||
) |
numaChangeRefCount()
Input: na delta (change to be applied) Return: 0 if OK, 1 on error
Input: numa first, last (clipping interval) Return: numa with the same values as the input, but clipped to the specified interval
Note: If you want the indices of the array values to be unchanged, use first = 0. Usage: This is useful to clip a histogram that has a few nonzero values to its nonzero range.
Input: na Return: ptr to same numa, or null on error
Input: nas size (of sel; greater than 0, odd; origin implicitly in center) Return: nad (opened), or null on error
Notes: (1) The structuring element (sel) is linear, all "hits" (2) If size == 1, this returns a copy (3) We add a border before doing this operation, for the same reason that we add a border to a pix before doing a safe closing. Without the border, a small component near the border gets clipped at the border on dilation, and can be entirely removed by the following erosion, violating the basic extensivity property of closing.
LEPT_DLL NUMA* numaContrastTRC | ( | l_float32 | factor | ) |
Input: factor (generally between 0.0 (no enhancement) and 1.0, but can be larger than 1.0) Return: na, or null on error
Notes: (1) The mapping is monotonic increasing, where 0 is mapped to 0 and 255 is mapped to 255. (2) As 'factor' is increased from 0.0 (where the mapping is linear), the map gets closer to its limit as a step function that jumps from 0 to 255 at the center (input value = 127).
LEPT_DLL L_DNA* numaConvertToDna | ( | NUMA * | na | ) |
numaConvertToDna
Input: na Return: da, or null on error
LEPT_DLL NUMA* numaConvertToInt | ( | NUMA * | nas | ) |
Input: na Return: na with all values rounded to nearest integer, or null on error
Input: na Return: copy of numa, or null on error
LEPT_DLL l_int32 numaCopyXParameters | ( | NUMA * | nad, |
NUMA * | nas | ||
) |
LEPT_DLL l_int32 numaCountReversals | ( | NUMA * | nas, |
l_float32 | minreversal, | ||
l_int32 * | pnr, | ||
l_float32 * | pnrpl | ||
) |
Input: nas (input values) minreversal (relative amount to resolve peaks and valleys) &nr (<optional return>=""> number of reversals &nrpl (<optional return>=""> reversal density: reversals/length) Return: 0 if OK, 1 on error
Notes: (1) The input numa is can be generated from pixExtractAlongLine(). If so, the x parameters can be used to find the reversal frequency along a line.
LEPT_DLL NUMA* numaCreate | ( | l_int32 | n | ) |
Input: size of number array to be alloc'd (0 for default) Return: na, or null on error
Input: farray (float) size (of the array) copyflag (L_INSERT or L_COPY) Return: na, or null on error
Notes: (1) With L_INSERT, ownership of the input array is transferred to the returned numa, and all elements are considered to be valid.
LEPT_DLL NUMA* numaCreateFromIArray | ( | l_int32 * | iarray, |
l_int32 | size | ||
) |
Input: iarray (integer) size (of the array) Return: na, or null on error
Notes: (1) We can't insert this int array into the numa, because a numa takes a float array. So this just copies the data from the input array into the numa. The input array continues to be owned by the caller.
Input: nax (<optional> numa of abscissa values) nay (numa of ordinate values, corresponding to nax) delta (parameter used to identify when a new peak can be found) Return: nad (abscissa pts at threshold), or null on error
Notes: (1) If nax == NULL, we use startx and delx from nay to compute the crossing values in nad.
Input: nax (<optional> numa of abscissa values; can be NULL) nay (numa of ordinate values, corresponding to nax) thresh (threshold value for nay) Return: nad (abscissa pts at threshold), or null on error
Notes: (1) If nax == NULL, we use startx and delx from nay to compute the crossing values in nad.
LEPT_DLL void numaDestroy | ( | NUMA ** | pna | ) |
Input: &na (<to be="" nulled="" if="" it="" exists>="">) Return: void
Notes: (1) Decrements the ref count and, if 0, destroys the numa. (2) Always nulls the input ptr.
LEPT_DLL l_int32 numaDifferentiateInterval | ( | NUMA * | nax, |
NUMA * | nay, | ||
l_float32 | x0, | ||
l_float32 | x1, | ||
l_int32 | npts, | ||
NUMA ** | pnadx, | ||
NUMA ** | pnady | ||
) |
Input: nax (numa of abscissa values) nay (numa of ordinate values, corresponding to nax) x0 (start value of interval) x1 (end value of interval) npts (number of points to evaluate function in interval) &nadx (<optional return>=""> array of x values in interval) &nady (<return> array of derivatives in interval) Return: 0 if OK, 1 on error (e.g., if x0 or x1 is outside range)
Notes: (1) The values in nax must be sorted in increasing order. If they are not sorted, it is done in the interpolation step, and a warning is issued. (2) Caller should check for valid return.
LEPT_DLL NUMA* numaDilate | ( | NUMA * | nas, |
l_int32 | size | ||
) |
Input: nas size (of sel; greater than 0, odd; origin implicitly in center) Return: nad (dilated), or null on error
Notes: (1) The structuring element (sel) is linear, all "hits" (2) If size == 1, this returns a copy
LEPT_DLL l_int32 numaDiscretizeRankAndIntensity | ( | NUMA * | na, |
l_int32 | nbins, | ||
NUMA ** | pnarbin, | ||
NUMA ** | pnam, | ||
NUMA ** | pnar, | ||
NUMA ** | pnabb | ||
) |
numaDiscretizeRankAndIntensity()
Input: na (normalized histogram of probability density vs intensity) nbins (number of bins at which the rank is divided) &pnarbin (<optional return>=""> rank bin value vs intensity) &pnam (<optional return>=""> median intensity in a bin vs rank bin value, with of discretized rank values) &pnar (<optional return>=""> rank vs intensity; this is a cumulative norm histogram) &pnabb (<optional return>=""> intensity at the right bin boundary vs rank bin) Return: 0 if OK, 1 on error
Notes: (1) We are inverting the rank(intensity) function to get the intensity(rank) function at equally spaced values of rank between 0.0 and 1.0. We save integer values for the intensity. (2) We are using the word "intensity" to describe the type of array values, but any array of non-negative numbers will work. (3) The output arrays give the following mappings, where the input is a normalized histogram of array values: array values --> rank bin number (narbin) rank bin number --> median array value in bin (nam) array values --> cumulative norm = rank (nar) rank bin number --> array value at right bin edge (nabb)
Input: na Return: 0 if OK; 1 on error
Notes: (1) This does not change the allocation of the array. It just clears the number of stored numbers, so that the array appears to be empty.
Input: pix (8 bpp, no colormap) fract (fraction of equalization movement of pixel values) factor (subsampling factor; integer >= 1) Return: nad, or null on error
Notes: (1) If fract == 0.0, no equalization will be performed. If fract == 1.0, equalization is complete. (2) Set the subsampling factor > 1 to reduce the amount of computation. (3) The map is returned as a numa with 256 values, specifying the equalized value (array value) for every input value (the array index).
Input: nas size (of sel; greater than 0, odd; origin implicitly in center) Return: nad (eroded), or null on error
Notes: (1) The structuring element (sel) is linear, all "hits" (2) If size == 1, this returns a copy (3) General comment. The morphological operations are equivalent to those that would be performed on a 1-dimensional fpix. However, because we have not implemented morphological operations on fpix, we do this here. Because it is only 1 dimensional, there is no reason to use the more complicated van Herk/Gil-Werman algorithm, and we do it by brute force.
LEPT_DLL l_int32 numaEvalBestHaarParameters | ( | NUMA * | nas, |
l_float32 | relweight, | ||
l_int32 | nwidth, | ||
l_int32 | nshift, | ||
l_float32 | minwidth, | ||
l_float32 | maxwidth, | ||
l_float32 * | pbestwidth, | ||
l_float32 * | pbestshift, | ||
l_float32 * | pbestscore | ||
) |
Input: nas (numa of non-negative signal values) relweight (relative weight of (-1 comb) / (+1 comb) contributions to the 'convolution'. In effect, the convolution kernel is a comb consisting of alternating +1 and -weight.) nwidth (number of widths to consider) nshift (number of shifts to consider for each width) minwidth (smallest width to consider) maxwidth (largest width to consider) &bestwidth (<return> width giving largest score) &bestshift (<return> shift giving largest score) &bestscore (<optional return>=""> convolution with "Haar"-like comb) Return: 0 if OK, 1 on error
Notes: (1) This does a linear sweep of widths, evaluating at shifts for each width, computing the score from a convolution with a long comb, and finding the (width, shift) pair that gives the maximum score. The best width is the "half-wavelength" of the signal. (2) The convolving function is a comb of alternating values +1 and -1 * relweight, separated by the width and phased by the shift. This is similar to a Haar transform, except there the convolution is performed with a square wave. (3) The function is useful for finding the line spacing and strength of line signal from pixel sum projections. (4) The score is normalized to the size of nas divided by the number of half-widths. For image applications, the input is typically an array of pixel projections, so one should normalize by dividing the score by the image width in the pixel projection direction.
LEPT_DLL l_int32 numaEvalHaarSum | ( | NUMA * | nas, |
l_float32 | width, | ||
l_float32 | shift, | ||
l_float32 | relweight, | ||
l_float32 * | pscore | ||
) |
Input: nas (numa of non-negative signal values) width (distance between +1 and -1 in convolution comb) shift (phase of the comb: location of first +1) relweight (relative weight of (-1 comb) / (+1 comb) contributions to the 'convolution'. In effect, the convolution kernel is a comb consisting of alternating +1 and -weight.) &score (<return> convolution with "Haar"-like comb) Return: 0 if OK, 1 on error
Notes: (1) This does a convolution with a comb of alternating values +1 and -relweight, separated by the width and phased by the shift. This is similar to a Haar transform, except that for Haar, (1) the convolution kernel is symmetric about 0, so the relweight is 1.0, and (2) the convolution is performed with a square wave. (2) The score is normalized to the size of nas divided by twice the "width". For image applications, the input is typically an array of pixel projections, so one should normalize by dividing the score by the image width in the pixel projection direction. (3) To get a Haar-like result, use relweight = 1.0. For detecting signals where you expect every other sample to be close to zero, as with barcodes or filtered text lines, you can use relweight > 1.0.
LEPT_DLL l_int32 numaExtendArray | ( | NUMA * | na | ) |
Input: na Return: 0 if OK, 1 on error
LEPT_DLL NUMA* numaFindExtrema | ( | NUMA * | nas, |
l_float32 | delta | ||
) |
Input: nas (input values) delta (relative amount to resolve peaks and valleys) Return: nad (locations of extrema), or null on error
Notes: (1) This returns a sequence of extrema (peaks and valleys). (2) The algorithm is analogous to that for determining mountain peaks. Suppose we have a local peak, with bumps on the side. Under what conditions can we consider those 'bumps' to be actual peaks? The answer: if the bump is separated from the peak by a saddle that is at least 500 feet below the bump. (3) Operationally, suppose we are looking for a peak. We are keeping the largest value we've seen since the last valley, and are looking for a value that is delta BELOW our current peak. When we find such a value, we label the peak, use the current value to label the valley, and then do the same operation in reverse (looking for a valley).
Input: source na max number of peaks to be found fract1 (min fraction of peak value) fract2 (min slope) Return: peak na, or null on error.
Notes: (1) The returned na consists of sets of four numbers representing the peak, in the following order: left edge; peak center; right edge; normalized peak area
Input: na (numa of ordinate values, to fit a max to) &maxval (<return> max value) naloc (<optional> associated numa of abscissa values) &maxloc (<return> abscissa value that gives max value in na; if naloc == null, this is given as an interpolated index value) Return: 0 if OK; 1 on error
Note: if naloc is given, there is no requirement that the data points are evenly spaced. Lagrangian interpolation handles that. The only requirement is that the data points are ordered so that the values in naloc are either increasing or decreasing. We test to make sure that the sizes of na and naloc are equal, and it is assumed that the correspondences na[i] as a function of naloc[i] are properly arranged for all i.
The formula for Lagrangian interpolation through 3 data pts is: y(x) = y1(x-x2)(x-x3)/((x1-x2)(x1-x3)) + y2(x-x1)(x-x3)/((x2-x1)(x2-x3)) + y3(x-x1)(x-x2)/((x3-x1)(x3-x2))
Then the derivative, using the constants (c1,c2,c3) defined below, is set to 0: y'(x) = 2x(c1+c2+c3) - c1(x2+x3) - c2(x1+x3) - c3(x1+x2) = 0
Input: gamma (gamma factor; must be > 0.0) minval (input value that gives 0 for output) maxval (input value that gives 255 for output) Return: na, or null on error
Notes: (1) The map is returned as a numa; values are clipped to [0, 255]. (2) To force all intensities into a range within fraction delta of white, use: minval = -256 * (1 - delta) / delta maxval = 255 (3) To force all intensities into a range within fraction delta of black, use: minval = 0 maxval = 256 * (1 - delta) / delta
LEPT_DLL l_int32 numaGetBinnedMedian | ( | NUMA * | na, |
l_int32 * | pval | ||
) |
Input: na &val (<return> integer median value) Return: 0 if OK; 1 on error
Notes: (1) Computes the median value of the numbers in the numa, using bin sort and finding the middle value in the sorted array. (2) See numaGetRankValue() for conditions on na for which this should be used. Otherwise, use numaGetMedian().
LEPT_DLL NUMA* numaGetBinSortIndex | ( | NUMA * | nas, |
l_int32 | sortorder | ||
) |
Input: na (of non-negative integers with a max that is typically less than 50,000) sortorder (L_SORT_INCREASING or L_SORT_DECREASING) Return: na (sorted), or null on error
Notes: (1) This creates an array (or lookup table) that gives the sorted position of the elements in the input Numa. (2) Because it uses a bin sort with buckets of size 1, it is not appropriate for sorting either small arrays or arrays containing very large integer values. For such arrays, use a standard general sort function like numaGetSortIndex().
LEPT_DLL l_int32 numaGetCount | ( | NUMA * | na | ) |
Input: na Return: count, or 0 if no numbers or on error
Input: numa type (L_LESS_THAN_ZERO, L_EQUAL_TO_ZERO, L_GREATER_THAN_ZERO) &count (<return> count of values of given type) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 numaGetEdgeValues | ( | NUMA * | na, |
l_int32 | edge, | ||
l_int32 * | pstart, | ||
l_int32 * | pend, | ||
l_int32 * | psign | ||
) |
Input: na (numa that is output of numaThresholdEdges()) edge (edge number, zero-based) &start (<optional return>=""> location of start of transition) &end (<optional return>=""> location of end of transition) &sign (<optional return>=""> transition sign: +1 is rising, -1 is falling) Output: 0 if OK, 1 on error
LEPT_DLL l_float32* numaGetFArray | ( | NUMA * | na, |
l_int32 | copyflag | ||
) |
Input: na copyflag (L_NOCOPY or L_COPY) Return: either the bare internal array or a copy of it, or null on error
Notes: (1) If copyflag == L_COPY, it makes a copy which the caller is responsible for freeing. Otherwise, it operates directly on the bare array of the numa. (2) Very important: for L_NOCOPY, any writes to the array will be in the numa. Do not write beyond the size of the count field, because it will not be accessable from the numa! If necessary, be sure to set the count field to a larger number (such as the alloc size) BEFORE calling this function. Creating with numaMakeConstant() is another way to insure full initialization.
Input: na index (into numa) &val (<return> float value; 0.0 on error) Return: 0 if OK; 1 on error
Notes: (1) Caller may need to check the function return value to decide if a 0.0 in the returned ival is valid.
LEPT_DLL l_int32 numaGetHistogramStats | ( | NUMA * | nahisto, |
l_float32 | startx, | ||
l_float32 | deltax, | ||
l_float32 * | pxmean, | ||
l_float32 * | pxmedian, | ||
l_float32 * | pxmode, | ||
l_float32 * | pxvariance | ||
) |
Input: nahisto (histogram: y(x(i)), i = 0 ... nbins - 1) startx (x value of first bin: x(0)) deltax (x increment between bins; the bin size; x(1) - x(0)) &xmean (<optional return>=""> mean value of histogram) &xmedian (<optional return>=""> median value of histogram) &xmode (<optional return>=""> mode value of histogram: xmode = x(imode), where y(xmode) >= y(x(i)) for all i != imode) &xvariance (<optional return>=""> variance of x) Return: 0 if OK, 1 on error
Notes: (1) If the histogram represents the relation y(x), the computed values that are returned are the x values. These are NOT the bucket indices i; they are related to the bucket indices by x(i) = startx + i * deltax
LEPT_DLL l_int32 numaGetHistogramStatsOnInterval | ( | NUMA * | nahisto, |
l_float32 | startx, | ||
l_float32 | deltax, | ||
l_int32 | ifirst, | ||
l_int32 | ilast, | ||
l_float32 * | pxmean, | ||
l_float32 * | pxmedian, | ||
l_float32 * | pxmode, | ||
l_float32 * | pxvariance | ||
) |
numaGetHistogramStatsOnInterval()
Input: nahisto (histogram: y(x(i)), i = 0 ... nbins - 1) startx (x value of first bin: x(0)) deltax (x increment between bins; the bin size; x(1) - x(0)) ifirst (first bin to use for collecting stats) ilast (last bin for collecting stats; use 0 to go to the end) &xmean (<optional return>=""> mean value of histogram) &xmedian (<optional return>=""> median value of histogram) &xmode (<optional return>=""> mode value of histogram: xmode = x(imode), where y(xmode) >= y(x(i)) for all i != imode) &xvariance (<optional return>=""> variance of x) Return: 0 if OK, 1 on error
Notes: (1) If the histogram represents the relation y(x), the computed values that are returned are the x values. These are NOT the bucket indices i; they are related to the bucket indices by x(i) = startx + i * deltax
LEPT_DLL l_int32* numaGetIArray | ( | NUMA * | na | ) |
Input: na Return: a copy of the bare internal array, integerized by rounding, or null on error Notes: (1) A copy of the array is always made, because we need to generate an integer array from the bare float array. The caller is responsible for freeing the array. (2) The array size is determined by the number of stored numbers, not by the size of the allocated array in the Numa. (3) This function is provided to simplify calculations using the bare internal array, rather than continually calling accessors on the numa. It is typically used on an array of size 256.
Input: na index (into numa) &ival (<return> integer value; 0 on error) Return: 0 if OK; 1 on error
Notes: (1) Caller may need to check the function return value to decide if a 0 in the returned ival is valid.
Input: na &maxval (<optional return>=""> max value) &imaxloc (<optional return>=""> index of max location) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 numaGetMedian | ( | NUMA * | na, |
l_float32 * | pval | ||
) |
Input: na &val (<return> median value) Return: 0 if OK; 1 on error
Notes: (1) Computes the median value of the numbers in the numa, by sorting and finding the middle value in the sorted array.
Input: na &medval (<optional return>=""> median value) &medvar (<return> median variation from median val) Return: 0 if OK; 1 on error
Notes: (1) Finds the median variation from the median value in the array.
Input: na &minval (<optional return>=""> min value) &iminloc (<optional return>=""> index of min location) Return: 0 if OK; 1 on error
Input: na &val (<return> mode val) &count (<optional return>=""> mode count) Return: 0 if OK; 1 on error
Notes: (1) Computes the mode value of the numbers in the numa, by sorting and finding the value of the number with the largest count. (2) Optionally, also returns that count.
LEPT_DLL l_int32 numaGetNonzeroRange | ( | NUMA * | na, |
l_float32 | eps, | ||
l_int32 * | pfirst, | ||
l_int32 * | plast | ||
) |
Input: numa eps (largest value considered to be zero) &first, &last (<return> interval of array indices where values are nonzero) Return: 0 if OK, 1 on error or if no nonzero range is found.
LEPT_DLL NUMA* numaGetPartialSums | ( | NUMA * | na | ) |
Input: na Return: nasum, or null on error
Notes: (1) nasum[i] is the sum for all j <= i of na[j]. So nasum[0] = na[0]. (2) If you want to generate a rank function, where rank[0] - 0.0, insert a 0.0 at the beginning of the nasum array.
Input: na (just an array of values) nbins (number of bins at which the rank is divided) &pnarbin (<optional return>=""> rank bin value vs array value) &pnam (<optional return>=""> median intensity in a bin vs rank bin value, with of discretized rank values) Return: 0 if OK, 1 on error
Notes: (1) Simple interface for getting a binned rank representation of an input array of values. This returns two mappings: array value --> rank bin number (narbin) rank bin number --> median array value in each rank bin (nam)
LEPT_DLL l_int32 numaGetRankValue | ( | NUMA * | na, |
l_float32 | fract, | ||
NUMA * | nasort, | ||
l_int32 | usebins, | ||
l_float32 * | pval | ||
) |
Input: na fract (use 0.0 for smallest, 1.0 for largest) nasort (<optional> increasing sorted version of na) usebins (0 for general sort; 1 for bin sort) &val (<return> rank val) Return: 0 if OK; 1 on error
Notes: (1) Computes the rank value of a number in the , which is the number that is a fraction from the small end of the sorted version of . (2) If you do this multiple times for different rank values, sort the array in advance and use that for ; if you're only calling this once, input == NULL. (3) If == 1, this uses a bin sorting method. Use this only where: * the numbers are non-negative integers * there are over 100 numbers * the maximum value is less than about 50,000 (4) The advantage of using a bin sort is that it is O(n), instead of O(nlogn) for general sort routines.
LEPT_DLL l_int32 numaGetRefcount | ( | NUMA * | na | ) |
numaGetRefCount()
Input: na Return: refcount, or UNDEF on error
LEPT_DLL NUMA* numaGetSortIndex | ( | NUMA * | na, |
l_int32 | sortorder | ||
) |
Input: na sortorder (L_SORT_INCREASING or L_SORT_DECREASING) Return: na giving an array of indices that would sort the input array, or null on error
Input: na (numa that is output of numaLowPassIntervals()) span (span number, zero-based) &start (<optional return>=""> location of start of transition) &end (<optional return>=""> location of end of transition) Output: 0 if OK, 1 on error
LEPT_DLL l_int32 numaGetStatsUsingHistogram | ( | NUMA * | na, |
l_int32 | maxbins, | ||
l_float32 * | pmin, | ||
l_float32 * | pmax, | ||
l_float32 * | pmean, | ||
l_float32 * | pvariance, | ||
l_float32 * | pmedian, | ||
l_float32 | rank, | ||
l_float32 * | prval, | ||
NUMA ** | phisto | ||
) |
Input: na (an arbitrary set of numbers; not ordered and not a histogram) maxbins (the maximum number of bins to be allowed in the histogram; use 0 for consecutive integer bins) &min (<optional return>=""> min value of set) &max (<optional return>=""> max value of set) &mean (<optional return>=""> mean value of set) &variance (<optional return>=""> variance) &median (<optional return>=""> median value of set) rank (in [0.0 ... 1.0]; median has a rank 0.5; ignored if &rval == NULL) &rval (<optional return>=""> value in na corresponding to ) &histo (<optional return>=""> Numa histogram; use NULL to prevent) Return: 0 if OK, 1 on error
Notes: (1) This is a simple interface for gathering statistics from a numa, where a histogram is used 'under the covers' to avoid sorting if a rank value is requested. In that case, by using a histogram we are trading speed for accuracy, because the values in are quantized to the center of a set of bins. (2) If the median, other rank value, or histogram are not requested, the calculation is all performed on the input Numa. (3) The variance is the average of the square of the difference from the mean. The median is the value in na with rank 0.5. (4) There are two situations where this gives rank results with accuracy comparable to computing stastics directly on the input data, without binning into a histogram: (a) the data is integers and the range of data is less than , and (b) the data is floats and the range is small compared to , so that the binsize is much less than 1. (5) If a histogram is used and the numbers in the Numa extend over a large range, you can limit the required storage by specifying the maximum number of bins in the histogram. Use == 0 to force the bin size to be 1. (6) This optionally returns the median and one arbitrary rank value. If you need several rank values, return the histogram and use numaHistogramGetValFromRank(nah, rank, &rval) multiple times.
LEPT_DLL l_int32 numaGetSum | ( | NUMA * | na, |
l_float32 * | psum | ||
) |
Input: na &sum (<return> sum of values) Return: 0 if OK, 1 on error
Input: na first (beginning index) last (final index) &sum (<return> sum of values in the index interval range) Return: 0 if OK, 1 on error
Input: na &startx (<optional return>=""> startx) &delx (<optional return>=""> delx) Return: 0 if OK, 1 on error
Input: nahash key (key to be hashed into a bucket number) value (float value to be appended to the specific numa) Return: 0 if OK; 1 on error
LEPT_DLL NUMAHASH* numaHashCreate | ( | l_int32 | nbuckets, |
l_int32 | initsize | ||
) |
Input: nbuckets (the number of buckets in the hash table, which should be prime.) initsize (initial size of each allocated numa; 0 for default) Return: ptr to new nahash, or null on error
Note: actual numa are created only as required by numaHashAdd()
LEPT_DLL void numaHashDestroy | ( | NUMAHASH ** | pnahash | ) |
Input: &nahash (<to be nulled, if it exists>) Return: void
LEPT_DLL NUMA* numaHashGetNuma | ( | NUMAHASH * | nahash, |
l_uint32 | key | ||
) |
Input: nahash key (key to be hashed into a bucket number) Return: ptr to numa
Input: na maxsamples (maximum number of samples to check) &allints (<return> 1 if all sampled values are ints; else 0) Return: 0 if OK, 1 on error
Notes: (1) Set == 0 to check every integer in na. Otherwise, this samples no more than .
Input: na (histogram) rval (value of input sample for which we want the rank) &rank (<return> fraction of total samples below rval) Return: 0 if OK, 1 on error
Notes: (1) If we think of the histogram as a function y(x), normalized to 1, for a given input value of x, this computes the rank of x, which is the integral of y(x) from the start value of x to the input value. (2) This function only makes sense when applied to a Numa that is a histogram. The values in the histogram can be ints and floats, and are computed as floats. The rank is returned as a float between 0.0 and 1.0. (3) The numa parameters startx and binsize are used to compute x from the Numa index i.
Input: na (histogram) rank (fraction of total samples) &rval (<return> approx. to the bin value) Return: 0 if OK, 1 on error
Notes: (1) If we think of the histogram as a function y(x), this returns the value x such that the integral of y(x) from the start value to x gives the fraction 'rank' of the integral of y(x) over all bins. (2) This function only makes sense when applied to a Numa that is a histogram. The values in the histogram can be ints and floats, and are computed as floats. The val is returned as a float, even though the buckets are of integer width. (3) The numa parameters startx and binsize are used to compute x from the Numa index i.
Input: na index (location in na to insert new value) val (float32 or integer to be added) Return: 0 if OK, 1 on error
Notes: (1) This shifts na[i] --> na[i + 1] for all i >= index, and then inserts val as na[index]. (2) It should not be used repeatedly on large arrays, because the function is O(n).
LEPT_DLL l_int32 numaIntegrateInterval | ( | NUMA * | nax, |
NUMA * | nay, | ||
l_float32 | x0, | ||
l_float32 | x1, | ||
l_int32 | npts, | ||
l_float32 * | psum | ||
) |
Input: nax (numa of abscissa values) nay (numa of ordinate values, corresponding to nax) x0 (start value of interval) x1 (end value of interval) npts (number of points to evaluate function in interval) &sum (<return> integral of function over interval) Return: 0 if OK, 1 on error (e.g., if x0 or x1 is outside range)
Notes: (1) The values in nax must be sorted in increasing order. If they are not sorted, it is done in the interpolation step, and a warning is issued. (2) Caller should check for valid return.
LEPT_DLL l_int32 numaInterpolateArbxInterval | ( | NUMA * | nax, |
NUMA * | nay, | ||
l_int32 | type, | ||
l_float32 | x0, | ||
l_float32 | x1, | ||
l_int32 | npts, | ||
NUMA ** | pnadx, | ||
NUMA ** | pnady | ||
) |
Input: nax (numa of abscissa values) nay (numa of ordinate values, corresponding to nax) type (L_LINEAR_INTERP, L_QUADRATIC_INTERP) x0 (start value of interval) x1 (end value of interval) npts (number of points to evaluate function in interval) &nadx (<optional return>=""> array of x values in interval) &nady (<return> array of y values in interval) Return: 0 if OK, 1 on error (e.g., if x0 or x1 is outside range)
Notes: (1) The values in nax must be sorted in increasing order. If they are not sorted, we do it here, and complain. (2) If the values in nax are equally spaced, you can use numaInterpolateEqxInterval(). (3) Caller should check for valid return. (4) We don't call numaInterpolateArbxVal() for each output point, because that requires an O(n) search for each point. Instead, we do a single O(n) pass through nax, saving the indices to be used for each output yval. (5) Uses lagrangian interpolation. See numaInterpolateEqxVal() for formulas.
LEPT_DLL l_int32 numaInterpolateArbxVal | ( | NUMA * | nax, |
NUMA * | nay, | ||
l_int32 | type, | ||
l_float32 | xval, | ||
l_float32 * | pyval | ||
) |
Input: nax (numa of abscissa values) nay (numa of ordinate values, corresponding to nax) type (L_LINEAR_INTERP, L_QUADRATIC_INTERP) xval &yval (<return> interpolated value) Return: 0 if OK, 1 on error (e.g., if xval is outside range)
Notes: (1) The values in nax must be sorted in increasing order. If, additionally, they are equally spaced, you can use numaInterpolateEqxVal(). (2) Caller should check for valid return. (3) Uses lagrangian interpolation. See numaInterpolateEqxVal() for formulas.
LEPT_DLL l_int32 numaInterpolateEqxInterval | ( | l_float32 | startx, |
l_float32 | deltax, | ||
NUMA * | nasy, | ||
l_int32 | type, | ||
l_float32 | x0, | ||
l_float32 | x1, | ||
l_int32 | npts, | ||
NUMA ** | pnax, | ||
NUMA ** | pnay | ||
) |
Input: startx (xval corresponding to first element in nas) deltax (x increment between array elements in nas) nasy (numa of ordinate values, assumed equally spaced) type (L_LINEAR_INTERP, L_QUADRATIC_INTERP) x0 (start value of interval) x1 (end value of interval) npts (number of points to evaluate function in interval) &nax (<optional return>=""> array of x values in interval) &nay (<return> array of y values in interval) Return: 0 if OK, 1 on error
Notes: (1) Considering nasy as a function of x, the x values are equally spaced. (2) This creates nay (and optionally nax) of interpolated values over the specified interval (x0, x1). (3) If the interval (x0, x1) lies partially outside the array nasy (as interpreted by startx and deltax), it is an error and returns 1. (4) Note that deltax is the intrinsic x-increment for the input array nasy, whereas delx is the intrinsic x-increment for the output interpolated array nay.
LEPT_DLL l_int32 numaInterpolateEqxVal | ( | l_float32 | startx, |
l_float32 | deltax, | ||
NUMA * | nay, | ||
l_int32 | type, | ||
l_float32 | xval, | ||
l_float32 * | pyval | ||
) |
Input: startx (xval corresponding to first element in array) deltax (x increment between array elements) nay (numa of ordinate values, assumed equally spaced) type (L_LINEAR_INTERP, L_QUADRATIC_INTERP) xval &yval (<return> interpolated value) Return: 0 if OK, 1 on error (e.g., if xval is outside range)
Notes: (1) Considering nay as a function of x, the x values are equally spaced (2) Caller should check for valid return.
For linear Lagrangian interpolation (through 2 data pts): y(x) = y1(x-x2)/(x1-x2) + y2(x-x1)/(x2-x1)
For quadratic Lagrangian interpolation (through 3 data pts): y(x) = y1(x-x2)(x-x3)/((x1-x2)(x1-x3)) + y2(x-x1)(x-x3)/((x2-x1)(x2-x3)) + y3(x-x1)(x-x2)/((x3-x1)(x3-x2))
LEPT_DLL NUMA* numaInvert | ( | NUMA * | nad, |
NUMA * | nas | ||
) |
Input: nad (<optional> can be null or equal to nas (in-place) nas Return: nad (always: 'inverts' nas)
Notes: (1) This is intended for use with indicator arrays (0s and 1s). It gives a boolean-type output, taking the input as an integer and inverting it: 0 --> 1 anything else --> 0
Input: nas sortorder (L_SORT_INCREASING or L_SORT_DECREASING) &sorted (<return> 1 if sorted; 0 if not) Return: 1 if OK; 0 on error
Notes: (1) This is a quick O(n) test if nas is sorted. It is useful in situations where the array is likely to be already sorted, and a sort operation can be avoided.
Input: nad (dest numa; add to this one) nas (<optional> source numa; add from this one) istart (starting index in nas) iend (ending index in nas; use 0 to cat all) Return: 0 if OK, 1 on error
Notes: (1) istart < 0 is taken to mean 'read from the start' (istart = 0) (2) iend <= 0 means 'read to the end' (3) if nas == NULL, this is a no-op
Input: nad (<optional> can be null or equal to na1 (in-place) na1 na2 op (L_UNION, L_INTERSECTION, L_SUBTRACTION, L_EXCLUSIVE_OR) Return: nad (always: operation applied to na1 and na2)
Notes: (1) The sizes of na1 and na2 must be equal. (2) nad can only null or equal to na1. (3) This is intended for use with indicator arrays (0s and 1s). Input data is extracted as integers (0 == false, anything else == true); output results are 0 and 1. (4) L_SUBTRACTION is subtraction of val2 from val1. For bit logical arithmetic this is (val1 & ~val2), but because these values are integers, we use (val1 && !val2).
Input: nas (input numa) thresh (threshold fraction of max; in [0.0 ... 1.0]) maxn (for normalizing; set maxn = 0.0 to use the max in nas) Output: nad (interval abscissa pairs), or null on error
Notes: (1) For each interval where the value is less than a specified fraction of the maximum, this records the left and right "x" value.
LEPT_DLL NUMA* numaMakeAbsValue | ( | NUMA * | nad, |
NUMA * | nas | ||
) |
Input: nad (can be null for new array, or the same as nas for inplace) nas (input numa) Return: nad (with all numbers being the absval of the input), or null on error
LEPT_DLL NUMA* numaMakeConstant | ( | l_float32 | val, |
l_int32 | size | ||
) |
Input: val size (of numa) Return: numa (of given size with all entries equal to 'val'), or null on error
LEPT_DLL NUMA* numaMakeDelta | ( | NUMA * | nas | ) |
Input: nas (input numa) Return: numa (of difference values val[i+1] - val[i]), or null on error
LEPT_DLL NUMA* numaMakeHistogram | ( | NUMA * | na, |
l_int32 | maxbins, | ||
l_int32 * | pbinsize, | ||
l_int32 * | pbinstart | ||
) |
Input: na maxbins (max number of histogram bins) &binsize (<return> size of histogram bins) &binstart (<optional return>=""> start val of minimum bin; input NULL to force start at 0) Return: na consisiting of histogram of integerized values, or null on error.
Note: (1) This simple interface is designed for integer data. The bins are of integer width and start on integer boundaries, so the results on float data will not have high precision. (2) Specify the max number of input bins. Then , the size of bins necessary to accommodate the input data, is returned. It is one of the sequence: {1, 2, 5, 10, 20, 50, ...}. (3) If &binstart is given, all values are accommodated, and the min value of the starting bin is returned. Otherwise, all negative values are discarded and the histogram bins start at 0.
LEPT_DLL NUMA* numaMakeHistogramAuto | ( | NUMA * | na, |
l_int32 | maxbins | ||
) |
Input: na (numa of floats; these may be integers) maxbins (max number of histogram bins; >= 1) Return: na consisiting of histogram of quantized float values, or null on error.
Notes: (1) This simple interface is designed for accurate binning of both integer and float data. (2) If the array data is integers, and the range of integers is smaller than , they are binned as they fall, with binsize = 1. (3) If the range of data, (maxval - minval), is larger than , or if the data is floats, they are binned into exactly bins. (4) Unlike numaMakeHistogram(), these bins in general have non-integer location and width, even for integer data.
Input: na binsize (typically 1.0) maxsize (of histogram ordinate) Return: na (histogram of bins of size , starting with the na[0] (x = 0.0) and going up to a maximum of x = , by increments of ), or null on error
Notes: (1) This simple function generates a histogram of values from na, discarding all values < 0.0 or greater than min(, maxval), where maxval is the maximum value in na. The histogram data is put in bins of size delx = , starting at x = 0.0. We use as many bins as are needed to hold the data.
LEPT_DLL l_int32 numaMakeRankFromHistogram | ( | l_float32 | startx, |
l_float32 | deltax, | ||
NUMA * | nasy, | ||
l_int32 | npts, | ||
NUMA ** | pnax, | ||
NUMA ** | pnay | ||
) |
Input: startx (xval corresponding to first element in nay) deltax (x increment between array elements in nay) nasy (input histogram, assumed equally spaced) npts (number of points to evaluate rank function) &nax (<optional return>=""> array of x values in range) &nay (<return> rank array of specified npts) Return: 0 if OK, 1 on error
Input: startval increment size (of sequence) Return: numa of sequence of evenly spaced values, or null on error
Input: nas (input numa) thresh (threshold value) type (L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE) Output: nad (indicator array: values are 0 and 1)
Notes: (1) For each element in nas, if the constraint given by 'type' correctly specifies its relation to thresh, a value of 1 is recorded in nad.
LEPT_DLL NUMA* numaNormalizeHistogram | ( | NUMA * | nas, |
l_float32 | area | ||
) |
Input: nas (input histogram) area (target sum of all numbers in dest histogram; e.g., use area = 1.0 if this represents a probability distribution) Return: nad (normalized histogram), or null on error
Input: nas size (of sel; greater than 0, odd; origin implicitly in center) Return: nad (opened), or null on error
Notes: (1) The structuring element (sel) is linear, all "hits" (2) If size == 1, this returns a copy
LEPT_DLL NUMA* numaPseudorandomSequence | ( | l_int32 | size, |
l_int32 | seed | ||
) |
Input: size (of sequence) seed (for random number generation) Return: na (pseudorandom on {0,...,size - 1}), or null on error
Notes: (1) This uses the Durstenfeld shuffle. See: http://en.wikipedia.org/wiki/Fisher–Yates_shuffle. Result is a pseudorandom permutation of the sequence of integers from 0 to size - 1.
LEPT_DLL NUMA* numaQuantizeCrossingsByWidth | ( | NUMA * | nas, |
l_float32 | binfract, | ||
NUMA ** | pnaehist, | ||
NUMA ** | pnaohist, | ||
l_int32 | debugflag | ||
) |
numaQuantizeCrossingsByWidth()
Input: nas (numa of crossing locations, in pixel units) binfract (histo binsize as a fraction of minsize; e.g., 0.25) &naehist (<optional return>=""> histo of even (black) bar widths) &naohist (<optional return>=""> histo of odd (white) bar widths) debugflag (1 to generate plots of histograms of bar widths) Return: nad (sequence of widths, in unit sizes), or null on error
Notes: (1) This first computes the histogram of black and white bar widths, binned in appropriate units. There should be well-defined peaks, each corresponding to a specific width. The sequence of barcode widths (namely, the integers from the set {1,2,3,4}) is returned. (2) The optional returned histograms are binned in width units that are inversely proportional to . For example, if = 0.25, there are 4.0 bins in the distance of the width of the narrowest bar.
LEPT_DLL NUMA* numaQuantizeCrossingsByWindow | ( | NUMA * | nas, |
l_float32 | ratio, | ||
l_float32 * | pwidth, | ||
l_float32 * | pfirstloc, | ||
NUMA ** | pnac, | ||
l_int32 | debugflag | ||
) |
numaQuantizeCrossingsByWindow()
Input: nas (numa of crossing locations) ratio (of max window size over min window size in search; typ. 2.0) &width (<optional return>=""> best window width) &firstloc (<optional return>=""> center of window for first xing) &nac (<optional return>=""> array of window crossings (0, 1, 2)) debugflag (1 to generate various plots of intermediate results) Return: nad (sequence of widths, in unit sizes), or null on error
Notes: (1) The minimum size of the window is set by the minimum distance between zero crossings. (2) The optional return signal is a sequence of 0s, 1s, and perhaps a few 2s, giving the number of crossings in each window. On the occasion where there is a '2', it is interpreted as ending two runs: the previous one and another one that has length 1.
LEPT_DLL NUMA* numaRandomPermutation | ( | NUMA * | nas, |
l_int32 | seed | ||
) |
Input: nas (input array) seed (for random number generation) Return: nas (randomly shuffled array), or null on error
Input: filename Return: na, or null on error
LEPT_DLL NUMA* numaReadStream | ( | FILE * | fp | ) |
Input: stream Return: numa, or null on error
LEPT_DLL NUMA* numaRebinHistogram | ( | NUMA * | nas, |
l_int32 | newsize | ||
) |
Input: nas (input histogram) newsize (number of old bins contained in each new bin) Return: nad (more coarsely re-binned histogram), or null on error
Input: nas left, right (number of elements to remove from each side) Return: nad (with removed elements at left and right), or null on error
LEPT_DLL l_int32 numaRemoveNumber | ( | NUMA * | na, |
l_int32 | index | ||
) |
Input: na index (element to be removed) Return: 0 if OK, 1 on error
Notes: (1) This shifts na[i] --> na[i - 1] for all i > index. (2) It should not be used repeatedly on large arrays, because the function is O(n).
Input: na index (element to be replaced) val (new value to replace old one) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 numaSelectCrossingThreshold | ( | NUMA * | nax, |
NUMA * | nay, | ||
l_float32 | estthresh, | ||
l_float32 * | pbestthresh | ||
) |
Input: nax (<optional> numa of abscissa values; can be NULL) nay (signal) estthresh (estimated pixel threshold for crossing: e.g., for images, white <--> black; typ. ~120) &bestthresh (<return> robust estimate of threshold to use) Return: 0 if OK, 1 on error
Note: (1) When a valid threshold is used, the number of crossings is a maximum, because none are missed. If no threshold intersects all the crossings, the crossings must be determined with numaCrossingsByPeaks(). (2) is an input estimate of the threshold that should be used. We compute the crossings with 41 thresholds (20 below and 20 above). There is a range in which the number of crossings is a maximum. Return a threshold in the center of this stable plateau of crossings. This can then be used with numaCrossingsByThreshold() to get a good estimate of crossing locations.
LEPT_DLL l_int32 numaSetCount | ( | NUMA * | na, |
l_int32 | newcount | ||
) |
Input: na newcount Return: 0 if OK, 1 on error
Notes: (1) If newcount <= na->nalloc, this resets na->n. Using newcount = 0 is equivalent to numaEmpty(). (2) If newcount > na->nalloc, this causes a realloc to a size na->nalloc = newcount. (3) All the previously unused values in na are set to 0.0.
Input: na index (to element to be set) val (to set element) Return: 0 if OK; 1 on error
Input: na startx (x value corresponding to na[0]) delx (difference in x values for the situation where the elements of na correspond to the evaulation of a function at equal intervals of size ) Return: 0 if OK, 1 on error
Input: na index (to element to change relative to the current value) diff (increment if diff > 0 or decrement if diff < 0) Return: 0 if OK; 1 on error
Input: naout (output numa; can be NULL or equal to nain) nain (input numa) sortorder (L_SORT_INCREASING or L_SORT_DECREASING) Return: naout (output sorted numa), or null on error
Notes: (1) Set naout = nain for in-place; otherwise, set naout = NULL. (2) Source: Shell sort, modified from K&R, 2nd edition, p.62. Slow but simple O(n logn) sort.
LEPT_DLL NUMA* numaSortByIndex | ( | NUMA * | nas, |
NUMA * | naindex | ||
) |
Input: nas naindex (na that maps from the new numa to the input numa) Return: nad (sorted), or null on error
LEPT_DLL l_int32 numaSortPair | ( | NUMA * | nax, |
NUMA * | nay, | ||
l_int32 | sortorder, | ||
NUMA ** | pnasx, | ||
NUMA ** | pnasy | ||
) |
Input: nax, nay (input arrays) sortorder (L_SORT_INCREASING or L_SORT_DECREASING) &nasx (<return> sorted) &naxy (<return> sorted exactly in order of nasx) Return: 0 if OK, 1 on error
Notes: (1) This function sorts the two input arrays, nax and nay, together, using nax as the key for sorting.
LEPT_DLL l_int32 numaSplitDistribution | ( | NUMA * | na, |
l_float32 | scorefract, | ||
l_int32 * | psplitindex, | ||
l_float32 * | pave1, | ||
l_float32 * | pave2, | ||
l_float32 * | pnum1, | ||
l_float32 * | pnum2, | ||
NUMA ** | pnascore | ||
) |
Input: na (histogram) scorefract (fraction of the max score, used to determine the range over which the histogram min is searched) &splitindex (<optional return>=""> index for splitting) &ave1 (<optional return>=""> average of lower distribution) &ave2 (<optional return>=""> average of upper distribution) &num1 (<optional return>=""> population of lower distribution) &num2 (<optional return>=""> population of upper distribution) &nascore (<optional return>=""> for debugging; otherwise use null) Return: 0 if OK, 1 on error
Notes: (1) This function is intended to be used on a distribution of values that represent two sets, such as a histogram of pixel values for an image with a fg and bg, and the goal is to determine the averages of the two sets and the best splitting point. (2) The Otsu method finds a split point that divides the distribution into two parts by maximizing a score function that is the product of two terms: (a) the square of the difference of centroids, (ave1 - ave2)^2 (b) fract1 * (1 - fract1) where fract1 is the fraction in the lower distribution. (3) This works well for images where the fg and bg are each relatively homogeneous and well-separated in color. However, if the actual fg and bg sets are very different in size, and the bg is highly varied, as can occur in some scanned document images, this will bias the split point into the larger "bump" (i.e., toward the point where the (b) term reaches its maximum of 0.25 at fract1 = 0.5. To avoid this, we define a range of values near the maximum of the score function, and choose the value within this range such that the histogram itself has a minimum value. The range is determined by scorefract: we include all abscissa values to the left and right of the value that maximizes the score, such that the score stays above (1 - scorefract) * maxscore. The intuition behind this modification is to try to find a split point that both has a high variance score and is at or near a minimum in the histogram, so that the histogram slope is small at the split point. (4) We normalize the score so that if the two distributions were of equal size and at opposite ends of the numa, the score would be 1.0.
LEPT_DLL NUMA* numaSubsample | ( | NUMA * | nas, |
l_int32 | subfactor | ||
) |
Input: nas subfactor (subsample factor, >= 1) Return: nad (evenly sampled values from nas), or null on error
LEPT_DLL NUMA* numaThresholdEdges | ( | NUMA * | nas, |
l_float32 | thresh1, | ||
l_float32 | thresh2, | ||
l_float32 | maxn | ||
) |
Input: nas (input numa) thresh1 (low threshold as fraction of max; in [0.0 ... 1.0]) thresh2 (high threshold as fraction of max; in [0.0 ... 1.0]) maxn (for normalizing; set maxn = 0.0 to use the max in nas) Output: nad (edge interval triplets), or null on error
Notes: (1) For each edge interval, where where the value is less than on one side, greater than on the other, and between these thresholds throughout the interval, this records a triplet of values: the 'left' and 'right' edges, and either +1 or -1, depending on whether the edge is rising or falling. (2) No assumption is made about the value outside the array, so if the value at the array edge is between the threshold values, it is not considered part of an edge. We start looking for edge intervals only after leaving the thresholded band.
LEPT_DLL NUMA* numaUniformSampling | ( | NUMA * | nas, |
l_int32 | nsamp | ||
) |
Input: nas (input numa) nsamp (number of samples) Output: nad (resampled array), or null on error
Notes: (1) This resamples the values in the array, using equal divisions.
LEPT_DLL NUMA* numaWindowedMean | ( | NUMA * | nas, |
l_int32 | wc | ||
) |
Input: nas wc (half width of the convolution window) Return: nad (after low-pass filtering), or null on error
Notes: (1) This is a convolution. The window has width = 2 * + 1. (2) We add a mirrored border of size to each end of the array.
LEPT_DLL NUMA* numaWindowedMeanSquare | ( | NUMA * | nas, |
l_int32 | wc | ||
) |
Input: nas wc (half width of the window) Return: nad (containing windowed mean square values), or null on error
Notes: (1) The window has width = 2 * + 1. (2) We add a mirrored border of size to each end of the array.
LEPT_DLL l_int32 numaWindowedStats | ( | NUMA * | nas, |
l_int32 | wc, | ||
NUMA ** | pnam, | ||
NUMA ** | pnams, | ||
NUMA ** | pnav, | ||
NUMA ** | pnarv | ||
) |
Input: nas (input numa) wc (half width of the window) &nam (<optional return>=""> mean value in window) &nams (<optional return>=""> mean square value in window) &pnav (<optional return>=""> variance in window) &pnarv (<optional return>=""> rms deviation from the mean) Return: 0 if OK, 1 on error
Notes: (1) This is a high-level convenience function for calculating any or all of these derived arrays. (2) These statistical measures over the values in the rectangular window are:
Input: nam (windowed mean values) nams (windowed mean square values) &pnav (<optional return>=""> numa of variance -- the ms deviation from the mean) &pnarv (<optional return>=""> numa of rms deviation from the mean) Return: 0 if OK, 1 on error
Notes: (1) The numas of windowed mean and mean square are precomputed, using numaWindowedMean() and numaWindowedMeanSquare(). (2) Either or both of the variance and square-root of variance are returned, where the variance is the average over the window of the mean square difference of the pixel value from the mean: <(x - <x>)*(x - <x>)> = <x*x> - <x>*<x>
Input: filename, na Return: 0 if OK, 1 on error
LEPT_DLL l_int32 numaWriteStream | ( | FILE * | fp, |
NUMA * | na | ||
) |
Input: stream, na Return: 0 if OK, 1 on error
LEPT_DLL char* parseForProtos | ( | const char * | filein, |
const char * | prestring | ||
) |
LEPT_DLL NUMA* parseStringForNumbers | ( | const char * | str, |
const char * | seps | ||
) |
Input: string (containing numbers; not changed) seps (string of characters that can be used between ints) Return: numa (of numbers found), or null on error
Note: (1) The numbers can be ints or floats.
Input: pixaa box copyflag (L_INSERT, L_COPY, L_CLONE) Return: 0 if OK, 1 on error
Notes: (1) The box can be used, for example, to hold the support region of a pixa that is being added to the pixaa.
Input: pixaa pixa (to be added) copyflag: L_INSERT inserts the pixa directly L_COPY makes a new pixa and copies each pix and each box L_CLONE gives a new handle to the input pixa L_COPY_CLONE makes a new pixa and inserts clones of all pix and boxes Return: 0 if OK; 1 on error
LEPT_DLL PIXAA* pixaaCreate | ( | l_int32 | n | ) |
Input: n (initial number of pixa ptrs) Return: pixaa, or null on error
Notes: (1) A pixaa provides a 2-level hierarchy of images. A common use is for segmentation masks, which are inexpensive to store in png format. (2) For example, suppose you want a mask for each textline in a two-column page. The textline masks for each column can be represented by a pixa, of which there are 2 in the pixaa. The boxes for the textline mask components within a column can have their origin referred to the column rather than the page. Then the boxa field can be used to represent the two box (regions) for the columns, and the (x,y) components of each box can be used to get the absolute position of the textlines on the page.
Input: pixa n (number specifying subdivision of pixa) type (L_CHOOSE_CONSECUTIVE, L_CHOOSE_SKIP_BY) copyflag (L_CLONE, L_COPY) Return: pixaa, or null on error
Notes: (1) This subdivides a pixa into a set of smaller pixa that are accumulated into a pixaa. (2) If type == L_CHOOSE_CONSECUTIVE, the first 'n' pix are put in a pixa and added to pixaa, then the next 'n', etc. If type == L_CHOOSE_SKIP_BY, the first pixa is made by aggregating pix[0], pix[n], pix[2*n], etc. (3) The copyflag specifies if each new pix is a copy or a clone.
LEPT_DLL PIXA* pixaAddBorderGeneral | ( | PIXA * | pixad, |
PIXA * | pixas, | ||
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot, | ||
l_uint32 | val | ||
) |
Input: pixad (can be null or equal to pixas) pixas (containing pix of all depths; colormap ok) left, right, top, bot (number of pixels added) val (value of added border pixels) Return: pixad (with border added to each pix), including on error
Notes: (1) For binary images: white: val = 0 black: val = 1 For grayscale images: white: val = 2 ** d - 1 black: val = 0 For rgb color images: white: val = 0xffffff00 black: val = 0 For colormapped images, use 'index' found this way: white: pixcmapGetRankIntensity(cmap, 1.0, &index); black: pixcmapGetRankIntensity(cmap, 0.0, &index); (2) For in-place replacement of each pix with a bordered version, use = . To make a new pixa, use = NULL. (3) In both cases, the boxa has sides adjusted as if it were expanded by the border.
Input: pixa box copyflag (L_INSERT, L_COPY, L_CLONE) Return: 0 if OK, 1 on error
Input: pixa pix (to be added) copyflag (L_INSERT, L_COPY, L_CLONE) Return: 0 if OK; 1 on error
LEPT_DLL void pixaaDestroy | ( | PIXAA ** | ppixaa | ) |
Input: &pixaa <to be="" nulled>=""> Return: void
Input: pixaa w, h (if set to 0, determines the size from the b.b. of the components in pixaa) Return: pix, or null on error
Notes: (1) Each pix of the pixaa is displayed at the location given by its box, translated by the box of the containing pixa if it exists.
Input: pixaa xspace between pix in pixa yspace between pixa max width of output pix Return: pix, or null on error
Notes: (1) Displays each pixa on a line (or set of lines), in order from top to bottom. Within each pixa, the pix are displayed in order from left to right. (2) The size of each pix in each pixa is assumed to be approximately equal to the size of the first pix in the pixa. If this assumption is not correct, this function will not work properly. (3) This ignores the boxa of the pixaa.
LEPT_DLL PIXA* pixaaDisplayTiledAndScaled | ( | PIXAA * | pixaa, |
l_int32 | outdepth, | ||
l_int32 | tilewidth, | ||
l_int32 | ncols, | ||
l_int32 | background, | ||
l_int32 | spacing, | ||
l_int32 | border | ||
) |
Input: pixaa outdepth (output depth: 1, 8 or 32 bpp) tilewidth (each pix is scaled to this width) ncols (number of tiles in each row) background (0 for white, 1 for black; this is the color of the spacing between the images) spacing (between images, and on outside) border (width of additional black border on each image; use 0 for no border) Return: pixa (of tiled images, one image for each pixa in the pixaa), or null on error
Notes: (1) For each pixa, this generates from all the pix a tiled/scaled output pix, and puts it in the output pixa. (2) See comments in pixaDisplayTiledAndScaled().
LEPT_DLL l_int32 pixaaExtendArray | ( | PIXAA * | pixaa | ) |
Input: pixaa Return: 0 if OK; 1 on error
Input: pixaa &naindex (<optional return>=""> the pixa index in the pixaa) copyflag (L_COPY or L_CLONE) Return: pixa, or null on error
Notes: (1) This 'flattens' the pixaa to a pixa, taking the pix in order in the first pixa, then the second, etc. (2) If &naindex is defined, we generate a Numa that gives, for each pix in the pixaa, the index of the pixa to which it belongs.
LEPT_DLL BOXA* pixaaGetBoxa | ( | PIXAA * | pixaa, |
l_int32 | accesstype | ||
) |
Input: pixaa accesstype (L_COPY, L_CLONE) Return: boxa, or null on error
Notes: (1) L_COPY returns a copy; L_CLONE returns a new reference to the boxa. (2) In both cases, invoke boxaDestroy() on the returned boxa.
LEPT_DLL l_int32 pixaaGetCount | ( | PIXAA * | pixaa | ) |
Input: pixaa Return: count, or 0 if no pixaa
Input: paa ipixa (index into the pixa array in the pixaa) ipix (index into the pix array in the pixa) accessflag (L_COPY or L_CLONE) Return: pix, or null on error
Input: pixaa index (to the index-th pixa) accesstype (L_COPY, L_CLONE, L_COPY_CLONE) Return: pixa, or null on error
Notes: (1) L_COPY makes a new pixa with a copy of every pix (2) L_CLONE just makes a new reference to the pixa, and bumps the counter. You would use this, for example, when you need to extract some data from a pix within a pixa within a pixaa. (3) L_COPY_CLONE makes a new pixa with a clone of every pix and box (4) In all cases, you must invoke pixaDestroy() on the returned pixa
LEPT_DLL l_int32 pixaAnyColormaps | ( | PIXA * | pixa, |
l_int32 * | phascmap | ||
) |
Input: pixa &hascmap (<return> 1 if any pix has a colormap; 0 otherwise) Return: 0 if OK; 1 on error
Input: filename Return: pixaa, or null on error
Notes: (1) The pix are stored in the file as png. If the png library is not linked, this will fail.
LEPT_DLL PIXAA* pixaaReadStream | ( | FILE * | fp | ) |
Input: stream Return: pixaa, or null on error
Notes: (1) The pix are stored in the file as png. If the png library is not linked, this will fail.
LEPT_DLL l_int32 pixaaWrite | ( | const char * | filename, |
PIXAA * | pixaa | ||
) |
Input: filename pixaa Return: 0 if OK, 1 on error
Notes: (1) The pix are stored in the file as png. If the png library is not linked, this will fail.
LEPT_DLL l_int32 pixaaWriteStream | ( | FILE * | fp, |
PIXAA * | pixaa | ||
) |
Input: stream (opened for "wb") pixaa Return: 0 if OK, 1 on error
Notes: (1) The pix are stored in the file as png. If the png library is not linked, this will fail.
LEPT_DLL PIXA* pixaBinSort | ( | PIXA * | pixas, |
l_int32 | sorttype, | ||
l_int32 | sortorder, | ||
NUMA ** | pnaindex, | ||
l_int32 | copyflag | ||
) |
Input: pixas sorttype (L_SORT_BY_X, L_SORT_BY_Y, L_SORT_BY_WIDTH, L_SORT_BY_HEIGHT, L_SORT_BY_PERIMETER) sortorder (L_SORT_INCREASING, L_SORT_DECREASING) &naindex (<optional return>=""> index of sorted order into original array) copyflag (L_COPY, L_CLONE) Return: pixad (sorted version of pixas), or null on error
Notes: (1) This sorts based on the data in the boxa. If the boxa count is not the same as the pixa count, this returns an error. (2) The copyflag refers to the pix and box copies that are inserted into the sorted pixa. These are either L_COPY or L_CLONE. (3) For a large number of boxes (say, greater than 1000), this O(n) binsort is much faster than the O(nlogn) shellsort. For 5000 components, this is over 20x faster than boxaSort(). (4) Consequently, pixaSort() calls this function if it will likely go much faster.
LEPT_DLL PIX* pixAbsDifference | ( | PIX * | pixs1, |
PIX * | pixs2 | ||
) |
Input: pixs1, pixs2 (both either 8 or 16 bpp gray, or 32 bpp RGB) Return: pixd, or null on error
Notes: (1) The depth of pixs1 and pixs2 must be equal. (2) Clips computation to the min size, aligning the UL corners (3) For 8 and 16 bpp, assumes one gray component. (4) For 32 bpp, assumes 3 color components, and ignores the LSB of each word (the alpha channel) (5) Computes the absolute value of the difference between each component value.
Input: pixacc pix (to be added) Return: 0 if OK, 1 on error
Input: w, h (of 32 bpp internal Pix) negflag (0 if only positive numbers are involved; 1 if there will be negative numbers) Return: pixacc, or null on error
Notes: (1) Use = 1 for safety if any negative numbers are going to be used in the chain of operations. Negative numbers arise, e.g., by subtracting a pix, or by adding a pix that has been pre-multiplied by a negative number. (2) Initializes the internal 32 bpp pix, similarly to the initialization in pixInitAccumulate().
LEPT_DLL PIXACC* pixaccCreateWithPix | ( | PIX * | pix, |
l_int32 | negflag | ||
) |
Input: pix negflag (0 if only positive numbers are involved; 1 if there will be negative numbers) Return: pixacc, or null on error
Notes: (1) See pixaccCreate()
LEPT_DLL void pixaccDestroy | ( | PIXACC ** | ppixacc | ) |
Input: &pixacc (<can be="" null>="">) Return: void
Notes: (1) Always nulls the input ptr.
LEPT_DLL PIX* pixaccFinal | ( | PIXACC * | pixacc, |
l_int32 | outdepth | ||
) |
Input: pixacc outdepth (8, 16 or 32 bpp) Return: pixd (8 , 16 or 32 bpp), or null on error
LEPT_DLL l_int32 pixaccGetOffset | ( | PIXACC * | pixacc | ) |
Input: pixacc Return: offset, or -1 on error
LEPT_DLL PIX* pixaccGetPix | ( | PIXACC * | pixacc | ) |
Input: pixacc Return: pix, or null on error
LEPT_DLL l_int32 pixaccMultConst | ( | PIXACC * | pixacc, |
l_float32 | factor | ||
) |
Input: pixacc factor Return: 0 if OK, 1 on error
Input: pixacc pix factor Return: 0 if OK, 1 on error
Notes: (1) This creates a temp pix that is multiplied by the constant . It then adds that into .
LEPT_DLL l_int32 pixaccSubtract | ( | PIXACC * | pixacc, |
PIX * | pix | ||
) |
Input: pixacc pix (to be subtracted) Return: 0 if OK, 1 on error
Input: pixd (32 bpp) pixs (1, 8, 16 or 32 bpp) op (L_ARITH_ADD or L_ARITH_SUBTRACT) Return: 0 if OK; 1 on error
Notes: (1) This adds or subtracts each pixs value from pixd. (2) This clips to the minimum of pixs and pixd, so they do not need to be the same size. (3) The alignment is to the origin (UL corner) of pixs & pixd.
LEPT_DLL PTA* pixaCentroids | ( | PIXA * | pixa | ) |
Input: pixa of components (1 or 8 bpp) Return: pta of centroids relative to the UL corner of each pix, or null on error
Notes: (1) An error message is returned if any pix has something other than 1 bpp or 8 bpp depth, and the centroid from that pix is saved as (0, 0).
LEPT_DLL l_int32 pixaChangeRefcount | ( | PIXA * | pixa, |
l_int32 | delta | ||
) |
Input: pixa Return: 0 if OK, 1 on error
Input: pixa Return: 0 if OK, 1 on error
Notes: (1) This destroys all pix in the pixa, as well as all boxes in the boxa. The ptrs in the pix ptr array are all null'd. The number of allocated pix, n, is set to 0.
LEPT_DLL PIXA* pixaClipToPix | ( | PIXA * | pixas, |
PIX * | pixs | ||
) |
Input: pixas pixs Return: pixad, or null on error
Notes: (1) This is intended for use in situations where pixas was originally generated from the input pixs. (2) Returns a pixad where each pix in pixas is ANDed with its associated region of the input pixs. This region is specified by the the box that is associated with the pix. (3) In a typical application of this function, pixas has a set of region masks, so this generates a pixa of the parts of pixs that correspond to each region mask component, along with the bounding box for the region.
Input: pixac box copyflag (L_INSERT, L_COPY) Return: 0 if OK, 1 on error
Input: pixac pix (to be added) comptype (IFF_DEFAULT, IFF_TIFF_G4, IFF_PNG, IFF_JFIF_JPEG) Return: 0 if OK; 1 on error
Notes: (1) The array is filled up to the (n-1)-th element, and this converts the input pix to a pixcomp and adds it at the n-th position.
LEPT_DLL l_int32 pixacompAddPixcomp | ( | PIXAC * | pixac, |
PIXC * | pixc | ||
) |
Input: pixac pixc (to be added by insertion) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 pixacompConvertToPdf | ( | PIXAC * | pixac, |
l_int32 | res, | ||
l_float32 | scalefactor, | ||
l_int32 | type, | ||
l_int32 | quality, | ||
const char * | title, | ||
const char * | fileout | ||
) |
Input: pixac (containing images all at the same resolution) res (override the resolution of each input image, in ppi; use 0 to respect the resolution embedded in the input) scalefactor (scaling factor applied to each image; > 0.0) type (encoding type (L_JPEG_ENCODE, L_G4_ENCODE, L_FLATE_ENCODE, or 0 for default) quality (used for JPEG only; 0 for default (75)) title (<optional> pdf title; if null, taken from the first image filename) fileout (pdf file of all images) Return: 0 if OK, 1 on error
Notes: (1) This follows closely the function pixaConvertToPdf() in pdfio.c. (2) The images are encoded with G4 if 1 bpp; JPEG if 8 bpp without colormap and many colors, or 32 bpp; FLATE for anything else. (3) The scalefactor must be > 0.0; otherwise it is set to 1.0. (4) Specifying one of the three encoding types for forces all images to be compressed with that type. Use 0 to have the type determined for each image based on depth and whether or not it has a colormap.
LEPT_DLL l_int32 pixacompConvertToPdfData | ( | PIXAC * | pixac, |
l_int32 | res, | ||
l_float32 | scalefactor, | ||
l_int32 | type, | ||
l_int32 | quality, | ||
const char * | title, | ||
l_uint8 ** | pdata, | ||
size_t * | pnbytes | ||
) |
Input: pixac (containing images all at the same resolution) res (input resolution of all images) scalefactor (scaling factor applied to each image; > 0.0) type (encoding type (L_JPEG_ENCODE, L_G4_ENCODE, L_FLATE_ENCODE, or 0 for default) quality (used for JPEG only; 0 for default (75)) title (<optional> pdf title; if null, taken from the first image filename) &data (<return> output pdf data (of all images) &nbytes (<return> size of output pdf data) Return: 0 if OK, 1 on error
Notes: (1) See pixacompConvertToPdf().
LEPT_DLL PIXAC* pixacompCreate | ( | l_int32 | n | ) |
Input: n (initial number of ptrs) Return: pixac, or null on error
LEPT_DLL PIXAC* pixacompCreateFromFiles | ( | const char * | dirname, |
const char * | substr, | ||
l_int32 | comptype | ||
) |
Input: dirname substr (<optional> substring filter on filenames; can be null) comptype (IFF_DEFAULT, IFF_TIFF_G4, IFF_PNG, IFF_JFIF_JPEG) Return: pixac, or null on error
Notes: (1) is the full path for the directory. (2) is the part of the file name (excluding the directory) that is to be matched. All matching filenames are read into the Pixa. If substr is NULL, all filenames are read into the Pixa. (3) Use == IFF_DEFAULT to have the compression type automatically determined for each file. (4) If the comptype is invalid for a file, the default will be substituted.
Input: pixa comptype (IFF_DEFAULT, IFF_TIFF_G4, IFF_PNG, IFF_JFIF_JPEG) accesstype (L_COPY, L_CLONE, L_COPY_CLONE; for boxa) Return: 0 if OK, 1 on error
Notes: (1) If == IFF_DEFAULT, the conversion format for each image is chosen automatically. Otherwise, we use the specified format unless it can't be done (e.g., jpeg for a 1, 2 or 4 bpp pix, or a pix with a colormap), in which case we use the default (assumed best) compression.
LEPT_DLL PIXAC* pixacompCreateFromSA | ( | SARRAY * | sa, |
l_int32 | comptype | ||
) |
Input: sarray (full pathnames for all files) comptype (IFF_DEFAULT, IFF_TIFF_G4, IFF_PNG, IFF_JFIF_JPEG) Return: pixac, or null on error
Notes: (1) Use == IFF_DEFAULT to have the compression type automatically determined for each file. (2) If the comptype is invalid for a file, the default will be substituted.
LEPT_DLL PIXAC* pixacompCreateInitialized | ( | l_int32 | n, |
l_int32 | offset, | ||
PIX * | pix, | ||
l_int32 | comptype | ||
) |
Input: n (initial number of ptrs) offset (difference: accessor index - pixacomp array index) pix (initialize each ptr in pixacomp to this pix) comptype (IFF_DEFAULT, IFF_TIFF_G4, IFF_PNG, IFF_JFIF_JPEG) Return: pixac, or null on error
Notes: (1) Initializes a pixacomp to be fully populated with . (2) Typically use a very small (w = h = 1) with == IFF_TIFF_G4 for the initialization. (3) Example usage: // Generate pixacomp for pages 30 - 49. This has an array // size of 20 and the page number offset is 30. Pix *pix = pixCreate(1, 1, 1); Pixacomp *pixac = pixacompCreateInitialized(20, 30, pix, IFF_TIFF_G4); for (pageno = 30; pageno < 50; pageno++) { Pix *pixt = ... // derived from image[pageno] if (pixt) pixacompReplacePix(pixac, pageno, pixt, IFF_TIFF_G4); pixDestroy(&pixt); } The result is a pixac with 20 compressed strings, and with selected pixt replacing the placeholders.
LEPT_DLL void pixacompDestroy | ( | PIXAC ** | ppixac | ) |
Input: &pixac (<to be="" nulled>="">) Return: void
Notes: (1) Always nulls the input ptr.
LEPT_DLL PIX* pixacompDisplayTiledAndScaled | ( | PIXAC * | pixac, |
l_int32 | outdepth, | ||
l_int32 | tilewidth, | ||
l_int32 | ncols, | ||
l_int32 | background, | ||
l_int32 | spacing, | ||
l_int32 | border | ||
) |
pixacompDisplayTiledAndScaled()
Input: pixac outdepth (output depth: 1, 8 or 32 bpp) tilewidth (each pix is scaled to this width) ncols (number of tiles in each row) background (0 for white, 1 for black; this is the color of the spacing between the images) spacing (between images, and on outside) border (width of additional black border on each image; use 0 for no border) Return: pix of tiled images, or null on error
Notes: (1) This is the same function as pixaDisplayTiledAndScaled(), except it works on a Pixacomp instead of a Pix. It is particularly useful for showing the images in a Pixacomp at reduced resolution. (2) This can be used to tile a number of renderings of an image that are at different scales and depths. (3) Each image, after scaling and optionally adding the black border, has width 'tilewidth'. Thus, the border does not affect the spacing between the image tiles. The maximum allowed border width is tilewidth / 5.
LEPT_DLL l_int32 pixacompExtendArray | ( | PIXAC * | pixac | ) |
Input: pixac Return: 0 if OK; 1 on error
Notes: (1) We extend the boxa array simultaneously. This is necessary in case we are NOT adding boxes simultaneously with adding pixc. We always want the sizes of the pixac and boxa ptr arrays to be equal.
Input: pixac index (caller's view of index within pixac; includes offset) accesstype (L_COPY or L_CLONE) Return: box (if null, not automatically an error), or null on error
Notes: (1) The includes the offset, which must be subtracted to get the actual index into the ptr array. (2) There is always a boxa with a pixac, and it is initialized so that each box ptr is NULL. (3) In general, we expect that there is either a box associated with each pixc, or no boxes at all in the boxa. (4) Having no boxes is thus not an automatic error. Whether it is an actual error is determined by the calling program. If the caller expects to get a box, it is an error; see, e.g., pixacGetBoxGeometry().
LEPT_DLL BOXA* pixacompGetBoxa | ( | PIXAC * | pixac, |
l_int32 | accesstype | ||
) |
Input: pixac accesstype (L_COPY, L_CLONE, L_COPY_CLONE) Return: boxa, or null on error
LEPT_DLL l_int32 pixacompGetBoxaCount | ( | PIXAC * | pixac | ) |
Input: pixac Return: count, or 0 on error
LEPT_DLL l_int32 pixacompGetBoxGeometry | ( | PIXAC * | pixac, |
l_int32 | index, | ||
l_int32 * | px, | ||
l_int32 * | py, | ||
l_int32 * | pw, | ||
l_int32 * | ph | ||
) |
Input: pixac index (caller's view of index within pixac; includes offset) &x, &y, &w, &h (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
Notes: (1) The includes the offset, which must be subtracted to get the actual index into the ptr array.
LEPT_DLL l_int32 pixacompGetCount | ( | PIXAC * | pixac | ) |
Input: pixac Return: count, or 0 if no pixa
LEPT_DLL l_int32 pixacompGetOffset | ( | PIXAC * | pixac | ) |
Input: pixac Return: offset, or 0 on error
Notes: (1) The offset is the difference between the caller's view of the index into the array and the actual array index. By default it is 0.
LEPT_DLL PIX* pixacompGetPix | ( | PIXAC * | pixac, |
l_int32 | index | ||
) |
Input: pixac index (caller's view of index within pixac; includes offset) Return: pix, or null on error
Notes: (1) The includes the offset, which must be subtracted to get the actual index into the ptr array.
LEPT_DLL PIXC* pixacompGetPixcomp | ( | PIXAC * | pixac, |
l_int32 | index | ||
) |
Input: pixac index (caller's view of index within pixac; includes offset) Return: pixc, or null on error
Notes: (1) The includes the offset, which must be subtracted to get the actual index into the ptr array. (2) Important: this is just a ptr to the pixc owned by the pixac. Do not destroy unless you are replacing the pixc.
LEPT_DLL l_int32 pixacompGetPixDimensions | ( | PIXAC * | pixac, |
l_int32 | index, | ||
l_int32 * | pw, | ||
l_int32 * | ph, | ||
l_int32 * | pd | ||
) |
Input: pixa index (caller's view of index within pixac; includes offset) &w, &h, &d (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
Notes: (1) The includes the offset, which must be subtracted to get the actual index into the ptr array.
LEPT_DLL PIXAC* pixacompRead | ( | const char * | filename | ) |
Input: filename Return: pixac, or null on error
Notes: (1) Unlike the situation with serialized Pixa, where the image data is stored in png format, the Pixacomp image data can be stored in tiffg4, png and jpg formats.
LEPT_DLL PIXAC* pixacompReadStream | ( | FILE * | fp | ) |
Input: stream Return: pixac, or null on error
Input: pixac index (caller's view of index within pixac; includes offset) pix (owned by the caller) comptype (IFF_DEFAULT, IFF_TIFF_G4, IFF_PNG, IFF_JFIF_JPEG) Return: 0 if OK; 1 on error
Notes: (1) The includes the offset, which must be subtracted to get the actual index into the ptr array. (2) The input is converted to a pixc, which is then inserted into the pixac.
Input: pixac index (caller's view of index within pixac; includes offset) pixc (to replace existing one, which is destroyed) Return: 0 if OK; 1 on error
Notes: (1) The includes the offset, which must be subtracted to get the actual index into the ptr array. (2) The inserted is now owned by the pixac. The caller must not destroy it.
LEPT_DLL l_int32 pixacompSetOffset | ( | PIXAC * | pixac, |
l_int32 | offset | ||
) |
Input: pixac offset (non-negative) Return: 0 if OK, 1 on error
Notes: (1) The offset is the difference between the caller's view of the index into the array and the actual array index. By default it is 0.
LEPT_DLL l_int32 pixacompWrite | ( | const char * | filename, |
PIXAC * | pixac | ||
) |
Input: filename pixac Return: 0 if OK, 1 on error
Notes: (1) Unlike the situation with serialized Pixa, where the image data is stored in png format, the Pixacomp image data can be stored in tiffg4, png and jpg formats.
LEPT_DLL l_int32 pixacompWriteStream | ( | FILE * | fp, |
PIXAC * | pixac | ||
) |
Input: stream pixac Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixacompWriteStreamInfo | ( | FILE * | fp, |
PIXAC * | pixac, | ||
const char * | text | ||
) |
Input: fp (file stream) pixac text (<optional> identifying string; can be null) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixaConvertToPdf | ( | PIXA * | pixa, |
l_int32 | res, | ||
l_float32 | scalefactor, | ||
l_int32 | type, | ||
l_int32 | quality, | ||
const char * | title, | ||
const char * | fileout | ||
) |
Input: pixa (containing images all at the same resolution) res (override the resolution of each input image, in ppi; use 0 to respect the resolution embedded in the input) scalefactor (scaling factor applied to each image; > 0.0) type (encoding type (L_JPEG_ENCODE, L_G4_ENCODE, L_FLATE_ENCODE, or 0 for default) quality (used for JPEG only; 0 for default (75)) title (<optional> pdf title; if null, taken from the first image filename) fileout (pdf file of all images) Return: 0 if OK, 1 on error
Notes: (1) The images are encoded with G4 if 1 bpp; JPEG if 8 bpp without colormap and many colors, or 32 bpp; FLATE for anything else. (2) The scalefactor must be > 0.0; otherwise it is set to 1.0. (3) Specifying one of the three encoding types for forces all images to be compressed with that type. Use 0 to have the type determined for each image based on depth and whether or not it has a colormap.
LEPT_DLL l_int32 pixaConvertToPdfData | ( | PIXA * | pixa, |
l_int32 | res, | ||
l_float32 | scalefactor, | ||
l_int32 | type, | ||
l_int32 | quality, | ||
const char * | title, | ||
l_uint8 ** | pdata, | ||
size_t * | pnbytes | ||
) |
Input: pixa (containing images all at the same resolution) res (input resolution of all images) scalefactor (scaling factor applied to each image; > 0.0) type (encoding type (L_JPEG_ENCODE, L_G4_ENCODE, L_FLATE_ENCODE, or 0 for default) quality (used for JPEG only; 0 for default (75)) title (<optional> pdf title; if null, taken from the first image filename) &data (<return> output pdf data (of all images) &nbytes (<return> size of output pdf data) Return: 0 if OK, 1 on error
Notes: (1) See pixaConvertToPdf().
Input: pixas copyflag: L_COPY makes a new pixa and copies each pix and each box L_CLONE gives a new ref-counted handle to the input pixa L_COPY_CLONE makes a new pixa and inserts clones of all pix and boxes Return: new pixa, or null on error
Note: see pix.h for description of the copy types.
LEPT_DLL NUMA* pixaCountPixels | ( | PIXA * | pixa | ) |
Input: pixa (array of 1 bpp pix) Return: na of ON pixels in each pix, or null on error
LEPT_DLL PIXA* pixaCreate | ( | l_int32 | n | ) |
Input: n (initial number of ptrs) Return: pixa, or null on error
Input: pixs boxa &cropwarn (<optional return>=""> TRUE if the boxa extent is larger than pixs. Return: pixad, or null on error
Notes: (1) This simply extracts from pixs the region corresponding to each box in the boxa. (2) The 3rd arg is optional. If the extent of the boxa exceeds the size of the pixa, so that some boxes are either clipped or entirely outside the pix, a warning is returned as TRUE. (3) pixad will have only the properly clipped elements, and the internal boxa will be correct.
Input: pixs (with individual components on a lattice) n (number of components) cellw (width of each cell) cellh (height of each cell) Return: pixa, or null on error
Note: for bpp = 1, we truncate each retrieved pix to the ON pixels, which we assume for now start at (0,0)
LEPT_DLL PIXA* pixaCreateFromPixacomp | ( | PIXAC * | pixac, |
l_int32 | accesstype | ||
) |
Input: pixac accesstype (L_COPY, L_CLONE, L_COPY_CLONE; for boxa) Return: pixa if OK, or null on error
LEPT_DLL PIX* pixAddBlackBorder | ( | PIX * | pixs, |
l_int32 | npix | ||
) |
Input: pixs (all depths; colormap ok) npix (number of pixels to be added to each side) Return: pixd (with the added exterior pixels), or null on error
Input: pixs (all depths; colormap ok) npix (number of pixels to be added to each side) val (value of added border pixels) Return: pixd (with the added exterior pixels), or null on error
Notes: (1) See pixAddBorderGeneral() for values of white & black pixels.
LEPT_DLL PIX* pixAddBorderGeneral | ( | PIX * | pixs, |
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot, | ||
l_uint32 | val | ||
) |
Input: pixs (all depths; colormap ok) left, right, top, bot (number of pixels added) val (value of added border pixels) Return: pixd (with the added exterior pixels), or null on error
Notes: (1) For binary images: white: val = 0 black: val = 1 For grayscale images: white: val = 2 ** d - 1 black: val = 0 For rgb color images: white: val = 0xffffff00 black: val = 0 For colormapped images, use 'index' found this way: white: pixcmapGetRankIntensity(cmap, 1.0, &index); black: pixcmapGetRankIntensity(cmap, 0.0, &index);
LEPT_DLL l_int32 pixAddConstantGray | ( | PIX * | pixs, |
l_int32 | val | ||
) |
Input: pixs (8, 16 or 32 bpp) val (amount to add to each pixel) Return: 0 if OK, 1 on error
Notes: (1) In-place operation. (2) No clipping for 32 bpp. (3) For 8 and 16 bpp, if val > 0 the result is clipped to 0xff and 0xffff, rsp. (4) For 8 and 16 bpp, if val < 0 the result is clipped to 0.
Input: pixd (<optional>; this can be null, equal to pixs1, or different from pixs1) pixs1 (can be == to pixd) pixs2 Return: pixd always
Notes: (1) Arithmetic addition of two 8, 16 or 32 bpp images. (2) For 8 and 16 bpp, we do explicit clipping to 0xff and 0xffff, respectively. (3) Alignment is to UL corner. (4) There are 3 cases. The result can go to a new dest, in-place to pixs1, or to an existing input dest: * pixd == null: (src1 + src2) --> new pixd * pixd == pixs1: (src1 + src2) --> src1 (in-place) * pixd != pixs1: (src1 + src2) --> input pixd (5) pixs2 must be different from both pixd and pixs1.
LEPT_DLL l_int32 pixAddGrayColormap8 | ( | PIX * | pixs | ) |
Input: pixs (8 bpp) Return: 0 if OK, 1 on error
Notes: (1) If pixs has a colormap, this is a no-op.
LEPT_DLL PIX* pixAddMinimalGrayColormap8 | ( | PIX * | pixs | ) |
Input: pixs (8 bpp) Return: 0 if OK, 1 on error
Notes: (1) This generates a colormapped version of the input image that has the same number of colormap entries as the input image has unique gray levels.
LEPT_DLL PIX* pixAddMirroredBorder | ( | PIX * | pixs, |
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot | ||
) |
Input: pixs (all depths; colormap ok) left, right, top, bot (number of pixels added) Return: pixd, or null on error
Notes: (1) This applies what is effectively mirror boundary conditions. For the added border pixels in pixd, the pixels in pixs near the border are mirror-copied into the border region. (2) This is useful for avoiding special operations near boundaries when doing image processing operations such as rank filters and convolution. In use, one first adds mirrored pixels to each side of the image. The number of pixels added on each side is half the filter dimension. Then the image processing operations proceed over a region equal to the size of the original image, and write directly into a dest pix of the same size as pixs. (3) The general pixRasterop() is used for an in-place operation here because there is no overlap between the src and dest rectangles.
LEPT_DLL PIX* pixAddMixedBorder | ( | PIX * | pixs, |
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot | ||
) |
Input: pixs (all depths; colormap ok) left, right, top, bot (number of pixels added) Return: pixd, or null on error
Notes: (1) This applies mirrored boundary conditions horizontally and repeated b.c. vertically. (2) It is specifically used for avoiding special operations near boundaries when convolving a hue-saturation histogram with a given window size. The repeated b.c. are used vertically for hue, and the mirrored b.c. are used horizontally for saturation. The number of pixels added on each side is approximately (but not quite) half the filter dimension. The image processing operations can then proceed over a region equal to the size of the original image, and write directly into a dest pix of the same size as pixs. (3) The general pixRasterop() can be used for an in-place operation here because there is no overlap between the src and dest rectangles.
LEPT_DLL PIX* pixAddRepeatedBorder | ( | PIX * | pixs, |
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot | ||
) |
Input: pixs (all depths; colormap ok) left, right, top, bot (number of pixels added) Return: pixd, or null on error
Notes: (1) This applies a repeated border, as if the central part of the image is tiled over the plane. So, for example, the pixels in the left border come from the right side of the image. (2) The general pixRasterop() is used for an in-place operation here because there is no overlap between the src and dest rectangles.
LEPT_DLL PIX* pixAddSingleTextblock | ( | PIX * | pixs, |
L_BMF * | bmf, | ||
const char * | textstr, | ||
l_uint32 | val, | ||
l_int32 | location, | ||
l_int32 * | poverflow | ||
) |
Input: pixs (input pix; colormap ok) bmf (bitmap font data) textstr (<optional> text string to be added) val (color to set the text) location (L_ADD_ABOVE, L_ADD_AT_TOP, L_ADD_AT_BOTTOM, L_ADD_BELOW) &overflow (<optional return>=""> 1 if text overflows allocated region and is clipped; 0 otherwise) Return: pixd (new pix with rendered text), or null on error
Notes: (1) This function paints a set of lines of text over an image. If is L_ADD_ABOVE or L_ADD_BELOW, the pix size is expanded with a border and rendered over the border. (2) is the pixel value to be painted through the font mask. It should be chosen to agree with the depth of pixs. If it is out of bounds, an intermediate value is chosen. For RGB, use hex notation: 0xRRGGBB00, where RR is the hex representation of the red intensity, etc. (3) If textstr == NULL, use the text field in the pix. (4) If there is a colormap, this does the best it can to use the requested color, or something similar to it. (5) Typical usage is for labelling a pix with some text data.
LEPT_DLL l_int32 pixAddText | ( | PIX * | pix, |
const char * | textstring | ||
) |
Input: pix textstring Return: 0 if OK, 1 on error
Notes: (1) This adds the new textstring to any existing text. (2) Either or both the existing text and the new text string can be null.
Input: pixs (1 bpp pix from which components are added; in-place) pixa (of connected components, some of which will be put into pixs) na (numa indicator: add components corresponding to 1s) Return: 0 if OK, 1 on error
Notes: (1) This complements pixRemoveWithIndicator(). Here, the selected components are added to pixs.
LEPT_DLL void pixaDestroy | ( | PIXA ** | ppixa | ) |
Input: &pixa (<can be="" nulled>="">) Return: void
Notes: (1) Decrements the ref count and, if 0, destroys the pixa. (2) Always nulls the input ptr.
Input: pixa w, h (if set to 0, determines the size from the b.b. of the components in pixa) Return: pix, or null on error
Notes: (1) This uses the boxes to place each pix in the rendered composite. (2) Set w = h = 0 to use the b.b. of the components to determine the size of the returned pix. (3) Uses the first pix in pixa to determine the depth. (4) The background is written "white". On 1 bpp, each successive pix is "painted" (adding foreground), whereas for grayscale or color each successive pix is blitted with just the src. (5) If the pixa is empty, returns an empty 1 bpp pix.
Input: pixa w, h (if set to 0, determines the size from the b.b. of the components in pixa) color (background color to use) Return: pix, or null on error
Notes: (1) This uses the boxes to place each pix in the rendered composite. (2) Set w = h = 0 to use the b.b. of the components to determine the size of the returned pix. (3) If any pix in are colormapped, or if the pix have different depths, it returns a 32 bpp pix. Otherwise, the depth of the returned pixa equals that of the pix in . (4) If the pixa is empty, return null.
Input: pixa xspace yspace Return: pix of composite images, or null on error
Notes: (1) This places each pix on sequentially on a regular lattice in the rendered composite. If a pix is too large to fit in the allocated lattice space, it is not rendered. (2) If any pix has a colormap, all pix are rendered in rgb. (3) This is useful when putting bitmaps of components, such as characters, into a single image.
Input: pixa (of 1 bpp components, with boxa) w, h (if set to 0, determines the size from the b.b. of the components in pixa) Return: pix (8 bpp, cmapped, with random colors on the components), or null on error
Notes: (1) This uses the boxes to place each pix in the rendered composite. (2) By default, the background color is: black, cmap index 0. This can be changed by pixcmapResetColor()
LEPT_DLL PIX* pixaDisplayTiled | ( | PIXA * | pixa, |
l_int32 | maxwidth, | ||
l_int32 | background, | ||
l_int32 | spacing | ||
) |
Input: pixa maxwidth (of output image) background (0 for white, 1 for black) spacing Return: pix of tiled images, or null on error
Notes: (1) This saves a pixa to a single image file of width not to exceed maxwidth, with background color either white or black, and with each subimage spaced on a regular lattice. (2) The lattice size is determined from the largest width and height, separately, of all pix in the pixa. (3) All pix in the pixa must be of equal depth. (4) If any pix has a colormap, all pix are rendered in rgb. (5) Careful: because no components are omitted, this is dangerous if there are thousands of small components and one or more very large one, because the size of the resulting pix can be huge!
LEPT_DLL PIX* pixaDisplayTiledAndScaled | ( | PIXA * | pixa, |
l_int32 | outdepth, | ||
l_int32 | tilewidth, | ||
l_int32 | ncols, | ||
l_int32 | background, | ||
l_int32 | spacing, | ||
l_int32 | border | ||
) |
Input: pixa outdepth (output depth: 1, 8 or 32 bpp) tilewidth (each pix is scaled to this width) ncols (number of tiles in each row) background (0 for white, 1 for black; this is the color of the spacing between the images) spacing (between images, and on outside) border (width of additional black border on each image; use 0 for no border) Return: pix of tiled images, or null on error
Notes: (1) This can be used to tile a number of renderings of an image that are at different scales and depths. (2) Each image, after scaling and optionally adding the black border, has width 'tilewidth'. Thus, the border does not affect the spacing between the image tiles. The maximum allowed border width is tilewidth / 5.
LEPT_DLL PIX* pixaDisplayTiledInRows | ( | PIXA * | pixa, |
l_int32 | outdepth, | ||
l_int32 | maxwidth, | ||
l_float32 | scalefactor, | ||
l_int32 | background, | ||
l_int32 | spacing, | ||
l_int32 | border | ||
) |
Input: pixa outdepth (output depth: 1, 8 or 32 bpp) maxwidth (of output image) scalefactor (applied to every pix; use 1.0 for no scaling) background (0 for white, 1 for black; this is the color of the spacing between the images) spacing (between images, and on outside) border (width of black border added to each image; use 0 for no border) Return: pixd (of tiled images), or null on error
Notes: (1) This saves a pixa to a single image file of width not to exceed maxwidth, with background color either white or black, and with each row tiled such that the top of each pix is aligned and separated by 'spacing' from the next one. A black border can be added to each pix. (2) All pix are converted to outdepth; existing colormaps are removed. (3) This does a reasonably spacewise-efficient job of laying out the individual pix images into a tiled composite.
LEPT_DLL PIX* pixaDisplayUnsplit | ( | PIXA * | pixa, |
l_int32 | nx, | ||
l_int32 | ny, | ||
l_int32 | borderwidth, | ||
l_uint32 | bordercolor | ||
) |
Input: pixa nx (number of mosaic cells horizontally) ny (number of mosaic cells vertically) borderwidth (of added border on all sides) bordercolor (in our RGBA format: 0xrrggbbaa) Return: pix of tiled images, or null on error
Notes: (1) This is a logical inverse of pixaSplitPix(). It constructs a pix from a mosaic of tiles, all of equal size. (2) For added generality, a border of arbitrary color can be added to each of the tiles. (3) In use, pixa will typically have either been generated from pixaSplitPix() or will derived from a pixa that was so generated. (4) All pix in the pixa must be of equal depth, and, if colormapped, have the same colormap.
LEPT_DLL l_int32 pixaEqual | ( | PIXA * | pixa1, |
PIXA * | pixa2, | ||
l_int32 | maxdist, | ||
NUMA ** | pnaindex, | ||
l_int32 * | psame | ||
) |
Input: pixa1 pixa2 maxdist &naindex (<optional return>=""> index array of correspondences &same (<return> 1 if equal; 0 otherwise) Return 0 if OK, 1 on error
Notes: (1) The two pixa are the "same" if they contain the same boxa and the same ordered set of pix. However, if they have boxa, the pix in each pixa can differ in ordering by an amount given by the parameter . If they don't have a boxa, the parameter is ignored, and the ordering must be identical. (2) This applies only to boxa geometry, pixels and ordering; other fields in the pix are ignored. (3) naindex[i] gives the position of the box in pixa2 that corresponds to box i in pixa1. It is only returned if the pixa have boxa and the boxa are equal. (4) In situations where the ordering is very different, so that a large is required for "equality", this should be implemented with a hash function for efficiency.
LEPT_DLL l_int32 pixaExtendArray | ( | PIXA * | pixa | ) |
Input: pixa Return: 0 if OK; 1 on error
Notes: (1) Doubles the size of the pixa and boxa ptr arrays.
LEPT_DLL l_int32 pixaExtendArrayToSize | ( | PIXA * | pixa, |
l_int32 | size | ||
) |
Input: pixa Return: 0 if OK; 1 on error
Notes: (1) If necessary, reallocs new pixa and boxa ptrs arrays to . The pixa and boxa ptr arrays must always be equal in size.
pixaExtractColumnFromEachPix()
Input: pixa (of identically sized, 8 bpp; not cmapped) col (column index) pixd (pix into which each column is inserted) Return: 0 if OK, 1 on error
Input: pixs (all depths; colormap ok) vc (vector of 6 coefficients for affine transformation) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Brings in either black or white pixels from the boundary (2) Removes any existing colormap, if necessary, before transforming
Input: pixs (32 bpp) vc (vector of 6 coefficients for affine transformation) colorval (e.g., 0 to bring in BLACK, 0xffffff00 for WHITE) Return: pixd, or null on error
Input: pixs (8 bpp) vc (vector of 6 coefficients for affine transformation) grayval (0 to bring in BLACK, 255 for WHITE) Return: pixd, or null on error
Input: pixs (all depths; colormap ok) ptad (3 pts of final coordinate space) ptas (3 pts of initial coordinate space) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Brings in either black or white pixels from the boundary (2) Removes any existing colormap, if necessary, before transforming
Input: pixs (32 bpp) ptad (3 pts of final coordinate space) ptas (3 pts of initial coordinate space) colorval (e.g., 0 to bring in BLACK, 0xffffff00 for WHITE) Return: pixd, or null on error
LEPT_DLL PIX* pixAffinePtaGammaXform | ( | PIX * | pixs, |
l_float32 | gamma, | ||
PTA * | ptad, | ||
PTA * | ptas, | ||
l_float32 | fract, | ||
l_int32 | border | ||
) |
Input: pixs (32 bpp rgb) gamma (gamma correction; must be > 0.0) ptad (3 pts of final coordinate space) ptas (3 pts of initial coordinate space) fract (between 0.0 and 1.0, with 1.0 fully transparent) border (of pixels to capture transformed source pixels) Return: pixd, or null on error
Notes: (1) This wraps a gamma/inverse-gamma photometric transform around pixAffinePtaWithAlpha(). (2) For usage, see notes in pixAffinePtaWithAlpha() and pixGammaTRCWithAlpha(). (3) The basic idea of a gamma/inverse-gamma transform is to remove any gamma correction before the affine transform, and restore it afterward. The effects can be subtle, but important for some applications. For example, using gamma > 1.0 will cause the dark areas to become somewhat lighter and slightly reduce aliasing effects when blending using the alpha channel.
Input: pixs (8 bpp) ptad (3 pts of final coordinate space) ptas (3 pts of initial coordinate space) grayval (0 to bring in BLACK, 255 for WHITE) Return: pixd, or null on error
LEPT_DLL PIX* pixAffinePtaWithAlpha | ( | PIX * | pixs, |
PTA * | ptad, | ||
PTA * | ptas, | ||
PIX * | pixg, | ||
l_float32 | fract, | ||
l_int32 | border | ||
) |
Input: pixs (32 bpp rgb) ptad (3 pts of final coordinate space) ptas (3 pts of initial coordinate space) pixg (<optional> 8 bpp, can be null) fract (between 0.0 and 1.0, with 0.0 fully transparent and 1.0 fully opaque) border (of pixels added to capture transformed source pixels) Return: pixd, or null on error
Notes: (1) The alpha channel is transformed separately from pixs, and aligns with it, being fully transparent outside the boundary of the transformed pixs. For pixels that are fully transparent, a blending function like pixBlendWithGrayMask() will give zero weight to corresponding pixels in pixs. (2) If pixg is NULL, it is generated as an alpha layer that is partially opaque, using . Otherwise, it is cropped to pixs if required and is ignored. The alpha channel in pixs is never used. (3) Colormaps are removed. (4) When pixs is transformed, it doesn't matter what color is brought in because the alpha channel will be transparent (0) there. (5) To avoid losing source pixels in the destination, it may be necessary to add a border to the source pix before doing the affine transformation. This can be any non-negative number. (6) The input and are in a coordinate space before the border is added. Internally, we compensate for this before doing the affine transform on the image after the border is added. (7) The default setting for the border values in the alpha channel is 0 (transparent) for the outermost ring of pixels and (0.5 * fract * 255) for the second ring. When blended over a second image, this (a) shrinks the visible image to make a clean overlap edge with an image below, and (b) softens the edges by weakening the aliasing there. Use l_setAlphaMaskBorder() to change these values.
Input: pixs (all depths) vc (vector of 6 coefficients for affine transformation) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Brings in either black or white pixels from the boundary. (2) Retains colormap, which you can do for a sampled transform.. (3) For 8 or 32 bpp, much better quality is obtained by the somewhat slower pixAffine(). See that function for relative timings between sampled and interpolated.
Input: pixs (all depths) ptad (3 pts of final coordinate space) ptas (3 pts of initial coordinate space) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Brings in either black or white pixels from the boundary. (2) Retains colormap, which you can do for a sampled transform.. (3) The 3 points must not be collinear. (4) The order of the 3 points is arbitrary; however, to compare with the sequential transform they must be in these locations and in this order: origin, x-axis, y-axis. (5) For 1 bpp images, this has much better quality results than pixAffineSequential(), particularly for text. It is about 3x slower, but does not require additional border pixels. The poor quality of pixAffineSequential() is due to repeated quantized transforms. It is strongly recommended that pixAffineSampled() be used for 1 bpp images. (6) For 8 or 32 bpp, much better quality is obtained by the somewhat slower pixAffinePta(). See that function for relative timings between sampled and interpolated. (7) To repeat, use of the sequential transform, pixAffineSequential(), for any images, is discouraged.
Input: pixs ptad (3 pts of final coordinate space) ptas (3 pts of initial coordinate space) bw (pixels of additional border width during computation) bh (pixels of additional border height during computation) Return: pixd, or null on error
Notes: (1) The 3 pts must not be collinear. (2) The 3 pts must be given in this order:
LEPT_DLL NUMA* pixaFindAreaFraction | ( | PIXA * | pixa | ) |
Input: pixa (of 1 bpp pix) Return: na (of area fractions for each pix), or null on error
Notes: (1) This is typically used for a pixa consisting of 1 bpp connected components.
LEPT_DLL NUMA* pixaFindAreaPerimRatio | ( | PIXA * | pixa | ) |
Input: pixa (of 1 bpp pix) Return: na (of area/perimeter ratio for each pix), or null on error
Notes: (1) This is typically used for a pixa consisting of 1 bpp connected components.
Input: pixa &naw (<optional return>=""> numa of pix widths) &nah (<optional return>=""> numa of pix heights) Return: 0 if OK, 1 on error
LEPT_DLL NUMA* pixaFindPerimSizeRatio | ( | PIXA * | pixa | ) |
Input: pixa (of 1 bpp pix) Return: na (of fg perimeter/(w*h) ratio for each pix), or null on error
Notes: (1) This is typically used for a pixa consisting of 1 bpp connected components.
LEPT_DLL NUMA* pixaFindWidthHeightProduct | ( | PIXA * | pixa | ) |
Input: pixa (of 1 bpp pix) Return: na (of width*height products for each pix), or null on error
Notes: (1) This is typically used for a pixa consisting of 1 bpp connected components.
LEPT_DLL NUMA* pixaFindWidthHeightRatio | ( | PIXA * | pixa | ) |
Input: pixa (of 1 bpp pix) Return: na (of width/height ratios for each pix), or null on error
Notes: (1) This is typically used for a pixa consisting of 1 bpp connected components.
LEPT_DLL PIXA* pixaGenerateFont | ( | const char * | dir, |
l_int32 | size, | ||
l_int32 * | pbl0, | ||
l_int32 * | pbl1, | ||
l_int32 * | pbl2 | ||
) |
Input: dir (directory holding image of character set) size (4, 6, 8, ... , 20, in pts at 300 ppi) &bl1 (<return> baseline of row 1) &bl2 (<return> baseline of row 2) &bl3 (<return> baseline of row 3) Return: pixa of font bitmaps for 95 characters, or null on error
These font generation functions use 9 sets, each with bitmaps of 94 ascii characters, all in Palatino-Roman font. Each input bitmap has 3 rows of characters. The range of ascii values in each row is as follows: row 0: 32-57 (32 is a space) row 1: 58-91 (92, '\', is not represented in this font) row 2: 93-126 We LR flip the '/' char to generate a bitmap for the missing '\' character, so that we have representations of all 95 printable chars.
Computation of the bitmaps and baselines for a single font takes from 40 to 200 msec on a 2 GHz processor, depending on the size. Use pixaGetFont() to read the generated character set directly from files that were produced in prog/genfonts.c using this function.
Input: pixa (of identically sized, 8 bpp pix; not cmapped) type (L_MEAN_ABSVAL, L_MEDIAN_VAL, L_MODE_VAL, L_MODE_COUNT) nbins (of histogram for median and mode; ignored for mean) thresh (on histogram for mode val; ignored for all other types) Return: pix (with pixelwise aligned stats), or null on error.
Notes: (1) Each pixel in the returned pix represents an average (or median, or mode) over the corresponding pixels in each pix in the pixa. (2) The parameter works with L_MODE_VAL only, and sets a minimum occupancy of the mode bin. If the occupancy of the mode bin is less than , the mode value is returned as 0. To always return the actual mode value, set = 0. See pixGetRowStats().
Input: pixa index (to the index-th pix) accesstype (L_COPY or L_CLONE) Return: box (if null, not automatically an error), or null on error
Notes: (1) There is always a boxa with a pixa, and it is initialized so that each box ptr is NULL. (2) In general, we expect that there is either a box associated with each pix, or no boxes at all in the boxa. (3) Having no boxes is thus not an automatic error. Whether it is an actual error is determined by the calling program. If the caller expects to get a box, it is an error; see, e.g., pixaGetBoxGeometry().
LEPT_DLL BOXA* pixaGetBoxa | ( | PIXA * | pixa, |
l_int32 | accesstype | ||
) |
Input: pixa accesstype (L_COPY, L_CLONE, L_COPY_CLONE) Return: boxa, or null on error
LEPT_DLL l_int32 pixaGetBoxaCount | ( | PIXA * | pixa | ) |
Input: pixa Return: count, or 0 on error
LEPT_DLL l_int32 pixaGetBoxGeometry | ( | PIXA * | pixa, |
l_int32 | index, | ||
l_int32 * | px, | ||
l_int32 * | py, | ||
l_int32 * | pw, | ||
l_int32 * | ph | ||
) |
Input: pixa index (to the index-th box) &x, &y, &w, &h (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixaGetCount | ( | PIXA * | pixa | ) |
Input: pixa Return: count, or 0 if no pixa
Input: pixa &maxdepth (<optional return>=""> max pixel depth of pix in pixa) &same (<optional return>=""> true if all depths are equal) Return: 0 if OK; 1 on error
LEPT_DLL PIXA* pixaGetFont | ( | const char * | dir, |
l_int32 | size, | ||
l_int32 * | pbl0, | ||
l_int32 * | pbl1, | ||
l_int32 * | pbl2 | ||
) |
Input: dir (directory holding pixa of character set) size (4, 6, 8, ... , 20) &bl1 (<return> baseline of row 1) &bl2 (<return> baseline of row 2) &bl3 (<return> baseline of row 3) Return: pixa of font bitmaps for 95 characters, or null on error
Notes: (1) This reads a pre-computed pixa file with the 95 ascii chars.
Input: pixa index (to the index-th pix) accesstype (L_COPY or L_CLONE) Return: pix, or null on error
LEPT_DLL PIX** pixaGetPixArray | ( | PIXA * | pixa | ) |
Input: pixa Return: pix array, or null on error
Notes: (1) This returns a ptr to the actual array. The array is owned by the pixa, so it must not be destroyed. (2) The caller should always check if the return value is NULL before accessing any of the pix ptrs in this array!
LEPT_DLL l_int32 pixaGetPixDimensions | ( | PIXA * | pixa, |
l_int32 | index, | ||
l_int32 * | pw, | ||
l_int32 * | ph, | ||
l_int32 * | pd | ||
) |
Input: pixa index (to the index-th box) &w, &h, &d (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
Input: pixa (typically empty) pix (to be replicated into the entire pixa ptr array) box (<optional> to be replicated into the entire boxa ptr array) Return: 0 if OK, 1 on error
Notes: (1) This initializes a pixa by filling up the entire pix ptr array with copies of . Any existing pix are destroyed. It also fills the boxa with copies of . After this oepration, the numbers of pix and boxes are equal to the number of allocated ptrs. (2) Note that we use pixaReplacePix() instead of pixaInsertPix(). They both have the same effect when inserting into a NULL ptr in the pixa ptr array: (3) Example usage. This function is useful to prepare for a random insertion (or replacement) of pix into a pixa. To randomly insert pix into a pixa, up to some index "max": Pixa *pixa = pixaCreate(max); Pix *pix = pixCreate(1, 1, 1); // little memory Box *box = boxCreate(...); pixaInitFull(pixa, pix, box); An existing pixa with a smaller ptr array can also be reused: pixaExtendArrayToSize(pixa, max); Pix *pix = pixCreate(...); Box *box = boxCreate(...); pixaInitFull(pixa, pix, box); For these situations, the pix should be small and disposable. The initialization allows the pixa to always be properly filled, even if all pix (and boxes) are not later replaced.
Input: pixa index (at which pix is to be inserted) pixs (new pix to be inserted) box (<optional> new box to be inserted) Return: 0 if OK, 1 on error
Notes: (1) This shifts pixa[i] --> pixa[i + 1] for all i >= index, and then inserts at pixa[index]. (2) To insert at the beginning of the array, set index = 0. (3) It should not be used repeatedly on large arrays, because the function is O(n). (4) To append a pix to a pixa, it's easier to use pixaAddPix().
Input: pixad (dest pixa; add to this one) pixas (source pixa; add from this one) istart (starting index in nas) iend (ending index in nas; use 0 to cat all) Return: 0 if OK, 1 on error
Notes: (1) This appends a clone of each indicated pix in pixas to pixad (2) istart < 0 is taken to mean 'read from the start' (istart = 0) (3) iend <= 0 means 'read to the end'
LEPT_DLL PIX* pixAlphaBlendUniform | ( | PIX * | pixs, |
l_uint32 | color | ||
) |
Input: pixs (32 bpp rgba, with alpha) color (32 bit color in 0xrrggbb00 format) Return: pixd (pixs blended over uniform color ), or null on error
Notes: (1) This is a convenience function that renders 32 bpp RGBA images (with an alpha channel) over a uniform background of value . To render over a white background, use = 0xffffff00. (2) If pixs does not have an alpha channel, the values of the 4th byte would typically be 0, which represents full transparency. Applying this function to such an image results in an image with only the uniformly colored background.
LEPT_DLL PIXA* pixaMorphSequenceByComponent | ( | PIXA * | pixas, |
const char * | sequence, | ||
l_int32 | minw, | ||
l_int32 | minh | ||
) |
pixaMorphSequenceByComponent()
Input: pixas (of 1 bpp pix) sequence (string specifying sequence) minw (minimum width to consider; use 0 or 1 for any width) minh (minimum height to consider; use 0 or 1 for any height) Return: pixad, or null on error
Notes: (1) See pixMorphSequence() for composing operation sequences. (2) This operates separately on each c.c. in the input pixa. (3) You can specify that the width and/or height must equal or exceed a minimum size for the operation to take place. (4) The input pixa should have a boxa giving the locations of the pix components.
LEPT_DLL PIXA* pixaMorphSequenceByRegion | ( | PIX * | pixs, |
PIXA * | pixam, | ||
const char * | sequence, | ||
l_int32 | minw, | ||
l_int32 | minh | ||
) |
Input: pixs (1 bpp) pixam (of 1 bpp mask elements) sequence (string specifying sequence) minw (minimum width to consider; use 0 or 1 for any width) minh (minimum height to consider; use 0 or 1 for any height) Return: pixad, or null on error
Notes: (1) See pixMorphSequence() for composing operation sequences. (2) This operates separately on each region in the input pixs defined by the components in pixam. (3) You can specify that the width and/or height of a mask component must equal or exceed a minimum size for the operation to take place. (4) The input pixam should have a boxa giving the locations of the regions in pixs.
Input: pixd (<optional>; this can be null, equal to pixs1, different from pixs1) pixs1 (can be == pixd) pixs2 (must be != pixd) Return: pixd always
Notes: (1) This gives the intersection of two images with equal depth, aligning them to the the UL corner. pixs1 and pixs2 need not have the same width and height. (2) There are 3 cases: (a) pixd == null, (src1 & src2) --> new pixd (b) pixd == pixs1, (src1 & src2) --> src1 (in-place) (c) pixd != pixs1, (src1 & src2) --> input pixd (3) For clarity, if the case is known, use these patterns: (a) pixd = pixAnd(NULL, pixs1, pixs2); (b) pixAnd(pixs1, pixs1, pixs2); (c) pixAnd(pixd, pixs1, pixs2); (4) The size of the result is determined by pixs1. (5) The depths of pixs1 and pixs2 must be equal. (6) Note carefully that the order of pixs1 and pixs2 only matters for the in-place case. For in-place, you must have pixd == pixs1. Setting pixd == pixs2 gives an incorrect result: the copy puts pixs1 image data in pixs2, and the rasterop is then between pixs2 and pixs2 (a no-op).
pixApplyInvBackgroundGrayMap()
Input: pixs (8 bpp grayscale; no colormap) pixm (16 bpp, inverse background map) sx (tile width in pixels) sy (tile height in pixels) Return: pixd (8 bpp), or null on error
LEPT_DLL PIX* pixApplyInvBackgroundRGBMap | ( | PIX * | pixs, |
PIX * | pixmr, | ||
PIX * | pixmg, | ||
PIX * | pixmb, | ||
l_int32 | sx, | ||
l_int32 | sy | ||
) |
Input: pixs (32 bpp rbg) pixmr (16 bpp, red inverse background map) pixmg (16 bpp, green inverse background map) pixmb (16 bpp, blue inverse background map) sx (tile width in pixels) sy (tile height in pixels) Return: pixd (32 bpp rbg), or null on error
Input: pixs (8 bpp grayscale; not colormapped) pixth (8 bpp array of local thresholds) redfactor ( ... ) Return: pixd (1 bpp, thresholded image), or null on error
Input: pixs (8 bpp) pixg (8 bpp, variable map) target (typ. 128 for threshold) Return: pixd (8 bpp), or null on error
Notes: (1) Suppose you have an image that you want to transform based on some photometric measurement at each point, such as the threshold value for binarization. Representing the photometric measurement as an image pixg, you can threshold in input image using pixVarThresholdToBinary(). Alternatively, you can map the input image pointwise so that the threshold over the entire image becomes a constant, such as 128. For example, if a pixel in pixg is 150 and the target is 128, the corresponding pixel in pixs is mapped linearly to a value (128/150) of the input value. If the resulting mapped image pixd were then thresholded at 128, you would obtain the same result as a direct binarization using pixg with pixVarThresholdToBinary(). (2) The sizes of pixs and pixg must be equal.
Input: filename Return: pixa, or null on error
Notes: (1) The pix are stored in the file as png. If the png library is not linked, this will fail.
LEPT_DLL PIXA* pixaReadFiles | ( | const char * | dirname, |
const char * | substr | ||
) |
Input: dirname substr (<optional> substring filter on filenames; can be null) Return: pixa, or null on error
Notes: (1) is the full path for the directory. (2) is the part of the file name (excluding the directory) that is to be matched. All matching filenames are read into the Pixa. If substr is NULL, all filenames are read into the Pixa.
LEPT_DLL PIXA* pixaReadFilesSA | ( | SARRAY * | sa | ) |
Input: sarray (full pathnames for all files) Return: pixa, or null on error
LEPT_DLL PIXA* pixaReadMultipageTiff | ( | const char * | filename | ) |
LEPT_DLL PIXA* pixaReadStream | ( | FILE * | fp | ) |
Input: stream Return: pixa, or null on error
Notes: (1) The pix are stored in the file as png. If the png library is not linked, this will fail.
LEPT_DLL l_int32 pixaRemovePix | ( | PIXA * | pixa, |
l_int32 | index | ||
) |
Input: pixa index (of pix to be removed) Return: 0 if OK, 1 on error
Notes: (1) This shifts pixa[i] --> pixa[i - 1] for all i > index. (2) It should not be used repeatedly on large arrays, because the function is O(n). (3) The corresponding box is removed as well, if it exists.
Input: pixs (1 bpp pix; can be null) pixa (of connected components, one of which will be put into pixs) index (of component to be rendered) Return: pixd, or null on error
Notes: (1) If pixs is null, this generates an empty pix. (2) The selected component is blitted into pixs.
Input: pixa index (to the index-th pix) pix (insert to replace existing one) box (<optional> insert to replace existing) Return: 0 if OK, 1 on error
Notes: (1) In-place replacement of one pix. (2) The previous pix at that location is destroyed.
LEPT_DLL l_int32 pixaSaveFont | ( | const char * | indir, |
const char * | outdir, | ||
l_int32 | size | ||
) |
Input: indir (directory holding image of character set) outdir (directory into which the output pixa file will be written) size (in pts, at 300 ppi) Return: 0 if OK, 1 on error
Notes: (1) This saves a font of a particular size. (2) prog/genfonts calls this function for each of the nine font sizes, to generate all the font pixa files.
LEPT_DLL PIXA* pixaSelectByAreaFraction | ( | PIXA * | pixas, |
l_float32 | thresh, | ||
l_int32 | type, | ||
l_int32 * | pchanged | ||
) |
Input: pixas thresh (threshold ratio of fg pixels to (w * h)) type (L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE) &changed (<optional return>=""> 1 if changed; 0 if clone returned) Return: pixad, or null on error
Notes: (1) Returns a pixa clone if no components are removed. (2) Uses pix and box clones in the new pixa. (3) This filters components based on the fraction of fg pixels of the component in its bounding box. (4) Use L_SELECT_IF_LT or L_SELECT_IF_LTE to save components with less than the threshold fraction of foreground, and L_SELECT_IF_GT or L_SELECT_IF_GTE to remove them.
LEPT_DLL PIXA* pixaSelectByAreaPerimRatio | ( | PIXA * | pixas, |
l_float32 | thresh, | ||
l_int32 | type, | ||
l_int32 * | pchanged | ||
) |
Input: pixas thresh (threshold ratio of interior/boundary pixels) type (L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE) &changed (<optional return>=""> 1 if changed; 0 if clone returned) Return: pixad, or null on error
Notes: (1) Returns a pixa clone if no components are removed. (2) Uses pix and box clones in the new pixa. (3) We define a thin component here to be one with a ratio of interior to boundary pixels that is smaller than a given threshold value. (4) Use L_SELECT_IF_LT or L_SELECT_IF_LTE to save the thin components, and L_SELECT_IF_GT or L_SELECT_IF_GTE to remove them.
LEPT_DLL PIXA* pixaSelectBySize | ( | PIXA * | pixas, |
l_int32 | width, | ||
l_int32 | height, | ||
l_int32 | type, | ||
l_int32 | relation, | ||
l_int32 * | pchanged | ||
) |
Input: pixas width, height (threshold dimensions) type (L_SELECT_WIDTH, L_SELECT_HEIGHT, L_SELECT_IF_EITHER, L_SELECT_IF_BOTH) relation (L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE) &changed (<optional return>=""> 1 if changed; 0 otherwise) Return: pixad, or null on error
Notes: (1) The args specify constraints on the size of the components that are kept. (2) Uses pix and box clones in the new pixa. (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.
LEPT_DLL PIXA* pixaSelectByWidthHeightRatio | ( | PIXA * | pixas, |
l_float32 | thresh, | ||
l_int32 | type, | ||
l_int32 * | pchanged | ||
) |
pixaSelectByWidthHeightRatio()
Input: pixas thresh (threshold ratio of width/height) type (L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE) &changed (<optional return>=""> 1 if changed; 0 if clone returned) Return: pixad, or null on error
Notes: (1) Returns a pixa clone if no components are removed. (2) Uses pix and box clones in the new pixa. (3) This filters components based on the width-to-height ratio of each pix. (4) Use L_SELECT_IF_LT or L_SELECT_IF_LTE to save components with less than the threshold ratio, and L_SELECT_IF_GT or L_SELECT_IF_GTE to remove them.
Input: pixas na (indicator numa) &changed (<optional return>=""> 1 if changed; 0 if clone returned) Return: pixad, or null on error
Notes: (1) Returns a pixa clone if no components are removed. (2) Uses pix and box clones in the new pixa. (3) The indicator numa has values 0 (ignore) and 1 (accept).
LEPT_DLL l_int32 pixaSizeRange | ( | PIXA * | pixa, |
l_int32 * | pminw, | ||
l_int32 * | pminh, | ||
l_int32 * | pmaxw, | ||
l_int32 * | pmaxh | ||
) |
Input: pixa &minw, &minh, &maxw, &maxh (<optional return>=""> range of dimensions of pix in the array) Return: 0 if OK, 1 on error
LEPT_DLL PIXA* pixaSort | ( | PIXA * | pixas, |
l_int32 | sorttype, | ||
l_int32 | sortorder, | ||
NUMA ** | pnaindex, | ||
l_int32 | copyflag | ||
) |
Input: pixas sorttype (L_SORT_BY_X, L_SORT_BY_Y, L_SORT_BY_WIDTH, L_SORT_BY_HEIGHT, L_SORT_BY_MIN_DIMENSION, L_SORT_BY_MAX_DIMENSION, L_SORT_BY_PERIMETER, L_SORT_BY_AREA, L_SORT_BY_ASPECT_RATIO) sortorder (L_SORT_INCREASING, L_SORT_DECREASING) &naindex (<optional return>=""> index of sorted order into original array) copyflag (L_COPY, L_CLONE) Return: pixad (sorted version of pixas), or null on error
Notes: (1) This sorts based on the data in the boxa. If the boxa count is not the same as the pixa count, this returns an error. (2) The copyflag refers to the pix and box copies that are inserted into the sorted pixa. These are either L_COPY or L_CLONE.
Input: pixas naa (numaa that maps from the new pixaa to the input pixas) copyflag (L_CLONE or L_COPY) Return: pixaa (sorted), or null on error
Input: pixas naindex (na that maps from the new pixa to the input pixa) copyflag (L_COPY, L_CLONE) Return: pixad (sorted), or null on error
LEPT_DLL PIXA* pixaSplitPix | ( | PIX * | pixs, |
l_int32 | nx, | ||
l_int32 | ny, | ||
l_int32 | borderwidth, | ||
l_uint32 | bordercolor | ||
) |
Input: pixs (with individual components on a lattice) nx (number of mosaic cells horizontally) ny (number of mosaic cells vertically) borderwidth (of added border on all sides) bordercolor (in our RGBA format: 0xrrggbbaa) Return: pixa, or null on error
Notes: (1) This is a variant on pixaCreateFromPix(), where we simply divide the image up into (approximately) equal subunits. If you want the subimages to have essentially the same aspect ratio as the input pix, use nx = ny. (2) If borderwidth is 0, we ignore the input bordercolor and redefine it to white. (3) The bordercolor is always used to initialize each tiled pix, so that if the src is clipped, the unblitted part will be this color. This avoids 1 pixel wide black stripes at the left and lower edges.
LEPT_DLL l_int32 pixAssignToNearestColor | ( | PIX * | pixd, |
PIX * | pixs, | ||
PIX * | pixm, | ||
l_int32 | level, | ||
l_int32 * | countarray | ||
) |
Input: pixd (8 bpp, colormapped) pixs (32 bpp; 24-bit color) pixm (<optional> 1 bpp) level (of octcube used for finding nearest color in cmap) countarray (<optional> ptr to array, in which we can store the number of pixels found in each color in the colormap in pixd) Return: 0 if OK, 1 on error
Notes: (1) This is used in phase 2 of color segmentation, where pixs is the original input image to pixColorSegment(), and pixd is the colormapped image returned from pixColorSegmentCluster(). It is also used, with a mask, in phase 4. (2) This is an in-place operation. (3) The colormap in pixd is unchanged. (4) pixs and pixd must be the same size (w, h). (5) The selection mask pixm can be null. If it exists, it must be the same size as pixs and pixd, and only pixels corresponding to fg in pixm are assigned. Set to NULL if all pixels in pixd are to be assigned. (6) The countarray can be null. If it exists, it is pre-allocated and of a size at least equal to the size of the colormap in pixd. (7) This does a best-fit (non-greedy) assignment of pixels to existing clusters. Specifically, it assigns each pixel in pixd to the color index in the pixd colormap that has a color closest to the corresponding rgb pixel in pixs. (8) 'level' is the octcube level used to quickly find the nearest color in the colormap for each pixel. For color segmentation, this parameter is set to LEVEL_IN_OCTCUBE. (9) We build a mapping table from octcube to colormap index so that this function can run in a time (otherwise) independent of the number of colors in the colormap. This avoids a brute-force search for the closest colormap color to each pixel in the image.
LEPT_DLL NUMA* pixAverageIntensityProfile | ( | PIX * | pixs, |
l_float32 | fract, | ||
l_int32 | dir, | ||
l_int32 | first, | ||
l_int32 | last, | ||
l_int32 | factor1, | ||
l_int32 | factor2 | ||
) |
LEPT_DLL l_float32 pixAverageOnLine | ( | PIX * | pixs, |
l_int32 | x1, | ||
l_int32 | y1, | ||
l_int32 | x2, | ||
l_int32 | y2, | ||
l_int32 | factor | ||
) |
Input: pixs (1 bpp or 8 bpp; no colormap) x1, y1 (starting pt for line) x2, y2 (end pt for line) factor (sampling; >= 1) Return: average of pixel values along line, or null on error.
Notes: (1) The line must be either horizontal or vertical, so either y1 == y2 (horizontal) or x1 == x2 (vertical). (2) If horizontal, x1 must be <= x2. If vertical, y1 must be <= y2. characterize the intensity smoothness along a line. (3) Input end points are clipped to the pix.
Input: filename pixa Return: 0 if OK, 1 on error
Notes: (1) The pix are stored in the file as png. If the png library is not linked, this will fail.
LEPT_DLL l_int32 pixaWriteCompressedToPS | ( | PIXA * | pixa, |
const char * | fileout, | ||
l_int32 | res, | ||
l_int32 | level | ||
) |
LEPT_DLL l_int32 pixaWriteFiles | ( | const char * | rootname, |
PIXA * | pixa, | ||
l_int32 | format | ||
) |
Input: rootname pixa format (defined in imageio.h) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 pixaWriteStream | ( | FILE * | fp, |
PIXA * | pixa | ||
) |
Input: stream (opened for "wb") pixa Return: 0 if OK, 1 on error
Notes: (1) The pix are stored in the file as png. If the png library is not linked, this will fail.
LEPT_DLL PIX* pixBackgroundNorm | ( | PIX * | pixs, |
PIX * | pixim, | ||
PIX * | pixg, | ||
l_int32 | sx, | ||
l_int32 | sy, | ||
l_int32 | thresh, | ||
l_int32 | mincount, | ||
l_int32 | bgval, | ||
l_int32 | smoothx, | ||
l_int32 | smoothy | ||
) |
Input: pixs (8 bpp grayscale or 32 bpp rgb) pixim (<optional> 1 bpp 'image' mask; can be null) pixg (<optional> 8 bpp grayscale version; can be null) sx, sy (tile size in pixels) thresh (threshold for determining foreground) mincount (min threshold on counts in a tile) bgval (target bg val; typ. > 128) smoothx (half-width of block convolution kernel width) smoothy (half-width of block convolution kernel height) Return: pixd (8 bpp or 32 bpp rgb), or null on error
Notes: (1) This is a top-level interface for normalizing the image intensity by mapping the image so that the background is near the input value 'bgval'. (2) The input image is either grayscale or rgb. (3) For each component in the input image, the background value in each tile is estimated using the values in the tile that are not part of the foreground, where the foreground is determined by the input 'thresh' argument. (4) An optional binary mask can be specified, with the foreground pixels typically over image regions. The resulting background map values will be determined by surrounding pixels that are not under the mask foreground. The origin (0,0) of this mask is assumed to be aligned with the origin of the input image. This binary mask must not fully cover pixs, because then there will be no pixels in the input image available to compute the background. (5) An optional grayscale version of the input pixs can be supplied. The only reason to do this is if the input is RGB and this grayscale version can be used elsewhere. If the input is RGB and this is not supplied, it is made internally using only the green component, and destroyed after use. (6) The dimensions of the pixel tile (sx, sy) give the amount by by which the map is reduced in size from the input image. (7) The threshold is used to binarize the input image, in order to locate the foreground components. If this is set too low, some actual foreground may be used to determine the maps; if set too high, there may not be enough background to determine the map values accurately. Typically, it's better to err by setting the threshold too high. (8) A 'mincount' threshold is a minimum count of pixels in a tile for which a background reading is made, in order for that pixel in the map to be valid. This number should perhaps be at least 1/3 the size of the tile. (9) A 'bgval' target background value for the normalized image. This should be at least 128. If set too close to 255, some clipping will occur in the result. (10) Two factors, 'smoothx' and 'smoothy', are input for smoothing the map. Each low-pass filter kernel dimension is is 2 * (smoothing factor) + 1, so a value of 0 means no smoothing. A value of 1 or 2 is recommended.
LEPT_DLL PIX* pixBackgroundNormFlex | ( | PIX * | pixs, |
l_int32 | sx, | ||
l_int32 | sy, | ||
l_int32 | smoothx, | ||
l_int32 | smoothy, | ||
l_int32 | delta | ||
) |
Input: pixs (8 bpp grayscale; not colormapped) sx, sy (desired tile dimensions; actual size may vary; use values between 3 and 10) smoothx, smoothy (half-width of convolution kernel applied to threshold array: use values between 1 and 3) delta (difference parameter in basin filling; use 0 to skip) Return: pixd (8 bpp, background-normalized), or null on error)
Notes: (1) This does adaptation flexibly to a quickly varying background. For that reason, all input parameters should be small. (2) sx and sy give the tile size; they should be in [5 - 7]. (3) The full width and height of the convolution kernel are (2 * smoothx + 1) and (2 * smoothy + 1). They should be in [1 - 2]. (4) Basin filling is used to fill the large fg regions. The parameter measures the height that the black background is raised from the local minima. By raising the background, it is possible to threshold the large fg regions to foreground. If is too large, bg regions will be lifted, causing thickening of the fg regions. Use 0 to skip.
LEPT_DLL l_int32 pixBackgroundNormGrayArray | ( | PIX * | pixs, |
PIX * | pixim, | ||
l_int32 | sx, | ||
l_int32 | sy, | ||
l_int32 | thresh, | ||
l_int32 | mincount, | ||
l_int32 | bgval, | ||
l_int32 | smoothx, | ||
l_int32 | smoothy, | ||
PIX ** | ppixd | ||
) |
Input: pixs (8 bpp grayscale) pixim (<optional> 1 bpp 'image' mask; can be null) sx, sy (tile size in pixels) thresh (threshold for determining foreground) mincount (min threshold on counts in a tile) bgval (target bg val; typ. > 128) smoothx (half-width of block convolution kernel width) smoothy (half-width of block convolution kernel height) &pixd (<return> 16 bpp array of inverted background value) Return: 0 if OK, 1 on error
Notes: (1) See notes in pixBackgroundNorm(). (2) This returns a 16 bpp pix that can be used by pixApplyInvBackgroundGrayMap() to generate a normalized version of the input pixs.
LEPT_DLL l_int32 pixBackgroundNormGrayArrayMorph | ( | PIX * | pixs, |
PIX * | pixim, | ||
l_int32 | reduction, | ||
l_int32 | size, | ||
l_int32 | bgval, | ||
PIX ** | ppixd | ||
) |
pixBackgroundNormGrayArrayMorph()
Input: pixs (8 bpp grayscale) pixim (<optional> 1 bpp 'image' mask; can be null) reduction (at which morph closings are done; between 2 and 16) size (of square Sel for the closing; use an odd number) bgval (target bg val; typ. > 128) &pixd (<return> 16 bpp array of inverted background value) Return: 0 if OK, 1 on error
Notes: (1) See notes in pixBackgroundNormMorph(). (2) This returns a 16 bpp pix that can be used by pixApplyInvBackgroundGrayMap() to generate a normalized version of the input pixs.
LEPT_DLL PIX* pixBackgroundNormMorph | ( | PIX * | pixs, |
PIX * | pixim, | ||
l_int32 | reduction, | ||
l_int32 | size, | ||
l_int32 | bgval | ||
) |
Input: pixs (8 bpp grayscale or 32 bpp rgb) pixim (<optional> 1 bpp 'image' mask; can be null) reduction (at which morph closings are done; between 2 and 16) size (of square Sel for the closing; use an odd number) bgval (target bg val; typ. > 128) Return: pixd (8 bpp), or null on error
Notes: (1) This is a top-level interface for normalizing the image intensity by mapping the image so that the background is near the input value 'bgval'. (2) The input image is either grayscale or rgb. (3) For each component in the input image, the background value is estimated using a grayscale closing; hence the 'Morph' in the function name. (4) An optional binary mask can be specified, with the foreground pixels typically over image regions. The resulting background map values will be determined by surrounding pixels that are not under the mask foreground. The origin (0,0) of this mask is assumed to be aligned with the origin of the input image. This binary mask must not fully cover pixs, because then there will be no pixels in the input image available to compute the background. (5) The map is computed at reduced size (given by 'reduction') from the input pixs and optional pixim. At this scale, pixs is closed to remove the background, using a square Sel of odd dimension. The product of reduction * size should be large enough to remove most of the text foreground. (6) No convolutional smoothing needs to be done on the map before inverting it. (7) A 'bgval' target background value for the normalized image. This should be at least 128. If set too close to 255, some clipping will occur in the result.
LEPT_DLL l_int32 pixBackgroundNormRGBArrays | ( | PIX * | pixs, |
PIX * | pixim, | ||
PIX * | pixg, | ||
l_int32 | sx, | ||
l_int32 | sy, | ||
l_int32 | thresh, | ||
l_int32 | mincount, | ||
l_int32 | bgval, | ||
l_int32 | smoothx, | ||
l_int32 | smoothy, | ||
PIX ** | ppixr, | ||
PIX ** | ppixg, | ||
PIX ** | ppixb | ||
) |
Input: pixs (32 bpp rgb) pixim (<optional> 1 bpp 'image' mask; can be null) pixg (<optional> 8 bpp grayscale version; can be null) sx, sy (tile size in pixels) thresh (threshold for determining foreground) mincount (min threshold on counts in a tile) bgval (target bg val; typ. > 128) smoothx (half-width of block convolution kernel width) smoothy (half-width of block convolution kernel height) &pixr (<return> 16 bpp array of inverted R background value) &pixg (<return> 16 bpp array of inverted G background value) &pixb (<return> 16 bpp array of inverted B background value) Return: 0 if OK, 1 on error
Notes: (1) See notes in pixBackgroundNorm(). (2) This returns a set of three 16 bpp pix that can be used by pixApplyInvBackgroundGrayMap() to generate a normalized version of each component of the input pixs.
LEPT_DLL l_int32 pixBackgroundNormRGBArraysMorph | ( | PIX * | pixs, |
PIX * | pixim, | ||
l_int32 | reduction, | ||
l_int32 | size, | ||
l_int32 | bgval, | ||
PIX ** | ppixr, | ||
PIX ** | ppixg, | ||
PIX ** | ppixb | ||
) |
pixBackgroundNormRGBArraysMorph()
Input: pixs (32 bpp rgb) pixim (<optional> 1 bpp 'image' mask; can be null) reduction (at which morph closings are done; between 2 and 16) size (of square Sel for the closing; use an odd number) bgval (target bg val; typ. > 128) &pixr (<return> 16 bpp array of inverted R background value) &pixg (<return> 16 bpp array of inverted G background value) &pixb (<return> 16 bpp array of inverted B background value) Return: 0 if OK, 1 on error
Notes: (1) See notes in pixBackgroundNormMorph(). (2) This returns a set of three 16 bpp pix that can be used by pixApplyInvBackgroundGrayMap() to generate a normalized version of each component of the input pixs.
Input: pixs (8 bpp grayscale or 32 bpp rgb) pixim (<optional> 1 bpp 'image' mask; can be null) pixg (<optional> 8 bpp grayscale version; can be null) Return: pixd (8 bpp or 32 bpp rgb), or null on error
Notes: (1) This is a simplified interface to pixBackgroundNorm(), where seven parameters are defaulted. (2) The input image is either grayscale or rgb. (3) See pixBackgroundNorm() for usage and function.
LEPT_DLL l_int32 pixBestCorrelation | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_int32 | area1, | ||
l_int32 | area2, | ||
l_int32 | etransx, | ||
l_int32 | etransy, | ||
l_int32 | maxshift, | ||
l_int32 * | tab8, | ||
l_int32 * | pdelx, | ||
l_int32 * | pdely, | ||
l_float32 * | pscore, | ||
l_int32 | debugflag | ||
) |
Input: pix1 (1 bpp) pix2 (1 bpp) area1 (number of on pixels in pix1) area2 (number of on pixels in pix2) etransx (estimated x translation of pix2 to align with pix1) etransy (estimated y translation of pix2 to align with pix1) maxshift (max x and y shift of pix2, around the estimated alignment location, relative to pix1) tab8 (<optional> sum tab for ON pixels in byte; can be NULL) &delx (<return> best x shift of pix2 relative to pix1 &dely (<return> best y shift of pix2 relative to pix1 &score (<optional return>=""> maximum score found; can be NULL) debugflag (<= 0 to skip; positive to generate output. The integer is used to label the debug image.) Return: 0 if OK, 1 on error
Notes: (1) This finds the actual shift (delx, dely) between two 1 bpp images that maximizes correlation score when pix2 is shifted by this amount relative to pix1. Also returns the max score. (2) Get the pixel counts using pixCountPixels(). Get the centroids using pixCentroid() and wrap them into a pta. (3) The centroid of pix2 is shifted with respect to the centroid of pix1 by all values between -maxshiftx and maxshiftx, and likewise for the y shifts. Therefore, the number of correlations computed is: (2 * maxshiftx + 1) * (2 * maxshifty + 1) Consequently, if pix1 and pix2 are large, you should do this in a coarse-to-fine sequence.
Input: pixs (all depths; colormap ok) vc (vector of 8 coefficients for bilinear transformation) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Brings in either black or white pixels from the boundary (2) Removes any existing colormap, if necessary, before transforming
Input: pixs (32 bpp) vc (vector of 8 coefficients for bilinear transformation) colorval (e.g., 0 to bring in BLACK, 0xffffff00 for WHITE) Return: pixd, or null on error
Input: pixs (8 bpp) vc (vector of 8 coefficients for bilinear transformation) grayval (0 to bring in BLACK, 255 for WHITE) Return: pixd, or null on error
Input: pixs (all depths; colormap ok) ptad (4 pts of final coordinate space) ptas (4 pts of initial coordinate space) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Brings in either black or white pixels from the boundary (2) Removes any existing colormap, if necessary, before transforming
Input: pixs (32 bpp) ptad (4 pts of final coordinate space) ptas (4 pts of initial coordinate space) colorval (e.g., 0 to bring in BLACK, 0xffffff00 for WHITE) Return: pixd, or null on error
LEPT_DLL PIX* pixBilinearPtaGammaXform | ( | PIX * | pixs, |
l_float32 | gamma, | ||
PTA * | ptad, | ||
PTA * | ptas, | ||
l_float32 | fract, | ||
l_int32 | border | ||
) |
Input: pixs (32 bpp rgb) gamma (gamma correction; must be > 0.0) ptad (3 pts of final coordinate space) ptas (3 pts of initial coordinate space) fract (between 0.0 and 1.0, with 1.0 fully transparent) border (of pixels to capture transformed source pixels) Return: pixd, or null on error
Notes: (1) This wraps a gamma/inverse-gamma photometric transform around pixBilinearPtaWithAlpha(). (2) For usage, see notes in pixBilinearPtaWithAlpha() and pixGammaTRCWithAlpha(). (3) The basic idea of a gamma/inverse-gamma transform is to remove any gamma correction before the bilinear transform, and restore it afterward. The effects can be subtle, but important for some applications. For example, using gamma > 1.0 will cause the dark areas to become somewhat lighter and slightly reduce aliasing effects when blending using the alpha channel.
Input: pixs (8 bpp) ptad (4 pts of final coordinate space) ptas (4 pts of initial coordinate space) grayval (0 to bring in BLACK, 255 for WHITE) Return: pixd, or null on error
LEPT_DLL PIX* pixBilinearPtaWithAlpha | ( | PIX * | pixs, |
PTA * | ptad, | ||
PTA * | ptas, | ||
PIX * | pixg, | ||
l_float32 | fract, | ||
l_int32 | border | ||
) |
Input: pixs (32 bpp rgb) ptad (4 pts of final coordinate space) ptas (4 pts of initial coordinate space) pixg (<optional> 8 bpp, can be null) fract (between 0.0 and 1.0, with 0.0 fully transparent and 1.0 fully opaque) border (of pixels added to capture transformed source pixels) Return: pixd, or null on error
Notes: (1) The alpha channel is transformed separately from pixs, and aligns with it, being fully transparent outside the boundary of the transformed pixs. For pixels that are fully transparent, a blending function like pixBlendWithGrayMask() will give zero weight to corresponding pixels in pixs. (2) If pixg is NULL, it is generated as an alpha layer that is partially opaque, using . Otherwise, it is cropped to pixs if required and is ignored. The alpha channel in pixs is never used. (3) Colormaps are removed. (4) When pixs is transformed, it doesn't matter what color is brought in because the alpha channel will be transparent (0) there. (5) To avoid losing source pixels in the destination, it may be necessary to add a border to the source pix before doing the bilinear transformation. This can be any non-negative number. (6) The input and are in a coordinate space before the border is added. Internally, we compensate for this before doing the bilinear transform on the image after the border is added. (7) The default setting for the border values in the alpha channel is 0 (transparent) for the outermost ring of pixels and (0.5 * fract * 255) for the second ring. When blended over a second image, this (a) shrinks the visible image to make a clean overlap edge with an image below, and (b) softens the edges by weakening the aliasing there. Use l_setAlphaMaskBorder() to change these values.
Input: pixs (all depths) vc (vector of 8 coefficients for bilinear transformation) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Brings in either black or white pixels from the boundary. (2) Retains colormap, which you can do for a sampled transform.. (3) For 8 or 32 bpp, much better quality is obtained by the somewhat slower pixBilinear(). See that function for relative timings between sampled and interpolated.
Input: pixs (all depths) ptad (4 pts of final coordinate space) ptas (4 pts of initial coordinate space) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Brings in either black or white pixels from the boundary. (2) Retains colormap, which you can do for a sampled transform.. (3) No 3 of the 4 points may be collinear. (4) For 8 and 32 bpp pix, better quality is obtained by the somewhat slower pixBilinearPta(). See that function for relative timings between sampled and interpolated.
Input: pixs1 (blendee) pixs2 (blender; typ. smaller) x,y (origin (UL corner) of pixs2 relative to the origin of pixs1; can be < 0) fract (blending fraction) Return: pixd (blended image), or null on error
Notes: (1) This is a simple top-level interface. For more flexibility, call directly into pixBlendMask(), etc.
LEPT_DLL PIX* pixBlendBackgroundToColor | ( | PIX * | pixd, |
PIX * | pixs, | ||
BOX * | box, | ||
l_uint32 | color, | ||
l_float32 | gamma, | ||
l_int32 | minval, | ||
l_int32 | maxval | ||
) |
Input: pixd (can be NULL or pixs) pixs (32 bpp rgb) box (region for blending; can be NULL)) color (32 bit color in 0xrrggbb00 format) gamma, minval, maxval (args for grayscale TRC mapping) Return: pixd always
Notes: (1) This in effect replaces light background pixels in pixs by the input color. It does it by alpha blending so that there are no visible artifacts from hard cutoffs. (2) If pixd == pixs, this is done in-place. (3) If box == NULL, this is performed on all of pixs. (4) The alpha component for blending is derived from pixs, by converting to grayscale and enhancing with a TRC. (5) The last three arguments specify the TRC operation. Suggested values are: = 0.3, = 50, = 200. To skip the TRC, use == 1, = 0, = 255. See pixGammaTRC() for details.
Input: pixs (any depth; can be cmapped) boxa (of boxes, to blend/paint) fract (of box color to use) Return: pixd (32 bpp, with blend/painted boxes), or null on error
Notes: (1) pixs is converted to 32 bpp. (2) This differs from pixPaintBoxaRandom(), in that the colors here are blended with the color of pixs. (3) We use up to 254 different colors for painting the regions. (4) If boxes overlap, the final color depends only on the last rect that is used.
Input: pixs (2, 4 or 8 bpp, with colormap) pixb (colormapped blender) x, y (UL corner of blender relative to pixs) sindex (colormap index of pixels in pixs to be changed) Return: 0 if OK, 1 on error
Note: (1) This function combines two colormaps, and replaces the pixels in pixs that have a specified color value with those in pixb. (2) sindex must be in the existing colormap; otherwise an error is returned. In use, sindex will typically be the index for white (255, 255, 255). (3) Blender colors that already exist in the colormap are used; others are added. If any blender colors cannot be stored in the colormap, an error is returned. (4) In the implementation, a mapping is generated from each original blender colormap index to the corresponding index in the expanded colormap for pixs. Then for each pixel in pixs with value sindex, and which is covered by a blender pixel, the new index corresponding to the blender pixel is substituted for sindex.
LEPT_DLL PIX* pixBlendColor | ( | PIX * | pixd, |
PIX * | pixs1, | ||
PIX * | pixs2, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 | fract, | ||
l_int32 | transparent, | ||
l_uint32 | transpix | ||
) |
Input: pixd (<optional>; either NULL or equal to pixs1 for in-place) pixs1 (blendee; depth > 1) pixs2 (blender, 32 bpp; typ. smaller in size than pixs1) x,y (origin (UL corner) of pixs2 relative to the origin of pixs1) fract (blending fraction) transparent (1 to use transparency; 0 otherwise) transpix (pixel color in pixs2 that is to be transparent) Return: pixd if OK; pixs1 on error
Notes: (1) pixs2 must be 32 bpp, and have no colormap. (2) Clipping of pixs2 to pixs1 is done in the inner pixel loop. (3) If pixs1 has a colormap, it is removed to generate a 32 bpp pix. (4) If pixs1 has depth < 32, it is unpacked to generate a 32 bpp pix. (5) For inplace operation, call it this way: pixBlendColor(pixs1, pixs1, pixs2, ...) (6) For generating a new pixd: pixd = pixBlendColor(NULL, pixs1, pixs2, ...) (7) Only call in-place if pixs1 is 32 bpp; otherwise it is an error. (8) If transparent = 0, the blending fraction (fract) is applied equally to all pixels. (9) If transparent = 1, all pixels of value transpix (typically either 0 or 0xffffff00) in pixs2 are transparent in the blend.
LEPT_DLL PIX* pixBlendColorByChannel | ( | PIX * | pixd, |
PIX * | pixs1, | ||
PIX * | pixs2, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 | rfract, | ||
l_float32 | gfract, | ||
l_float32 | bfract, | ||
l_int32 | transparent, | ||
l_uint32 | transpix | ||
) |
LEPT_DLL PIX* pixBlendGray | ( | PIX * | pixd, |
PIX * | pixs1, | ||
PIX * | pixs2, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 | fract, | ||
l_int32 | type, | ||
l_int32 | transparent, | ||
l_uint32 | transpix | ||
) |
Input: pixd (<optional>; either NULL or equal to pixs1 for in-place) pixs1 (blendee; depth > 1) pixs2 (blender, 8 bpp; typ. smaller in size than pixs1) x,y (origin (UL corner) of pixs2 relative to the origin of pixs1; can be < 0) fract (blending fraction) type (L_BLEND_GRAY, L_BLEND_GRAY_WITH_INVERSE) transparent (1 to use transparency; 0 otherwise) transpix (pixel grayval in pixs2 that is to be transparent) Return: pixd if OK; pixs1 on error
Notes: (1) pixs2 must be 8 bpp, and have no colormap. (2) Clipping of pixs2 to pixs1 is done in the inner pixel loop. (3) If pixs1 has a colormap, it is removed. (4) If pixs1 has depth < 8, it is unpacked to generate a 8 bpp pix. (5) For inplace operation, call it this way: pixBlendGray(pixs1, pixs1, pixs2, ...) (6) For generating a new pixd: pixd = pixBlendGray(NULL, pixs1, pixs2, ...) (7) Only call in-place if pixs1 does not have a colormap; otherwise it is an error. (8) If transparent = 0, the blending fraction (fract) is applied equally to all pixels. (9) If transparent = 1, all pixels of value transpix (typically either 0 or 0xff) in pixs2 are transparent in the blend. (10) After processing pixs1, it is either 8 bpp or 32 bpp:
LEPT_DLL PIX* pixBlendGrayAdapt | ( | PIX * | pixd, |
PIX * | pixs1, | ||
PIX * | pixs2, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 | fract, | ||
l_int32 | shift | ||
) |
Input: pixd (<optional>; either NULL or equal to pixs1 for in-place) pixs1 (blendee; depth > 1) pixs2 (blender, 8 bpp; typ. smaller in size than pixs1) x,y (origin (UL corner) of pixs2 relative to the origin of pixs1; can be < 0) fract (blending fraction) shift (>= 0 but <= 128: shift of zero blend value from median source; use -1 for default value; ) Return: pixd if OK; pixs1 on error
Notes: (1) pixs2 must be 8 bpp, and have no colormap. (2) Clipping of pixs2 to pixs1 is done in the inner pixel loop. (3) If pixs1 has a colormap, it is removed. (4) If pixs1 has depth < 8, it is unpacked to generate a 8 bpp pix. (5) For inplace operation, call it this way: pixBlendGray(pixs1, pixs1, pixs2, ...) For generating a new pixd: pixd = pixBlendGray(NULL, pixs1, pixs2, ...) Only call in-place if pixs1 does not have a colormap; otherwise it is an error. (6) This does a blend with inverse. Whereas in pixGlendGray(), the zero blend point is where the blendee pixel is 128, here the zero blend point is found adaptively, with respect to the median of the blendee region. If the median is < 128, the zero blend point is found from median + shift. Otherwise, if the median >= 128, the zero blend point is median - shift. The purpose of shifting the zero blend point away from the median is to prevent a situation in pixBlendGray() where the median is 128 and the blender is not visible. The default value of shift is 64. (7) After processing pixs1, it is either 8 bpp or 32 bpp:
LEPT_DLL PIX* pixBlendGrayInverse | ( | PIX * | pixd, |
PIX * | pixs1, | ||
PIX * | pixs2, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 | fract | ||
) |
Input: pixd (<optional>; either NULL or equal to pixs1 for in-place) pixs1 (blendee; depth > 1) pixs2 (blender, 8 bpp; typ. smaller in size than pixs1) x,y (origin (UL corner) of pixs2 relative to the origin of pixs1; can be < 0) fract (blending fraction) Return: pixd if OK; pixs1 on error
Notes: (1) pixs2 must be 8 bpp, and have no colormap. (2) Clipping of pixs2 to pixs1 is done in the inner pixel loop. (3) If pixs1 has a colormap, it is removed. (4) If pixs1 has depth < 8, it is unpacked to generate a 8 bpp pix. (5) For inplace operation, call it this way: pixBlendGray(pixs1, pixs1, pixs2, ...) (6) For generating a new pixd: pixd = pixBlendGrayInverse(NULL, pixs1, pixs2, ...) (7) Only call in-place if pixs1 does not have a colormap; otherwise it is an error. (8) This is a no-nonsense blender. It changes the src1 pixel except when the src1 pixel is midlevel gray. Use fract == 1 for the most aggressive blending, where, if the gray pixel in pixs2 is 0, we get a complete inversion of the color of the src pixel in pixs1. (9) The basic logic is that each component transforms by: d --> c * d + (1 - c ) * (f * (1 - d) + d * (1 - f)) where c is the blender pixel from pixs2, f is , c and d are normalized to [0...1] This has the property that for f == 0 (no blend) or c == 1 (white): d --> d For c == 0 (black) we get maximum inversion: d --> f * (1 - d) + d * (1 - f) [inversion by fraction f]
LEPT_DLL PIX* pixBlendHardLight | ( | PIX * | pixd, |
PIX * | pixs1, | ||
PIX * | pixs2, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 | fract | ||
) |
Input: pixs (32 bpp rgb) box (<optional> in which all pixels will be blended) val (blend value; 0xrrggbb00) fract (fraction of color to be blended with each pixel in pixs) Return: 0 if OK; 1 on error
Notes: (1) This is an in-place function. It blends the input color with the pixels in pixs in the specified rectangle. If no rectangle is specified, it blends over the entire image.
LEPT_DLL PIX* pixBlendMask | ( | PIX * | pixd, |
PIX * | pixs1, | ||
PIX * | pixs2, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 | fract, | ||
l_int32 | type | ||
) |
Input: pixd (<optional>; either NULL or equal to pixs1 for in-place) pixs1 (blendee; depth > 1) pixs2 (blender; typ. smaller in size than pixs1) x,y (origin (UL corner) of pixs2 relative to the origin of pixs1; can be < 0) fract (blending fraction) type (L_BLEND_WITH_INVERSE, L_BLEND_TO_WHITE, L_BLEND_TO_BLACK) Return: pixd if OK; pixs1 on error
Notes: (1) pixs2 must be 1 bpp (2) Clipping of pixs2 to pixs1 is done in the inner pixel loop. (3) If pixs1 has a colormap, it is removed. (4) For inplace operation, call it this way: pixBlendMask(pixs1, pixs1, pixs2, ...) (5) For generating a new pixd: pixd = pixBlendMask(NULL, pixs1, pixs2, ...) (6) Only call in-place if pixs1 does not have a colormap.
Input: pixs1 (8 bpp gray, rgb or colormapped) pixs2 (8 bpp gray, rgb or colormapped) pixg (8 bpp gray, for transparency of pixs2; can be null) x, y (UL corner of pixg with respect to pixs1) Return: pixd (blended image), or null on error
Notes: (1) The result is 8 bpp grayscale if both pixs1 and pixs2 are 8 bpp gray. Otherwise, the result is 32 bpp rgb. (2) pixg is an 8 bpp transparency image, where 0 is transparent and 255 is opaque. It determines the transparency of pixs2 when applied over pixs1. It can be null if pixs2 is rgb, in which case we use the alpha component of pixs2. (3) If pixg exists, both it and pixs2 must be the same size, and they are applied with both their UL corners at the location (x, y) in pixs1. (4) The pixels in pixd are a combination of those in pixs1 and pixs2, where the amount from pixs2 is proportional to the value of the pixel (p) in pixg, and the amount from pixs1 is proportional to (255 - p). Thus pixg is a transparency image (usually called an alpha blender) where each pixel can be associated with a pixel in pixs2, and determines the amount of the pixs2 pixel in the final result. For example, if pixg is all 0, pixs2 is transparent and the result in pixd is simply pixs1. (5) A typical use is for the pixs2/pixg combination to be a small watermark that is applied to pixs1.
Input: pix (8 or 32 bpp; or 2, 4 or 8 bpp with colormap) wc, hc (half width/height of convolution kernel) Return: pixd, or null on error
Notes: (1) The full width and height of the convolution kernel are (2 * wc + 1) and (2 * hc + 1) (2) Returns a copy if both wc and hc are 0 (3) Require that w >= 2 * wc + 1 and h >= 2 * hc + 1, where (w,h) are the dimensions of pixs.
LEPT_DLL PIX* pixBlockconvAccum | ( | PIX * | pixs | ) |
Input: pixs (1, 8 or 32 bpp) Return: accum pix (32 bpp), or null on error.
Notes: (1) The general recursion relation is a(i,j) = v(i,j) + a(i-1, j) + a(i, j-1) - a(i-1, j-1) For the first line, this reduces to the special case a(i,j) = v(i,j) + a(i, j-1) For the first column, the special case is a(i,j) = v(i,j) + a(i-1, j)
Input: pix (8 bpp) accum pix (32 bpp; can be null) wc, hc (half width/height of convolution kernel) Return: pix (8 bpp), or null on error
Notes: (1) If accum pix is null, make one and destroy it before returning; otherwise, just use the input accum pix. (2) The full width and height of the convolution kernel are (2 * wc + 1) and (2 * hc + 1). (3) Returns a copy if both wc and hc are 0. (4) Require that w >= 2 * wc + 1 and h >= 2 * hc + 1, where (w,h) are the dimensions of pixs.
Input: pixs (8 bpp gray) pixacc (32 bpp accum pix) wc, hc (half width/height of convolution kernel) Return: pixd, or null on error
Notes: (1) The full width and height of the convolution kernel are (2 * wc + 1) and (2 * hc + 1) (2) Assumes that the input pixs is padded with (wc + 1) pixels on left and right, and with (hc + 1) pixels on top and bottom. The returned pix has these stripped off; they are only used for computation. (3) Returns a copy if both wc and hc are 0 (4) Require that w > 2 * wc + 1 and h > 2 * hc + 1, where (w,h) are the dimensions of pixs.
pixBlockconvGrayUnnormalized()
Input: pixs (8 bpp) wc, hc (half width/height of convolution kernel) Return: pix (32 bpp; containing the convolution without normalizing for the window size), or null on error
Notes: (1) The full width and height of the convolution kernel are (2 * wc + 1) and (2 * hc + 1). (2) Require that w >= 2 * wc + 1 and h >= 2 * hc + 1, where (w,h) are the dimensions of pixs. (3) Returns a copy if both wc and hc are 0. (3) Adds mirrored border to avoid treating the boundary pixels specially. Note that we add wc + 1 pixels to the left and wc to the right. The added width is 2 * wc + 1 pixels, and the particular choice simplifies the indexing in the loop. Likewise, add hc + 1 pixels to the top and hc to the bottom. (4) To get the normalized result, divide by the area of the convolution kernel: (2 * wc + 1) * (2 * hc + 1) Specifically, do this: pixc = pixBlockconvGrayUnnormalized(pixs, wc, hc); fract = 1. / ((2 * wc + 1) * (2 * hc + 1)); pixMultConstantGray(pixc, fract); pixd = pixGetRGBComponent(pixc, L_ALPHA_CHANNEL); (5) Unlike pixBlockconvGray(), this always computes the accumulation pix because its size is tied to wc and hc. (6) Compare this implementation with pixBlockconvGray(), where most of the code in blockconvLow() is special casing for efficiently handling the boundary. Here, the use of mirrored borders and destination indexing makes the implementation very simple.
Input: pix (8 or 32 bpp; or 2, 4 or 8 bpp with colormap) wc, hc (half width/height of convolution kernel) nx, ny (subdivision into tiles) Return: pixd, or null on error
Notes: (1) The full width and height of the convolution kernel are (2 * wc + 1) and (2 * hc + 1) (2) Returns a copy if both wc and hc are 0 (3) Require that w >= 2 * wc + 1 and h >= 2 * hc + 1, where (w,h) are the dimensions of pixs. (4) For nx == ny == 1, this defaults to pixBlockconv(), which is typically about twice as fast, and gives nearly identical results as pixBlockconvGrayTile(). (5) If the tiles are too small, nx and/or ny are reduced a minimum amount so that the tiles are expanded to the smallest workable size in the problematic direction(s). (6) Why a tiled version? Three reasons: (a) Because the accumulator is a uint32, overflow can occur for an image with more than 16M pixels. (b) The accumulator array for 16M pixels is 64 MB; using tiles reduces the size of this array. (c) Each tile can be processed independently, in parallel, on a multicore processor.
Input: pixs (1 bpp) accum pix (<optional> 32 bpp) wc, hc (half width/height of block sum/rank kernel) rank (between 0.0 and 1.0; 0.5 is median filter) Return: pixd (1 bpp)
Notes: (1) The full width and height of the convolution kernel are (2 * wc + 1) and (2 * hc + 1) (2) This returns a pixd where each pixel is a 1 if the neighborhood (2 * wc + 1) x (2 * hc + 1)) pixels contains the rank fraction of 1 pixels. Otherwise, the returned pixel is 0. Note that the special case of rank = 0.0 is always satisfied, so the returned pixd has all pixels with value 1. (3) If accum pix is null, make one, use it, and destroy it before returning; otherwise, just use the input accum pix (4) If both wc and hc are 0, returns a copy unless rank == 0.0, in which case this returns an all-ones image. (5) Require that w >= 2 * wc + 1 and h >= 2 * hc + 1, where (w,h) are the dimensions of pixs.
Input: pixs (1 bpp) accum pix (<optional> 32 bpp) wc, hc (half width/height of block sum/rank kernel) Return: pixd (8 bpp)
Notes: (1) If accum pix is null, make one and destroy it before returning; otherwise, just use the input accum pix (2) The full width and height of the convolution kernel are (2 * wc + 1) and (2 * hc + 1) (3) Use of wc = hc = 1, followed by pixInvert() on the 8 bpp result, gives a nice anti-aliased, and somewhat darkened, result on text. (4) Require that w >= 2 * wc + 1 and h >= 2 * hc + 1, where (w,h) are the dimensions of pixs. (5) Returns in each dest pixel the sum of all src pixels that are within a block of size of the kernel, centered on the dest pixel. This sum is the number of src ON pixels in the block at each location, normalized to 255 for a block containing all ON pixels. For pixels near the boundary, where the block is not entirely contained within the image, we then multiply by a second normalization factor that is greater than one, so that all results are normalized by the number of participating pixels within the block.
Input: pixs (8 bpp) halfsize (of square over which neighbors are averaged) accum pix (<optional> 32 bpp) Return: pixd (1 bpp)
Notes: (1) The Census transform was invented by Ramin Zabih and John Woodfill ("Non-parametric local transforms for computing visual correspondence", Third European Conference on Computer Vision, Stockholm, Sweden, May 1994); see publications at http://www.cs.cornell.edu/~rdz/index.htm This compares each pixel against the average of its neighbors, in a square of odd dimension centered on the pixel. If the pixel is greater than the average of its neighbors, the output pixel value is 1; otherwise it is 0. (2) This can be used as an encoding for an image that is fairly robust against slow illumination changes, with applications in image comparison and mosaicing. (3) The size of the convolution kernel is (2 * halfsize + 1) on a side. The halfsize parameter must be >= 1. (4) If accum pix is null, make one, use it, and destroy it before returning; otherwise, just use the input accum pix
LEPT_DLL l_int32 pixCentroid | ( | PIX * | pix, |
l_int32 * | centtab, | ||
l_int32 * | sumtab, | ||
l_float32 * | pxave, | ||
l_float32 * | pyave | ||
) |
Input: pix (1 or 8 bpp) centtab (<optional> table for finding centroids; can be null) sumtab (<optional> table for finding pixel sums; can be null) &xave, &yave (<return> coordinates of centroid, relative to the UL corner of the pix) Return: 0 if OK, 1 on error
Notes: (1) Any table not passed in will be made internally and destroyed after use.
LEPT_DLL l_int32 pixChangeRefcount | ( | PIX * | pix, |
l_int32 | delta | ||
) |
LEPT_DLL l_int32 pixChooseOutputFormat | ( | PIX * | pix | ) |
Input: pix Return: output format, or 0 on error
Notes: (1) This should only be called if the requested format is IFF_DEFAULT. (2) If the pix wasn't read from a file, its input format value will be IFF_UNKNOWN, and in that case it is written out in a compressed but lossless format.
LEPT_DLL l_int32 pixCleanupByteProcessing | ( | PIX * | pix, |
l_uint8 ** | lineptrs | ||
) |
Input: pix (8 bpp, no colormap) lineptrs (ptrs to the beginning of each raster line of data) Return: 0 if OK, 1 on error
Notes: (1) This must be called after processing that was initiated by pixSetupByteProcessing() has finished.
LEPT_DLL l_int32 pixClearAll | ( | PIX * | pix | ) |
Input: pix (all depths; use cmapped with caution) Return: 0 if OK, 1 on error
Notes: (1) Clears all data to 0. For 1 bpp, this is white; for grayscale or color, this is black. (2) Caution: for colormapped pix, this sets the color to the first one in the colormap. Be sure that this is the intended color!
LEPT_DLL l_int32 pixClearInRect | ( | PIX * | pix, |
BOX * | box | ||
) |
Input: pix (all depths; can be cmapped) box (in which all pixels will be cleared) Return: 0 if OK, 1 on error
Notes: (1) Clears all data in rect to 0. For 1 bpp, this is white; for grayscale or color, this is black. (2) Caution: for colormapped pix, this sets the color to the first one in the colormap. Be sure that this is the intended color!
Input: pix (x,y) pixel coords Return: 0 if OK; 1 on error.
LEPT_DLL l_int32 pixClipBoxToEdges | ( | PIX * | pixs, |
BOX * | boxs, | ||
l_int32 | lowthresh, | ||
l_int32 | highthresh, | ||
l_int32 | maxwidth, | ||
l_int32 | factor, | ||
PIX ** | ppixd, | ||
BOX ** | pboxd | ||
) |
Input: pixs (1 bpp) boxs (<optional> ; use full image if null) lowthresh (threshold to choose clipping location) highthresh (threshold required to find an edge) maxwidth (max allowed width between low and high thresh locs) factor (sampling factor along pixel counting direction) &pixd (<optional return>=""> clipped pix returned) &boxd (<optional return>=""> bounding box) Return: 0 if OK; 1 on error or if a fg edge is not found from all four sides.
Notes: (1) At least one of {&pixd, &boxd} must be specified. (2) If there are no fg pixels, the returned ptrs are null. (3) This function attempts to locate rectangular "image" regions of high-density fg pixels, that have well-defined edges on the four sides. (4) Edges are searched for on each side, iterating in order from left, right, top and bottom. As each new edge is found, the search box is resized to use that location. Once an edge is found, it is held. If no more edges are found in one iteration, the search fails. (5) See pixScanForEdge() for usage of the thresholds and . (6) The thresholds must be at least 1, and the low threshold cannot be larger than the high threshold. (7) If the low and high thresholds are both 1, this is equivalent to pixClipBoxToForeground().
Input: pixs (1 bpp) boxs (<optional> ; use full image if null) &pixd (<optional return>=""> clipped pix returned) &boxd (<optional return>=""> bounding box) Return: 0 if OK; 1 on error or if there are no fg pixels
Notes: (1) At least one of {&pixd, &boxd} must be specified. (2) If there are no fg pixels, the returned ptrs are null. (3) Do not use &pixs for the 3rd arg or &boxs for the 4th arg; this will leak memory.
Input: pixs (1, 2, 4, 8, 16, 32 bpp; colormap ok) pixm (clipping mask, 1 bpp) x, y (origin of clipping mask relative to pixs) outval (val to use for pixels that are outside the mask) Return: pixd, (clipped pix) or null on error or if pixm doesn't intersect pixs
Notes: (1) If pixs has a colormap, it is preserved in pixd. (2) The depth of pixd is the same as that of pixs. (3) If the depth of pixs is 1, use = 0 for white background and 1 for black; otherwise, use the max value for white and 0 for black. If pixs has a colormap, the max value for is 0xffffffff; otherwise, it is 2^d - 1. (4) When using 1 bpp pixs, this is a simple clip and blend operation. For example, if both pix1 and pix2 are black text on white background, and you want to OR the fg on the two images, let pixm be the inverse of pix2. Then the operation takes all of pix1 that's in the bg of pix2, and for the remainder (which are the pixels corresponding to the fg of the pix2), paint them black (1) in pix1. The function call looks like pixClipMasked(pix2, pixInvert(pix1, pix1), x, y, 1);
Input: pixs box (requested clipping region; const) &boxc (<optional return>=""> actual box of clipped region) Return: clipped pix, or null on error or if rectangle doesn't intersect pixs
Notes:
This should be simple, but there are choices to be made. The box is defined relative to the pix coordinates. However, if the box is not contained within the pix, we have two choices:
(1) clip the box to the pix (2) make a new pix equal to the full box dimensions, but let rasterop do the clipping and positioning of the src with respect to the dest
Choice (2) immediately brings up the problem of what pixel values to use that were not taken from the src. For example, on a grayscale image, do you want the pixels not taken from the src to be black or white or something else? To implement choice 2, one needs to specify the color of these extra pixels.
So we adopt (1), and clip the box first, if necessary, before making the dest pix and doing the rasterop. But there is another issue to consider. If you want to paste the clipped pix back into pixs, it must be properly aligned, and it is necessary to use the clipped box for alignment. Accordingly, this function has a third (optional) argument, which is the input box clipped to the src pix.
Input: pixs (1 bpp) &pixd (<optional return>=""> clipped pix returned) &box (<optional return>=""> bounding box) Return: 0 if OK; 1 on error or if there are no fg pixels
Notes: (1) At least one of {&pixd, &box} must be specified. (2) If there are no fg pixels, the returned ptrs are null.
Input: pix Return: same pix (ptr), or null on error
Notes: (1) A "clone" is simply a handle (ptr) to an existing pix. It is implemented because (a) images can be large and hence expensive to copy, and (b) extra handles to a data structure need to be made with a simple policy to avoid both double frees and memory leaks. Pix are reference counted. The side effect of pixClone() is an increase by 1 in the ref count. (2) The protocol to be used is: (a) Whenever you want a new handle to an existing image, call pixClone(), which just bumps a ref count. (b) Always call pixDestroy() on all handles. This decrements the ref count, nulls the handle, and only destroys the pix when pixDestroy() has been called on all handles.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) sel Return: pixd
Notes: (1) Generic morphological closing, using hits in the Sel. (2) This implementation is a strict dual of the opening if symmetric boundary conditions are used (see notes at top of this file). (3) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (4) For clarity, if the case is known, use these patterns: (a) pixd = pixClose(NULL, pixs, ...); (b) pixClose(pixs, pixs, ...); (c) pixClose(pixd, pixs, ...); (5) The size of the result is determined by pixs.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd, or null on error
Notes: (1) Sel is a brick with all elements being hits (2) The origin is at (x, y) = (hsize/2, vsize/2) (3) Do separably if both hsize and vsize are > 1. (4) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (5) For clarity, if the case is known, use these patterns: (a) pixd = pixCloseBrick(NULL, pixs, ...); (b) pixCloseBrick(pixs, pixs, ...); (c) pixCloseBrick(pixd, pixs, ...); (6) The size of the result is determined by pixs.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
Notes: (1) This is a 'safe' closing; we add an extra border of 32 OFF pixels for the standard asymmetric b.c. (2) These implement 2D brick Sels, using linear Sels generated with selaAddBasic(). (3) A brick Sel has hits for all elements. (4) The origin of the Sel is at (x, y) = (hsize/2, vsize/2) (5) Do separably if both hsize and vsize are > 1. (6) It is necessary that both horizontal and vertical Sels of the input size are defined in the basic sela. (7) Note that we must always set or clear the border pixels before each operation, depending on the the b.c. (symmetric or asymmetric). (8) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (9) For clarity, if the case is known, use these patterns: (a) pixd = pixCloseBrickDwa(NULL, pixs, ...); (b) pixCloseBrickDwa(pixs, pixs, ...); (c) pixCloseBrickDwa(pixd, pixs, ...); (10) The size of the result is determined by pixs. (11) If either linear Sel is not found, this calls the appropriate decomposible function.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd, or null on error
Notes: (1) Sel is a brick with all elements being hits (2) The origin is at (x, y) = (hsize/2, vsize/2) (3) Do compositely for each dimension > 1. (4) Do separably if both hsize and vsize are > 1. (5) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (6) For clarity, if the case is known, use these patterns: (a) pixd = pixCloseCompBrick(NULL, pixs, ...); (b) pixCloseCompBrick(pixs, pixs, ...); (c) pixCloseCompBrick(pixd, pixs, ...); (7) The dimensions of the resulting image are determined by pixs. (8) CAUTION: both hsize and vsize are being decomposed. The decomposer chooses a product of sizes (call them 'terms') for each that is close to the input size, but not necessarily equal to it. It attempts to optimize: (a) for consistency with the input values: the product of terms is close to the input size (b) for efficiency of the operation: the sum of the terms is small; ideally about twice the square root of the input size. So, for example, if the input hsize = 37, which is a prime number, the decomposer will break this into two terms, 6 and 6, so that the net result is a dilation with hsize = 36.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
Notes: (1) This implements a separable composite safe closing with 2D brick Sels. (2) For efficiency, it may decompose each linear morphological operation into two (brick + comb). (3) A brick Sel has hits for all elements. (4) The origin of the Sel is at (x, y) = (hsize/2, vsize/2) (5) Do separably if both hsize and vsize are > 1. (6) It is necessary that both horizontal and vertical Sels of the input size are defined in the basic sela. (7) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (8) For clarity, if the case is known, use these patterns: (a) pixd = pixCloseCompBrickDwa(NULL, pixs, ...); (b) pixCloseCompBrickDwa(pixs, pixs, ...); (c) pixCloseCompBrickDwa(pixd, pixs, ...); (9) The size of pixd is determined by pixs. (10) CAUTION: both hsize and vsize are being decomposed. The decomposer chooses a product of sizes (call them 'terms') for each that is close to the input size, but not necessarily equal to it. It attempts to optimize: (a) for consistency with the input values: the product of terms is close to the input size (b) for efficiency of the operation: the sum of the terms is small; ideally about twice the square root of the input size. So, for example, if the input hsize = 37, which is a prime number, the decomposer will break this into two terms, 6 and 6, so that the net result is a dilation with hsize = 36.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
(1) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (2) There is no need to call this directly: pixCloseCompBrickDwa() calls this function if either brick dimension exceeds 63.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) sel Return: pixd
Notes: (1) Generalized morphological closing, using both hits and misses in the Sel. (2) This does a dilation using the hits, followed by a hit-miss transform. (3) This operation is a dual of the generalized opening. (4) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (5) For clarity, if the case is known, use these patterns: (a) pixd = pixCloseGeneralized(NULL, pixs, ...); (b) pixCloseGeneralized(pixs, pixs, ...); (c) pixCloseGeneralized(pixd, pixs, ...); (6) The size of the result is determined by pixs.
Input: pixs (8 bpp, not cmapped) hsize (1 or 3) vsize (1 or 3) Return: pixd, or null on error
Notes: (1) Special case for 1x3, 3x1 or 3x3 brick sel (all hits) (2) If hsize = vsize = 1, just returns a copy.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) sel Return: pixd
Notes: (1) Generic morphological closing, using hits in the Sel. (2) If non-symmetric boundary conditions are used, this function adds a border of OFF pixels that is of sufficient size to avoid losing pixels from the dilation, and it removes the border after the operation is finished. It thus enforces a correct extensive result for closing. (3) If symmetric b.c. are used, it is not necessary to add and remove this border. (4) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (5) For clarity, if the case is known, use these patterns: (a) pixd = pixCloseSafe(NULL, pixs, ...); (b) pixCloseSafe(pixs, pixs, ...); (c) pixCloseSafe(pixd, pixs, ...); (6) The size of the result is determined by pixs.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd, or null on error
Notes: (1) Sel is a brick with all elements being hits (2) The origin is at (x, y) = (hsize/2, vsize/2) (3) Do separably if both hsize and vsize are > 1. (4) Safe closing adds a border of 0 pixels, of sufficient size so that all pixels in input image are processed within 32-bit words in the expanded image. As a result, there is no special processing for pixels near the boundary, and there are no boundary effects. The border is removed at the end. (5) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (6) For clarity, if the case is known, use these patterns: (a) pixd = pixCloseBrick(NULL, pixs, ...); (b) pixCloseBrick(pixs, pixs, ...); (c) pixCloseBrick(pixd, pixs, ...); (7) The size of the result is determined by pixs.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd, or null on error
Notes: (1) Sel is a brick with all elements being hits (2) The origin is at (x, y) = (hsize/2, vsize/2) (3) Do compositely for each dimension > 1. (4) Do separably if both hsize and vsize are > 1. (5) Safe closing adds a border of 0 pixels, of sufficient size so that all pixels in input image are processed within 32-bit words in the expanded image. As a result, there is no special processing for pixels near the boundary, and there are no boundary effects. The border is removed at the end. (6) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (7) For clarity, if the case is known, use these patterns: (a) pixd = pixCloseSafeCompBrick(NULL, pixs, ...); (b) pixCloseSafeCompBrick(pixs, pixs, ...); (c) pixCloseSafeCompBrick(pixd, pixs, ...); (8) The dimensions of the resulting image are determined by pixs. (9) CAUTION: both hsize and vsize are being decomposed. The decomposer chooses a product of sizes (call them 'terms') for each that is close to the input size, but not necessarily equal to it. It attempts to optimize: (a) for consistency with the input values: the product of terms is close to the input size (b) for efficiency of the operation: the sum of the terms is small; ideally about twice the square root of the input size. So, for example, if the input hsize = 37, which is a prime number, the decomposer will break this into two terms, 6 and 6, so that the net result is a dilation with hsize = 36.
Input: cmap color (0 for black, 1 for white) &index (<optional return>=""> index of color; can be null) Return: 0 if OK, 1 on error
Notes: (1) This only adds color if not already there. (2) This sets index to the requested color. (3) If there is no room in the colormap, returns the index of the closest color.
Input: cmap rval, gval, bval (colormap entry to be added; each number is in range [0, ... 255]) Return: 0 if OK, 1 on error
Note: always adds the color if there is room.
LEPT_DLL l_int32 pixcmapAddNearestColor | ( | PIXCMAP * | cmap, |
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval, | ||
l_int32 * | pindex | ||
) |
Input: cmap rval, gval, bval (colormap entry to be added; each number is in range [0, ... 255]) &index (<return> index of color) Return: 0 if OK, 1 on error
Notes: (1) This only adds color if not already there. (2) If it's not in the colormap and there is no room to add another color, this returns the index of the nearest color.
LEPT_DLL l_int32 pixcmapAddNewColor | ( | PIXCMAP * | cmap, |
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval, | ||
l_int32 * | pindex | ||
) |
Input: cmap rval, gval, bval (colormap entry to be added; each number is in range [0, ... 255]) &index (<return> index of color) Return: 0 if OK, 1 on error; 2 if unable to add color
Notes: (1) This only adds color if not already there. (2) This returns the index of the new (or existing) color. (3) Returns 2 with a warning if unable to add this color; the caller should check the return value.
LEPT_DLL l_int32 pixcmapClear | ( | PIXCMAP * | cmap | ) |
Input: cmap Return: 0 if OK, 1 on error
Note: this removes the colors by setting the count to 0.
LEPT_DLL PIXCMAP* pixcmapColorToGray | ( | PIXCMAP * | cmaps, |
l_float32 | rwt, | ||
l_float32 | gwt, | ||
l_float32 | bwt | ||
) |
Input: cmap rwt, gwt, bwt (non-negative; these should add to 1.0) Return: cmap (gray), or null on error
Notes: (1) This creates a gray colormap from an arbitrary colormap. (2) In use, attach the output gray colormap to the pix (or a copy of it) that provided the input colormap.
LEPT_DLL l_int32 pixcmapContrastTRC | ( | PIXCMAP * | cmap, |
l_float32 | factor | ||
) |
Input: colormap factor (generally between 0.0 (no enhancement) and 1.0, but can be larger than 1.0) Return: 0 if OK; 1 on error
Notes: (1) This is an in-place transform (2) See pixContrastTRC() and numaContrastTRC() in enhance.c for description and use of transform
LEPT_DLL l_int32 pixcmapConvertHSVToRGB | ( | PIXCMAP * | cmap | ) |
Input: colormap Return: 0 if OK; 1 on error
Notes:
LEPT_DLL l_int32 pixcmapConvertRGBToHSV | ( | PIXCMAP * | cmap | ) |
Input: colormap Return: 0 if OK; 1 on error
Notes:
LEPT_DLL l_int32 pixcmapConvertRGBToYUV | ( | PIXCMAP * | cmap | ) |
Input: colormap Return: 0 if OK; 1 on error
Notes:
LEPT_DLL char* pixcmapConvertToHex | ( | l_uint8 * | data, |
l_int32 | nbytes, | ||
l_int32 | ncolors | ||
) |
Input: data (binary serialized data) nbytes (size of data) ncolors (in colormap) Return: hexdata (bracketed, space-separated ascii hex string), or null on error.
Notes: (1) If rgb, there are 3 colors/component; if rgba, there are 4. (2) Output is in form: < r0g0b0 r1g1b1 ... rngnbn > where r0, g0, b0, ... are each 2 bytes of hex ascii (3) This is used in pdf files to express the colormap as an array in ascii (human-readable) format.
LEPT_DLL l_int32 pixcmapConvertYUVToRGB | ( | PIXCMAP * | cmap | ) |
Input: colormap Return: 0 if OK; 1 on error
Notes:
LEPT_DLL PIXCMAP* pixcmapCopy | ( | PIXCMAP * | cmaps | ) |
Input: cmaps Return: cmapd, or null on error
LEPT_DLL l_int32 pixcmapCountGrayColors | ( | PIXCMAP * | cmap, |
l_int32 * | pngray | ||
) |
Input: cmap &ngray (<return> number of gray colors) Return: 0 if OK, 1 on error
Notes: (1) This counts the unique gray colors, including black and white.
LEPT_DLL PIXCMAP* pixcmapCreate | ( | l_int32 | depth | ) |
Input: depth (bpp, of pix) Return: cmap, or null on error
LEPT_DLL PIXCMAP* pixcmapCreateLinear | ( | l_int32 | d, |
l_int32 | nlevels | ||
) |
Input: d (depth of pix for this colormap; 1, 2, 4 or 8) nlevels (valid in range [2, 2^d]) Return: cmap, or null on error
Notes: (1) Colormap has equally spaced gray color values from black (0, 0, 0) to white (255, 255, 255).
Input: depth (bpp, of pix; 2, 4 or 8) hasblack (1 if the first color is black; 0 if no black) haswhite (1 if the last color is white; 0 if no white) Return: cmap, or null on error
Notes: (1) This sets up a colormap with random colors, where the first color is optionally black, the last color is optionally white, and the remaining colors are chosen randomly. (2) The number of randomly chosen colors is: 2^(depth) - haswhite - hasblack (3) Because rand() is seeded, it might disrupt otherwise deterministic results if also used elsewhere in a program. (4) rand() is not threadsafe, and will generate garbage if run on multiple threads at once -- though garbage is generally what you want from a random number generator! (5) Modern rand()s have equal randomness in low and high order bits, but older ones don't. Here, we're just using rand() to choose colors for output.
pixcmapDeserializeFromMemory()
Input: data (binary string, 3 or 4 bytes per color) ncolors nbytes (size of returned data) Return: cmap, or null on error
LEPT_DLL void pixcmapDestroy | ( | PIXCMAP ** | pcmap | ) |
Input: &cmap (<set to="" null>="">) Return: void
LEPT_DLL l_int32 pixcmapGammaTRC | ( | PIXCMAP * | cmap, |
l_float32 | gamma, | ||
l_int32 | minval, | ||
l_int32 | maxval | ||
) |
Input: colormap gamma (gamma correction; must be > 0.0) minval (input value that gives 0 for output; can be < 0) maxval (input value that gives 255 for output; can be > 255) Return: 0 if OK; 1 on error
Notes: (1) This is an in-place transform (2) See pixGammaTRC() and numaGammaTRC() in enhance.c for description and use of transform
LEPT_DLL l_int32 pixcmapGetColor | ( | PIXCMAP * | cmap, |
l_int32 | index, | ||
l_int32 * | prval, | ||
l_int32 * | pgval, | ||
l_int32 * | pbval | ||
) |
Input: cmap index &rval, &gval, &bval (<return> each color value in l_int32) Return: 0 if OK, 1 if not accessable (caller should check)
Input: cmap index &val32 (<return> 32-bit rgba color value) Return: 0 if OK, 1 if not accessable (caller should check)
Notes: (1) The returned alpha channel value is zero, because it is not used in leptonica colormaps.
LEPT_DLL l_int32 pixcmapGetComponentRange | ( | PIXCMAP * | cmap, |
l_int32 | color, | ||
l_int32 * | pminval, | ||
l_int32 * | pmaxval | ||
) |
Input: cmap color (L_SELECT_RED, L_SELECT_GREEN or L_SELECT_BLUE) &minval (<optional return>=""> minimum value of component) &maxval (<optional return>=""> minimum value of component) Return: 0 if OK, 1 on error
Notes: (1) Returns for selected components the extreme value (either min or max) of the color component that is found in the colormap.
LEPT_DLL l_int32 pixcmapGetCount | ( | PIXCMAP * | cmap | ) |
Input: cmap Return: count, or 0 on error
LEPT_DLL l_int32 pixcmapGetDepth | ( | PIXCMAP * | cmap | ) |
Input: cmap Return: depth, or 0 on error
LEPT_DLL l_int32 pixcmapGetExtremeValue | ( | PIXCMAP * | cmap, |
l_int32 | type, | ||
l_int32 * | prval, | ||
l_int32 * | pgval, | ||
l_int32 * | pbval | ||
) |
Input: cmap type (L_SELECT_MIN or L_SELECT_MAX) &rval (<optional return>=""> red component) &gval (<optional return>=""> green component) &bval (<optional return>=""> blue component) Return: 0 if OK, 1 on error
Notes: (1) Returns for selected components the extreme value (either min or max) of the color component that is found in the colormap.
LEPT_DLL l_int32 pixcmapGetFreeCount | ( | PIXCMAP * | cmap | ) |
Input: cmap Return: free entries, or 0 on error
LEPT_DLL l_int32 pixcmapGetIndex | ( | PIXCMAP * | cmap, |
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval, | ||
l_int32 * | pindex | ||
) |
Input: cmap rval, gval, bval (colormap colors to search for; each number is in range [0, ... 255]) &index (<return>) Return: 0 if found, 1 if not found (caller must check)
LEPT_DLL l_int32 pixcmapGetMinDepth | ( | PIXCMAP * | cmap, |
l_int32 * | pmindepth | ||
) |
Input: cmap &mindepth (<return> minimum depth to support the colormap) Return: 0 if OK, 1 on error
Notes: (1) On error, &mindepth is returned as 0.
Input: cmap val (gray value to search for; in range [0, ... 255]) &index (<return> the index of the nearest color) Return: 0 if OK, 1 on error (caller must check)
Notes: (1) This should be used on gray colormaps. It uses only the green value of the colormap. (2) Returns the index of the exact color if possible, otherwise the index of the color closest to the target color.
LEPT_DLL l_int32 pixcmapGetNearestIndex | ( | PIXCMAP * | cmap, |
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval, | ||
l_int32 * | pindex | ||
) |
Input: cmap rval, gval, bval (colormap colors to search for; each number is in range [0, ... 255]) &index (<return> the index of the nearest color) Return: 0 if OK, 1 on error (caller must check)
Notes: (1) Returns the index of the exact color if possible, otherwise the index of the color closest to the target color. (2) Nearest color is that which is the least sum-of-squares distance from the target color.
Input: cmap rankval (0.0 for darkest, 1.0 for lightest color) &index (<return> the index into the colormap that corresponds to the rank intensity color) Return: 0 if OK, 1 on error
LEPT_DLL PIXCMAP* pixcmapGrayToColor | ( | l_uint32 | color | ) |
Input: color Return: cmap, or null on error
Notes: (1) This creates a colormap that maps from gray to a specific color. In the mapping, each component is faded to white, depending on the gray value. (2) In use, this is simply attached to a grayscale pix to give it the input color.
LEPT_DLL l_int32 pixcmapHasColor | ( | PIXCMAP * | cmap, |
l_int32 * | pcolor | ||
) |
Input: cmap &color (<return> TRUE if cmap has color; FALSE otherwise) Return: 0 if OK, 1 on error
LEPT_DLL PIXCMAP* pixcmapReadStream | ( | FILE * | fp | ) |
Input: stream Return: cmap, or null on error
LEPT_DLL l_int32 pixcmapResetColor | ( | PIXCMAP * | cmap, |
l_int32 | index, | ||
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval | ||
) |
Input: cmap index rval, gval, bval (colormap entry to be reset; each number is in range [0, ... 255]) Return: 0 if OK, 1 if not accessable (caller should check)
Notes: (1) This resets sets the color of an entry that has already been set and included in the count of colors.
LEPT_DLL l_int32 pixcmapSerializeToMemory | ( | PIXCMAP * | cmap, |
l_int32 | cpc, | ||
l_int32 * | pncolors, | ||
l_uint8 ** | pdata, | ||
l_int32 * | pnbytes | ||
) |
Input: colormap cpc (components/color: 3 for rgb, 4 for rgba) &ncolors (<return> number of colors in table) &data (<return> binary string, 3 or 4 bytes per color) &nbytes (<return> size of data) Return: 0 if OK; 1 on error
Notes: (1) If == 4, we leave room for the alpha channel value in each color entry, but it is set to 0.
Input: cmap setblack (0 for no operation; 1 to set darkest color to black) setwhite (0 for no operation; 1 to set lightest color to white) Return: 0 if OK, 1 on error
Input: colormap srcval (source color: 0xrrggbb00) dstval (target color: 0xrrggbb00) Return: 0 if OK; 1 on error
Notes: (1) This is an in-place transform (2) It implements pixelShiftByComponent() for each color. The mapping is specified by srcval and dstval. (3) If a component decreases, the component in the colormap decreases by the same ratio. Likewise for increasing, except all ratios are taken with respect to the distance from 255.
LEPT_DLL l_int32 pixcmapShiftIntensity | ( | PIXCMAP * | cmap, |
l_float32 | fraction | ||
) |
Input: colormap fraction (between -1.0 and +1.0) Return: 0 if OK; 1 on error
Notes: (1) This is an in-place transform (2) It does a proportional shift of the intensity for each color. (3) If fraction < 0.0, it moves all colors towards (0,0,0). This darkens the image. If fraction > 0.0, it moves all colors towards (255,255,255) This fades the image. (4) The equivalent transform can be accomplished with pixcmapGammaTRC(), but it is considerably more difficult (see numaGammaTRC()).
LEPT_DLL l_int32 pixcmapToArrays | ( | PIXCMAP * | cmap, |
l_int32 ** | prmap, | ||
l_int32 ** | pgmap, | ||
l_int32 ** | pbmap | ||
) |
Input: colormap &rmap, &gmap, &bmap (<return> colormap arrays) Return: 0 if OK; 1 on error
Input: cmap level (significant bits for each of RGB; valid in [1...6]) metric (L_MANHATTAN_DISTANCE, L_EUCLIDEAN_DISTANCE) Return: tab[2**(3 * level)]
Notes: (1) This function is used to quickly find the colormap color that is closest to any rgb color. It is used to assign rgb colors to an existing colormap. It can be very expensive to search through the entire colormap for the closest color to each pixel. Instead, we first set up this table, which is populated by the colormap index nearest to each octcube color. Then we go through the image; for each pixel, do two table lookups: first to generate the octcube index from rgb and second to use this table to read out the colormap index. (2) Do a slight modification for white and black. For level = 4, each octcube size is 16. The center of the whitest octcube is at (248, 248, 248), which is closer to 242 than 255. Consequently, any gray color between 242 and 254 will be selected, even if white (255, 255, 255) exists. This is typically not optimal, because the original color was likely white. Therefore, if white exists in the colormap, use it for any rgb color that falls into the most white octcube. Do the similar thing for black. (3) Here are the actual function calls for quantizing to a specified colormap:
Input: colormap &tab (<return> table of rgba values for the colormap) &ncolors (<optional return>=""> size of table) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 pixcmapUsableColor | ( | PIXCMAP * | cmap, |
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval, | ||
l_int32 * | pusable | ||
) |
Input: cmap rval, gval, bval (colormap entry to be added; each number is in range [0, ... 255]) usable (<return> 1 if usable; 0 if not) Return: 0 if OK, 1 on error
Notes: (1) This checks if the color already exists or if there is room to add it. It makes no change in the colormap.
LEPT_DLL l_int32 pixcmapWriteStream | ( | FILE * | fp, |
PIXCMAP * | cmap | ||
) |
Input: stream, cmap Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixColorContent | ( | PIX * | pixs, |
l_int32 | rwhite, | ||
l_int32 | gwhite, | ||
l_int32 | bwhite, | ||
l_int32 | mingray, | ||
PIX ** | ppixr, | ||
PIX ** | ppixg, | ||
PIX ** | ppixb | ||
) |
Input: pixs (32 bpp rgb or 8 bpp colormapped) rwhite, gwhite, bwhite (color value associated with white point) mingray (min gray value for which color is measured) &pixr (<optional return>=""> 8 bpp red 'content') &pixg (<optional return>=""> 8 bpp green 'content') &pixb (<optional return>=""> 8 bpp blue 'content') Return: 0 if OK, 1 on error
Notes: (1) This returns the color content in each component, which is a measure of the deviation from gray, and is defined as the difference between the component and the average of the other two components. See the discussion at the top of this file. (2) The three numbers (rwhite, gwhite and bwhite) can be thought of as the values in the image corresponding to white. They are used to compensate for an unbalanced color white point. They must either be all 0 or all non-zero. To turn this off, set them all to 0. (3) If the maximum component after white point correction, max(r,g,b), is less than mingray, all color components for that pixel are set to zero. Use mingray = 0 to turn off this filtering of dark pixels. (4) Therefore, use 0 for all four input parameters if the color magnitude is to be calculated without either white balance correction or dark filtering.
LEPT_DLL l_int32 pixColorFraction | ( | PIX * | pixs, |
l_int32 | darkthresh, | ||
l_int32 | lightthresh, | ||
l_int32 | diffthresh, | ||
l_int32 | factor, | ||
l_float32 * | ppixfract, | ||
l_float32 * | pcolorfract | ||
) |
Input: pixs (32 bpp rgb) darkthresh (threshold near black; if the lightest component is below this, the pixel is not considered in the statistics; typ. 20) lightthresh (threshold near white; if the darkest component is above this, the pixel is not considered in the statistics; typ. 244) diffthresh (thresh for the maximum difference between component value; below this the pixel is not considered to have sufficient color) factor (subsampling factor) &pixfract (<return> fraction of pixels in intermediate brightness range that were considered for color content) &colorfract (<return> fraction of pixels that meet the criterion for sufficient color; 0.0 on error) Return: 0 if OK, 1 on error
Notes: (1) This function is asking the question: to what extent does the image appear to have color? The amount of color a pixel appears to have depends on both the deviation of the individual components from their average and on the average intensity itself. For example, the color will be much more obvious with a small deviation from white than the same deviation from black. (2) Any pixel that meets these three tests is considered a colorful pixel: (a) the lightest component must equal or exceed (b) the darkest component must not exceed (c) the max difference between components must equal or exceed . (3) The dark pixels are removed from consideration because they don't appear to have color. (4) The very lightest pixels are removed because if an image has a lot of "white", the color fraction will be artificially low, even if all the other pixels are colorful. (5) If pixfract is very small, there are few pixels that are neither black nor white. If colorfract is very small, the pixels that are neither black nor white have very little color content. The product 'pixfract * colorfract' gives the fraction of pixels with significant color content. (6) One use of this function is as a preprocessing step for median cut quantization (colorquant2.c), which does a very poor job splitting the color space into rectangular volume elements when all the pixels are near the diagonal of the color cube. For octree quantization of an image with only gray values, the 2^(level) octcubes on the diagonal are the only ones that can be occupied.
LEPT_DLL l_int32 pixColorGray | ( | PIX * | pixs, |
BOX * | box, | ||
l_int32 | type, | ||
l_int32 | thresh, | ||
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval | ||
) |
Input: pixs (8 bpp gray, rgb or colormapped image) box (<optional> region in which to apply color; can be NULL) type (L_PAINT_LIGHT, L_PAINT_DARK) thresh (average value below/above which pixel is unchanged) rval, gval, bval (new color to paint) Return: 0 if OK; 1 on error
Notes: (1) This is an in-place operation; pixs is modified. If pixs is colormapped, the operation will add colors to the colormap. Otherwise, pixs will be converted to 32 bpp rgb if it is initially 8 bpp gray. (2) If type == L_PAINT_LIGHT, it colorizes non-black pixels, preserving antialiasing. If type == L_PAINT_DARK, it colorizes non-white pixels, preserving antialiasing. (3) If box is NULL, applies function to the entire image; otherwise, clips the operation to the intersection of the box and pix. (4) If colormapped, calls pixColorGrayCmap(), which applies the coloring algorithm only to pixels that are strictly gray. (5) For RGB, determines a "gray" value by averaging; then uses this value, plus the input rgb target, to generate the output pixel values. (6) thresh is only used for rgb; it is ignored for colormapped pix. If type == L_PAINT_LIGHT, use thresh = 0 if all pixels are to be colored (black pixels will be unaltered). In situations where there are a lot of black pixels, setting thresh > 0 will make the function considerably more efficient without affecting the final result. If type == L_PAINT_DARK, use thresh = 255 if all pixels are to be colored (white pixels will be unaltered). In situations where there are a lot of white pixels, setting thresh < 255 will make the function considerably more efficient without affecting the final result.
LEPT_DLL l_int32 pixColorGrayCmap | ( | PIX * | pixs, |
BOX * | box, | ||
l_int32 | type, | ||
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval | ||
) |
Input: pixs (2, 4 or 8 bpp, with colormap) box (<optional> region to set color; can be NULL) type (L_PAINT_LIGHT, L_PAINT_DARK) rval, gval, bval (target color) Return: 0 if OK, 1 on error
Notes: (1) This is an in-place operation. (2) If type == L_PAINT_LIGHT, it colorizes non-black pixels, preserving antialiasing. If type == L_PAINT_DARK, it colorizes non-white pixels, preserving antialiasing. (3) If box is NULL, applies function to the entire image; otherwise, clips the operation to the intersection of the box and pix. (4) This can also be called through pixColorGray(). (5) This increases the colormap size by the number of different gray (non-black or non-white) colors in the input colormap. If there is not enough room in the colormap for this expansion, it returns 1 (error), and the caller should check the return value. If an error is returned and the cmap is only 2 or 4 bpp, the pix can be converted to 8 bpp and this function will succeed if run again on a larger colormap. (6) Using the darkness of each original pixel in the rect, it generates a new color (based on the input rgb values). If type == L_PAINT_LIGHT, the new color is a (generally) darken-to-black version of the input rgb color, where the amount of darkening increases with the darkness of the original pixel color. If type == L_PAINT_DARK, the new color is a (generally) faded-to-white version of the input rgb color, where the amount of fading increases with the brightness of the original pixel color.
Input: pixs (8 bpp gray; 2, 4 or 8 bpp colormapped) color (32 bit rgba pixel) cmapflag (1 for result to have colormap; 0 for RGB) Return: pixd (8 bpp colormapped or 32 bpp rgb), or null on error
Notes: (1) This applies the specific color to the grayscale image. (2) If pixs already has a colormap, it is removed to gray before colorizing.
LEPT_DLL PIX* pixColorMagnitude | ( | PIX * | pixs, |
l_int32 | rwhite, | ||
l_int32 | gwhite, | ||
l_int32 | bwhite, | ||
l_int32 | type | ||
) |
Input: pixs (32 bpp rgb or 8 bpp colormapped) rwhite, gwhite, bwhite (color value associated with white point) type (chooses the method for calculating the color magnitude: L_MAX_DIFF_FROM_AVERAGE_2, L_MAX_MIN_DIFF_FROM_2, L_MAX_DIFF) Return: pixd (8 bpp, amount of color in each source pixel), or NULL on error
Notes: (1) For an RGB image, a gray pixel is one where all three components are equal. We define the amount of color in an RGB pixel by considering the absolute value of the differences between the three color components. Consider the two largest of these differences. The pixel component in common to these two differences is the color farthest from the other two. The color magnitude in an RGB pixel can be taken as: * the average of these two differences; i.e., the average distance from the two components that are nearest to each other to the third component, or * the minimum value of these two differences; i.e., the maximum over all components of the minimum distance from that component to the other two components. Even more simply, the color magnitude can be taken as * the maximum difference between component values (2) As an example, suppose that R and G are the closest in magnitude. Then the color is determined as: * the average distance of B from these two; namely, (|B - R| + |B - G|) / 2, which can also be found from |B - (R + G) / 2|, or * the minimum distance of B from these two; namely, min(|B - R|, |B - G|). * the max(|B - R|, |B - G|) (3) The three numbers (rwhite, gwhite and bwhite) can be thought of as the values in the image corresponding to white. They are used to compensate for an unbalanced color white point. They must either be all 0 or all non-zero. To turn this off, set them all to 0. (4) We allow the following methods for choosing the color magnitude from the three components: * L_MAX_DIFF_FROM_AVERAGE_2 * L_MAX_MIN_DIFF_FROM_2 * L_MAX_DIFF These are described above in (1) and (2), as well as at the top of this file.
Input: pixs type (L_MORPH_DILATE, L_MORPH_ERODE, L_MORPH_OPEN, or L_MORPH_CLOSE) hsize (of Sel; must be odd; origin implicitly in center) vsize (ditto) Return: pixd
Notes: (1) This does the morph operation on each component separately, and recombines the result. (2) Sel is a brick with all elements being hits. (3) If hsize = vsize = 1, just returns a copy.
LEPT_DLL PIX* pixColorMorphSequence | ( | PIX * | pixs, |
const char * | sequence, | ||
l_int32 | dispsep, | ||
l_int32 | dispy | ||
) |
Input: pixs sequence (string specifying sequence) dispsep (controls debug display of each result in the sequence: 0: no output > 0: gives horizontal separation in pixels between successive displays < 0: pdf output; abs(dispsep) is used for naming) dispy (if dispsep > 0, this gives the y-value of the UL corner for display; otherwise it is ignored) Return: pixd, or null on error
Notes: (1) This works on 32 bpp rgb images. (2) Each component is processed separately. (3) This runs a pipeline of operations; no branching is allowed. (4) This only uses brick SELs. (5) A new image is always produced; the input image is not changed. (6) This contains an interpreter, allowing sequences to be generated and run. (7) Sel sizes (width, height) must each be odd numbers. (8) The format of the sequence string is defined below. (9) Intermediate results can optionally be displayed. (10) The sequence string is formatted as follows:
LEPT_DLL PIX* pixColorSegment | ( | PIX * | pixs, |
l_int32 | maxdist, | ||
l_int32 | maxcolors, | ||
l_int32 | selsize, | ||
l_int32 | finalcolors | ||
) |
Input: pixs (32 bpp; 24-bit color) maxdist (max euclidean dist to existing cluster) maxcolors (max number of colors allowed in first pass) selsize (linear size of sel for closing to remove noise) finalcolors (max number of final colors allowed after 4th pass) Return: pixd (8 bit with colormap), or null on error
Color segmentation proceeds in four phases:
Phase 1: pixColorSegmentCluster() The image is traversed in raster order. Each pixel either becomes the representative for a new cluster or is assigned to an existing cluster. Assignment is greedy. The data is stored in a colormapped image. Three auxiliary arrays are used to hold the colors of the representative pixels, for fast lookup. The average color in each cluster is computed.
Phase 2. pixAssignToNearestColor() A second (non-greedy) clustering pass is performed, where each pixel is assigned to the nearest cluster (average). We also keep track of how many pixels are assigned to each cluster.
Phase 3. pixColorSegmentClean() For each cluster, starting with the largest, do a morphological closing to eliminate small components within larger ones.
Phase 4. pixColorSegmentRemoveColors() Eliminate all colors except the most populated 'finalcolors'. Then remove unused colors from the colormap, and reassign those pixels to the nearest remaining cluster, using the original pixel values.
Notes: (1) The goal is to generate a small number of colors. Typically this would be specified by 'finalcolors', a number that would be somewhere between 3 and 6. The parameter 'maxcolors' specifies the maximum number of colors generated in the first phase. This should be larger than finalcolors, perhaps twice as large. If more than 'maxcolors' are generated in the first phase using the input 'maxdist', the distance is repeatedly increased by a multiplicative factor until the condition is satisfied. The implicit relation between 'maxdist' and 'maxcolors' is thus adjusted programmatically. (2) As a very rough guideline, given a target value of 'finalcolors', here are approximate values of 'maxdist' and 'maxcolors' to start with:
finalcolors maxcolors maxdist ----------- --------- ------- 3 6 100 4 8 90 5 10 75 6 12 60
For a given number of finalcolors, if you use too many maxcolors, the result will be noisy. If you use too few, the result will be a relatively poor assignment of colors.
Input: pixs (8 bpp, colormapped) selsize (for closing) countarray (ptr to array containing the number of pixels found in each color in the colormap) Return: 0 if OK, 1 on error
Notes: (1) This operation is in-place. (2) This is phase 3 of color segmentation. It is the first part of a two-step noise removal process. Colors with a large population are closed first; this operation absorbs small sets of intercolated pixels of a different color.
Input: pixs (32 bpp; 24-bit color) maxdist (max euclidean dist to existing cluster) maxcolors (max number of colors allowed in first pass) Return: pixd (8 bit with colormap), or null on error
Notes: (1) This is phase 1. See description in pixColorSegment(). (2) Greedy unsupervised classification. If the limit 'maxcolors' is exceeded, the computation is repeated with a larger allowed cluster size. (3) On each successive iteration, 'maxdist' is increased by a constant factor. See comments in pixColorSegment() for a guideline on parameter selection. Note that the diagonal of the 8-bit rgb color cube is about 440, so for 'maxdist' = 440, you are guaranteed to get 1 color!
Input: pixd (8 bpp, colormapped) pixs (32 bpp rgb, with initial pixel values) finalcolors (max number of colors to retain) Return: 0 if OK, 1 on error
Notes: (1) This operation is in-place. (2) This is phase 4 of color segmentation, and the second part of the 2-step noise removal. Only 'finalcolors' different colors are retained, with colors with smaller populations being replaced by the nearest color of the remaining colors. For highest accuracy, for pixels that are being replaced, we find the nearest colormap color to the original rgb color.
LEPT_DLL l_int32 pixColorsForQuantization | ( | PIX * | pixs, |
l_int32 | thresh, | ||
l_int32 * | pncolors, | ||
l_int32 * | piscolor, | ||
l_int32 | debug | ||
) |
pixColorsForQuantization() Input: pixs (8 bpp gray or 32 bpp rgb; with or without colormap) thresh (binary threshold on edge gradient; 0 for default) &ncolors (<return> the number of colors found) &iscolor (<optional return>=""> 1 if significant color is found; 0 otherwise. If pixs is 8 bpp, and does not have a colormap with color entries, this is 0) debug (1 to output masked image that is tested for colors; 0 otherwise) Return: 0 if OK, 1 on error.
Notes: (1) This function finds a measure of the number of colors that are found in low-gradient regions of an image. By its magnitude relative to some threshold (not specified in this function), it gives a good indication of whether quantization will generate posterization. This number is larger for images with regions of slowly varying intensity (if 8 bpp) or color (if rgb). Such images, if quantized, may require dithering to avoid posterization, and lossless compression is then expected to be poor. (2) If pixs has a colormap, the number of colors returned is the number in the colormap. (3) It is recommended that document images be reduced to a width of 800 pixels before applying this function. Then it can be expected that color detection will be fairly accurate and the number of colors will reflect both the content and the type of compression to be used. For less than 15 colors, there is unlikely to be a halftone image, and lossless quantization should give both a good visual result and better compression. (4) When using the default threshold on the gradient (15), images (both gray and rgb) where ncolors is greater than about 15 will compress poorly with either lossless compression or dithered quantization, and they may be posterized with non-dithered quantization. (5) For grayscale images, or images without significant color, this returns the number of significant gray levels in the low-gradient regions. The actual number of gray levels can be large due to jpeg compression noise in the background. (6) Similarly, for color images, the actual number of different (r,g,b) colors in the low-gradient regions (rather than the number of occupied level 4 octcubes) can be quite large, e.g., due to jpeg compression noise, even for regions that appear to be of a single color. By quantizing to level 4 octcubes, most of these superfluous colors are removed from the counting. (7) The image is tested for color. If there is very little color, it is thresholded to gray and the number of gray levels in the low gradient regions is found. If the image has color, the number of occupied level 4 octcubes is found. (8) The number of colors in the low-gradient regions increases monotonically with the threshold on the edge gradient. (9) Background: grayscale and color quantization is often useful to achieve highly compressed images with little visible distortion. However, gray or color washes (regions of low gradient) can defeat this approach to high compression. How can one determine if an image is expected to compress well using gray or color quantization? We use the fact that * gray washes, when quantized with less than 50 intensities, have posterization (visible boundaries between regions of uniform 'color') and poor lossless compression * color washes, when quantized with level 4 octcubes, typically result in both posterization and the occupancy of many level 4 octcubes. Images can have colors either intrinsically or as jpeg compression artifacts. This function reduces but does not completely eliminate measurement of jpeg quantization noise in the white background of grayscale or color images.
LEPT_DLL l_int32 pixColumnStats | ( | PIX * | pixs, |
NUMA ** | pnamean, | ||
NUMA ** | pnamedian, | ||
NUMA ** | pnamode, | ||
NUMA ** | pnamodecount, | ||
NUMA ** | pnavar, | ||
NUMA ** | pnarootvar | ||
) |
Input: pixs (8 bpp; not cmapped) &namean (<optional return>=""> numa of mean values) &namedian (<optional return>=""> numa of median values) &namode (<optional return>=""> numa of mode intensity values) &namodecount (<optional return>=""> numa of mode counts) &navar (<optional return>=""> numa of variance) &narootvar (<optional return>=""> numa of square root of variance) Return: na (numa of requested statistic for each column), or null on error
Notes: (1) This computes numas that represent row vectors of statistics, with each of its values derived from the corresponding col of a Pix. (2) Use NULL on input to prevent computation of any of the 5 numas. (3) Other functions that compute pixel column statistics are: pixCountPixelsByColumn() pixSumPixelsByColumn() pixGetColumnStats()
Input: pixd (1 bpp, 8 bpp gray or 32 bpp rgb; no cmap) pixs (1 bpp, 8 bpp gray or 32 bpp rgb; no cmap) pixm (<optional> 1 bpp mask; no operation if NULL) Return: 0 if OK; 1 on error
Notes: (1) In-place operation; pixd is changed. (2) This sets each pixel in pixd that co-locates with an ON pixel in pixm to the corresponding value of pixs. (3) pixs and pixd must be the same depth and not colormapped. (4) All three input pix are aligned at the UL corner, and the operation is clipped to the intersection of all three images. (5) If pixm == NULL, it's a no-op. (6) Implementation: see notes in pixCombineMaskedGeneral(). For 8 bpp selective masking, you might guess that it would be faster to generate an 8 bpp version of pixm, using pixConvert1To8(pixm, 0, 255), and then use a general combine operation d = (d & ~m) | (s & m) on a word-by-word basis. Not always. The word-by-word combine takes a time that is independent of the mask data. If the mask is relatively sparse, the byte-check method is actually faster!
LEPT_DLL l_int32 pixCombineMaskedGeneral | ( | PIX * | pixd, |
PIX * | pixs, | ||
PIX * | pixm, | ||
l_int32 | x, | ||
l_int32 | y | ||
) |
Input: pixd (1 bpp, 8 bpp gray or 32 bpp rgb) pixs (1 bpp, 8 bpp gray or 32 bpp rgb) pixm (<optional> 1 bpp mask) x, y (origin of pixs and pixm relative to pixd; can be negative) Return: 0 if OK; 1 on error
Notes: (1) In-place operation; pixd is changed. (2) This is a generalized version of pixCombinedMasked(), where the source and mask can be placed at the same (arbitrary) location relative to pixd. (3) pixs and pixd must be the same depth and not colormapped. (4) The UL corners of both pixs and pixm are aligned with the point (x, y) of pixd, and the operation is clipped to the intersection of all three images. (5) If pixm == NULL, it's a no-op. (6) Implementation. There are two ways to do these. In the first, we use rasterop, ORing the part of pixs under the mask with pixd (which has been appropriately cleared there first). In the second, the mask is used one pixel at a time to selectively replace pixels of pixd with those of pixs. Here, we use rasterop for 1 bpp and pixel-wise replacement for 8 and 32 bpp. To use rasterop for 8 bpp, for example, we must first generate an 8 bpp version of the mask. The code is simple:
Pix *pixm8 = pixConvert1To8(NULL, pixm, 0, 255); Pix *pixt = pixAnd(NULL, pixs, pixm8); pixRasterop(pixd, x, y, wmin, hmin, PIX_DST & PIX_NOT(PIX_SRC), pixm8, 0, 0); pixRasterop(pixd, x, y, wmin, hmin, PIX_SRC | PIX_DST, pixt, 0, 0); pixDestroy(&pixt); pixDestroy(&pixm8);
LEPT_DLL l_int32 pixCompareBinary | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_int32 | comptype, | ||
l_float32 * | pfract, | ||
PIX ** | ppixdiff | ||
) |
Input: pix1 (1 bpp) pix2 (1 bpp) comptype (L_COMPARE_XOR, L_COMPARE_SUBTRACT) &fract (<return> fraction of pixels that are different) &pixdiff (<optional return>=""> pix of difference) Return: 0 if OK; 1 on error
Notes: (1) The two images are aligned at the UL corner, and do not need to be the same size. (2) If using L_COMPARE_SUBTRACT, pix2 is subtracted from pix1. (3) The total number of pixels is determined by pix1.
LEPT_DLL l_int32 pixCompareGray | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_int32 | comptype, | ||
l_int32 | plottype, | ||
l_int32 * | psame, | ||
l_float32 * | pdiff, | ||
l_float32 * | prmsdiff, | ||
PIX ** | ppixdiff | ||
) |
Input: pix1 (8 or 16 bpp, not cmapped) pix2 (8 or 16 bpp, not cmapped) comptype (L_COMPARE_SUBTRACT, L_COMPARE_ABS_DIFF) plottype (gplot plot output type, or 0 for no plot) &same (<optional return>=""> 1 if pixel values are identical) &diff (<optional return>=""> average difference) &rmsdiff (<optional return>=""> rms of difference) &pixdiff (<optional return>=""> pix of difference) Return: 0 if OK; 1 on error
Notes: (1) See pixCompareGrayOrRGB() for details. (2) Use pixCompareGrayOrRGB() if the input pix are colormapped.
LEPT_DLL l_int32 pixCompareGrayOrRGB | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_int32 | comptype, | ||
l_int32 | plottype, | ||
l_int32 * | psame, | ||
l_float32 * | pdiff, | ||
l_float32 * | prmsdiff, | ||
PIX ** | ppixdiff | ||
) |
Input: pix1 (8 or 16 bpp gray, 32 bpp rgb, or colormapped) pix2 (8 or 16 bpp gray, 32 bpp rgb, or colormapped) comptype (L_COMPARE_SUBTRACT, L_COMPARE_ABS_DIFF) plottype (gplot plot output type, or 0 for no plot) &same (<optional return>=""> 1 if pixel values are identical) &diff (<optional return>=""> average difference) &rmsdiff (<optional return>=""> rms of difference) &pixdiff (<optional return>=""> pix of difference) Return: 0 if OK; 1 on error
Notes: (1) The two images are aligned at the UL corner, and do not need to be the same size. If they are not the same size, the comparison will be made over overlapping pixels. (2) If there is a colormap, it is removed and the result is either gray or RGB depending on the colormap. (3) If RGB, each component is compared separately. (4) If type is L_COMPARE_ABS_DIFF, pix2 is subtracted from pix1 and the absolute value is taken. (5) If type is L_COMPARE_SUBTRACT, pix2 is subtracted from pix1 and the result is clipped to 0. (6) The plot output types are specified in gplot.h. Use 0 if no difference plot is to be made. (7) If the images are pixelwise identical, no difference plot is made, even if requested. The result (TRUE or FALSE) is optionally returned in the parameter 'same'. (8) The average difference (either subtracting or absolute value) is optionally returned in the parameter 'diff'. (9) The RMS difference is optionally returned in the parameter 'rmsdiff'. For RGB, we return the average of the RMS differences for each of the components.
Input: pix1 (8 bpp gray or 32 bpp rgb, or colormapped) pix2 (8 bpp gray or 32 bpp rgb, or colormapped) factor (subsampling factor; use 0 or 1 for no subsampling) Return: narank (numa of rank difference), or null on error
Notes: (1) This answers the question: if the pixel values in each component are compared by absolute difference, for any value of difference, what is the fraction of pixel pairs that have a difference of this magnitude or greater. For a difference of 0, the fraction is 1.0. In this sense, it is a mapping from pixel difference to rank order of difference. (2) The two images are aligned at the UL corner, and do not need to be the same size. If they are not the same size, the comparison will be made over overlapping pixels. (3) If there is a colormap, it is removed and the result is either gray or RGB depending on the colormap. (4) If RGB, pixel differences for each component are aggregated into a single histogram.
LEPT_DLL l_int32 pixCompareRGB | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_int32 | comptype, | ||
l_int32 | plottype, | ||
l_int32 * | psame, | ||
l_float32 * | pdiff, | ||
l_float32 * | prmsdiff, | ||
PIX ** | ppixdiff | ||
) |
Input: pix1 (32 bpp rgb) pix2 (32 bpp rgb) comptype (L_COMPARE_SUBTRACT, L_COMPARE_ABS_DIFF) plottype (gplot plot output type, or 0 for no plot) &same (<optional return>=""> 1 if pixel values are identical) &diff (<optional return>=""> average difference) &rmsdiff (<optional return>=""> rms of difference) &pixdiff (<optional return>=""> pix of difference) Return: 0 if OK; 1 on error
Notes: (1) See pixCompareGrayOrRGB() for details.
LEPT_DLL l_int32 pixCompareTiled | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_int32 | sx, | ||
l_int32 | sy, | ||
l_int32 | type, | ||
PIX ** | ppixdiff | ||
) |
Input: pix1 (8 bpp or 32 bpp rgb) pix2 (8 bpp 32 bpp rgb) sx, sy (tile size; must be > 1) type (L_MEAN_ABSVAL or L_ROOT_MEAN_SQUARE) &pixdiff (<return> pix of difference) Return: 0 if OK; 1 on error
Notes: (1) With L_MEAN_ABSVAL, we compute for each tile the average abs value of the pixel component difference between the two (aligned) images. With L_ROOT_MEAN_SQUARE, we compute instead the rms difference over all components. (2) The two input pix must be the same depth. Comparison is made using UL corner alignment. (3) For 32 bpp, the distance between corresponding tiles is found by averaging the measured difference over all three components of each pixel in the tile. (4) The result, pixdiff, contains one pixel for each source tile.
LEPT_DLL l_int32 pixCompareWithTranslation | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_int32 | thresh, | ||
l_int32 * | pdelx, | ||
l_int32 * | pdely, | ||
l_float32 * | pscore, | ||
l_int32 | debugflag | ||
) |
Input: pix1, pix2 (any depth; colormap OK) thresh (threshold for converting to 1 bpp) &delx (<return> x translation on pix2 to align with pix1) &dely (<return> y translation on pix2 to align with pix1) &score (<return> correlation score at best alignment) debugflag (1 for debug output; 0 for no debugging) Return: 0 if OK, 1 on error
Notes: (1) This does a coarse-to-fine search for best translational alignment of two images, measured by a scoring function that is the correlation between the fg pixels. (2) The threshold is used if the images aren't 1 bpp. (3) With debug on, you get a pdf that shows, as a grayscale image, the score as a function of shift from the initial estimate, for each of the four levels. The shift is 0 at the center of the image. (4) With debug on, you also get a pdf that shows the difference at the best alignment between the two images, at each of the four levels. The red and green pixels show locations where one image has a fg pixel and the other doesn't. The black pixels are where both images have fg pixels, and white pixels are where neither image has fg pixels.
LEPT_DLL PIXC* pixcompCreateFromFile | ( | const char * | filename, |
l_int32 | comptype | ||
) |
Input: filename comptype (IFF_DEFAULT, IFF_TIFF_G4, IFF_PNG, IFF_JFIF_JPEG) Return: pixc, or null on error
Notes: (1) Use == IFF_DEFAULT to have the compression type automatically determined. (2) If the comptype is invalid for this file, the default will be substituted.
LEPT_DLL PIXC* pixcompCreateFromPix | ( | PIX * | pix, |
l_int32 | comptype | ||
) |
Input: pix comptype (IFF_DEFAULT, IFF_TIFF_G4, IFF_PNG, IFF_JFIF_JPEG) Return: pixc, or null on error
Notes: (1) Use == IFF_DEFAULT to have the compression type automatically determined.
LEPT_DLL PIXC* pixcompCreateFromString | ( | l_uint8 * | data, |
size_t | size, | ||
l_int32 | copyflag | ||
) |
Input: data (compressed string) size (number of bytes) copyflag (L_INSERT or L_COPY) Return: pixc, or null on error
Notes: (1) This works when the compressed string is png, jpeg or tiffg4. (2) The copyflag determines if the data in the new Pixcomp is a copy of the input data.
LEPT_DLL void pixcompDestroy | ( | PIXC ** | ppixc | ) |
Input: &pixc <will be="" nulled>=""> Return: void
Notes: (1) Always nulls the input ptr.
LEPT_DLL l_int32 pixcompDetermineFormat | ( | l_int32 | comptype, |
l_int32 | d, | ||
l_int32 | cmapflag, | ||
l_int32 * | pformat | ||
) |
Input: comptype (IFF_DEFAULT, IFF_TIFF_G4, IFF_PNG, IFF_JFIF_JPEG) d (pix depth) cmapflag (1 if pix to be compressed as a colormap; 0 otherwise) &format (return IFF_TIFF, IFF_PNG or IFF_JFIF_JPEG) Return: 0 if OK; 1 on error
Notes: (1) This determines the best format for a pix, given both the request () and the image characteristics. (2) If == IFF_DEFAULT, this does not necessarily result in png encoding. Instead, it returns one of the three formats that is both valid and most likely to give best compression. (3) If the pix cannot be compressed by the input value of , this selects IFF_PNG, which can compress all pix.
Input: pixc &w, &h, &d (<optional return>="">) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixcompWriteStreamInfo | ( | FILE * | fp, |
PIXC * | pixc, | ||
const char * | text | ||
) |
Input: fp (file stream) pixc text (<optional> identifying string; can be null) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixConformsToRectangle | ( | PIX * | pixs, |
BOX * | box, | ||
l_int32 | dist, | ||
l_int32 * | pconforms | ||
) |
Input: pixs (1 bpp) box (<optional> if null, use the entire pixs) dist (max distance allowed between bounding box and nearest foreground pixel within it) &conforms (<return> 0 (false) if not conforming; 1 (true) if conforming) Return: 0 if OK, 1 on error
Notes: (1) There are several ways to test if a connected component has an essentially rectangular boundary, such as: a. Fraction of fill into the bounding box b. Max-min distance of fg pixel from periphery of bounding box c. Max depth of bg intrusions into component within bounding box The weakness of (a) is that it is highly sensitive to holes within the c.c. The weakness of (b) is that it can have arbitrarily large intrusions into the c.c. Method (c) tests the integrity of the outer boundary of the c.c., with respect to the enclosing bounding box, so we use it. (2) This tests if the connected component within the box conforms to the box at all points on the periphery within . Inside, at a distance from the box boundary that is greater than , we don't care about the pixels in the c.c. (3) We can think of the conforming condition as follows: No pixel inside a distance from the boundary can connect to the boundary through a path through the bg. To implement this, we need to do a flood fill. We can go either from inside toward the boundary, or the other direction. It's easiest to fill from the boundary, and then verify that there are no filled pixels farther than from the boundary.
Input: pixs (1 bpp) &pixa (<optional return>=""> pixa of each c.c.) connectivity (4 or 8) Return: boxa, or null on error
Notes: (1) This is the top-level call for getting bounding boxes or a pixa of the components, and it can be used instead of either pixConnCompBB() or pixConnCompPixa(), rsp.
LEPT_DLL BOXA* pixConnCompBB | ( | PIX * | pixs, |
l_int32 | connectivity | ||
) |
Input: pixs (1 bpp) connectivity (4 or 8) Return: boxa, or null on error
Notes: (1) Finds bounding boxes of 4- or 8-connected components in a binary image. (2) This works on a copy of the input pix. The c.c. are located in raster order and erased one at a time. In the process, the b.b. is computed and saved.
Input: pixs (1 bpp) &pixa (<return> pixa of each c.c.) connectivity (4 or 8) Return: boxa, or null on error
Notes: (1) This finds bounding boxes of 4- or 8-connected components in a binary image, and saves images of each c.c in a pixa array. (2) It sets up 2 temporary pix, and for each c.c. that is located in raster order, it erases the c.c. from one pix, then uses the b.b. to extract the c.c. from the two pix using an XOR, and finally erases the c.c. from the second pix. (3) A clone of the returned boxa (where all boxes in the array are clones) is inserted into the pixa. (4) If the input is valid, this always returns a boxa and a pixa. If pixs is empty, the boxa and pixa will be empty.
LEPT_DLL PIX* pixContrastNorm | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_int32 | sx, | ||
l_int32 | sy, | ||
l_int32 | mindiff, | ||
l_int32 | smoothx, | ||
l_int32 | smoothy | ||
) |
Input: pixd (<optional> 8 bpp; null or equal to pixs) pixs (8 bpp grayscale; not colormapped) sx, sy (tile dimensions) mindiff (minimum difference to accept as valid) smoothx, smoothy (half-width of convolution kernel applied to min and max arrays: use 0 for no smoothing) Return: pixd always
Notes: (1) This function adaptively attempts to expand the contrast to the full dynamic range in each tile. If the contrast in a tile is smaller than , it uses the min and max pixel values from neighboring tiles. It also can use convolution to smooth the min and max values from neighboring tiles. After all that processing, it is possible that the actual pixel values in the tile are outside the computed [min ... max] range for local contrast normalization. Such pixels are taken to be at either 0 (if below the min) or 255 (if above the max). (2) pixd can be equal to pixs (in-place operation) or null (makes a new pixd). (3) sx and sy give the tile size; they are typically at least 20. (4) mindiff is used to eliminate results for tiles where it is likely that either fg or bg is missing. A value around 50 or more is reasonable. (5) The full width and height of the convolution kernel are (2 * smoothx + 1) and (2 * smoothy + 1). Some smoothing is typically useful, and we limit the smoothing half-widths to the range from 0 to 8. (6) A linear TRC (gamma = 1.0) is applied to increase the contrast in each tile. The result can subsequently be globally corrected, by applying pixGammaTRC() with arbitrary values of gamma and the 0 and 255 points of the mapping.
Input: pixd (<optional> null or equal to pixs) pixs (8 or 32 bpp; or 2, 4 or 8 bpp with colormap) factor (0.0 is no enhancement) Return: pixd always
Notes: (1) pixd must either be null or equal to pixs. For in-place operation, set pixd == pixs: pixContrastTRC(pixs, pixs, ...); To get a new image, set pixd == null: pixd = pixContrastTRC(NULL, pixs, ...); (2) If pixs is colormapped, the colormap is transformed, either in-place or in a copy of pixs. (3) Contrast is enhanced by mapping each color component using an atan function with maximum slope at 127. Pixels below 127 are lowered in intensity and pixels above 127 are increased. (4) The useful range for the contrast factor is scaled to be in (0.0 to 1.0), but larger values can also be used. (5) If factor == 0.0, no enhancement is performed; return a copy unless in-place, in which case this is a no-op. (6) For color images that are not colormapped, the mapping is applied to each component.
Input: pixd (<optional> null or equal to pixs) pixs (8 or 32 bpp; or 2, 4 or 8 bpp with colormap) pixm (<optional> null or 1 bpp) factor (0.0 is no enhancement) Return: pixd always
Notes: (1) Same as pixContrastTRC() except mapping is optionally over a subset of pixels described by pixm. (2) Masking does not work for colormapped images. (3) See pixContrastTRC() for details on how to use the parameters.
LEPT_DLL PIX* pixConvert16To8 | ( | PIX * | pixs, |
l_int32 | whichbyte | ||
) |
Input: pixs (16 bpp) whichbyte (1 for MSB, 0 for LSB) Return: pixd (8 bpp), or null on error
Notes: (1) For each dest pixel, use either the MSB or LSB of each src pixel.
Input: pixd (<optional> 16 bpp, can be null) pixs (1 bpp) val0 (16 bit value to be used for 0s in pixs) val1 (16 bit value to be used for 1s in pixs) Return: pixd (16 bpp)
Notes: (1) If pixd is null, a new pix is made. (2) If pixd is not null, it must be of equal width and height as pixs. It is always returned.
Input: pixd (<optional> 2 bpp, can be null) pixs (1 bpp) val0 (2 bit value to be used for 0s in pixs) val1 (2 bit value to be used for 1s in pixs) Return: pixd (2 bpp)
Notes: (1) If pixd is null, a new pix is made. (2) If pixd is not null, it must be of equal width and height as pixs. It is always returned. (3) A simple unpacking might use val0 = 0 and val1 = 3. (4) If you want a colormapped pixd, use pixConvert1To2Cmap().
LEPT_DLL PIX* pixConvert1To2Cmap | ( | PIX * | pixs | ) |
Input: pixs (1 bpp) Return: pixd (2 bpp, cmapped)
Notes: (1) Input 0 is mapped to (255, 255, 255); 1 is mapped to (0, 0, 0)
Input: pixd (<optional> 32 bpp, can be null) pixs (1 bpp) val0 (32 bit value to be used for 0s in pixs) val1 (32 bit value to be used for 1s in pixs) Return: pixd (32 bpp)
Notes: (1) If pixd is null, a new pix is made. (2) If pixd is not null, it must be of equal width and height as pixs. It is always returned.
Input: pixd (<optional> 4 bpp, can be null) pixs (1 bpp) val0 (4 bit value to be used for 0s in pixs) val1 (4 bit value to be used for 1s in pixs) Return: pixd (4 bpp)
Notes: (1) If pixd is null, a new pix is made. (2) If pixd is not null, it must be of equal width and height as pixs. It is always returned. (3) A simple unpacking might use val0 = 0 and val1 = 15, or v.v. (4) If you want a colormapped pixd, use pixConvert1To4Cmap().
LEPT_DLL PIX* pixConvert1To4Cmap | ( | PIX * | pixs | ) |
Input: pixs (1 bpp) Return: pixd (4 bpp, cmapped)
Notes: (1) Input 0 is mapped to (255, 255, 255); 1 is mapped to (0, 0, 0)
Input: pixd (<optional> 8 bpp, can be null) pixs (1 bpp) val0 (8 bit value to be used for 0s in pixs) val1 (8 bit value to be used for 1s in pixs) Return: pixd (8 bpp)
Notes: (1) If pixd is null, a new pix is made. (2) If pixd is not null, it must be of equal width and height as pixs. It is always returned. (3) A simple unpacking might use val0 = 0 and val1 = 255, or v.v. (4) In a typical application where one wants to use a colormap with the dest, you can use val0 = 0, val1 = 1 to make a non-cmapped 8 bpp pix, and then make a colormap and set 0 and 1 to the desired colors. Here is an example: pixd = pixConvert1To8(NULL, pixs, 0, 1); cmap = pixCreate(8); pixcmapAddColor(cmap, 255, 255, 255); pixcmapAddColor(cmap, 0, 0, 0); pixSetColormap(pixd, cmap);
LEPT_DLL PIX* pixConvert24To32 | ( | PIX * | pixs | ) |
Input: pixs (24 bpp rgb) Return: pixd (32 bpp rgb), or null on error
Notes: (1) 24 bpp rgb pix are not supported in leptonica. The data is a byte array, with pixels in order r,g,b, and padded to 32 bit boundaries in each line. (2) Because they are conveniently generated by programs such as xpdf, we need to provide the ability to write them in png, jpeg and tiff, as well as to convert between 24 and 32 bpp in memory.
LEPT_DLL PIX* pixConvert2To8 | ( | PIX * | pixs, |
l_uint8 | val0, | ||
l_uint8 | val1, | ||
l_uint8 | val2, | ||
l_uint8 | val3, | ||
l_int32 | cmapflag | ||
) |
Input: pixs (2 bpp) val0 (8 bit value to be used for 00 in pixs) val1 (8 bit value to be used for 01 in pixs) val2 (8 bit value to be used for 10 in pixs) val3 (8 bit value to be used for 11 in pixs) cmapflag (TRUE if pixd is to have a colormap; FALSE otherwise) Return: pixd (8 bpp), or null on error
Notes:
LEPT_DLL PIX* pixConvert32To24 | ( | PIX * | pixs | ) |
Input: pixs (32 bpp rgb) Return: pixd (24 bpp rgb), or null on error
Notes: (1) 24 bpp rgb pix are not supported in leptonica. The data is a byte array, with pixels in order r,g,b, and padded to 32 bit boundaries in each line. (2) This function is put here for completeness, and so that we can generate 24 bpp for testing. The test has two parts: (a) convert the 24 bpp pix back to 32 bpp, and test for pixel component equality (b) write the 24 bpp pix as a png and verify that it is identical to the file obtained by writing the 32 bpp pix.
LEPT_DLL PIX* pixConvert4To8 | ( | PIX * | pixs, |
l_int32 | cmapflag | ||
) |
Input: pixs (4 bpp) cmapflag (TRUE if pixd is to have a colormap; FALSE otherwise) Return: pixd (8 bpp), or null on error
Notes:
LEPT_DLL PIX* pixConvert8To16 | ( | PIX * | pixs, |
l_int32 | leftshift | ||
) |
Input: pixs (8 bpp; colormap removed to gray) leftshift (number of bits: 0 is no shift; 8 replicates in MSB and LSB of dest) Return: pixd (16 bpp), or null on error
Notes: (1) For left shift of 8, the 8 bit value is replicated in both the MSB and the LSB of the pixels in pixd. That way, we get proportional mapping, with a correct map from 8 bpp white (0xff) to 16 bpp white (0xffff).
LEPT_DLL PIX* pixConvert8To32 | ( | PIX * | pixs | ) |
Input: pix (8 bpp) Return: 32 bpp rgb pix, or null on error
Notes: (1) If there is no colormap, replicates the gray value into the 3 MSB of the dest pixel. (2) Implicit assumption about RGB component ordering.
LEPT_DLL PIX* pixConvertColorToSubpixelRGB | ( | PIX * | pixs, |
l_float32 | scalex, | ||
l_float32 | scaley, | ||
l_int32 | order | ||
) |
pixConvertColorToSubpixelRGB()
Input: pixs (32 bpp or colormapped) scalex, scaley order (of subpixel rgb color components in composition of pixd: L_SUBPIXEL_ORDER_RGB, L_SUBPIXEL_ORDER_BGR, L_SUBPIXEL_ORDER_VRGB, L_SUBPIXEL_ORDER_VBGR)
Return: pixd (32 bpp), or null on error
Notes: (1) If pixs has a colormap, it is removed to 32 bpp rgb. If the colormap has no color, pixConvertGrayToSubpixelRGB() should be called instead, because it will give the same result more efficiently. The function pixConvertToSubpixelRGB() will do the best thing for all cases. (2) For horizontal subpixel splitting, the input rgb image is rescaled by vertically and by 3.0 times horizontally. Then for each horizontal triplet of pixels, the r component of the final pixel is selected from the r component of the appropriate pixel in the triplet, and likewise for g and b. Vertical subpixel splitting is handled similarly.
LEPT_DLL PIX* pixConvertForPSWrap | ( | PIX * | pixs | ) |
Input: pixs (1, 2, 4, 8, 16, 32 bpp) Return: pixd (1, 8, or 32 bpp), or null on error
Notes: (1) For wrapping in PostScript, we convert pixs to 1 bpp, 8 bpp (gray) and 32 bpp (RGB color). (2) Colormaps are removed. For pixs with colormaps, the images are converted to either 8 bpp gray or 32 bpp RGB, depending on whether the colormap has color content. (3) Images without colormaps, that are not 1 bpp or 32 bpp, are converted to 8 bpp gray.
LEPT_DLL PIX* pixConvertGrayToColormap | ( | PIX * | pixs | ) |
Input: pixs (2, 4 or 8 bpp grayscale) Return: pixd (2, 4 or 8 bpp with colormap), or null on error
Notes: (1) This is a simple interface for adding a colormap to a 2, 4 or 8 bpp grayscale image without causing any quantization. There is some similarity to operations in grayquant.c, such as pixThresholdOn8bpp(), where the emphasis is on quantization with an arbitrary number of levels, and a colormap is an option. (2) Returns a copy if pixs already has a colormap. (3) For 8 bpp src, this is a lossless transformation. (4) For 2 and 4 bpp src, this generates a colormap that assumes full coverage of the gray space, with equally spaced levels: 4 levels for d = 2 and 16 levels for d = 4. (5) In all cases, the depth of the dest is the same as the src.
LEPT_DLL PIX* pixConvertGrayToColormap8 | ( | PIX * | pixs, |
l_int32 | mindepth | ||
) |
Input: pixs (8 bpp grayscale) mindepth (of pixd; valid values are 2, 4 and 8) Return: pixd (2, 4 or 8 bpp with colormap), or null on error
Notes: (1) Returns a copy if pixs already has a colormap. (2) This is a lossless transformation; there is no quantization. We compute the number of different gray values in pixs, and construct a colormap that has exactly these values. (3) 'mindepth' is the minimum depth of pixd. If mindepth == 8, pixd will always be 8 bpp. Let the number of different gray values in pixs be ngray. If mindepth == 4, we attempt to save pixd as a 4 bpp image, but if ngray > 16, pixd must be 8 bpp. Likewise, if mindepth == 2, the depth of pixd will be 2 if ngray <= 4 and 4 if ngray > 4 but <= 16.
LEPT_DLL PIX* pixConvertGrayToFalseColor | ( | PIX * | pixs, |
l_float32 | gamma | ||
) |
Input: pixs (8 or 16 bpp grayscale) gamma factor (0.0 or 1.0 for default; > 1.0 for brighter; 2.0 is quite nice) Return: pixd (8 bpp with colormap), or null on error
Notes: (1) For 8 bpp input, this simply adds a colormap to the input image. (2) For 16 bpp input, it first converts to 8 bpp and then adds the colormap. (3) The colormap is modeled after the Matlab "jet" configuration.
LEPT_DLL PIX* pixConvertGrayToSubpixelRGB | ( | PIX * | pixs, |
l_float32 | scalex, | ||
l_float32 | scaley, | ||
l_int32 | order | ||
) |
Input: pixs (8 bpp or colormapped) scalex, scaley order (of subpixel rgb color components in composition of pixd: L_SUBPIXEL_ORDER_RGB, L_SUBPIXEL_ORDER_BGR, L_SUBPIXEL_ORDER_VRGB, L_SUBPIXEL_ORDER_VBGR)
Return: pixd (32 bpp), or null on error
Notes: (1) If pixs has a colormap, it is removed to 8 bpp. (2) For horizontal subpixel splitting, the input gray image is rescaled by vertically and by 3.0 times horizontally. Then each horizontal triplet of pixels is mapped back to a single rgb pixel, with the r, g and b values being assigned from the triplet of gray values. Similar operations are used for vertical subpixel splitting. (3) This is a form of subpixel rendering that tends to give the resulting text a sharper and somewhat chromatic display. For horizontal subpixel splitting, the observable difference between =L_SUBPIXEL_ORDER_RGB and =L_SUBPIXEL_ORDER_BGR is reduced by optical diffusers in the display that make the pixel color appear to emerge from the entire pixel.
LEPT_DLL PIX* pixConvertHSVToRGB | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
Input: pixd (can be NULL; if not NULL, must == pixs) pixs Return: pixd always
Notes: (1) For pixs = pixd, this is in-place; otherwise pixd must be NULL. (2) The user takes responsibility for making sure that pixs is in our HSV space. The definition of our HSV space is given in convertRGBToHSV(). (3) The h, s and v values are stored in the same places as the r, g and b values, respectively. Here, they are explicitly placed in the 3 MS bytes in the pixel.
LEPT_DLL PIX* pixConvertLossless | ( | PIX * | pixs, |
l_int32 | d | ||
) |
Input: pixs (1, 2, 4, 8 bpp, not cmapped) d (destination depth: 2, 4 or 8) Return: pixd (2, 4 or 8 bpp), or null on error
Notes: (1) This is a lossless unpacking (depth-increasing) conversion. If ds is the depth of pixs, then
LEPT_DLL PIX* pixConvertRGBToColormap | ( | PIX * | pixs, |
l_int32 | ditherflag | ||
) |
Input: pixs (32 bpp rgb) ditherflag (1 to dither, 0 otherwise) Return: pixd (2, 4 or 8 bpp with colormap), or null on error
Notes: (1) This function has two relatively simple modes of color quantization: (a) If the image is made orthographically and has not more than 256 'colors' at the level 4 octcube leaves, it is quantized nearly exactly. The ditherflag is ignored. (b) Most natural images have more than 256 different colors; in that case we use adaptive octree quantization, with dithering if requested. (2) If there are not more than 256 occupied level 4 octcubes, the color in the colormap that represents all pixels in one of those octcubes is given by the first pixel that falls into that octcube. (3) If there are more than 256 colors, we use adaptive octree color quantization. (4) Dithering gives better visual results on images where there is a color wash (a slow variation of color), but it is about twice as slow and results in significantly larger files when losslessly compressed (e.g., into png).
Input: pix (32 bpp RGB) rwt, gwt, bwt (non-negative; these should add to 1.0, or use 0.0 for default) Return: 8 bpp pix, or null on error
Notes: (1) Use a weighted average of the RGB values.
LEPT_DLL PIX* pixConvertRGBToGrayFast | ( | PIX * | pixs | ) |
Input: pix (32 bpp RGB) Return: 8 bpp pix, or null on error
Notes: (1) This function should be used if speed of conversion is paramount, and the green channel can be used as a fair representative of the RGB intensity. It is several times faster than pixConvertRGBToGray(). (2) To combine RGB to gray conversion with subsampling, use pixScaleRGBToGrayFast() instead.
LEPT_DLL PIX* pixConvertRGBToGrayMinMax | ( | PIX * | pixs, |
l_int32 | type | ||
) |
Input: pix (32 bpp RGB) type (L_CHOOSE_MIN or L_CHOOSE_MAX) Return: 8 bpp pix, or null on error
Notes: (1) chooses among the 3 color components for each pixel (2) This is useful when looking for the maximum deviation of a component from either 0 or 255. For finding the deviation of a single component, it is more sensitive than using a weighted average.
LEPT_DLL PIX* pixConvertRGBToHSV | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
Input: pixd (can be NULL; if not NULL, must == pixs) pixs Return: pixd always
Notes: (1) For pixs = pixd, this is in-place; otherwise pixd must be NULL. (2) The definition of our HSV space is given in convertRGBToHSV(). (3) The h, s and v values are stored in the same places as the r, g and b values, respectively. Here, they are explicitly placed in the 3 MS bytes in the pixel. (4) Normalizing to 1 and considering the r,g,b components, a simple way to understand the HSV space is:
LEPT_DLL PIX* pixConvertRGBToHue | ( | PIX * | pixs | ) |
Input: pixs (32 bpp RGB or 8 bpp with colormap) Return: pixd (8 bpp hue of HSV), or null on error
Notes: (1) The conversion to HSV hue is in-lined here. (2) If there is a colormap, it is removed. (3) If you just want the hue component, this does it at about 10 Mpixels/sec/GHz, which is about 2x faster than using pixConvertRGBToHSV()
LEPT_DLL PIX* pixConvertRGBToLuminance | ( | PIX * | pixs | ) |
Input: pix (32 bpp RGB) Return: 8 bpp pix, or null on error
Notes: (1) Use a standard luminance conversion.
LEPT_DLL PIX* pixConvertRGBToSaturation | ( | PIX * | pixs | ) |
Input: pixs (32 bpp RGB or 8 bpp with colormap) Return: pixd (8 bpp sat of HSV), or null on error
Notes: (1) The conversion to HSV sat is in-lined here. (2) If there is a colormap, it is removed. (3) If you just want the saturation component, this does it at about 12 Mpixels/sec/GHz.
LEPT_DLL PIX* pixConvertRGBToValue | ( | PIX * | pixs | ) |
Input: pixs (32 bpp RGB or 8 bpp with colormap) Return: pixd (8 bpp max component intensity of HSV), or null on error
Notes: (1) The conversion to HSV sat is in-lined here. (2) If there is a colormap, it is removed. (3) If you just want the value component, this does it at about 35 Mpixels/sec/GHz.
LEPT_DLL PIX* pixConvertRGBToYUV | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
Input: pixd (can be NULL; if not NULL, must == pixs) pixs Return: pixd always
Notes: (1) For pixs = pixd, this is in-place; otherwise pixd must be NULL. (2) The Y, U and V values are stored in the same places as the r, g and b values, respectively. Here, they are explicitly placed in the 3 MS bytes in the pixel. (3) Normalizing to 1 and considering the r,g,b components, a simple way to understand the YUV space is:
LEPT_DLL PIX* pixConvertTo1 | ( | PIX * | pixs, |
l_int32 | threshold | ||
) |
Input: pixs (1, 2, 4, 8, 16 or 32 bpp) threshold (for final binarization, relative to 8 bpp) Return: pixd (1 bpp), or null on error
Notes: (1) This is a top-level function, with simple default values used in pixConvertTo8() if unpacking is necessary. (2) Any existing colormap is removed. (3) If the input image has 1 bpp and no colormap, the operation is lossless and a copy is returned.
LEPT_DLL PIX* pixConvertTo16 | ( | PIX * | pixs | ) |
Input: pixs (1, 8 bpp) Return: pixd (16 bpp), or null on error
Usage: Top-level function, with simple default values for unpacking. 1 bpp: val0 = 0xffff, val1 = 0 8 bpp: replicates the 8 bit value in both the MSB and LSB of the 16 bit pixel.
Input: pixs (1, 2, 4, 8, 16 or 32 bpp) factor (submsampling factor; integer >= 1) threshold (for final binarization, relative to 8 bpp) Return: pixd (1 bpp), or null on error
Notes: (1) This is a fast, quick/dirty, top-level converter. (2) See pixConvertTo1() for default values.
LEPT_DLL PIX* pixConvertTo32 | ( | PIX * | pixs | ) |
Input: pixs (1, 2, 4, 8, 16 or 32 bpp) Return: pixd (32 bpp), or null on error
Usage: Top-level function, with simple default values for unpacking. 1 bpp: val0 = 255, val1 = 0 and then replication into R, G and B components 2 bpp: if colormapped, use the colormap values; otherwise, use val0 = 0, val1 = 0x55, val2 = 0xaa, val3 = 255 and replicate gray into R, G and B components 4 bpp: if colormapped, use the colormap values; otherwise, replicate 2 nybs into a byte, and then into R,G,B components 8 bpp: if colormapped, use the colormap values; otherwise, replicate gray values into R, G and B components 16 bpp: replicate MSB into R, G and B components 24 bpp: unpack the pixels, maintaining word alignment on each scanline 32 bpp: makes a copy
Notes: (1) Implicit assumption about RGB component ordering.
LEPT_DLL PIX* pixConvertTo32BySampling | ( | PIX * | pixs, |
l_int32 | factor | ||
) |
Input: pixs (1, 2, 4, 8, 16 or 32 bpp) factor (submsampling factor; integer >= 1) Return: pixd (32 bpp), or null on error
Notes: (1) This is a fast, quick/dirty, top-level converter. (2) See pixConvertTo32() for default values.
LEPT_DLL PIX* pixConvertTo8 | ( | PIX * | pixs, |
l_int32 | cmapflag | ||
) |
Input: pixs (1, 2, 4, 8, 16 or 32 bpp) cmapflag (TRUE if pixd is to have a colormap; FALSE otherwise) Return: pixd (8 bpp), or null on error
Notes: (1) This is a top-level function, with simple default values for unpacking. (2) The result, pixd, is made with a colormap if specified. (3) If d == 8, and cmapflag matches the existence of a cmap in pixs, the operation is lossless and it returns a copy. (4) The default values used are:
Input: pixs (1, 2, 4, 8, 16 or 32 bpp) factor (submsampling factor; integer >= 1) cmapflag (TRUE if pixd is to have a colormap; FALSE otherwise) Return: pixd (8 bpp), or null on error
Notes: (1) This is a fast, quick/dirty, top-level converter. (2) See pixConvertTo8() for default values.
Input: pixs (1, 2, 4, 8, 16, with or without colormap; or 32 bpp rgb) copyflag (use 0 to return clone if pixs does not need to be changed; 1 to return a copy in those situations) warnflag (1 to issue warning if colormap is removed; else 0) Return: pixd (8 bpp grayscale or 32 bpp rgb), or null on error
Notes: (1) If there is a colormap, the colormap is removed to 8 or 32 bpp, depending on whether the colors in the colormap are all gray. (2) If the input is either rgb or 8 bpp without a colormap, this returns either a clone or a copy, depending on . (3) Otherwise, the pix is converted to 8 bpp grayscale. In all cases, pixd does not have a colormap.
LEPT_DLL DPIX* pixConvertToDPix | ( | PIX * | pixs, |
l_int32 | ncomps | ||
) |
Input: pix (1, 2, 4, 8, 16 or 32 bpp) ncomps (number of components: 3 for RGB, 1 otherwise) Return: dpix, or null on error
Notes: (1) If colormapped, remove to grayscale. (2) If 32 bpp and == 3, this is RGB; convert to luminance. In all other cases the src image is treated as having a single component of pixel values.
LEPT_DLL FPIX* pixConvertToFPix | ( | PIX * | pixs, |
l_int32 | ncomps | ||
) |
Input: pix (1, 2, 4, 8, 16 or 32 bpp) ncomps (number of components: 3 for RGB, 1 otherwise) Return: fpix, or null on error
Notes: (1) If colormapped, remove to grayscale. (2) If 32 bpp and == 3, this is RGB; convert to luminance. In all other cases the src image is treated as having a single component of pixel values.
LEPT_DLL l_int32 pixConvertToPdf | ( | PIX * | pix, |
l_int32 | type, | ||
l_int32 | quality, | ||
const char * | fileout, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | res, | ||
L_PDF_DATA ** | plpd, | ||
l_int32 | position, | ||
const char * | title | ||
) |
Input: pix type (L_G4_ENCODE, L_JPEG_ENCODE, L_FLATE_ENCODE) quality (used for JPEG only; 0 for default (75)) fileout (output pdf file; only required on last image on page) x, y (location of lower-left corner of image, in pixels, relative to the PostScript origin (0,0) at the lower-left corner of the page) res (override the resolution of the input image, in ppi; use 0 to respect the resolution embedded in the input) &lpd (ptr to lpd, which is created on the first invocation and returned until last image is processed) position (in image sequence: L_FIRST_IMAGE, L_NEXT_IMAGE, L_LAST_IMAGE) title (<optional> pdf title; taken from the first image placed on a page; e.g., an input image filename) Return: 0 if OK, 1 on error
Notes: (1) If == 0 and the input resolution field is 0, this will use DEFAULT_INPUT_RES. (2) This only writes data to fileout if it is the last image to be written on the page. (3) See comments in convertToPdf().
LEPT_DLL l_int32 pixConvertToPdfData | ( | PIX * | pix, |
l_int32 | type, | ||
l_int32 | quality, | ||
l_uint8 ** | pdata, | ||
size_t * | pnbytes, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | res, | ||
L_PDF_DATA ** | plpd, | ||
l_int32 | position, | ||
const char * | title | ||
) |
Input: pix (all depths; cmap OK) type (L_G4_ENCODE, L_JPEG_ENCODE, L_FLATE_ENCODE) quality (used for JPEG only; 0 for default (75)) &data (<return> pdf array) &nbytes (<return> number of bytes in pdf array) x, y (location of lower-left corner of image, in pixels, relative to the PostScript origin (0,0) at the lower-left corner of the page) res (override the resolution of the input image, in ppi; use 0 to respect the resolution embedded in the input) &lpd (ptr to lpd, which is created on the first invocation and returned until last image is processed) position (in image sequence: L_FIRST_IMAGE, L_NEXT_IMAGE, L_LAST_IMAGE) title (<optional> pdf title; taken from the first image placed on a page; e.g., an input image filename) Return: 0 if OK, 1 on error
Notes: (1) If == 0 and the input resolution field is 0, this will use DEFAULT_INPUT_RES. (2) This only writes if it is the last image to be written on the page. (3) See comments in convertToPdf().
LEPT_DLL l_int32 pixConvertToPdfDataSegmented | ( | PIX * | pixs, |
l_int32 | res, | ||
l_int32 | type, | ||
l_int32 | thresh, | ||
BOXA * | boxa, | ||
l_int32 | quality, | ||
l_float32 | scalefactor, | ||
l_uint8 ** | pdata, | ||
size_t * | pnbytes, | ||
const char * | title | ||
) |
pixConvertToPdfDataSegmented()
Input: pixs (any depth, cmap OK) res (input image resolution; typ. 300 ppi; use 0 for default) type (compression type for non-image regions; the image regions are always compressed with L_JPEG_ENCODE) thresh (used for converting gray --> 1 bpp with L_G4_ENCODE) boxa (<optional> of image regions; can be null) quality (used for jpeg image regions; 0 for default) scalefactor (used for jpeg regions; must be <= 1.0) &data (<return> pdf data in memory) &nbytes (<return> number of bytes in pdf data) title (<optional> pdf title; typically taken from the input file for the pix) Return: 0 if OK, 1 on error
Notes: (1) See convertToPdfSegmented() for details.
LEPT_DLL l_int32 pixConvertToPdfSegmented | ( | PIX * | pixs, |
l_int32 | res, | ||
l_int32 | type, | ||
l_int32 | thresh, | ||
BOXA * | boxa, | ||
l_int32 | quality, | ||
l_float32 | scalefactor, | ||
const char * | fileout, | ||
const char * | title | ||
) |
Input: pixs (any depth, cmap OK) res (input image resolution; typ. 300 ppi; use 0 for default) type (compression type for non-image regions; the image regions are always compressed with L_JPEG_ENCODE) thresh (used for converting gray --> 1 bpp with L_G4_ENCODE) boxa (<optional> of image regions; can be null) quality (used for jpeg image regions; 0 for default) scalefactor (used for jpeg regions; must be <= 1.0) fileout (output pdf file) title (<optional> pdf title; typically taken from the input file for the pix) Return: 0 if OK, 1 on error
Notes: (1) See convertToPdfSegmented() for details.
LEPT_DLL PIX* pixConvertToSubpixelRGB | ( | PIX * | pixs, |
l_float32 | scalex, | ||
l_float32 | scaley, | ||
l_int32 | order | ||
) |
Input: pixs (8 bpp grayscale, 32 bpp rgb, or colormapped) scalex, scaley (anisotropic scaling permitted between source and destination) order (of subpixel rgb color components in composition of pixd: L_SUBPIXEL_ORDER_RGB, L_SUBPIXEL_ORDER_BGR, L_SUBPIXEL_ORDER_VRGB, L_SUBPIXEL_ORDER_VBGR)
Return: pixd (32 bpp), or null on error
Notes: (1) If pixs has a colormap, it is removed based on its contents to either 8 bpp gray or rgb. (2) For horizontal subpixel splitting, the input image is rescaled by vertically and by 3.0 times horizontally. Then each horizontal triplet of pixels is mapped back to a single rgb pixel, with the r, g and b values being assigned based on the pixel triplet. For gray triplets, the r, g, and b values are set equal to the three gray values. For color triplets, the r, g and b values are set equal to the components from the appropriate subpixel. Vertical subpixel splitting is handled similarly. (3) See pixConvertGrayToSubpixelRGB() and pixConvertColorToSubpixelRGB() for further details.
LEPT_DLL PIX* pixConvertYUVToRGB | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
Input: pixd (can be NULL; if not NULL, must == pixs) pixs Return: pixd always
Notes: (1) For pixs = pixd, this is in-place; otherwise pixd must be NULL. (2) The user takes responsibility for making sure that pixs is in YUV space. (3) The Y, U and V values are stored in the same places as the r, g and b values, respectively. Here, they are explicitly placed in the 3 MS bytes in the pixel.
Input: pixs (8, 16, 32 bpp; no colormap) kernel outdepth (of pixd: 8, 16 or 32) normflag (1 to normalize kernel to unit sum; 0 otherwise) Return: pixd (8, 16 or 32 bpp)
Notes: (1) This gives a convolution with an arbitrary kernel. (2) The input pixs must have only one sample/pixel. To do a convolution on an RGB image, use pixConvolveRGB(). (3) The parameter determines the depth of the result. If the kernel is normalized to unit sum, the output values can never exceed 255, so an output depth of 8 bpp is sufficient. If the kernel is not normalized, it may be necessary to use 16 or 32 bpp output to avoid overflow. (4) If normflag == 1, the result is normalized by scaling all kernel values for a unit sum. Do not normalize if the kernel has null sum, such as a DoG. (5) The kernel values can be positive or negative, but the result for the convolution can only be stored as a positive number. Consequently, if it goes negative, the choices are to clip to 0 or take the absolute value. We're choosing the former for now. Another possibility would be to output a second unsigned image for the negative values. (6) This uses a mirrored border to avoid special casing on the boundaries. (7) To get a subsampled output, call l_setConvolveSampling(). The time to make a subsampled output is reduced by the product of the sampling factors. (8) The function is slow, running at about 12 machine cycles for each pixel-op in the convolution. For example, with a 3 GHz cpu, a 1 Mpixel grayscale image, and a kernel with (sx * sy) = 25 elements, the convolution takes about 100 msec.
LEPT_DLL PIX* pixConvolveRGB | ( | PIX * | pixs, |
L_KERNEL * | kel | ||
) |
Input: pixs (32 bpp rgb) kernel Return: pixd (32 bpp rgb)
Notes: (1) This gives a convolution on an RGB image using an arbitrary kernel (which we normalize to keep each component within the range [0 ... 255]. (2) The input pixs must be RGB. (3) The kernel values can be positive or negative, but the result for the convolution can only be stored as a positive number. Consequently, if it goes negative, we clip the result to 0. (4) To get a subsampled output, call l_setConvolveSampling(). The time to make a subsampled output is reduced by the product of the sampling factors. (5) This uses a mirrored border to avoid special casing on the boundaries.
Input: pixs (32 bpp rgb) kelx (x-dependent kernel) kely (y-dependent kernel) Return: pixd (32 bpp rgb)
Notes: (1) This does a convolution on an RGB image using a separable kernel that is a sequence of convolutions in x and y. The two one-dimensional kernel components must be input separately; the full kernel is the product of these components. The support for the full kernel is thus a rectangular region. (2) The kernel values can be positive or negative, but the result for the convolution can only be stored as a positive number. Consequently, if it goes negative, we clip the result to 0. (3) To get a subsampled output, call l_setConvolveSampling(). The time to make a subsampled output is reduced by the product of the sampling factors. (4) This uses a mirrored border to avoid special casing on the boundaries.
LEPT_DLL PIX* pixConvolveSep | ( | PIX * | pixs, |
L_KERNEL * | kelx, | ||
L_KERNEL * | kely, | ||
l_int32 | outdepth, | ||
l_int32 | normflag | ||
) |
Input: pixs (8, 16, 32 bpp; no colormap) kelx (x-dependent kernel) kely (y-dependent kernel) outdepth (of pixd: 8, 16 or 32) normflag (1 to normalize kernel to unit sum; 0 otherwise) Return: pixd (8, 16 or 32 bpp)
Notes: (1) This does a convolution with a separable kernel that is is a sequence of convolutions in x and y. The two one-dimensional kernel components must be input separately; the full kernel is the product of these components. The support for the full kernel is thus a rectangular region. (2) The input pixs must have only one sample/pixel. To do a convolution on an RGB image, use pixConvolveSepRGB(). (3) The parameter determines the depth of the result. If the kernel is normalized to unit sum, the output values can never exceed 255, so an output depth of 8 bpp is sufficient. If the kernel is not normalized, it may be necessary to use 16 or 32 bpp output to avoid overflow. (2) The parameter is used as in pixConvolve(). (4) The kernel values can be positive or negative, but the result for the convolution can only be stored as a positive number. Consequently, if it goes negative, the choices are to clip to 0 or take the absolute value. We're choosing the former for now. Another possibility would be to output a second unsigned image for the negative values. (5) Warning: if you use l_setConvolveSampling() to get a subsampled output, and the sampling factor is larger than the kernel half-width, it is faster to use the non-separable version pixConvolve(). This is because the first convolution here must be done on every raster line, regardless of the vertical sampling factor. If the sampling factor is smaller than kernel half-width, it's faster to use the separable convolution. (6) This uses mirrored borders to avoid special casing on the boundaries.
Input: pixd (<optional>; can be null, or equal to pixs, or different from pixs) pixs Return: pixd, or null on error
Notes: (1) There are three cases: (a) pixd == null (makes a new pix; refcount = 1) (b) pixd == pixs (no-op) (c) pixd != pixs (data copy; no change in refcount) If the refcount of pixd > 1, case (c) will side-effect these handles. (2) The general pattern of use is: pixd = pixCopy(pixd, pixs); This will work for all three cases. For clarity when the case is known, you can use: (a) pixd = pixCopy(NULL, pixs); (c) pixCopy(pixd, pixs); (3) For case (c), we check if pixs and pixd are the same size (w,h,d). If so, the data is copied directly. Otherwise, the data is reallocated to the correct size and the copy proceeds. The refcount of pixd is unchanged. (4) This operation, like all others that may involve a pre-existing pixd, will side-effect any existing clones of pixd.
LEPT_DLL PIX* pixCopyBorder | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot | ||
) |
Input: pixd (all depths; colormap ok; can be NULL) pixs (same depth and size as pixd) left, right, top, bot (number of pixels to copy) Return: pixd, or null on error if pixd is not defined
Notes: (1) pixd can be null, but otherwise it must be the same size and depth as pixs. Always returns pixd. (1) This is useful in situations where by setting a few border pixels we can avoid having to copy all pixels in pixs into pixd as an initialization step for some operation.
LEPT_DLL l_int32 pixCopyColormap | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
Input: src and dest Pix Return: 0 if OK, 1 on error
Notes: (1) This always destroys any colormap in pixd (except if the operation is a no-op.
LEPT_DLL l_int32 pixCopyDimensions | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
Input: pixd pixd Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixCopyInputFormat | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
LEPT_DLL l_int32 pixCopyResolution | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
LEPT_DLL l_int32 pixCopyText | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
Input: pix1 (1 bpp) pix2 (1 bpp) &val (<return> correlation) Return: 0 if OK; 1 on error
Notes: (1) The correlation is a number between 0.0 and 1.0, based on foreground similarity: (|1 AND 2|)**2 correlation = -------------- |1| * |2| where |x| is the count of foreground pixels in image x. If the images are identical, this is 1.0. If they have no fg pixels in common, this is 0.0. If one or both images have no fg pixels, the correlation is 0.0. (2) Typically the two images are of equal size, but this is not enforced. Instead, the UL corners are be aligned.
LEPT_DLL l_float32 pixCorrelationScore | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_int32 | area1, | ||
l_int32 | area2, | ||
l_float32 | delx, | ||
l_float32 | dely, | ||
l_int32 | maxdiffw, | ||
l_int32 | maxdiffh, | ||
l_int32 * | tab | ||
) |
Input: pix1 (test pix, 1 bpp) pix2 (exemplar pix, 1 bpp) area1 (number of on pixels in pix1) area2 (number of on pixels in pix2) delx (x comp of centroid difference) dely (y comp of centroid difference) maxdiffw (max width difference of pix1 and pix2) maxdiffh (max height difference of pix1 and pix2) tab (sum tab for byte) Return: correlation score
Note: we check first that the two pix are roughly the same size. For jbclass (jbig2) applications at roughly 300 ppi, maxdiffw and maxdiffh should be at least 2.
Only if they meet that criterion do we compare the bitmaps. The centroid difference is used to align the two images to the nearest integer for the correlation.
The correlation score is the ratio of the square of the number of pixels in the AND of the two bitmaps to the product of the number of ON pixels in each. Denote the number of ON pixels in pix1 by |1|, the number in pix2 by |2|, and the number in the AND of pix1 and pix2 by |1 & 2|. The correlation score is then (|1 & 2|)**2 / (|1|*|2|).
This score is compared with an input threshold, which can be modified depending on the weight of the template. The modified threshold is thresh + (1.0 - thresh) * weight * R where weight is a fixed input factor between 0.0 and 1.0 R = |2| / area(2) and area(2) is the total number of pixels in 2 (i.e., width x height).
To understand why a weight factor is useful, consider what happens with thick, sans-serif characters that look similar and have a value of R near 1. Different characters can have a high correlation value, and the classifier will make incorrect substitutions. The weight factor raises the threshold for these characters.
Yet another approach to reduce such substitutions is to run the classifier in a non-greedy way, matching to the template with the highest score, not the first template with a score satisfying the matching constraint. However, this is not particularly effective.
The implementation here gives the same result as in pixCorrelationScoreSimple(), where a temporary Pix is made to hold the AND and implementation uses rasterop: pixt = pixCreateTemplate(pix1); pixRasterop(pixt, idelx, idely, wt, ht, PIX_SRC, pix2, 0, 0); pixRasterop(pixt, 0, 0, wi, hi, PIX_SRC & PIX_DST, pix1, 0, 0); pixCountPixels(pixt, &count, tab); pixDestroy(&pixt); However, here it is done in a streaming fashion, counting as it goes, and touching memory exactly once, giving a 3-4x speedup over the simple implementation. This very fast correlation matcher was contributed by William Rucklidge.
LEPT_DLL l_float32 pixCorrelationScoreShifted | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_int32 | area1, | ||
l_int32 | area2, | ||
l_int32 | delx, | ||
l_int32 | dely, | ||
l_int32 * | tab | ||
) |
Input: pix1 (1 bpp) pix2 (1 bpp) area1 (number of on pixels in pix1) area2 (number of on pixels in pix2) delx (x translation of pix2 relative to pix1) dely (y translation of pix2 relative to pix1) tab (sum tab for byte) Return: correlation score
Notes: (1) This finds the correlation between two 1 bpp images, when pix2 is shifted by (delx, dely) with respect to each other. (2) This is implemented by starting with a copy of pix1 and ANDing its pixels with those of a shifted pix2. (3) Get the pixel counts for area1 and area2 using piCountPixels(). (4) A good estimate for a shift that would maximize the correlation is to align the centroids (cx1, cy1; cx2, cy2), giving the relative translations etransx and etransy: etransx = cx1 - cx2 etransy = cy1 - cy2 Typically delx is chosen to be near etransx; ditto for dely. This function is used in pixBestCorrelation(), where the translations delx and dely are varied to find the best alignment. (5) We do not check the sizes of pix1 and pix2, because they should be comparable.
LEPT_DLL l_float32 pixCorrelationScoreSimple | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_int32 | area1, | ||
l_int32 | area2, | ||
l_float32 | delx, | ||
l_float32 | dely, | ||
l_int32 | maxdiffw, | ||
l_int32 | maxdiffh, | ||
l_int32 * | tab | ||
) |
Input: pix1 (test pix, 1 bpp) pix2 (exemplar pix, 1 bpp) area1 (number of on pixels in pix1) area2 (number of on pixels in pix2) delx (x comp of centroid difference) dely (y comp of centroid difference) maxdiffw (max width difference of pix1 and pix2) maxdiffh (max height difference of pix1 and pix2) tab (sum tab for byte) Return: correlation score
Notes: (1) This calculates exactly the same value as pixCorrelationScore(). It is 2-3x slower, but much simpler to understand.
LEPT_DLL l_int32 pixCorrelationScoreThresholded | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_int32 | area1, | ||
l_int32 | area2, | ||
l_float32 | delx, | ||
l_float32 | dely, | ||
l_int32 | maxdiffw, | ||
l_int32 | maxdiffh, | ||
l_int32 * | tab, | ||
l_int32 * | downcount, | ||
l_float32 | score_threshold | ||
) |
pixCorrelationScoreThresholded()
Input: pix1 (test pix, 1 bpp) pix2 (exemplar pix, 1 bpp) area1 (number of on pixels in pix1) area2 (number of on pixels in pix2) delx (x comp of centroid difference) dely (y comp of centroid difference) maxdiffw (max width difference of pix1 and pix2) maxdiffh (max height difference of pix1 and pix2) tab (sum tab for byte) downcount (count of 1 pixels below each row of pix1) score_threshold Return: whether the correlation score is >= score_threshold
Note: we check first that the two pix are roughly the same size. Only if they meet that criterion do we compare the bitmaps. The centroid difference is used to align the two images to the nearest integer for the correlation.
The correlation score is the ratio of the square of the number of pixels in the AND of the two bitmaps to the product of the number of ON pixels in each. Denote the number of ON pixels in pix1 by |1|, the number in pix2 by |2|, and the number in the AND of pix1 and pix2 by |1 & 2|. The correlation score is then (|1 & 2|)**2 / (|1|*|2|).
This score is compared with an input threshold, which can be modified depending on the weight of the template. The modified threshold is thresh + (1.0 - thresh) * weight * R where weight is a fixed input factor between 0.0 and 1.0 R = |2| / area(2) and area(2) is the total number of pixels in 2 (i.e., width x height).
To understand why a weight factor is useful, consider what happens with thick, sans-serif characters that look similar and have a value of R near 1. Different characters can have a high correlation value, and the classifier will make incorrect substitutions. The weight factor raises the threshold for these characters.
Yet another approach to reduce such substitutions is to run the classifier in a non-greedy way, matching to the template with the highest score, not the first template with a score satisfying the matching constraint. However, this is not particularly effective.
This very fast correlation matcher was contributed by William Rucklidge.
LEPT_DLL l_int32 pixCountArbInRect | ( | PIX * | pixs, |
BOX * | box, | ||
l_int32 | val, | ||
l_int32 | factor, | ||
l_int32 * | pcount | ||
) |
Input: pixs (8 bpp, or colormapped) box (<optional>) over which count is made; use entire image null) val (pixel value to count) factor (subsampling factor; integer >= 1) &count (<return> count; estimate it if factor > 1) Return: na (histogram), or null on error
Notes: (1) If pixs is cmapped, is compared to the colormap index; otherwise, is compared to the grayscale value. (2) Set the subsampling > 1 to reduce the amount of computation. If > 1, multiply the count by * .
Input: pixs (1 bpp) connectivity (4 or 8) &count (<return> Return: 0 if OK, 1 on error
Notes: (1) This is the top-level call for getting the number of 4- or 8-connected components in a 1 bpp image. (2) It works on a copy of the input pix. The c.c. are located in raster order and erased one at a time.
Input: pix (1 bpp) &count (<return> count of ON pixels) tab8 (<optional> 8-bit pixel lookup table) Return: 0 if OK; 1 on error
LEPT_DLL NUMA* pixCountPixelsByColumn | ( | PIX * | pix | ) |
Input: pix (1 bpp) Return: na of counts in each column, or null on error
LEPT_DLL NUMA* pixCountPixelsByRow | ( | PIX * | pix, |
l_int32 * | tab8 | ||
) |
Input: pix (1 bpp) tab8 (<optional> 8-bit pixel lookup table) Return: na of counts, or null on error
Input: pix (1 bpp) row number &count (<return> sum of ON pixels in raster line) tab8 (<optional> 8-bit pixel lookup table) Return: 0 if OK; 1 on error
Input: width, height, depth Return: pixd (with data allocated and initialized to 0), or null on error
LEPT_DLL PIX* pixCreateFromPixcomp | ( | PIXC * | pixc | ) |
Input: pixc Return: pix, or null on error
Input: width, height, depth Return: pixd (with no data allocated), or null on error
Input: width, height, depth Return: pixd (with data allocated but not initialized), or null on error
Notes: (1) Must set pad bits to avoid reading unitialized data, because some optimized routines (e.g., pixConnComp()) read from pad bits.
Input: 8 bpp red pix 8 bpp green pix 8 bpp blue pix Return: 32 bpp pix, interleaved with 4 samples/pixel, or null on error
Notes: (1) the 4th byte, sometimes called the "alpha channel", and which is often used for blending between different images, is left with 0 value. (2) see Note (4) in pix.h for details on storage of 8-bit samples within each 32-bit word. (3) This implementation, setting the r, g and b components sequentially, is much faster than setting them in parallel by constructing an RGB dest pixel and writing it to dest. The reason is there are many more cache misses when reading from 3 input images simultaneously.
LEPT_DLL PIX* pixCreateTemplate | ( | PIX * | pixs | ) |
LEPT_DLL PIX* pixCreateTemplateNoInit | ( | PIX * | pixs | ) |
LEPT_DLL PIX* pixDeserializeFromMemory | ( | const l_uint32 * | data, |
size_t | nbytes | ||
) |
Input: data (serialized data in memory) nbytes (number of bytes in data string) Return: pix, or NULL on error
Notes: (1) See pixSerializeToMemory() for the binary format.
Input: pixs (any depth) redsearch (for binary search: reduction factor = 1, 2 or 4; use 0 for default) Return: pixd (deskewed pix), or null on error
Notes: (1) This binarizes if necessary and finds the skew angle. If the angle is large enough and there is sufficient confidence, it returns a deskewed image; otherwise, it returns a clone.
LEPT_DLL PIX* pixDeskewBarcode | ( | PIX * | pixs, |
PIX * | pixb, | ||
BOX * | box, | ||
l_int32 | margin, | ||
l_int32 | threshold, | ||
l_float32 * | pangle, | ||
l_float32 * | pconf | ||
) |
Input: pixs (input image; 8 bpp) pixb (binarized edge-filtered input image) box (identified region containing barcode) margin (of extra pixels around box to extract) threshold (for binarization; ~20) &angle (<optional return>=""> in degrees, clockwise is positive) &conf (<optional return>=""> confidence) Return: pixd (deskewed barcode), or null on error
Note: (1) The (optional) angle returned is the angle in degrees (cw positive) necessary to rotate the image so that it is deskewed.
LEPT_DLL PIX* pixDeskewGeneral | ( | PIX * | pixs, |
l_int32 | redsweep, | ||
l_float32 | sweeprange, | ||
l_float32 | sweepdelta, | ||
l_int32 | redsearch, | ||
l_int32 | thresh, | ||
l_float32 * | pangle, | ||
l_float32 * | pconf | ||
) |
Input: pixs (any depth) redsweep (for linear search: reduction factor = 1, 2 or 4; use 0 for default) sweeprange (in degrees in each direction from 0; use 0.0 for default) sweepdelta (in degrees; use 0.0 for default) redsearch (for binary search: reduction factor = 1, 2 or 4; use 0 for default;) thresh (for binarizing the image; use 0 for default) &angle (<optional return>=""> angle required to deskew, in degrees; use NULL to skip) &conf (<optional return>=""> conf value is ratio of max/min scores; use NULL to skip) Return: pixd (deskewed pix), or null on error
Notes: (1) This binarizes if necessary and finds the skew angle. If the angle is large enough and there is sufficient confidence, it returns a deskewed image; otherwise, it returns a clone.
LEPT_DLL PIX* pixDeskewLocal | ( | PIX * | pixs, |
l_int32 | nslices, | ||
l_int32 | redsweep, | ||
l_int32 | redsearch, | ||
l_float32 | sweeprange, | ||
l_float32 | sweepdelta, | ||
l_float32 | minbsdelta | ||
) |
Input: pixs nslices (the number of horizontal overlapping slices; must be larger than 1 and not exceed 20; use 0 for default) redsweep (sweep reduction factor: 1, 2, 4 or 8; use 0 for default value) redsearch (search reduction factor: 1, 2, 4 or 8, and not larger than redsweep; use 0 for default value) sweeprange (half the full range, assumed about 0; in degrees; use 0.0 for default value) sweepdelta (angle increment of sweep; in degrees; use 0.0 for default value) minbsdelta (min binary search increment angle; in degrees; use 0.0 for default value) Return: pixd, or null on error
Notes: (1) This function allows deskew of a page whose skew changes approximately linearly with vertical position. It uses a projective tranform that in effect does a differential shear about the LHS of the page, and makes all text lines horizontal. (2) The origin of the keystoning can be either a cheap document feeder that rotates the page as it is passed through, or a camera image taken from either the left or right side of the vertical. (3) The image transformation is a projective warping, not a rotation. Apart from this function, the text lines must be properly aligned vertically with respect to each other. This can be done by pre-processing the page; e.g., by rotating or horizontally shearing it. Typically, this can be achieved by vertically aligning the page edge.
LEPT_DLL void pixDestroy | ( | PIX ** | ppix | ) |
Input: &pix <will be="" nulled>=""> Return: void
Notes: (1) Decrements the ref count and, if 0, destroys the pix. (2) Always nulls the input ptr.
LEPT_DLL l_int32 pixDestroyColormap | ( | PIX * | pix | ) |
Input: pix Return: 0 if OK, 1 on error
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) sel Return: pixd
Notes: (1) This dilates src using hits in Sel. (2) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (3) For clarity, if the case is known, use these patterns: (a) pixd = pixDilate(NULL, pixs, ...); (b) pixDilate(pixs, pixs, ...); (c) pixDilate(pixd, pixs, ...); (4) The size of the result is determined by pixs.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
Notes: (1) Sel is a brick with all elements being hits (2) The origin is at (x, y) = (hsize/2, vsize/2) (3) Do separably if both hsize and vsize are > 1. (4) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (5) For clarity, if the case is known, use these patterns: (a) pixd = pixDilateBrick(NULL, pixs, ...); (b) pixDilateBrick(pixs, pixs, ...); (c) pixDilateBrick(pixd, pixs, ...); (6) The size of the result is determined by pixs.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
Notes: (1) These implement 2D brick Sels, using linear Sels generated with selaAddBasic(). (2) A brick Sel has hits for all elements. (3) The origin of the Sel is at (x, y) = (hsize/2, vsize/2) (4) Do separably if both hsize and vsize are > 1. (5) It is necessary that both horizontal and vertical Sels of the input size are defined in the basic sela. (6) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (7) For clarity, if the case is known, use these patterns: (a) pixd = pixDilateBrickDwa(NULL, pixs, ...); (b) pixDilateBrickDwa(pixs, pixs, ...); (c) pixDilateBrickDwa(pixd, pixs, ...); (8) The size of pixd is determined by pixs. (9) If either linear Sel is not found, this calls the appropriate decomposible function.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd, or null on error
Notes: (1) Sel is a brick with all elements being hits (2) The origin is at (x, y) = (hsize/2, vsize/2) (3) Do compositely for each dimension > 1. (4) Do separably if both hsize and vsize are > 1. (5) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (6) For clarity, if the case is known, use these patterns: (a) pixd = pixDilateCompBrick(NULL, pixs, ...); (b) pixDilateCompBrick(pixs, pixs, ...); (c) pixDilateCompBrick(pixd, pixs, ...); (7) The dimensions of the resulting image are determined by pixs. (8) CAUTION: both hsize and vsize are being decomposed. The decomposer chooses a product of sizes (call them 'terms') for each that is close to the input size, but not necessarily equal to it. It attempts to optimize: (a) for consistency with the input values: the product of terms is close to the input size (b) for efficiency of the operation: the sum of the terms is small; ideally about twice the square root of the input size. So, for example, if the input hsize = 37, which is a prime number, the decomposer will break this into two terms, 6 and 6, so that the net result is a dilation with hsize = 36.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
Notes: (1) These implement a separable composite dilation with 2D brick Sels. (2) For efficiency, it may decompose each linear morphological operation into two (brick + comb). (3) A brick Sel has hits for all elements. (4) The origin of the Sel is at (x, y) = (hsize/2, vsize/2) (5) Do separably if both hsize and vsize are > 1. (6) It is necessary that both horizontal and vertical Sels of the input size are defined in the basic sela. (7) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (8) For clarity, if the case is known, use these patterns: (a) pixd = pixDilateCompBrickDwa(NULL, pixs, ...); (b) pixDilateCompBrickDwa(pixs, pixs, ...); (c) pixDilateCompBrickDwa(pixd, pixs, ...); (9) The size of pixd is determined by pixs. (10) CAUTION: both hsize and vsize are being decomposed. The decomposer chooses a product of sizes (call them 'terms') for each that is close to the input size, but not necessarily equal to it. It attempts to optimize: (a) for consistency with the input values: the product of terms is close to the input size (b) for efficiency of the operation: the sum of the terms is small; ideally about twice the square root of the input size. So, for example, if the input hsize = 37, which is a prime number, the decomposer will break this into two terms, 6 and 6, so that the net result is a dilation with hsize = 36.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
Notes: (1) Ankur Jain suggested and implemented extending the composite DWA operations beyond the 63 pixel limit. This is a simplified and approximate implementation of the extension. This allows arbitrary Dwa morph operations using brick Sels, by decomposing the horizontal and vertical dilations into a sequence of 63-element dilations plus a dilation of size between 3 and 62. (2) The 63-element dilations are exact, whereas the extra dilation is approximate, because the underlying decomposition is in pixDilateCompBrickDwa(). See there for further details. (3) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (4) There is no need to call this directly: pixDilateCompBrickDwa() calls this function if either brick dimension exceeds 63.
Input: pixs (8 bpp, not cmapped) hsize (1 or 3) vsize (1 or 3) Return: pixd, or null on error
Notes: (1) Special case for 1x3, 3x1 or 3x3 brick sel (all hits) (2) If hsize = vsize = 1, just returns a copy.
Input: pix (1, 2, 4, 8, 16, 32 bpp) x, y (location of display frame on the screen) Return: 0 if OK; 1 on error
Notes: (1) This displays the image using xv, xli or xzgv on Unix, or i_view on Windows. The display program must be on your $PATH variable. It is chosen by setting the global var_DISPLAY_PROG, using l_chooseDisplayProg(). Default on Unix is xv. (2) Images with dimensions larger than MAX_DISPLAY_WIDTH or MAX_DISPLAY_HEIGHT are downscaled to fit those constraints. This is particulary important for displaying 1 bpp images with xv, because xv automatically downscales large images by subsampling, which looks lousy. For 1 bpp, we use scale-to-gray to get decent-looking anti-aliased images. In all cases, we write a temporary file to /tmp, that is read by the display program. (3) Note: this function uses a static internal variable to number output files written by a single process. Behavior with a shared library may be unpredictable.
LEPT_DLL PIX* pixDisplayColorArray | ( | l_uint32 * | carray, |
l_int32 | ncolors, | ||
l_int32 | side, | ||
l_int32 | ncols, | ||
l_int32 | textflag | ||
) |
Input: carray (array of colors: 0xrrggbb00) ncolors (size of array) side (size of each color square; suggest 200) ncols (number of columns in output color matrix) textflag (1 to label each square with text; 0 otherwise) Return: pixd (color array), or null on error
LEPT_DLL PIX* pixDisplayDiffBinary | ( | PIX * | pix1, |
PIX * | pix2 | ||
) |
Input: pix1 (1 bpp) pix2 (1 bpp) Return: pixd (4 bpp cmapped), or null on error
Notes: (1) This gives a color representation of the difference between pix1 and pix2. The color difference depends on the order. The pixels in pixd have 4 colors: * unchanged: black (on), white (off) * on in pix1, off in pix2: red * on in pix2, off in pix1: green (2) This aligns the UL corners of pix1 and pix2, and crops to the overlapping pixels.
LEPT_DLL PIX* pixDisplayHitMissSel | ( | PIX * | pixs, |
SEL * | sel, | ||
l_int32 | scalefactor, | ||
l_uint32 | hitcolor, | ||
l_uint32 | misscolor | ||
) |
Input: pixs (1 bpp) sel (hit-miss in general) scalefactor (an integer >= 1; use 0 for default) hitcolor (RGB0 color for center of hit pixels) misscolor (RGB0 color for center of miss pixels) Return: pixd (RGB showing both pixs and sel), or null on error Notes: (1) We don't allow scalefactor to be larger than MAX_SEL_SCALEFACTOR (2) The colors are conveniently given as 4 bytes in hex format, such as 0xff008800. The least significant byte is ignored.
LEPT_DLL PIX* pixDisplayMatchedPattern | ( | PIX * | pixs, |
PIX * | pixp, | ||
PIX * | pixe, | ||
l_int32 | x0, | ||
l_int32 | y0, | ||
l_uint32 | color, | ||
l_float32 | scale, | ||
l_int32 | nlevels | ||
) |
Input: pixs (input image, 1 bpp) pixp (pattern to be removed from image, 1 bpp) pixe (image after erosion by Sel that approximates pixp, 1 bpp) x0, y0 (center of Sel) color (to paint the matched patterns; 0xrrggbb00) scale (reduction factor for output pixd) nlevels (if scale < 1.0, threshold to this number of levels) Return: pixd (8 bpp, colormapped), or null on error
Notes: (1) A 4 bpp colormapped image is generated. (2) If scale <= 1.0, do scale to gray for the output, and threshold to nlevels of gray. (3) You can use various functions in selgen to create a Sel that will generate pixe from pixs. (4) This function is applied after pixe has been computed. It finds the centroid of each c.c., and colors the output pixels using pixp (appropriately aligned) as a stencil. Alignment is done using the origin of the Sel and the centroid of the eroded image to place the stencil pixp.
LEPT_DLL l_int32 pixDisplayMultiple | ( | const char * | filepattern | ) |
Input: filepattern Return: 0 if OK; 1 on error
Notes: (1) This allows display of multiple images using gthumb on unix and i_view32 on windows. The is a regular expression that is expanded by the shell. (2) _fullpath automatically changes '/' to '\' if necessary.
Input: pixd (can be same as pixs or null; 32 bpp if in-place) pixs (1, 2, 4, 8, 16 or 32 bpp) pta (of path to be plotted) Return: pixd (32 bpp RGB version of pixs, with path in green).
Notes: (1) To write on an existing pixs, pixs must be 32 bpp and call with pixd == pixs: pixDisplayPta(pixs, pixs, pta); To write to a new pix, use pixd == NULL and call: pixd = pixDisplayPta(NULL, pixs, pta); (2) On error, returns pixd to avoid losing pixs if called as pixs = pixDisplayPta(pixs, pixs, pta);
LEPT_DLL PIX* pixDisplayPtaa | ( | PIX * | pixs, |
PTAA * | ptaa | ||
) |
Input: pixs (1, 2, 4, 8, 16 or 32 bpp) ptaa (array of paths to be plotted) Return: pixd (32 bpp RGB version of pixs, with paths plotted in different colors), or null on error
LEPT_DLL PIX* pixDisplayPtaaPattern | ( | PIX * | pixd, |
PIX * | pixs, | ||
PTAA * | ptaa, | ||
PIX * | pixp, | ||
l_int32 | cx, | ||
l_int32 | cy | ||
) |
Input: pixd (32 bpp) pixs (1, 2, 4, 8, 16 or 32 bpp; 32 bpp if in place) ptaa (giving locations at which the pattern is displayed) pixp (1 bpp pattern to be placed such that its reference point co-locates with each point in pta) cx, cy (reference point in pattern) Return: pixd (32 bpp RGB version of pixs).
Notes: (1) To write on an existing pixs, pixs must be 32 bpp and call with pixd == pixs: pixDisplayPtaPattern(pixs, pixs, pta, ...); To write to a new pix, use pixd == NULL and call: pixd = pixDisplayPtaPattern(NULL, pixs, pta, ...); (2) Puts a random color on each pattern associated with a pta. (3) On error, returns pixd to avoid losing pixs if called as pixs = pixDisplayPtaPattern(pixs, pixs, pta, ...); (4) A typical pattern to be used is a circle, generated with generatePtaFilledCircle()
LEPT_DLL PIX* pixDisplayPtaPattern | ( | PIX * | pixd, |
PIX * | pixs, | ||
PTA * | pta, | ||
PIX * | pixp, | ||
l_int32 | cx, | ||
l_int32 | cy, | ||
l_uint32 | color | ||
) |
Input: pixd (can be same as pixs or null; 32 bpp if in-place) pixs (1, 2, 4, 8, 16 or 32 bpp) pta (giving locations at which the pattern is displayed) pixp (1 bpp pattern to be placed such that its reference point co-locates with each point in pta) cx, cy (reference point in pattern) color (in 0xrrggbb00 format) Return: pixd (32 bpp RGB version of pixs).
Notes: (1) To write on an existing pixs, pixs must be 32 bpp and call with pixd == pixs: pixDisplayPtaPattern(pixs, pixs, pta, ...); To write to a new pix, use pixd == NULL and call: pixd = pixDisplayPtaPattern(NULL, pixs, pta, ...); (2) On error, returns pixd to avoid losing pixs if called as pixs = pixDisplayPtaPattern(pixs, pixs, pta, ...); (3) A typical pattern to be used is a circle, generated with generatePtaFilledCircle()
LEPT_DLL l_int32 pixDisplayWithTitle | ( | PIX * | pixs, |
l_int32 | x, | ||
l_int32 | y, | ||
const char * | title, | ||
l_int32 | dispflag | ||
) |
Input: pix (1, 2, 4, 8, 16, 32 bpp) x, y (location of display frame) title (<optional> on frame; can be NULL); dispflag (1 to write, else disabled) Return: 0 if OK; 1 on error
Notes: (1) See notes for pixDisplay(). (2) This displays the image if dispflag == 1.
LEPT_DLL l_int32 pixDisplayWrite | ( | PIX * | pixs, |
l_int32 | reduction | ||
) |
Input: pix (1, 2, 4, 8, 16, 32 bpp) reduction (-1 to reset/erase; 0 to disable; otherwise this is a reduction factor) Return: 0 if OK; 1 on error
Notes: (1) This defaults to jpeg output for pix that are 32 bpp or 8 bpp without a colormap. If you want to write all images losslessly, use format == IFF_PNG in pixDisplayWriteFormat(). (2) See pixDisplayWriteFormat() for usage details.
Input: pix (1, 2, 4, 8, 16, 32 bpp) reduction (-1 to reset/erase; 0 to disable; otherwise this is a reduction factor) format (IFF_PNG or IFF_JFIF_JPEG) Return: 0 if OK; 1 on error
Notes: (1) This writes files if reduction > 0. These can be displayed using pixDisplayMultiple("/tmp/junk_write_display*"); (2) All previously written files can be erased by calling with reduction < 0; the value of pixs is ignored. (3) If reduction > 1 and depth == 1, this does a scale-to-gray reduction. (4) This function uses a static internal variable to number output files written by a single process. Behavior with a shared library may be unpredictable. (5) Output file format is as follows: format == IFF_JFIF_JPEG: png if d < 8 or d == 16 or if the output pix has a colormap. Otherwise, output is jpg. format == IFF_PNG: png (lossless) on all images. (6) For 16 bpp, the choice of full dynamic range with log scale is the best for displaying these images. Alternative outputs are pix8 = pixMaxDynamicRange(pixt, L_LINEAR_SCALE); pix8 = pixConvert16To8(pixt, 0); // low order byte pix8 = pixConvert16To8(pixt, 1); // high order byte
LEPT_DLL PIX* pixDistanceFunction | ( | PIX * | pixs, |
l_int32 | connectivity, | ||
l_int32 | outdepth, | ||
l_int32 | boundcond | ||
) |
Input: pixs (1 bpp source) connectivity (4 or 8) outdepth (8 or 16 bits for pixd) boundcond (L_BOUNDARY_BG, L_BOUNDARY_FG) Return: pixd, or null on error
Notes: (1) This computes the distance of each pixel from the nearest background pixel. All bg pixels therefore have a distance of 0, and the fg pixel distances increase linearly from 1 at the boundary. It can also be used to compute the distance of each pixel from the nearest fg pixel, by inverting the input image before calling this function. Then all fg pixels have a distance 0 and the bg pixel distances increase linearly from 1 at the boundary. (2) The algorithm, described in Leptonica on the page on seed filling and connected components, is due to Luc Vincent. In brief, we generate an 8 or 16 bpp image, initialized with the fg pixels of the input pix set to 1 and the 1-boundary pixels (i.e., the boundary pixels of width 1 on the four sides set as either: * L_BOUNDARY_BG: 0 * L_BOUNDARY_FG: max where max = 0xff for 8 bpp and 0xffff for 16 bpp. Then do raster/anti-raster sweeps over all pixels interior to the 1-boundary, where the value of each new pixel is taken to be 1 more than the minimum of the previously-seen connected pixels (using either 4 or 8 connectivity). Finally, set the 1-boundary pixels using the mirrored method; this removes the max values there. (3) Using L_BOUNDARY_BG clamps the distance to 0 at the boundary. Using L_BOUNDARY_FG allows the distance at the image boundary to "float". (4) For 4-connected, one could initialize only the left and top 1-boundary pixels, and go all the way to the right and bottom; then coming back reset left and top. But we instead use a method that works for both 4- and 8-connected.
LEPT_DLL PIX* pixDitherTo2bpp | ( | PIX * | pixs, |
l_int32 | cmapflag | ||
) |
Input: pixs (8 bpp) cmapflag (1 to generate a colormap) Return: pixd (dithered 2 bpp), or null on error
An analog of the Floyd-Steinberg error diffusion dithering algorithm is used to "dibitize" an 8 bpp grayscale image to 2 bpp, using equally spaced gray values of 0, 85, 170, and 255, which are served by thresholds of 43, 128 and 213. If cmapflag == 1, the colormap values are set to 0, 85, 170 and 255. If a pixel has a value between 0 and 42, it is dibitized to 0, and the excess (above 0) is added to the three neighboring pixels, in the fractions 3/8 to (i, j+1), 3/8 to (i+1, j) and 1/4 to (i+1, j+1), truncating to 255 if necessary. If a pixel has a value between 43 and 127, it is dibitized to 1, and the excess (above 85) is added to the three neighboring pixels as before. If the value is below 85, the excess is subtracted. With a value between 128 and 212, it is dibitized to 2, with the excess on either side of 170 distributed as before. Finally, with a value between 213 and 255, it is dibitized to 3, with the excess (below 255) subtracted from the neighbors. We always truncate to 0 or 255. The details can be seen in the lookup table generation.
This function differs from straight dithering in that it allows clipping of grayscale to 0 or 255 if the values are sufficiently close, without distribution of the excess. This uses default values (from pix.h) to specify the range of lower and upper values (near 0 and 255, rsp) that are clipped to black and white without propagating the excess. Not propagating the excess has the effect of reducing the snake patterns in parts of the image that are nearly black or white; however, it also prevents any attempt to reproduce gray for those values.
The implementation uses 3 lookup tables for simplicity, and a pair of line buffers to avoid modifying pixs.
LEPT_DLL PIX* pixDitherTo2bppSpec | ( | PIX * | pixs, |
l_int32 | lowerclip, | ||
l_int32 | upperclip, | ||
l_int32 | cmapflag | ||
) |
Input: pixs (8 bpp) lowerclip (lower clip distance to black; use 0 for default) upperclip (upper clip distance to white; use 0 for default) cmapflag (1 to generate a colormap) Return: pixd (dithered 2 bpp), or null on error
Notes: (1) See comments above in pixDitherTo2bpp() for details. (2) The input parameters lowerclip and upperclip specify the range of lower and upper values (near 0 and 255, rsp) that are clipped to black and white without propagating the excess. For that reason, lowerclip and upperclip should be small numbers.
LEPT_DLL PIX* pixDitherToBinary | ( | PIX * | pixs | ) |
Input: pixs Return: pixd (dithered binary), or null on error
The Floyd-Steinberg error diffusion dithering algorithm binarizes an 8 bpp grayscale image to a threshold of 128. If a pixel has a value above 127, it is binarized to white and the excess (below 255) is subtracted from three neighboring pixels in the fractions 3/8 to (i, j+1), 3/8 to (i+1, j) and 1/4 to (i+1,j+1), truncating to 0 if necessary. Likewise, if it the pixel has a value below 128, it is binarized to black and the excess above 0 is added to the neighboring pixels, truncating to 255 if necessary.
This function differs from straight dithering in that it allows clipping of grayscale to 0 or 255 if the values are sufficiently close, without distribution of the excess. This uses default values to specify the range of lower and upper values (near 0 and 255, rsp) that are clipped to black and white without propagating the excess. Not propagating the excess has the effect of reducing the snake patterns in parts of the image that are nearly black or white; however, it also prevents the attempt to reproduce gray for those values.
The implementation is straightforward. It uses a pair of line buffers to avoid changing pixs. It is about 2x faster than the implementation using LUTs.
Input: pixs lowerclip (lower clip distance to black; use -1 for default) upperclip (upper clip distance to white; use -1 for default) Return: pixd (dithered binary), or null on error
This implementation is deprecated. You should use pixDitherToBinary().
See comments in pixDitherToBinary()
This implementation additionally uses three lookup tables to generate the output pixel value and the excess or deficit carried over to the neighboring pixels.
Input: pixs lowerclip (lower clip distance to black; use 0 for default) upperclip (upper clip distance to white; use 0 for default) Return: pixd (dithered binary), or null on error
Notes: (1) See comments above in pixDitherToBinary() for details. (2) The input parameters lowerclip and upperclip specify the range of lower and upper values (near 0 and 255, rsp) that are clipped to black and white without propagating the excess. For that reason, lowerclip and upperclip should be small numbers.
Input: pixs (any depth; can be cmapped) boxa (of boxes, to draw) width (of lines) val (rgba color to draw) Return: pixd (with outlines of boxes added), or null on error
Notes: (1) If pixs is 1 bpp or is colormapped, it is converted to 8 bpp and the boxa is drawn using a colormap; otherwise, it is converted to 32 bpp rgb.
Input: pixs (any depth, can be cmapped) boxa (of boxes, to draw) width (thickness of line) Return: pixd (with box outlines drawn), or null on error
Notes: (1) If pixs is 1 bpp, we draw the boxa using a colormap; otherwise, we convert to 32 bpp. (2) We use up to 254 different colors for drawing the boxes. (3) If boxes overlap, the later ones draw over earlier ones.
LEPT_DLL l_int32 pixelFractionalShift | ( | l_int32 | rval, |
l_int32 | gval, | ||
l_int32 | bval, | ||
l_float32 | fraction, | ||
l_uint32 * | ppixel | ||
) |
Input: rval, gval, bval fraction (negative toward black; positive toward white) &ppixel (<return> rgb value) Return: 0 if OK, 1 on error
Notes: (1) This transformation leaves the hue invariant, while changing the saturation and intensity. It can be used for that purpose in pixLinearMapToTargetColor(). (2) is in the range [-1 .... +1]. If < 0, saturation is increased and brightness is reduced. The opposite results if > 0. If == -1, the resulting pixel is black; == 1 results in white.
LEPT_DLL l_int32 pixelLinearMapToTargetColor | ( | l_uint32 | scolor, |
l_uint32 | srcmap, | ||
l_uint32 | dstmap, | ||
l_uint32 * | pdcolor | ||
) |
Input: scolor (rgb source color: 0xrrggbb00) srcmap (source mapping color: 0xrrggbb00) dstmap (target mapping color: 0xrrggbb00) &pdcolor (<return> rgb dest color: 0xrrggbb00) Return: 0 if OK, 1 on error
Notes: (1) This does this does a piecewise linear mapping of each component of to , based on the relation between the components of and . It is the same transformation, performed on a single color, as mapped on every pixel in a pix by pixLinearMapToTargetColor(). (2) For each component, if the sval is larger than the smap, the dval will be pushed up from dmap towards white. Otherwise, dval will be pushed down from dmap towards black. This is because you can visualize the transformation as a linear stretching where smap moves to dmap, and everything else follows linearly with 0 and 255 fixed. (3) The mapping will in general change the hue of . However, if the and targets are related by a transformation given by pixelFractionalShift(), the hue will be invariant.
LEPT_DLL l_int32 pixelShiftByComponent | ( | l_int32 | rval, |
l_int32 | gval, | ||
l_int32 | bval, | ||
l_uint32 | srcval, | ||
l_uint32 | dstval, | ||
l_uint32 * | ppixel | ||
) |
Input: rval, gval, bval srcval (source color: 0xrrggbb00) dstval (target color: 0xrrggbb00) &ppixel (<return> rgb value) Return: 0 if OK, 1 on error
Notes: (1) This is a linear transformation that gives the same result on a single pixel as pixShiftByComponent() gives on a pix. Each component is handled separately. If the dest component is larger than the src, then the component is pushed toward 255 by the same fraction as the src --> dest shift.
LEPT_DLL PIX* pixEmbedForRotation | ( | PIX * | pixs, |
l_float32 | angle, | ||
l_int32 | incolor, | ||
l_int32 | width, | ||
l_int32 | height | ||
) |
Input: pixs (1, 2, 4, 8, 32 bpp rgb) angle (radians; clockwise is positive) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) width (original width; use 0 to avoid embedding) height (original height; use 0 to avoid embedding) Return: pixd, or null on error
Notes: (1) For very small rotations, just return a clone. (2) Generate larger image to embed pixs if necessary, and place in the center. (3) Rotation brings either white or black pixels in from outside the image. For colormapped images where there is no white or black, a new color is added if possible for these pixels; otherwise, either the lightest or darkest color is used. In most cases, the colormap will be removed prior to rotation. (4) The dest is to be expanded so that no image pixels are lost after rotation. Input of the original width and height allows the expansion to stop at the maximum required size, which is a square with side equal to sqrt(w*w + h*h). (5) For an arbitrary angle, the expansion can be found by considering the UL and UR corners. As the image is rotated, these move in an arc centered at the center of the image. Normalize to a unit circle by dividing by half the image diagonal. After a rotation of T radians, the UL and UR corners are at points T radians along the unit circle. Compute the x and y coordinates of both these points and take the max of absolute values; these represent the half width and half height of the containing rectangle. The arithmetic is done using formulas for sin(a+b) and cos(a+b), where b = T. For the UR corner, sin(a) = h/d and cos(a) = w/d. For the UL corner, replace a by (pi - a), and you have sin(pi - a) = h/d, cos(pi - a) = -w/d. The equations given below follow directly.
LEPT_DLL l_int32 pixEndianByteSwap | ( | PIX * | pixs | ) |
Input: pixs Return: 0 if OK, 1 on error
Notes: (1) This is used on little-endian platforms to swap the bytes within a word; bytes 0 and 3 are swapped, and bytes 1 and 2 are swapped. (2) This is required for little-endians in situations where we convert from a serialized byte order that is in raster order, as one typically has in file formats, to one with MSB-to-the-left in each 32-bit word, or v.v. See pix.h for a description of the canonical format (MSB-to-the left) that is used for both little-endian and big-endian platforms. For big-endians, the MSB-to-the-left word order has the bytes in raster order when serialized, so no byte flipping is required.
LEPT_DLL PIX* pixEndianByteSwapNew | ( | PIX * | pixs | ) |
Input: pixs Return: pixd, or null on error
Notes: (1) This is used to convert the data in a pix to a serialized byte buffer in raster order, and, for RGB, in order RGBA. This requires flipping bytes within each 32-bit word for little-endian platforms, because the words have a MSB-to-the-left rule, whereas byte raster-order requires the left-most byte in each word to be byte 0. For big-endians, no swap is necessary, so this returns a clone. (2) Unlike pixEndianByteSwap(), which swaps the bytes in-place, this returns a new pix (or a clone). We provide this because often when serialization is done, the source pix needs to be restored to canonical little-endian order, and this requires a second byte swap. In such a situation, it is twice as fast to make a new pix in big-endian order, use it, and destroy it.
LEPT_DLL l_int32 pixEndianTwoByteSwap | ( | PIX * | pixs | ) |
Input: pixs Return: 0 if OK, 1 on error
Notes: (1) This is used on little-endian platforms to swap the 2-byte entities within a 32-bit word. (2) This is equivalent to a full byte swap, as performed by pixEndianByteSwap(), followed by byte swaps in each of the 16-bit entities separately.
LEPT_DLL PIX* pixEndianTwoByteSwapNew | ( | PIX * | pixs | ) |
Input: pixs Return: 0 if OK, 1 on error
Notes: (1) This is used on little-endian platforms to swap the 2-byte entities within a 32-bit word. (2) This is equivalent to a full byte swap, as performed by pixEndianByteSwap(), followed by byte swaps in each of the 16-bit entities separately. (3) Unlike pixEndianTwoByteSwap(), which swaps the shorts in-place, this returns a new pix (or a clone). We provide this to avoid having to swap twice in situations where the input pix must be restored to canonical little-endian order.
Input: pix1 pix2 &same (<return> 1 if same; 0 if different) Return: 0 if OK; 1 on error
Notes: (1) Equality is defined as having the same pixel values for each respective image pixel. (2) This works on two pix of any depth. If one or both pix have a colormap, the depths can be different and the two pix can still be equal. (3) If both pix have colormaps and the depths are equal, use the pixEqualWithCmap() function, which does a fast comparison if the colormaps are identical and a relatively slow comparison otherwise. (4) In all other cases, any existing colormaps must first be removed before doing pixel comparison. After the colormaps are removed, the resulting two images must have the same depth. The "lowest common denominator" is RGB, but this is only chosen when necessary, or when both have colormaps but different depths. (5) For 32 bpp, ignore the bits in the 4th byte (the 'A' byte of the RGBA pixel) (6) For images without colormaps that are not 32 bpp, all bits in the image part of the data array must be identical.
Input: pixd (<optional> null or equal to pixs) pixs (8 bpp gray, 32 bpp rgb, or colormapped) fract (fraction of equalization movement of pixel values) factor (subsampling factor; integer >= 1) Return: pixd, or null on error
Notes: (1) pixd must either be null or equal to pixs. For in-place operation, set pixd == pixs: pixEqualizeTRC(pixs, pixs, ...); To get a new image, set pixd == null: pixd = pixEqualizeTRC(NULL, pixs, ...); (2) In histogram equalization, a tone reproduction curve mapping is used to make the number of pixels at each intensity equal. (3) If fract == 0.0, no equalization is performed; return a copy unless in-place, in which case this is a no-op. If fract == 1.0, equalization is complete. (4) Set the subsampling factor > 1 to reduce the amount of computation. (5) If pixs is colormapped, the colormap is removed and converted to rgb or grayscale. (6) If pixs has color, equalization is done in each channel separately. (7) Note that even if there is a colormap, we can get an in-place operation because the intermediate image pixt is copied back to pixs (which for in-place is the same as pixd).
Input: pix1 pix2 &same Return: 0 if OK, 1 on error
Notes: (1) This returns same = TRUE if the images have identical content. (2) Both pix must have a colormap, and be of equal size and depth. If these conditions are not satisfied, it is not an error; the returned result is same = FALSE. (3) We then check whether the colormaps are the same; if so, the comparison proceeds 32 bits at a time. (4) If the colormaps are different, the comparison is done by slow brute force.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) sel Return: pixd
Notes: (1) This erodes src using hits in Sel. (2) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (3) For clarity, if the case is known, use these patterns: (a) pixd = pixErode(NULL, pixs, ...); (b) pixErode(pixs, pixs, ...); (c) pixErode(pixd, pixs, ...); (4) The size of the result is determined by pixs.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
Notes: (1) Sel is a brick with all elements being hits (2) The origin is at (x, y) = (hsize/2, vsize/2) (3) Do separably if both hsize and vsize are > 1. (4) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (5) For clarity, if the case is known, use these patterns: (a) pixd = pixErodeBrick(NULL, pixs, ...); (b) pixErodeBrick(pixs, pixs, ...); (c) pixErodeBrick(pixd, pixs, ...); (6) The size of the result is determined by pixs.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
Notes: (1) These implement 2D brick Sels, using linear Sels generated with selaAddBasic(). (2) A brick Sel has hits for all elements. (3) The origin of the Sel is at (x, y) = (hsize/2, vsize/2) (4) Do separably if both hsize and vsize are > 1. (5) It is necessary that both horizontal and vertical Sels of the input size are defined in the basic sela. (6) Note that we must always set or clear the border pixels before each operation, depending on the the b.c. (symmetric or asymmetric). (7) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (8) For clarity, if the case is known, use these patterns: (a) pixd = pixErodeBrickDwa(NULL, pixs, ...); (b) pixErodeBrickDwa(pixs, pixs, ...); (c) pixErodeBrickDwa(pixd, pixs, ...); (9) The size of the result is determined by pixs. (10) If either linear Sel is not found, this calls the appropriate decomposible function.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd, or null on error
Notes: (1) Sel is a brick with all elements being hits (2) The origin is at (x, y) = (hsize/2, vsize/2) (3) Do compositely for each dimension > 1. (4) Do separably if both hsize and vsize are > 1. (5) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (6) For clarity, if the case is known, use these patterns: (a) pixd = pixErodeCompBrick(NULL, pixs, ...); (b) pixErodeCompBrick(pixs, pixs, ...); (c) pixErodeCompBrick(pixd, pixs, ...); (7) The dimensions of the resulting image are determined by pixs. (8) CAUTION: both hsize and vsize are being decomposed. The decomposer chooses a product of sizes (call them 'terms') for each that is close to the input size, but not necessarily equal to it. It attempts to optimize: (a) for consistency with the input values: the product of terms is close to the input size (b) for efficiency of the operation: the sum of the terms is small; ideally about twice the square root of the input size. So, for example, if the input hsize = 37, which is a prime number, the decomposer will break this into two terms, 6 and 6, so that the net result is a dilation with hsize = 36.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
Notes: (1) These implement a separable composite erosion with 2D brick Sels. (2) For efficiency, it may decompose each linear morphological operation into two (brick + comb). (3) A brick Sel has hits for all elements. (4) The origin of the Sel is at (x, y) = (hsize/2, vsize/2) (5) Do separably if both hsize and vsize are > 1. (6) It is necessary that both horizontal and vertical Sels of the input size are defined in the basic sela. (7) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (8) For clarity, if the case is known, use these patterns: (a) pixd = pixErodeCompBrickDwa(NULL, pixs, ...); (b) pixErodeCompBrickDwa(pixs, pixs, ...); (c) pixErodeCompBrickDwa(pixd, pixs, ...); (9) The size of pixd is determined by pixs. (10) CAUTION: both hsize and vsize are being decomposed. The decomposer chooses a product of sizes (call them 'terms') for each that is close to the input size, but not necessarily equal to it. It attempts to optimize: (a) for consistency with the input values: the product of terms is close to the input size (b) for efficiency of the operation: the sum of the terms is small; ideally about twice the square root of the input size. So, for example, if the input hsize = 37, which is a prime number, the decomposer will break this into two terms, 6 and 6, so that the net result is a dilation with hsize = 36.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
Notes: (1) See pixDilateCompBrickExtendDwa() for usage. (2) There is no need to call this directly: pixErodeCompBrickDwa() calls this function if either brick dimension exceeds 63.
Input: pixs (8 bpp, not cmapped) hsize (1 or 3) vsize (1 or 3) Return: pixd, or null on error
Notes: (1) Special case for 1x3, 3x1 or 3x3 brick sel (all hits) (2) If hsize = vsize = 1, just returns a copy. (3) It would be nice not to add a border, but it is required if we want the same results as from the general case. We add 4 bytes on the left to speed up the copying, and 8 bytes at the right and bottom to allow unrolling of the computation of 8 pixels.
LEPT_DLL PIX* pixExpandBinaryPower2 | ( | PIX * | pixs, |
l_int32 | factor | ||
) |
Input: pixs (1 bpp) factor (expansion factor: 1, 2, 4, 8, 16) Return: pixd (expanded 1 bpp by replication), or null on error
LEPT_DLL PIX* pixExpandBinaryReplicate | ( | PIX * | pixs, |
l_int32 | factor | ||
) |
Input: pixs (1 bpp) factor (integer scale factor for replicative expansion) Return: pixd (scaled up), or null on error
LEPT_DLL PIX* pixExpandReplicate | ( | PIX * | pixs, |
l_int32 | factor | ||
) |
Input: pixs (1, 2, 4, 8, 16, 32 bpp) factor (integer scale factor for replicative expansion) Return: pixd (scaled up), or null on error.
Input: pixs (8 bpp) addw (number of extra pixels horizontally to add) addh (number of extra pixels vertically to add) Return: pixd (extended with replicated pixel values), or null on error
Notes: (1) The pixel values are extended to the left and down, as required.
Input: pixs (input image; 8 bpp) thresh (estimated pixel threshold for crossing white <--> black; typ. ~120) debugflag (use 1 to generate debug output) Return: numa (of crossings, in pixel units), or null on error
LEPT_DLL PIXA* pixExtractBarcodes | ( | PIX * | pixs, |
l_int32 | debugflag | ||
) |
Input: pixs (8 bpp, no colormap) debugflag (use 1 to generate debug output) Return: pixa (deskewed and cropped barcodes), or null if none found or on error
LEPT_DLL NUMA* pixExtractBarcodeWidths1 | ( | PIX * | pixs, |
l_float32 | thresh, | ||
l_float32 | binfract, | ||
NUMA ** | pnaehist, | ||
NUMA ** | pnaohist, | ||
l_int32 | debugflag | ||
) |
Input: pixs (input image; 8 bpp) thresh (estimated pixel threshold for crossing white <--> black; typ. ~120) binfract (histo binsize as a fraction of minsize; e.g., 0.25) &naehist (<optional return>=""> histogram of black widths; NULL ok) &naohist (<optional return>=""> histogram of white widths; NULL ok) debugflag (use 1 to generate debug output) Return: nad (numa of barcode widths in encoded integer units), or null on error
Note: (1) The widths are alternating black/white, starting with black and ending with black. (2) This method uses the widths of the bars directly, in terms of the (float) number of pixels between transitions. The histograms of these widths for black and white bars is generated and interpreted.
LEPT_DLL NUMA* pixExtractBarcodeWidths2 | ( | PIX * | pixs, |
l_float32 | thresh, | ||
l_float32 * | pwidth, | ||
NUMA ** | pnac, | ||
l_int32 | debugflag | ||
) |
Input: pixs (input image; 8 bpp) thresh (estimated pixel threshold for crossing white <--> black; typ. ~120) &width (<optional return>=""> best decoding window width, in pixels) &nac (<optional return>=""> number of transitions in each window) debugflag (use 1 to generate debug output) Return: nad (numa of barcode widths in encoded integer units), or null on error
Notes: (1) The widths are alternating black/white, starting with black and ending with black. (2) The optional best decoding window width is the width of the window that is used to make a decision about whether a transition occurs. It is approximately the average width in pixels of the narrowest white and black bars (i.e., those corresponding to unit width). (3) The optional return signal is a sequence of 0s, 1s, and perhaps a few 2s, giving the number of crossings in each window. On the occasion where there is a '2', it is interpreted as as ending two runs: the previous one and another one that has length 1.
LEPT_DLL PIX* pixExtractBorderConnComps | ( | PIX * | pixs, |
l_int32 | connectivity | ||
) |
Input: pixs (1 bpp) filling connectivity (4 or 8) Return: pixd (all pixels in the src that are in connected components touching the border), or null on error
LEPT_DLL PIX* pixExtractBoundary | ( | PIX * | pixs, |
l_int32 | type | ||
) |
Input: pixs (1 bpp) type (0 for background pixels; 1 for foreground pixels) Return: pixd, or null on error
Notes: (1) Extracts the fg or bg boundary pixels for each component. Components are assumed to end at the boundary of pixs.
LEPT_DLL l_uint32* pixExtractData | ( | PIX * | pixs | ) |
Notes: (1) This extracts the pix image data for use in another context. The caller still needs to use pixDestroy() on the input pix. (2) If refcount == 1, the data is extracted and the pix->data ptr is set to NULL. (3) If refcount > 1, this simply returns a copy of the data, using the pix allocator, and leaving the input pix unchanged.
LEPT_DLL NUMA* pixExtractOnLine | ( | PIX * | pixs, |
l_int32 | x1, | ||
l_int32 | y1, | ||
l_int32 | x2, | ||
l_int32 | y2, | ||
l_int32 | factor | ||
) |
Input: pixs (1 bpp or 8 bpp; no colormap) x1, y1 (one end point for line) x2, y2 (another end pt for line) factor (sampling; >= 1) Return: na (of pixel values along line), or null on error.
Notes: (1) Input end points are clipped to the pix. (2) If the line is either horizontal, or closer to horizontal than to vertical, the points will be extracted from left to right in the pix. Likewise, if the line is vertical, or closer to vertical than to horizontal, the points will be extracted from top to bottom. (3) Can be used with numaCountReverals(), for example, to characterize the intensity smoothness along a line.
Input: pixs (colormapped or 8 bpp or 32 bpp) pixb (8 bpp blender) factor (multiplicative factor to apply to blender value) type (L_BLEND_TO_WHITE, L_BLEND_TO_BLACK) Return: pixd, or null on error
Notes: (1) This function combines two pix aligned to the UL corner; they need not be the same size. (2) Each pixel in pixb is multiplied by 'factor' divided by 255, and clipped to the range [0 ... 1]. This gives the fade fraction to be appied to pixs. Fade either to white (L_BLEND_TO_WHITE) or to black (L_BLEND_TO_BLACK).
Input: pixs xsize (width of max/min op, smoothing; any integer >= 1) ysize (height of max/min op, smoothing; any integer >= 1) type (L_TOPHAT_WHITE: image - min L_TOPHAT_BLACK: max - image) Return: pixd, or null on error
Notes: (1) Don't be fooled. This is NOT a tophat. It is a tophat-like operation, where the result is similar to what you'd get if you used an erosion instead of an opening, or a dilation instead of a closing. (2) Instead of opening or closing at full resolution, it does a fast downscale/minmax operation, then a quick small smoothing at low res, a replicative expansion of the "background" to full res, and finally a removal of the background level from the input image. The smoothing step may not be important. (3) It does not remove noise as well as a tophat, but it is 5 to 10 times faster. If you need the preciseness of the tophat, don't use this. (4) The L_TOPHAT_WHITE flag emphasizes small bright regions, whereas the L_TOPHAT_BLACK flag emphasizes small dark regions.
LEPT_DLL PIX* pixFewColorsMedianCutQuantMixed | ( | PIX * | pixs, |
l_int32 | ncolor, | ||
l_int32 | ngray, | ||
l_int32 | maxncolors, | ||
l_int32 | darkthresh, | ||
l_int32 | lightthresh, | ||
l_int32 | diffthresh | ||
) |
pixFewColorsMedianCutQuantMixed()
Input: pixs (32 bpp rgb) ncolor (number of colors to be assigned to pixels with significant color) ngray (number of gray colors to be used; must be >= 2) maxncolors (maximum number of colors to be returned from pixColorsForQuantization(); use 0 for default) darkthresh (threshold near black; if the lightest component is below this, the pixel is not considered to be gray or color; use 0 for default) lightthresh (threshold near white; if the darkest component is above this, the pixel is not considered to be gray or color; use 0 for default) diffthresh (thresh for the max difference between component values; for differences below this, the pixel is considered to be gray; use 0 for default) considered gray; use 0 for default) Return: pixd (8 bpp, median cut quantized for pixels that are not gray; gray pixels are quantized separately over the full gray range); null if too many colors or on error
Notes: (1) This is the "few colors" version of pixMedianCutQuantMixed(). It fails (returns NULL) if it finds more than maxncolors, but otherwise it gives the same result. (2) Recommended input parameters are: : 20 : 20 : 244 : 15 (any higher can miss colors differing slightly from gray) (3) Both ncolor and ngray should be at least equal to maxncolors. If they're not, they are automatically increased, and a warning is given. (4) If very little color content is found, the input is converted to gray and quantized in equal intervals. (5) This can be useful for quantizing orthographically generated images such as color maps, where there may be more than 256 colors because of aliasing or jpeg artifacts on text or lines, but there are a relatively small number of solid colors. (6) Example of usage: // Try to quantize, using default values for mixed med cut Pix *pixq = pixFewColorsMedianCutQuantMixed(pixs, 100, 20, 0, 0, 0, 0); if (!pixq) // too many colors; don't quantize pixq = pixClone(pixs);
LEPT_DLL PIX* pixFewColorsOctcubeQuant1 | ( | PIX * | pixs, |
l_int32 | level | ||
) |
Input: pixs (32 bpp rgb) level (significant bits for each of RGB; valid in [1...6]) Return: pixd (quantized to octcube) or null on error
Notes: (1) Generates a colormapped image, where the colormap table values are the averages of all pixels that are found in the octcube. (2) This fails if there are more than 256 colors (i.e., more than 256 occupied octcubes). (3) Often level 3 (512 octcubes) will succeed because not more than half of them are occupied with 1 or more pixels. (4) The depth of the result, which is either 2, 4 or 8 bpp, is the minimum required to hold the number of colors that are found. (5) This can be useful for quantizing orthographically generated images such as color maps, where there may be more than 256 colors because of aliasing or jpeg artifacts on text or lines, but there are a relatively small number of solid colors. Then, use with level = 3 can often generate a compact and accurate representation of the original RGB image. For this purpose, it is better than pixFewColorsOctcubeQuant2(), because it uses the average value of pixels in the octcube rather than the first found pixel. It is also simpler to use, because it generates the histogram internally.
LEPT_DLL PIX* pixFewColorsOctcubeQuant2 | ( | PIX * | pixs, |
l_int32 | level, | ||
NUMA * | na, | ||
l_int32 | ncolors, | ||
l_int32 * | pnerrors | ||
) |
Input: pixs (32 bpp rgb) level (of octcube indexing, for histogram: 3, 4, 5, 6) na (histogram of pixel occupation in octree leaves at given level) ncolors (number of occupied octree leaves at given level) &nerrors (<optional return>=""> num of pixels not exactly represented in the colormap) Return: pixd (2, 4 or 8 bpp with colormap), or null on error
Notes: (1) Generates a colormapped image, where the colormap table values are the averages of all pixels that are found in the octcube. (2) This fails if there are more than 256 colors (i.e., more than 256 occupied octcubes). (3) Often level 3 (512 octcubes) will succeed because not more than half of them are occupied with 1 or more pixels. (4) For an image with not more than 256 colors, it is unlikely that two pixels of different color will fall in the same octcube at level = 4. However it is possible, and this function optionally returns , the number of pixels where, because more than one color is in the same octcube, the pixel color is not exactly reproduced in the colormap. The colormap for an occupied leaf of the octree contains the color of the first pixel encountered in that octcube. (5) This differs from pixFewColorsOctcubeQuant1(), which also requires not more than 256 occupied leaves, but represents the color of each leaf by an average over the pixels in that leaf. This also requires precomputing the histogram of occupied octree leaves, which is generated using pixOctcubeHistogram(). (6) This is used in pixConvertRGBToColormap() for images that are determined, by their histogram, to have relatively few colors. This typically happens with orthographically produced images (as oppopsed to natural images), where it is expected that most of the pixels within a leaf octcube have exactly the same color, and quantization to that color is lossless.
LEPT_DLL PIX* pixFewColorsOctcubeQuantMixed | ( | PIX * | pixs, |
l_int32 | level, | ||
l_int32 | darkthresh, | ||
l_int32 | lightthresh, | ||
l_int32 | diffthresh, | ||
l_float32 | minfract, | ||
l_int32 | maxspan | ||
) |
pixFewColorsOctcubeQuantMixed()
Input: pixs (32 bpp rgb) level (significant octcube bits for each of RGB; valid in [1...6]; use 0 for default) darkthresh (threshold near black; if the lightest component is below this, the pixel is not considered to be gray or color; uses 0 for default) lightthresh (threshold near white; if the darkest component is above this, the pixel is not considered to be gray or color; use 0 for default) diffthresh (thresh for the max difference between component values; for differences below this, the pixel is considered to be gray; use 0 for default) considered gray; use 0 for default) minfract (min fraction of pixels for gray histo bin; use 0.0 for default) maxspan (max size of gray histo bin; use 0 for default) Return: pixd (8 bpp, quantized to octcube for pixels that are not gray; gray pixels are quantized separately over the full gray range), or null on error
Notes: (1) First runs pixFewColorsOctcubeQuant1(). If this succeeds, it separates the color from gray(ish) entries in the cmap, and re-quantizes the gray pixels. The result has some pixels in color and others in gray. (2) This fails if there are more than 256 colors (i.e., more than 256 occupied octcubes in the color quantization). (3) Level 3 (512 octcubes) will usually succeed because not more than half of them are occupied with 1 or more pixels. (4) This uses the criterion from pixColorFraction() for deciding if a colormap entry is color; namely, if the color components are not too close to either black or white, and the maximum difference between component values equals or exceeds a threshold. (5) For quantizing the gray pixels, it uses a histogram-based method where input parameters determining the buckets are the minimum population fraction and the maximum allowed size. (6) Recommended input parameters are: : 3 or 4 (3 is default) : 20 : 244 : 20 : 0.05 : 15 These numbers are intended to be conservative (somewhat over- sensitive) in color detection, It's usually better to pay extra with octcube quantization of a grayscale image than to use grayscale quantization on an image that has some actual color. Input 0 on any of these to get the default. (7) This can be useful for quantizing orthographically generated images such as color maps, where there may be more than 256 colors because of aliasing or jpeg artifacts on text or lines, but there are a relatively small number of solid colors. It usually gives results that are better than pixOctcubeQuantMixedWithGray(), both in size and appearance. But it is a bit slower.
PIX * pixFHMTGen_1 | ( | PIX * | pixd, |
PIX * | pixs, | ||
char * | selname | ||
) |
Input: pixd (usual 3 choices: null, == pixs, != pixs) pixs (1 bpp) sel name Return: pixd
Notes: (1) This is a dwa implementation of the hit-miss transform on pixs by the sel. (2) The sel must be limited in size to not more than 31 pixels about the origin. It must have at least one hit, and it can have any number of misses. (3) This handles all required setting of the border pixels before erosion and dilation.
LEPT_DLL PIX* pixFillClosedBorders | ( | PIX * | pixs, |
l_int32 | connectivity | ||
) |
Input: pixs (1 bpp) filling connectivity (4 or 8) Return: pixd (all topologically outer closed borders are filled as connected comonents), or null on error
Notes: (1) Start with 1-pixel black border on otherwise white pixd (2) Subtract input pixs to remove border pixels that were also on the closed border (3) Use the inverted pixs as the filling mask to fill in all the pixels from the outer border to the closed border on pixs (4) Invert the result to get the filled component, including the input border (5) If the borders are 4-c.c., use 8-c.c. filling, and v.v. (6) Closed borders within c.c. that represent holes, etc., are filled.
LEPT_DLL PIX* pixFillHolesToBoundingRect | ( | PIX * | pixs, |
l_int32 | minsize, | ||
l_float32 | maxhfract, | ||
l_float32 | minfgfract | ||
) |
Input: pixs (1 bpp) minsize (min number of pixels in the hole) maxhfract (max hole area as fraction of fg pixels in the cc) minfgfract (min fg area as fraction of bounding rectangle) Return: pixd (pixs, with some holes possibly filled and some c.c. possibly expanded to their bounding rects), or null on error
Notes: (1) This does not fill holes that are smaller in area than 'minsize'. (2) This does not fill holes with an area larger than 'maxhfract' times the fg area of the c.c. (3) This does not expand the fg of the c.c. to bounding rect if the fg area is less than 'minfgfract' times the area of the bounding rect. (4) The decisions are made as follows:
Input: pix (8 bpp; a map, with one pixel for each tile in a larger image) nx (number of horizontal pixel tiles that are entirely covered with pixels in the original source image) ny (ditto for the number of vertical pixel tiles) filltype (L_FILL_WHITE or L_FILL_BLACK) Return: 0 if OK, 1 on error
Notes: (1) This is an in-place operation on pix (the map). pix is typically a low-resolution version of some other image from which it was derived, where each pixel in pix corresponds to a rectangular tile (say, m x n) of pixels in the larger image. All we need to know about the larger image is whether or not the rightmost column and bottommost row of pixels in pix correspond to tiles that are only partially covered by pixels in the larger image. (2) Typically, some number of pixels in the input map are not known, and their values must be determined by near pixels that are known. These unknown pixels are the 'holes'. They can take on only two values, 0 and 255, and the instruction about which to fill is given by the filltype flag. (3) The "holes" can come from two sources. The first is when there are not enough foreground or background pixels in a tile; the second is when a tile is at least partially covered by an image mask. If we're filling holes in a fg mask, the holes are initialized to black (0) and use L_FILL_BLACK. For filling holes in a bg mask, initialize the holes to white (255) and use L_FILL_WHITE. (4) If w is the map width, nx = w or nx = w - 1; ditto for h and ny.
Input: pixs (32 bpp) offset (same as used for initialization) depth (8, 16 or 32 bpp, of destination) Return: pixd (8, 16 or 32 bpp), or null on error
Notes: (1) The offset must be >= 0 and should not exceed 0x40000000. (2) The offset is subtracted from the src 32 bpp image (3) For 8 bpp dest, the result is clipped to [0, 0xff] (4) For 16 bpp dest, the result is clipped to [0, 0xffff]
Input: pixs (32 bpp) offset (same as used for initialization) threshold (values less than this are set in the destination) Return: pixd (1 bpp), or null on error
Notes: (1) The offset must be >= 0 and should not exceed 0x40000000. (2) The offset is subtracted from the src 32 bpp image
Input: pixs (1 bpp) tab (<optional> pixel sum table, can be NULL) &fract (<return> fg area/size ratio) Return: 0 if OK, 1 on error
Notes: (1) This finds the ratio of the number of fg pixels to the size of the pix (w * h). It is typically used for a single connected component.
Input: pixs (1 bpp) tab (<optional> pixel sum table, can be NULL) &fract (<return> area/perimeter ratio) Return: 0 if OK, 1 on error
Notes: (1) The area is the number of fg pixels that are not on the boundary (i.e., not 8-connected to a bg pixel), and the perimeter is the number of boundary fg pixels. (2) This is typically used for a pixa consisting of 1 bpp connected components.
Input: pixs (1 bpp) &pta (<optional return>=""> pairs of pts corresponding to approx. ends of each text line) debug (usually 0; set to 1 for debugging output) Return: na (of baseline y values), or null on error
Notes: (1) Input binary image must have text lines already aligned horizontally. This can be done by either rotating the image with pixDeskew(), or, if a projective transform is required, by doing pixDeskewLocal() first. (2) Input null for &pta if you don't want this returned. The pta will come in pairs of points (left and right end of each baseline). (3) Caution: this will not work properly on text with multiple columns, where the lines are not aligned between columns. If there are multiple columns, they should be extracted separately before finding the baselines. (4) This function constructs different types of output for baselines; namely, a set of raster line values and a set of end points of each baseline. (5) This function was designed to handle short and long text lines without using dangerous thresholds on the peak heights. It does this by combining the differential signal with a morphological analysis of the locations of the text lines. One can also combine this data to normalize the peak heights, by weighting the differential signal in the region of each baseline by the inverse of the width of the text line found there. (6) There are various debug sections that can be turned on with the debug flag.
LEPT_DLL PTA* pixFindCornerPixels | ( | PIX * | pixs | ) |
Input: pixs (1 bpp) Return: pta, or null on error
Notes: (1) Finds the 4 corner-most pixels, as defined by a search inward from each corner, using a 45 degree line.
LEPT_DLL l_int32 pixFindDifferentialSquareSum | ( | PIX * | pixs, |
l_float32 * | psum | ||
) |
pixFindDifferentialSquareSum()
Input: pixs &sum (<return> result) Return: 0 if OK, 1 on error
Notes: (1) At the top and bottom, we skip:
LEPT_DLL PIX* pixFindEqualValues | ( | PIX * | pixs1, |
PIX * | pixs2 | ||
) |
Input: pixs1 (8 bpp) pixs2 (8 bpp) Return: pixd (1 bpp mask), or null on error
Notes: (1) The two images are aligned at the UL corner, and the returned image has ON pixels where the pixels in pixs1 and pixs2 have equal values.
LEPT_DLL l_int32 pixFindHistoPeaksHSV | ( | PIX * | pixs, |
l_int32 | type, | ||
l_int32 | width, | ||
l_int32 | height, | ||
l_int32 | npeaks, | ||
l_float32 | erasefactor, | ||
PTA ** | ppta, | ||
NUMA ** | pnatot, | ||
PIXA ** | ppixa | ||
) |
Input: pixs (32 bpp; HS, HV or SV histogram; not changed) type (L_HS_HISTO, L_HV_HISTO or L_SV_HISTO) width (half width of sliding window) height (half height of sliding window) npeaks (number of peaks to look for) erasefactor (ratio of erase window size to sliding window size) &pta (locations of maximum for each integrated peak area) &natot (integrated peak areas) &pixa (<optional return>=""> pixa for debugging; NULL to skip) Return: 0 if OK, 1 on error
Notes: (1) pixs is a 32 bpp histogram in a pair of HSV colorspace. It should be thought of as a single sample with 32 bps (bits/sample). (2) After each peak is found, the peak is erased with a window that is centered on the peak and scaled from the sliding window by . Typically, is chosen to be > 1.0. (3) Data for a maximum of is returned in and . (4) For debugging, after the pixa is returned, display with: pixd = pixaDisplayTiledInRows(pixa, 32, 1000, 1.0, 0, 30, 2);
LEPT_DLL l_int32 pixFindHorizontalRuns | ( | PIX * | pix, |
l_int32 | y, | ||
l_int32 * | xstart, | ||
l_int32 * | xend, | ||
l_int32 * | pn | ||
) |
Input: pix (1 bpp) y (line to traverse) xstart (returns array of start positions for fg runs) xend (returns array of end positions for fg runs) &n (<return> the number of runs found) Return: 0 if OK; 1 on error
Notes: (1) This finds foreground horizontal runs on a single scanline. (2) To find background runs, use pixInvert() before applying this function. (3) The xstart and xend arrays are input. They should be of size w/2 + 1 to insure that they can hold the maximum number of runs in the raster line.
LEPT_DLL l_int32 pixFindLargestRectangle | ( | PIX * | pixs, |
l_int32 | polarity, | ||
BOX ** | pbox, | ||
const char * | debugfile | ||
) |
Input: pixs (1 bpp) polarity (0 within background, 1 within foreground) &box (<return> largest rectangle, either by area or by perimeter) debugflag (1 to output image with rectangle drawn on it) Return: 0 if OK, 1 on error
Notes: (1) Why is this here? This is a simple and elegant solution to a problem in computational geometry that at first appears quite difficult: what is the largest rectangle that can be placed in the image, covering only pixels of one polarity (bg or fg)? The solution is O(n), where n is the number of pixels in the image, and it requires nothing more than using a simple recursion relation in a single sweep of the image. (2) In a sweep from UL to LR with left-to-right being the fast direction, calculate the largest white rectangle at (x, y), using previously calculated values at pixels #1 and #2: #1: (x, y - 1) #2: (x - 1, y) We also need the most recent "black" pixels that were seen in the current row and column. Consider the largest area. There are only two possibilities: (a) Min(w(1), horizdist) * (h(1) + 1) (b) Min(h(2), vertdist) * (w(2) + 1) where horizdist: the distance from the rightmost "black" pixel seen in the current row across to the current pixel vertdist: the distance from the lowest "black" pixel seen in the current column down to the current pixel and we choose the Max of (a) and (b). (3) To convince yourself that these recursion relations are correct, it helps to draw the maximum rectangles at #1 and #2. Then for #1, you try to extend the rectangle down one line, so that the height is h(1) + 1. Do you get the full width of #1, w(1)? It depends on where the black pixels are in the current row. You know the final width is bounded by w(1) and w(2) + 1, but the actual value depends on the distribution of black pixels in the current row that are at a distance from the current pixel that is between these limits. We call that value "horizdist", and the area is then given by the expression (a) above. Using similar reasoning for #2, where you attempt to extend the rectangle to the right by 1 pixel, you arrive at (b). The largest rectangle is then found by taking the Max.
LEPT_DLL l_int32 pixFindNormalizedSquareSum | ( | PIX * | pixs, |
l_float32 * | phratio, | ||
l_float32 * | pvratio, | ||
l_float32 * | pfract | ||
) |
Input: pixs &hratio (<optional return>=""> ratio of normalized horiz square sum to result if the pixel distribution were uniform) &vratio (<optional return>=""> ratio of normalized vert square sum to result if the pixel distribution were uniform) &fract (<optional return>=""> ratio of fg pixels to total pixels) Return: 0 if OK, 1 on error or if there are no fg pixels
Notes: (1) Let the image have h scanlines and N fg pixels. If the pixels were uniformly distributed on scanlines, the sum of squares of fg pixels on each scanline would be h * (N / h)^2. However, if the pixels are not uniformly distributed (e.g., for text), the sum of squares of fg pixels will be larger. We return in hratio and vratio the ratio of these two values. (2) If there are no fg pixels, hratio and vratio are returned as 0.0.
LEPT_DLL l_int32 pixFindOverlapFraction | ( | PIX * | pixs1, |
PIX * | pixs2, | ||
l_int32 | x2, | ||
l_int32 | y2, | ||
l_int32 * | tab, | ||
l_float32 * | pratio, | ||
l_int32 * | pnoverlap | ||
) |
Input: pixs1, pixs2 (1 bpp) x2, y2 (location in pixs1 of UL corner of pixs2) tab (<optional> pixel sum table, can be null) &ratio (<return> ratio fg intersection to fg union) &noverlap (<optional return>=""> number of overlapping pixels) Return: 0 if OK, 1 on error
Notes: (1) The UL corner of pixs2 is placed at (x2, y2) in pixs1. (2) This measure is similar to the correlation.
Input: pixs (1 bpp) tab (<optional> pixel sum table, can be NULL) &ratio (<return> perimeter/size ratio) Return: 0 if OK, 1 on error
Notes: (1) The size is the sum of the width and height of the pix, and the perimeter is the number of boundary fg pixels. (2) This has a large value for dendritic, fractal-like components with highly irregular boundaries. (3) This is typically used for a single connected component.
Input: pixs (1 bpp) dist (max distance allowed between bounding box and nearest foreground pixel within it) minw, minh (minimum size in each direction as a requirement for a conforming rectangle) Return: boxa (of components that conform), or null on error
Notes: (1) This applies the function pixConformsToRectangle() to each 8-c.c. in pixs, and returns a boxa containing the regions of all components that are conforming. (2) Conforming components must satisfy both the size constraint given by and the slop in conforming to a rectangle determined by .
Input: pixs (1 bpp) &angle (<return> angle required to deskew, in degrees) &conf (<return> confidence value is ratio max/min scores) Return: 0 if OK, 1 on error or if angle measurment not valid
Notes: (1) This is a simple high-level interface, that uses default values of the parameters for reasonable speed and accuracy. (2) The angle returned is the negative of the skew angle of the image. It is the angle required for deskew. Clockwise rotations are positive angles.
LEPT_DLL PIX* pixFindSkewAndDeskew | ( | PIX * | pixs, |
l_int32 | redsearch, | ||
l_float32 * | pangle, | ||
l_float32 * | pconf | ||
) |
Input: pixs (any depth) redsearch (for binary search: reduction factor = 1, 2 or 4; use 0 for default) &angle (<optional return>=""> angle required to deskew, in degrees; use NULL to skip) &conf (<optional return>=""> conf value is ratio of max/min scores; use NULL to skip) Return: pixd (deskewed pix), or null on error
Notes: (1) This binarizes if necessary and finds the skew angle. If the angle is large enough and there is sufficient confidence, it returns a deskewed image; otherwise, it returns a clone.
LEPT_DLL l_int32 pixFindSkewOrthogonalRange | ( | PIX * | pixs, |
l_float32 * | pangle, | ||
l_float32 * | pconf, | ||
l_int32 | redsweep, | ||
l_int32 | redsearch, | ||
l_float32 | sweeprange, | ||
l_float32 | sweepdelta, | ||
l_float32 | minbsdelta, | ||
l_float32 | confprior | ||
) |
LEPT_DLL l_int32 pixFindSkewSweep | ( | PIX * | pixs, |
l_float32 * | pangle, | ||
l_int32 | reduction, | ||
l_float32 | sweeprange, | ||
l_float32 | sweepdelta | ||
) |
Input: pixs (1 bpp) &angle (<return> angle required to deskew, in degrees) reduction (factor = 1, 2, 4 or 8) sweeprange (half the full range; assumed about 0; in degrees) sweepdelta (angle increment of sweep; in degrees) Return: 0 if OK, 1 on error or if angle measurment not valid
Notes: (1) This examines the 'score' for skew angles with equal intervals. (2) Caller must check the return value for validity of the result.
LEPT_DLL l_int32 pixFindSkewSweepAndSearch | ( | PIX * | pixs, |
l_float32 * | pangle, | ||
l_float32 * | pconf, | ||
l_int32 | redsweep, | ||
l_int32 | redsearch, | ||
l_float32 | sweeprange, | ||
l_float32 | sweepdelta, | ||
l_float32 | minbsdelta | ||
) |
Input: pixs (1 bpp) &angle (<return> angle required to deskew; in degrees) &conf (<return> confidence given by ratio of max/min score) redsweep (sweep reduction factor = 1, 2, 4 or 8) redsearch (binary search reduction factor = 1, 2, 4 or 8; and must not exceed redsweep) sweeprange (half the full range, assumed about 0; in degrees) sweepdelta (angle increment of sweep; in degrees) minbsdelta (min binary search increment angle; in degrees) Return: 0 if OK, 1 on error or if angle measurment not valid
Notes: (1) This finds the skew angle, doing first a sweep through a set of equal angles, and then doing a binary search until convergence. (2) Caller must check the return value for validity of the result. (3) In computing the differential line sum variance score, we sum the result over scanlines, but we always skip:
LEPT_DLL l_int32 pixFindSkewSweepAndSearchScore | ( | PIX * | pixs, |
l_float32 * | pangle, | ||
l_float32 * | pconf, | ||
l_float32 * | pendscore, | ||
l_int32 | redsweep, | ||
l_int32 | redsearch, | ||
l_float32 | sweepcenter, | ||
l_float32 | sweeprange, | ||
l_float32 | sweepdelta, | ||
l_float32 | minbsdelta | ||
) |
pixFindSkewSweepAndSearchScore()
Input: pixs (1 bpp) &angle (<return> angle required to deskew; in degrees) &conf (<return> confidence given by ratio of max/min score) &endscore (<optional return>=""> max score; use NULL to ignore) redsweep (sweep reduction factor = 1, 2, 4 or 8) redsearch (binary search reduction factor = 1, 2, 4 or 8; and must not exceed redsweep) sweepcenter (angle about which sweep is performed; in degrees) sweeprange (half the full range, taken about sweepcenter; in degrees) sweepdelta (angle increment of sweep; in degrees) minbsdelta (min binary search increment angle; in degrees) Return: 0 if OK, 1 on error or if angle measurment not valid
Notes: (1) This finds the skew angle, doing first a sweep through a set of equal angles, and then doing a binary search until convergence. (2) There are two built-in constants that determine if the returned confidence is nonzero:
LEPT_DLL l_int32 pixFindSkewSweepAndSearchScorePivot | ( | PIX * | pixs, |
l_float32 * | pangle, | ||
l_float32 * | pconf, | ||
l_float32 * | pendscore, | ||
l_int32 | redsweep, | ||
l_int32 | redsearch, | ||
l_float32 | sweepcenter, | ||
l_float32 | sweeprange, | ||
l_float32 | sweepdelta, | ||
l_float32 | minbsdelta, | ||
l_int32 | pivot | ||
) |
pixFindSkewSweepAndSearchScorePivot()
Input: pixs (1 bpp) &angle (<return> angle required to deskew; in degrees) &conf (<return> confidence given by ratio of max/min score) &endscore (<optional return>=""> max score; use NULL to ignore) redsweep (sweep reduction factor = 1, 2, 4 or 8) redsearch (binary search reduction factor = 1, 2, 4 or 8; and must not exceed redsweep) sweepcenter (angle about which sweep is performed; in degrees) sweeprange (half the full range, taken about sweepcenter; in degrees) sweepdelta (angle increment of sweep; in degrees) minbsdelta (min binary search increment angle; in degrees) pivot (L_SHEAR_ABOUT_CORNER, L_SHEAR_ABOUT_CENTER) Return: 0 if OK, 1 on error or if angle measurment not valid
Notes: (1) See notes in pixFindSkewSweepAndSearchScore(). (2) This allows choice of shear pivoting from either the UL corner or the center. For small angles, the ability to discriminate angles is better with shearing from the UL corner. However, for large angles (say, greater than 20 degrees), it is better to shear about the center because a shear from the UL corner loses too much of the image.
LEPT_DLL l_int32 pixFindVerticalRuns | ( | PIX * | pix, |
l_int32 | x, | ||
l_int32 * | ystart, | ||
l_int32 * | yend, | ||
l_int32 * | pn | ||
) |
Input: pix (1 bpp) x (line to traverse) ystart (returns array of start positions for fg runs) yend (returns array of end positions for fg runs) &n (<return> the number of runs found) Return: 0 if OK; 1 on error
Notes: (1) This finds foreground vertical runs on a single scanline. (2) To find background runs, use pixInvert() before applying this function. (3) The ystart and yend arrays are input. They should be of size h/2 + 1 to insure that they can hold the maximum number of runs in the raster line.
LEPT_DLL PIX* pixFixedOctcubeQuant256 | ( | PIX * | pixs, |
l_int32 | ditherflag | ||
) |
Input: pixs (32 bpp; 24-bit color) ditherflag (1 for dithering; 0 for no dithering) Return: pixd (8 bit with colormap), or null on error
This simple 1-pass color quantization works by breaking the color space into 256 pieces, with 3 bits quantized for each of red and green, and 2 bits quantized for blue. We shortchange blue because the eye is least sensitive to blue. This division of the color space is into two levels of octrees, followed by a further division by 4 (not 8), where both blue octrees have been combined in the third level.
The color map is generated from the 256 color centers by taking the representative color to be the center of the cell volume. This gives a maximum error in the red and green values of 16 levels, and a maximum error in the blue sample of 32 levels.
Each pixel in the 24-bit color image is placed in its containing cell, given by the relevant MSbits of the red, green and blue samples. An error-diffusion dithering is performed on each color sample to give the appearance of good average local color. Dithering is required; without it, the contouring and visible color errors are very bad.
I originally implemented this algorithm in two passes, where the first pass was used to compute the weighted average of each sample in each pre-allocated region of color space. The idea was to use these centroids in the dithering algorithm of the second pass, to reduce the average error that was being dithered. However, with dithering, there is virtually no difference, so there is no reason to make the first pass. Consequently, this 1-pass version just assigns the pixels to the centers of the pre-allocated cells. We use dithering to spread the difference between the sample value and the location of the center of the cell. For speed and simplicity, we use integer dithering and propagate only to the right, down, and diagonally down-right, with ratios 3/8, 3/8 and 1/4, respectively. The results should be nearly as good, and a bit faster, with propagation only to the right and down.
The algorithm is very fast, because there is no search, only fast generation of the cell index for each pixel. We use a simple mapping from the three 8 bit rgb samples to the 8 bit cell index; namely, (r7 r6 r5 g7 g6 g5 b7 b6). This is not in an octcube format, but it doesn't matter. There are no storage requirements. We could keep a running average of the center of each sample in each cluster, rather than using the center of the cell, but this is just extra work, esp. with dithering.
This method gives surprisingly good results with dithering. However, without dithering, the loss of color accuracy is evident in regions that are very light or that have subtle blending of colors.
LEPT_DLL PIX* pixFixedOctcubeQuantGenRGB | ( | PIX * | pixs, |
l_int32 | level | ||
) |
Input: pixs (32 bpp rgb) level (significant bits for each of r,g,b) Return: pixd (rgb; quantized to octcube centers), or null on error
Notes: (1) Unlike the other color quantization functions, this one generates an rgb image. (2) The pixel values are quantized to the center of each octcube (at the specified level) containing the pixel. They are not quantized to the average of the pixels in that octcube.
LEPT_DLL PIX* pixFlipFHMTGen | ( | PIX * | pixd, |
PIX * | pixs, | ||
char * | selname | ||
) |
Input: pixd (<optional>; can be null, equal to pixs, or different from pixs) pixs (all depths) Return: pixd, or null on error
Notes: (1) This does a left-right flip of the image, which is equivalent to a rotation out of the plane about a vertical line through the image center. (2) There are 3 cases for input: (a) pixd == null (creates a new pixd) (b) pixd == pixs (in-place operation) (c) pixd != pixs (existing pixd) (3) For clarity, use these three patterns, respectively: (a) pixd = pixFlipLR(NULL, pixs); (b) pixFlipLR(pixs, pixs); (c) pixFlipLR(pixd, pixs); (4) If an existing pixd is not the same size as pixs, the image data will be reallocated.
Input: pix (x,y) pixel coords Return: 0 if OK; 1 on error
Input: pixd (<optional>; can be null, equal to pixs, or different from pixs) pixs (all depths) Return: pixd, or null on error
Notes: (1) This does a top-bottom flip of the image, which is equivalent to a rotation out of the plane about a horizontal line through the image center. (2) There are 3 cases for input: (a) pixd == null (creates a new pixd) (b) pixd == pixs (in-place operation) (c) pixd != pixs (existing pixd) (3) For clarity, use these three patterns, respectively: (a) pixd = pixFlipTB(NULL, pixs); (b) pixFlipTB(pixs, pixs); (c) pixFlipTB(pixd, pixs); (4) If an existing pixd is not the same size as pixs, the image data will be reallocated.
PIX * pixFMorphopGen_1 | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_int32 | operation, | ||
char * | selname | ||
) |
Input: pixd (usual 3 choices: null, == pixs, != pixs) pixs (1 bpp) operation (L_MORPH_DILATE, L_MORPH_ERODE, L_MORPH_OPEN, L_MORPH_CLOSE) sel name Return: pixd
Notes: (1) This is a dwa operation, and the Sels must be limited in size to not more than 31 pixels about the origin. (2) A border of appropriate size (32 pixels, or 64 pixels for safe closing with asymmetric b.c.) must be added before this function is called. (3) This handles all required setting of the border pixels before erosion and dilation. (4) The closing operation is safe; no pixels can be removed near the boundary.
PIX * pixFMorphopGen_2 | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_int32 | operation, | ||
char * | selname | ||
) |
Input: pixd (usual 3 choices: null, == pixs, != pixs) pixs (1 bpp) operation (L_MORPH_DILATE, L_MORPH_ERODE, L_MORPH_OPEN, L_MORPH_CLOSE) sel name Return: pixd
Notes: (1) This is a dwa operation, and the Sels must be limited in size to not more than 31 pixels about the origin. (2) A border of appropriate size (32 pixels, or 64 pixels for safe closing with asymmetric b.c.) must be added before this function is called. (3) This handles all required setting of the border pixels before erosion and dilation. (4) The closing operation is safe; no pixels can be removed near the boundary.
LEPT_DLL l_int32 pixForegroundFraction | ( | PIX * | pix, |
l_float32 * | pfract | ||
) |
Input: pix (1 bpp) &fract (<return> fraction of ON pixels) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 pixFreeData | ( | PIX * | pix | ) |
Notes: (1) This frees the data and sets the pix data ptr to null. It should be used before pixSetData() in the situation where you want to free any existing data before doing a subsequent assignment with pixSetData().
LEPT_DLL PIX* pixGammaTRC | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_float32 | gamma, | ||
l_int32 | minval, | ||
l_int32 | maxval | ||
) |
Input: pixd (<optional> null or equal to pixs) pixs (8 or 32 bpp; or 2, 4 or 8 bpp with colormap) gamma (gamma correction; must be > 0.0) minval (input value that gives 0 for output; can be < 0) maxval (input value that gives 255 for output; can be > 255) Return: pixd always
Notes: (1) pixd must either be null or equal to pixs. For in-place operation, set pixd == pixs: pixGammaTRC(pixs, pixs, ...); To get a new image, set pixd == null: pixd = pixGammaTRC(NULL, pixs, ...); (2) If pixs is colormapped, the colormap is transformed, either in-place or in a copy of pixs. (3) We use a gamma mapping between minval and maxval. (4) If gamma < 1.0, the image will appear darker; if gamma > 1.0, the image will appear lighter; (5) If gamma = 1.0 and minval = 0 and maxval = 255, no enhancement is performed; return a copy unless in-place, in which case this is a no-op. (6) For color images that are not colormapped, the mapping is applied to each component. (7) minval and maxval are not restricted to the interval [0, 255]. If minval < 0, an input value of 0 is mapped to a nonzero output. This will turn black to gray. If maxval > 255, an input value of 255 is mapped to an output value less than 255. This will turn white (e.g., in the background) to gray. (8) Increasing minval darkens the image. (9) Decreasing maxval bleaches the image. (10) Simultaneously increasing minval and decreasing maxval will darken the image and make the colors more intense; e.g., minval = 50, maxval = 200. (11) See numaGammaTRC() for further examples of use.
LEPT_DLL PIX* pixGammaTRCMasked | ( | PIX * | pixd, |
PIX * | pixs, | ||
PIX * | pixm, | ||
l_float32 | gamma, | ||
l_int32 | minval, | ||
l_int32 | maxval | ||
) |
Input: pixd (<optional> null or equal to pixs) pixs (8 or 32 bpp; not colormapped) pixm (<optional> null or 1 bpp) gamma (gamma correction; must be > 0.0) minval (input value that gives 0 for output; can be < 0) maxval (input value that gives 255 for output; can be > 255) Return: pixd always
Notes: (1) Same as pixGammaTRC() except mapping is optionally over a subset of pixels described by pixm. (2) Masking does not work for colormapped images. (3) See pixGammaTRC() for details on how to use the parameters.
LEPT_DLL PIX* pixGammaTRCWithAlpha | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_float32 | gamma, | ||
l_int32 | minval, | ||
l_int32 | maxval | ||
) |
Input: pixd (<optional> null or equal to pixs) pixs (32 bpp) gamma (gamma correction; must be > 0.0) minval (input value that gives 0 for output; can be < 0) maxval (input value that gives 255 for output; can be > 255) Return: pixd always
Notes: (1) See usage notes in pixGammaTRC(). (2) This version saves the alpha channel. It is only valid for 32 bpp (no colormap), and is a bit slower.
LEPT_DLL L_COMPRESSED_DATA* pixGenerateFlateData | ( | PIX * | pixs, |
l_int32 | ascii85flag | ||
) |
Input: pixs ascii85flag (0 for gzipped; 1 for ascii85-encoded gzipped) Return: cid (flate compressed image data), or null on error
Input: pta w, h (of pix) Return: pix (1 bpp), or null on error
Notes: (1) Points are rounded to nearest ints. (2) Any points outside (w,h) are silently discarded. (3) Output 1 bpp pix has values 1 for each point in the pta.
LEPT_DLL L_COMPRESSED_DATA* pixGenerateG4Data | ( | PIX * | pixs, |
l_int32 | ascii85flag | ||
) |
Input: pixs (1 bpp) ascii85flag (0 for gzipped; 1 for ascii85-encoded gzipped) Return: cid (g4 compressed image data), or null on error
Notes: (1) Set ascii85flag:
LEPT_DLL L_COMPRESSED_DATA* pixGenerateJpegData | ( | PIX * | pixs, |
l_int32 | ascii85flag, | ||
l_int32 | quality | ||
) |
Input: pixs (8 or 32 bpp, no colormap) ascii85flag (0 for jpeg; 1 for ascii85-encoded jpeg) quality (0 for default, which is 75) Return: cid (jpeg compressed data), or null on error
Notes: (1) Set ascii85flag:
LEPT_DLL PIX* pixGenerateMaskByBand | ( | PIX * | pixs, |
l_int32 | lower, | ||
l_int32 | upper, | ||
l_int32 | inband, | ||
l_int32 | usecmap | ||
) |
Input: pixs (4 or 8 bpp, or colormapped) lower, upper (two pixel values from which a range, either between (inband) or outside of (!inband), determines which pixels in pixs cause us to set a 1 in the dest mask) inband (1 for finding pixels in [lower, upper]; 0 for finding pixels in [0, lower) union (upper, 255]) usecmap (1 to retain cmap values; 0 to convert to gray) Return: pixd (1 bpp), or null on error
Notes: (1) Generates a 1 bpp mask pixd, the same size as pixs, where the fg pixels in the mask are those either within the specified band (for inband == 1) or outside the specified band (for inband == 0). (2) If pixs is colormapped, determines if the colormap values are used, or if the colormap is removed to gray and the gray values are used. For the latter, it generates an approximate grayscale value for each pixel, and then looks for gray pixels with the value .
Input: pixs (32 bpp) refval (reference rgb value) delm (max amount below the ref value for any component) delp (max amount above the ref value for any component) Return: pixd (1 bpp), or null on error
Notes: (1) Generates a 1 bpp mask pixd, the same size as pixs, where the fg pixels in the mask are those where each component is within -delm to +delp of the reference value.
LEPT_DLL PIX* pixGenerateMaskByDiscr32 | ( | PIX * | pixs, |
l_uint32 | refval1, | ||
l_uint32 | refval2, | ||
l_int32 | distflag | ||
) |
Input: pixs (32 bpp) refval1 (reference rgb value) refval2 (reference rgb value) distflag (L_MANHATTAN_DISTANCE, L_EUCLIDEAN_DISTANCE) Return: pixd (1 bpp), or null on error
Notes: (1) Generates a 1 bpp mask pixd, the same size as pixs, where the fg pixels in the mask are those where the pixel in pixs is "closer" to refval1 than to refval2. (2) "Closer" can be defined in several ways, such as:
Input: pixs (4 or 8 bpp, or colormapped) val (of pixels for which we set 1 in dest) usecmap (1 to retain cmap values; 0 to convert to gray) Return: pixd (1 bpp), or null on error
Notes: (1) is the gray value of the pixels that we are selecting. (2) If pixs is colormapped, determines if the colormap values are used, or if the colormap is removed to gray and the gray values are used. For the latter, it generates an approximate grayscale value for each pixel, and then looks for gray pixels with the value .
LEPT_DLL SEL* pixGenerateSelBoundary | ( | PIX * | pixs, |
l_int32 | hitdist, | ||
l_int32 | missdist, | ||
l_int32 | hitskip, | ||
l_int32 | missskip, | ||
l_int32 | topflag, | ||
l_int32 | botflag, | ||
l_int32 | leftflag, | ||
l_int32 | rightflag, | ||
PIX ** | ppixe | ||
) |
Input: pix (1 bpp, typically small, to be used as a pattern) hitdist (min distance from fg boundary pixel) missdist (min distance from bg boundary pixel) hitskip (number of boundary pixels skipped between hits) missskip (number of boundary pixels skipped between misses) topflag (flag for extra pixels of bg added above) botflag (flag for extra pixels of bg added below) leftflag (flag for extra pixels of bg added to left) rightflag (flag for extra pixels of bg added to right) &pixe (<optional return>=""> input pix expanded by extra pixels) Return: sel (hit-miss for input pattern), or null on error
Notes: (1) All fg elements selected are exactly hitdist pixels away from the nearest fg boundary pixel, and ditto for bg elements. Valid inputs of hitdist and missdist are 0, 1, 2, 3 and 4. For example, a hitdist of 0 puts the hits at the fg boundary. Usually, the distances should be > 0 avoid the effect of noise at the boundary. (2) Set hitskip < 0 if no hits are to be used. Ditto for missskip. If both hitskip and missskip are < 0, the sel would be empty, and NULL is returned. (3) The 4 flags determine whether the sel is increased on that side to allow bg misses to be placed all along that boundary. The increase in sel size on that side is the minimum necessary to allow the misses to be placed at mindist. For text characters, the topflag and botflag are typically set to 1, and the leftflag and rightflag to 0. (4) The input pix, as extended by the extra pixels on selected sides, can optionally be returned. For debugging, call pixDisplayHitMissSel() to visualize the hit-miss sel superimposed on the generating bitmap. (5) This is probably the best of the three sel generators, in the sense that you have the most flexibility with the smallest number of hits and misses.
LEPT_DLL SEL* pixGenerateSelRandom | ( | PIX * | pixs, |
l_float32 | hitfract, | ||
l_float32 | missfract, | ||
l_int32 | distance, | ||
l_int32 | toppix, | ||
l_int32 | botpix, | ||
l_int32 | leftpix, | ||
l_int32 | rightpix, | ||
PIX ** | ppixe | ||
) |
Input: pix (1 bpp, typically small, to be used as a pattern) hitfract (fraction of allowable fg pixels that are hits) missfract (fraction of allowable bg pixels that are misses) distance (min distance from boundary pixel; use 0 for default) toppix (number of extra pixels of bg added above) botpix (number of extra pixels of bg added below) leftpix (number of extra pixels of bg added to left) rightpix (number of extra pixels of bg added to right) &pixe (<optional return>=""> input pix expanded by extra pixels) Return: sel (hit-miss for input pattern), or null on error
Notes: (1) Either of hitfract and missfract can be zero. If both are zero, the sel would be empty, and NULL is returned. (2) No elements are selected that are less than 'distance' pixels away from a boundary pixel of the same color. This makes the match much more robust to edge noise. Valid inputs of 'distance' are 0, 1, 2, 3 and 4. If distance is either 0 or greater than 4, we reset it to the default value. (3) The 4 numbers for adding rectangles of pixels outside the fg can be use if the pattern is expected to be surrounded by bg (white) pixels. On the other hand, if the pattern may be near other fg (black) components on some sides, use 0 for those sides. (4) The input pix, as extended by the extra pixels on selected sides, can optionally be returned. For debugging, call pixDisplayHitMissSel() to visualize the hit-miss sel superimposed on the generating bitmap.
LEPT_DLL SEL* pixGenerateSelWithRuns | ( | PIX * | pixs, |
l_int32 | nhlines, | ||
l_int32 | nvlines, | ||
l_int32 | distance, | ||
l_int32 | minlength, | ||
l_int32 | toppix, | ||
l_int32 | botpix, | ||
l_int32 | leftpix, | ||
l_int32 | rightpix, | ||
PIX ** | ppixe | ||
) |
Input: pix (1 bpp, typically small, to be used as a pattern) nhlines (number of hor lines along which elements are found) nvlines (number of vert lines along which elements are found) distance (min distance from boundary pixel; use 0 for default) minlength (min runlength to set hit or miss; use 0 for default) toppix (number of extra pixels of bg added above) botpix (number of extra pixels of bg added below) leftpix (number of extra pixels of bg added to left) rightpix (number of extra pixels of bg added to right) &pixe (<optional return>=""> input pix expanded by extra pixels) Return: sel (hit-miss for input pattern), or null on error
Notes: (1) The horizontal and vertical lines along which elements are selected are roughly equally spaced. The actual locations of the hits and misses are the centers of respective run-lengths. (2) No elements are selected that are less than 'distance' pixels away from a boundary pixel of the same color. This makes the match much more robust to edge noise. Valid inputs of 'distance' are 0, 1, 2, 3 and 4. If distance is either 0 or greater than 4, we reset it to the default value. (3) The 4 numbers for adding rectangles of pixels outside the fg can be use if the pattern is expected to be surrounded by bg (white) pixels. On the other hand, if the pattern may be near other fg (black) components on some sides, use 0 for those sides. (4) The pixels added to a side allow you to have miss elements there. There is a constraint between distance, minlength, and the added pixels for this to work. We illustrate using the default values. If you add 5 pixels to the top, and use a distance of 1, then you end up with a vertical run of at least 4 bg pixels along the top edge of the image. If you use a minimum runlength of 3, each vertical line will always find a miss near the center of its run. However, if you use a minimum runlength of 5, you will not get a miss on every vertical line. As another example, if you have 7 added pixels and a distance of 2, you can use a runlength up to 5 to guarantee that the miss element is recorded. We give a warning if the contraint does not guarantee a miss element outside the image proper. (5) The input pix, as extended by the extra pixels on selected sides, can optionally be returned. For debugging, call pixDisplayHitMissSel() to visualize the hit-miss sel superimposed on the generating bitmap.
Input: pixs (1 bpp, assumed to be 150 to 200 ppi) &pixtext (<optional return>=""> text part of pixs) &htfound (<optional return>=""> 1 if the mask is not empty) debug (flag: 1 for debug output) Return: pixd (halftone mask), or null on error
Input: pixs (1 bpp, textline mask, assumed to be 150 to 200 ppi) pixvws (vertical white space mask) debug (flag: 1 for debug output) Return: pixd (textblock mask), or null on error
Notes: (1) Both the input masks (textline and vertical white space) and the returned textblock mask are at the same resolution. (2) The result is somewhat noisy, in that small "blocks" of text may be included. These can be removed by post-processing, using, e.g., pixSelectBySize(pix, 60, 60, 4, L_SELECT_IF_EITHER, L_SELECT_IF_GTE, NULL);
Input: pixs (1 bpp, assumed to be 150 to 200 ppi) &pixvws (<return> vertical whitespace mask) &tlfound (<optional return>=""> 1 if the mask is not empty) debug (flag: 1 for debug output) Return: pixd (textline mask), or null on error
Notes: (1) The input pixs should be deskewed. (2) pixs should have no halftone pixels. (3) Both the input image and the returned textline mask are at the same resolution.
LEPT_DLL CCBORDA* pixGetAllCCBorders | ( | PIX * | pixs | ) |
Input: pixs (1 bpp) Return: ccborda, or null on error
LEPT_DLL l_int32 pixGetAverageMasked | ( | PIX * | pixs, |
PIX * | pixm, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | factor, | ||
l_int32 | type, | ||
l_float32 * | pval | ||
) |
Input: pixs (8 or 16 bpp, or colormapped) pixm (<optional> 1 bpp mask over which average is to be taken; use all pixels if null) x, y (UL corner of pixm relative to the UL corner of pixs; can be < 0) factor (subsampling factor; >= 1) type (L_MEAN_ABSVAL, L_ROOT_MEAN_SQUARE, L_STANDARD_DEVIATION, L_VARIANCE) &val (<return> measured value of given 'type') Return: 0 if OK, 1 on error
Notes: (1) Use L_MEAN_ABSVAL to get the average value of pixels in pixs that are under the fg of the optional mask. If the mask is null, it finds the average of the pixels in pixs. (2) Likewise, use L_ROOT_MEAN_SQUARE to get the rms value of pixels in pixs, either masked or not; L_STANDARD_DEVIATION to get the standard deviation from the mean of the pixels; L_VARIANCE to get the average squared difference from the expected value. The variance is the square of the stdev. For the standard deviation, we use sqrt(<(<x> - x)>^2) = sqrt(<x^2> - <x>^2) (3) Set the subsampling > 1 to reduce the amount of computation. (4) Clipping of pixm (if it exists) to pixs is done in the inner loop. (5) Input x,y are ignored unless pixm exists.
LEPT_DLL l_int32 pixGetAverageMaskedRGB | ( | PIX * | pixs, |
PIX * | pixm, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | factor, | ||
l_int32 | type, | ||
l_float32 * | prval, | ||
l_float32 * | pgval, | ||
l_float32 * | pbval | ||
) |
Input: pixs (32 bpp, or colormapped) pixm (<optional> 1 bpp mask over which average is to be taken; use all pixels if null) x, y (UL corner of pixm relative to the UL corner of pixs; can be < 0) factor (subsampling factor; >= 1) type (L_MEAN_ABSVAL, L_ROOT_MEAN_SQUARE, L_STANDARD_DEVIATION, L_VARIANCE) &rval (<return optional>=""> measured red value of given 'type') &gval (<return optional>=""> measured green value of given 'type') &bval (<return optional>=""> measured blue value of given 'type') Return: 0 if OK, 1 on error
Notes: (1) For usage, see pixGetAverageMasked(). (2) If there is a colormap, it is removed before the 8 bpp component images are extracted.
Input: pixs (8 bpp, or colormapped) sx, sy (tile size; must be at least 2 x 2) type (L_MEAN_ABSVAL, L_ROOT_MEAN_SQUARE, L_STANDARD_DEVIATION) Return: pixd (average values in each tile), or null on error
Notes: (1) Only computes for tiles that are entirely contained in pixs. (2) Use L_MEAN_ABSVAL to get the average abs value within the tile; L_ROOT_MEAN_SQUARE to get the rms value within each tile; L_STANDARD_DEVIATION to get the standard dev. from the average within each tile. (3) If colormapped, converts to 8 bpp gray.
LEPT_DLL l_int32 pixGetAverageTiledRGB | ( | PIX * | pixs, |
l_int32 | sx, | ||
l_int32 | sy, | ||
l_int32 | type, | ||
PIX ** | ppixr, | ||
PIX ** | ppixg, | ||
PIX ** | ppixb | ||
) |
Input: pixs (32 bpp, or colormapped) sx, sy (tile size; must be at least 2 x 2) type (L_MEAN_ABSVAL, L_ROOT_MEAN_SQUARE, L_STANDARD_DEVIATION) &pixr (<optional return>=""> tiled 'average' of red component) &pixg (<optional return>=""> tiled 'average' of green component) &pixb (<optional return>=""> tiled 'average' of blue component) Return: 0 if OK, 1 on error
Notes: (1) For usage, see pixGetAverageTiled(). (2) If there is a colormap, it is removed before the 8 bpp component images are extracted.
Input: pixs (8 bpp, 32 bpp or colormapped) factor (subsampling factor; integer >= 1) type (L_MEAN_ABSVAL, L_ROOT_MEAN_SQUARE, L_STANDARD_DEVIATION, L_VARIANCE) &value (<return> pixel value corresponding to input rank) Return: 0 if OK, 1 on error
Notes: (1) Simple function to get average statistical values of an image.
LEPT_DLL l_int32 pixGetBackgroundGrayMap | ( | PIX * | pixs, |
PIX * | pixim, | ||
l_int32 | sx, | ||
l_int32 | sy, | ||
l_int32 | thresh, | ||
l_int32 | mincount, | ||
PIX ** | ppixd | ||
) |
Input: pixs (8 bpp grayscale; not cmapped) pixim (<optional> 1 bpp 'image' mask; can be null; it should not have all foreground pixels) sx, sy (tile size in pixels) thresh (threshold for determining foreground) mincount (min threshold on counts in a tile) &pixd (<return> 8 bpp grayscale map) Return: 0 if OK, 1 on error
Notes: (1) The background is measured in regions that don't have images. It is then propagated into the image regions, and finally smoothed in each image region.
LEPT_DLL l_int32 pixGetBackgroundGrayMapMorph | ( | PIX * | pixs, |
PIX * | pixim, | ||
l_int32 | reduction, | ||
l_int32 | size, | ||
PIX ** | ppixm | ||
) |
pixGetBackgroundGrayMapMorph()
Input: pixs (8 bpp grayscale; not cmapped) pixim (<optional> 1 bpp 'image' mask; can be null; it should not have all foreground pixels) reduction (factor at which closing is performed) size (of square Sel for the closing; use an odd number) &pixm (<return> grayscale map) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixGetBackgroundRGBMap | ( | PIX * | pixs, |
PIX * | pixim, | ||
PIX * | pixg, | ||
l_int32 | sx, | ||
l_int32 | sy, | ||
l_int32 | thresh, | ||
l_int32 | mincount, | ||
PIX ** | ppixmr, | ||
PIX ** | ppixmg, | ||
PIX ** | ppixmb | ||
) |
Input: pixs (32 bpp rgb) pixim (<optional> 1 bpp 'image' mask; can be null; it should not have all foreground pixels) pixg (<optional> 8 bpp grayscale version; can be null) sx, sy (tile size in pixels) thresh (threshold for determining foreground) mincount (min threshold on counts in a tile) &pixmr, &pixmg, &pixmb (<return> rgb maps) Return: 0 if OK, 1 on error
Notes: (1) If pixg, which is a grayscale version of pixs, is provided, use this internally to generate the foreground mask. Otherwise, a grayscale version of pixs will be generated from the green component only, used, and destroyed.
LEPT_DLL l_int32 pixGetBackgroundRGBMapMorph | ( | PIX * | pixs, |
PIX * | pixim, | ||
l_int32 | reduction, | ||
l_int32 | size, | ||
PIX ** | ppixmr, | ||
PIX ** | ppixmg, | ||
PIX ** | ppixmb | ||
) |
Input: pixs (32 bpp rgb) pixim (<optional> 1 bpp 'image' mask; can be null; it should not have all foreground pixels) reduction (factor at which closing is performed) size (of square Sel for the closing; use an odd number) &pixmr (<return> red component map) &pixmg (<return> green component map) &pixmb (<return> blue component map) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixGetBinnedColor | ( | PIX * | pixs, |
PIX * | pixg, | ||
l_int32 | factor, | ||
l_int32 | nbins, | ||
NUMA * | nalut, | ||
l_uint32 ** | pcarray, | ||
l_int32 | debugflag | ||
) |
Input: pixs (32 bpp) pixg (8 bpp grayscale version of pixs) factor (sampling factor along pixel counting direction) nbins (number of intensity bins) nalut (LUT for mapping from intensity to bin number) &carray (<return> array of average color values in each bin) debugflag (1 to display output debug plots of color components; 2 to write them as png to file) Return: 0 if OK; 1 on error
Notes: (1) This takes a color image, a grayscale (intensity) version, a LUT from intensity to bin number, and the number of bins. It computes the average color for pixels whose intensity is in each bin. This is returned as an array of l_uint32 colors in our standard RGBA ordering. (2) This function generates equal width intensity bins and finds the average color in each bin. Compare this with pixGetRankColorArray(), which rank orders the pixels by the value of the selected component in each pixel, sets up bins with equal population (not intensity width!), and gets the average color in each bin.
LEPT_DLL l_int32 pixGetBinnedComponentRange | ( | PIX * | pixs, |
l_int32 | nbins, | ||
l_int32 | factor, | ||
l_int32 | color, | ||
l_int32 * | pminval, | ||
l_int32 * | pmaxval, | ||
l_uint32 ** | pcarray, | ||
l_int32 | debugflag | ||
) |
Input: pixs (32 bpp rgb) nbins (number of equal population bins; must be > 1) factor (subsampling factor; >= 1) color (L_SELECT_RED, L_SELECT_GREEN or L_SELECT_BLUE) &minval (<optional return>=""> minimum value of component) &maxval (<optional return>=""> maximum value of component) &carray (<optional return>=""> color array of bins) debugflag (1 for debug output) Return: 0 if OK, 1 on error
Notes: (1) This returns the min and max average values of the selected color component in the set of rank bins, where the ranking is done using the specified component.
LEPT_DLL CCBORD* pixGetCCBorders | ( | PIX * | pixs, |
BOX * | box | ||
) |
Input: pixs (1 bpp, one 8-connected component) box (xul, yul, width, height) in global coords Return: ccbord, or null on error
Notes: (1) We are finding the exterior and interior borders of an 8-connected component. This should be used on a pix that has exactly one 8-connected component. (2) Typically, pixs is a c.c. in some larger pix. The input box gives its location in global coordinates. This box is saved, as well as the boxes for the borders of any holes within the c.c., but the latter are given in relative coords within the c.c. (3) The calculations for the exterior border are done on a pix with a 1-pixel added border, but the saved pixel coordinates are the correct (relative) ones for the input pix (without a 1-pixel border) (4) For the definition of the three tables -- xpostab[], ypostab[] and qpostab[] -- see above where they are defined.
LEPT_DLL NUMA* pixGetCmapHistogram | ( | PIX * | pixs, |
l_int32 | factor | ||
) |
Input: pixs (colormapped: d = 2, 4 or 8) factor (subsampling factor; integer >= 1) Return: na (histogram of cmap indices), or null on error
Notes: (1) This generates a histogram of colormap pixel indices, and is of size 2^d. (2) Set the subsampling > 1 to reduce the amount of computation.
Input: pixs (colormapped: d = 2, 4 or 8) box (<optional>) over which histogram is to be computed; use full image if null) factor (subsampling factor; integer >= 1) Return: na (histogram), or null on error
Notes: (1) This generates a histogram of colormap pixel indices, and is of size 2^d. (2) Set the subsampling > 1 to reduce the amount of computation. (3) Clipping to the box is done in the inner loop.
LEPT_DLL NUMA* pixGetCmapHistogramMasked | ( | PIX * | pixs, |
PIX * | pixm, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | factor | ||
) |
Input: pixs (colormapped: d = 2, 4 or 8) pixm (<optional> 1 bpp mask over which histogram is to be computed; use all pixels if null) x, y (UL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null) factor (subsampling factor; integer >= 1) Return: na (histogram), or null on error
Notes: (1) This generates a histogram of colormap pixel indices, and is of size 2^d. (2) Set the subsampling > 1 to reduce the amount of computation. (3) Clipping of pixm to pixs is done in the inner loop.
LEPT_DLL l_int32 pixGetColorHistogram | ( | PIX * | pixs, |
l_int32 | factor, | ||
NUMA ** | pnar, | ||
NUMA ** | pnag, | ||
NUMA ** | pnab | ||
) |
Input: pixs (rgb or colormapped) factor (subsampling factor; integer >= 1) &nar (<return> red histogram) &nag (<return> green histogram) &nab (<return> blue histogram) Return: 0 if OK, 1 on error
Notes: (1) This generates a set of three 256 entry histograms, one for each color component (r,g,b). (2) Set the subsampling > 1 to reduce the amount of computation.
LEPT_DLL l_int32 pixGetColorHistogramMasked | ( | PIX * | pixs, |
PIX * | pixm, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | factor, | ||
NUMA ** | pnar, | ||
NUMA ** | pnag, | ||
NUMA ** | pnab | ||
) |
Input: pixs (32 bpp rgb, or colormapped) pixm (<optional> 1 bpp mask over which histogram is to be computed; use all pixels if null) x, y (UL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null) factor (subsampling factor; integer >= 1) &nar (<return> red histogram) &nag (<return> green histogram) &nab (<return> blue histogram) Return: 0 if OK, 1 on error
Notes: (1) This generates a set of three 256 entry histograms, (2) Set the subsampling > 1 to reduce the amount of computation. (3) Clipping of pixm (if it exists) to pixs is done in the inner loop. (4) Input x,y are ignored unless pixm exists.
LEPT_DLL PIXCMAP* pixGetColormap | ( | PIX * | pix | ) |
LEPT_DLL l_int32 pixGetColumnStats | ( | PIX * | pixs, |
l_int32 | type, | ||
l_int32 | nbins, | ||
l_int32 | thresh, | ||
l_float32 * | rowvect | ||
) |
Input: pixs (8 bpp; not cmapped) type (L_MEAN_ABSVAL, L_MEDIAN_VAL, L_MODE_VAL, L_MODE_COUNT) nbins (of histogram for median and mode; ignored for mean) thresh (on histogram for mode val; ignored for all other types) rowvect (vector of results gathered down the columns of pixs) Return: 0 if OK, 1 on error
Notes: (1) This computes a row vector of statistics using each column of a Pix. The result is put in . (2) The parameter works with L_MODE_VAL only, and sets a minimum occupancy of the mode bin. If the occupancy of the mode bin is less than , the mode value is returned as 0. To always return the actual mode value, set = 0. (3) What is the meaning of this parameter? For each column, the total count in the histogram is h, the image height. So , relative to h, gives a measure of the ratio of the bin width to the width of the distribution. The larger , the narrower the distribution must be for the mode value to be returned (instead of returning 0).
LEPT_DLL l_int32 pixGetComponentRange | ( | PIX * | pixs, |
l_int32 | factor, | ||
l_int32 | color, | ||
l_int32 * | pminval, | ||
l_int32 * | pmaxval | ||
) |
Input: pixs (8 bpp grayscale, 32 bpp rgb, or colormapped) factor (subsampling factor; >= 1; ignored if colormapped) color (L_SELECT_RED, L_SELECT_GREEN or L_SELECT_BLUE) &minval (<optional return>=""> minimum value of component) &maxval (<optional return>=""> maximum value of component) Return: 0 if OK, 1 on error
Notes: (1) If pixs is 8 bpp grayscale, the color selection type is ignored.
LEPT_DLL l_uint32* pixGetData | ( | PIX * | pix | ) |
Notes: (1) This gives a new handle for the data. The data is still owned by the pix, so do not call FREE() on it.
LEPT_DLL l_int32 pixGetDepth | ( | PIX * | pix | ) |
Input: pix1 (8 bpp gray or 32 bpp rgb, or colormapped) pix2 (8 bpp gray or 32 bpp rgb, or colormapped) factor (subsampling factor; use 0 or 1 for no subsampling) Return: na (Numa of histogram of differences), or null on error
Notes: (1) The two images are aligned at the UL corner, and do not need to be the same size. If they are not the same size, the comparison will be made over overlapping pixels. (2) If there is a colormap, it is removed and the result is either gray or RGB depending on the colormap. (3) If RGB, the maximum difference between pixel components is saved in the histogram.
LEPT_DLL l_int32 pixGetDifferenceStats | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_int32 | factor, | ||
l_int32 | mindiff, | ||
l_float32 * | pfractdiff, | ||
l_float32 * | pavediff, | ||
l_int32 | printstats | ||
) |
Input: pix1 (8 bpp gray or 32 bpp rgb, or colormapped) pix2 (8 bpp gray or 32 bpp rgb, or colormapped) factor (subsampling factor; use 0 or 1 for no subsampling) mindiff (minimum pixel difference to be counted; > 0) &fractdiff (<return> fraction of pixels with diff greater than or equal to mindiff) &avediff (<return> average difference of pixels with diff greater than or equal to mindiff, less mindiff) printstats (use 1 to print normalized histogram to stderr) Return: 0 if OK, 1 on error
Notes: (1) This takes a threshold and describes the difference between two images in terms of two numbers: (a) the fraction of pixels, , whose difference equals or exceeds the threshold , and (b) the average value of the difference in pixel value for the pixels in the set given by (a), after you subtract . The reason for subtracting is that you then get a useful measure for the rate of falloff of the distribution for larger differences. For example, if = 10 and you find that = 2.5, it says that of the pixels with diff > 10, the average of their diffs is just mindiff + 2.5 = 12.5. This is a fast falloff in the histogram with increasing difference. (2) The two images are aligned at the UL corner, and do not need to be the same size. If they are not the same size, the comparison will be made over overlapping pixels. (3) If there is a colormap, it is removed and the result is either gray or RGB depending on the colormap. (4) If RGB, the maximum difference between pixel components is saved in the histogram.
Input: pix &w, &h, &d (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
LEPT_DLL NUMA* pixGetEdgeProfile | ( | PIX * | pixs, |
l_int32 | side, | ||
const char * | debugfile | ||
) |
Input: pixs (1 bpp) side (L_FROM_LEFT, L_FROM_RIGHT, L_FROM_TOP, L_FROM_BOTTOM) debugfile (<optional> displays constructed edge; use NULL for no output) Return: na (of fg edge pixel locations), or null on error
LEPT_DLL l_int32 pixGetExtremeValue | ( | PIX * | pixs, |
l_int32 | factor, | ||
l_int32 | type, | ||
l_int32 * | prval, | ||
l_int32 * | pgval, | ||
l_int32 * | pbval, | ||
l_int32 * | pgrayval | ||
) |
Input: pixs (8 bpp grayscale, 32 bpp rgb, or colormapped) factor (subsampling factor; >= 1; ignored if colormapped) type (L_SELECT_MIN or L_SELECT_MAX) &rval (<optional return>=""> red component) &gval (<optional return>=""> green component) &bval (<optional return>=""> blue component) &grayval (<optional return>=""> min gray value) Return: 0 if OK, 1 on error
Notes: (1) If pixs is grayscale, the result is returned in &grayval. Otherwise, if there is a colormap or d == 32, each requested color component is returned. At least one color component (address) must be input.
LEPT_DLL NUMA* pixGetGrayHistogram | ( | PIX * | pixs, |
l_int32 | factor | ||
) |
Input: pixs (1, 2, 4, 8, 16 bpp; can be colormapped) factor (subsampling factor; integer >= 1) Return: na (histogram), or null on error
Notes: (1) If pixs has a colormap, it is converted to 8 bpp gray. If you want a histogram of the colormap indices, use pixGetCmapHistogram(). (2) If pixs does not have a colormap, the output histogram is of size 2^d, where d is the depth of pixs. (3) This always returns a 256-value histogram of pixel values. (4) Set the subsampling factor > 1 to reduce the amount of computation.
Input: pixs (8 bpp, or colormapped) box (<optional>) over which histogram is to be computed; use full image if null) factor (subsampling factor; integer >= 1) Return: na (histogram), or null on error
Notes: (1) If pixs is cmapped, it is converted to 8 bpp gray. If you want a histogram of the colormap indices, use pixGetCmapHistogramInRect(). (2) This always returns a 256-value histogram of pixel values. (3) Set the subsampling > 1 to reduce the amount of computation.
LEPT_DLL NUMA* pixGetGrayHistogramMasked | ( | PIX * | pixs, |
PIX * | pixm, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | factor | ||
) |
Input: pixs (8 bpp, or colormapped) pixm (<optional> 1 bpp mask over which histogram is to be computed; use all pixels if null) x, y (UL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null) factor (subsampling factor; integer >= 1) Return: na (histogram), or null on error
Notes: (1) If pixs is cmapped, it is converted to 8 bpp gray. If you want a histogram of the colormap indices, use pixGetCmapHistogramMasked(). (2) This always returns a 256-value histogram of pixel values. (3) Set the subsampling factor > 1 to reduce the amount of computation. (4) Clipping of pixm (if it exists) to pixs is done in the inner loop. (5) Input x,y are ignored unless pixm exists.
LEPT_DLL l_int32 pixGetHeight | ( | PIX * | pix | ) |
Input: ccb (the exterior border is already made) pixs (for the connected component at hand) box (for the specific hole border, in relative coordinates to the c.c.) xs, ys (first pixel on hole border, relative to c.c.) Return: 0 if OK, 1 on error
Notes: (1) we trace out hole border on pixs without addition of single pixel added border to pixs (2) therefore all coordinates are relative within the c.c. (pixs) (3) same position tables and stopping condition as for exterior borders
LEPT_DLL l_int32 pixGetInputFormat | ( | PIX * | pix | ) |
LEPT_DLL PIX* pixGetInvBackgroundMap | ( | PIX * | pixs, |
l_int32 | bgval, | ||
l_int32 | smoothx, | ||
l_int32 | smoothy | ||
) |
Input: pixs (8 bpp grayscale; no colormap) bgval (target bg val; typ. > 128) smoothx (half-width of block convolution kernel width) smoothy (half-width of block convolution kernel height) Return: pixd (16 bpp), or null on error
Note:
LEPT_DLL l_int32 pixGetLastOffPixelInRun | ( | PIX * | pixs, |
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | direction, | ||
l_int32 * | ploc | ||
) |
LEPT_DLL l_int32 pixGetLastOnPixelInRun | ( | PIX * | pixs, |
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | direction, | ||
l_int32 * | ploc | ||
) |
LEPT_DLL void** pixGetLinePtrs | ( | PIX * | pix, |
l_int32 * | psize | ||
) |
Input: pix &size (<optional return>=""> array size, which is the pix height) Return: array of line ptrs, or null on error
Notes: (1) This is intended to be used for fast random pixel access. For example, for an 8 bpp image, val = GET_DATA_BYTE(lines8[i], j); is equivalent to, but much faster than, pixGetPixel(pix, j, i, &val); (2) How much faster? For 1 bpp, it's from 6 to 10x faster. For 8 bpp, it's an amazing 30x faster. So if you are doing random access over a substantial part of the image, use this line ptr array. (3) When random access is used in conjunction with a stack, queue or heap, the overall computation time depends on the operations performed on each struct that is popped or pushed, and whether we are using a priority queue (O(logn)) or a queue or stack (O(1)). For example, for maze search, the overall ratio of time for line ptrs vs. pixGet/Set* is Maze type Type Time ratio binary queue 0.4 gray heap (priority queue) 0.6 (4) Because this returns a void** and the accessors take void*, the compiler cannot check the pointer types. It is strongly recommended that you adopt a naming scheme for the returned ptr arrays that indicates the pixel depth. (This follows the original intent of Simonyi's "Hungarian" application notation, where naming is used proactively to make errors visibly obvious.) By doing this, you can tell by inspection if the correct accessor is used. For example, for an 8 bpp pixg: void **lineg8 = pixGetLinePtrs(pixg, NULL); val = GET_DATA_BYTE(lineg8[i], j); // fast access; BYTE, 8 ... FREE(lineg8); // don't forget this (5) These are convenient for accessing bytes sequentially in an 8 bpp grayscale image. People who write image processing code on 8 bpp images are accustomed to grabbing pixels directly out of the raster array. Note that for little endians, you first need to reverse the byte order in each 32-bit word. Here's a typical usage pattern: pixEndianByteSwap(pix); // always safe; no-op on big-endians l_uint8 **lineptrs = (l_uint8 **)pixGetLinePtrs(pix, NULL); pixGetDimensions(pix, &w, &h, NULL); for (i = 0; i < h; i++) { l_uint8 *line = lineptrs[i]; for (j = 0; j < w; j++) { val = line[j]; ... } } pixEndianByteSwap(pix); // restore big-endian order FREE(lineptrs); This can be done even more simply as follows: l_uint8 **lineptrs = pixSetupByteProcessing(pix, &w, &h); for (i = 0; i < h; i++) { l_uint8 *line = lineptrs[i]; for (j = 0; j < w; j++) { val = line[j]; ... } } pixCleanupByteProcessing(pix, lineptrs);
LEPT_DLL NUMA* pixGetLocalSkewAngles | ( | PIX * | pixs, |
l_int32 | nslices, | ||
l_int32 | redsweep, | ||
l_int32 | redsearch, | ||
l_float32 | sweeprange, | ||
l_float32 | sweepdelta, | ||
l_float32 | minbsdelta, | ||
l_float32 * | pa, | ||
l_float32 * | pb | ||
) |
Input: pixs nslices (the number of horizontal overlapping slices; must be larger than 1 and not exceed 20; use 0 for default) redsweep (sweep reduction factor: 1, 2, 4 or 8; use 0 for default value) redsearch (search reduction factor: 1, 2, 4 or 8, and not larger than redsweep; use 0 for default value) sweeprange (half the full range, assumed about 0; in degrees; use 0.0 for default value) sweepdelta (angle increment of sweep; in degrees; use 0.0 for default value) minbsdelta (min binary search increment angle; in degrees; use 0.0 for default value) &a (<optional return>=""> slope of skew as fctn of y) &b (<optional return>=""> intercept at y=0 of skew as fctn of y) Return: naskew, or null on error
Notes: (1) The local skew is measured in a set of overlapping strips. We then do a least square linear fit parameters to get the slope and intercept parameters a and b in skew-angle = a * y + b (degrees) for the local skew as a function of raster line y. This is then used to make naskew, which can be interpreted as the computed skew angle (in degrees) at the left edge of each raster line. (2) naskew can then be used to find the baselines of text, because each text line has a baseline that should intersect the left edge of the image with the angle given by this array, evaluated at the raster line of intersection.
LEPT_DLL l_int32 pixGetLocalSkewTransform | ( | PIX * | pixs, |
l_int32 | nslices, | ||
l_int32 | redsweep, | ||
l_int32 | redsearch, | ||
l_float32 | sweeprange, | ||
l_float32 | sweepdelta, | ||
l_float32 | minbsdelta, | ||
PTA ** | pptas, | ||
PTA ** | pptad | ||
) |
Input: pixs nslices (the number of horizontal overlapping slices; must be larger than 1 and not exceed 20; use 0 for default) redsweep (sweep reduction factor: 1, 2, 4 or 8; use 0 for default value) redsearch (search reduction factor: 1, 2, 4 or 8, and not larger than redsweep; use 0 for default value) sweeprange (half the full range, assumed about 0; in degrees; use 0.0 for default value) sweepdelta (angle increment of sweep; in degrees; use 0.0 for default value) minbsdelta (min binary search increment angle; in degrees; use 0.0 for default value) &ptas (<return> 4 points in the source) &ptad (<return> the corresponding 4 pts in the dest) Return: 0 if OK, 1 on error
Notes: (1) This generates two pairs of points in the src, each pair corresponding to a pair of points that would lie along the same raster line in a transformed (dewarped) image. (2) The sets of 4 src and 4 dest points returned by this function can then be used, in a projective or bilinear transform, to remove keystoning in the src.
LEPT_DLL l_int32 pixGetMaxValueInRect | ( | PIX * | pixs, |
BOX * | box, | ||
l_uint32 * | pmaxval, | ||
l_int32 * | pxmax, | ||
l_int32 * | pymax | ||
) |
Input: pixs (8 bpp or 32 bpp grayscale; no color space components) box (<optional> region; set box = NULL to use entire pixs) &maxval (<optional return>=""> max value in region) &xmax (<optional return>=""> x location of max value) &ymax (<optional return>=""> y location of max value) Return: 0 if OK, 1 on error
Notes: (1) This can be used to find the maximum and its location in a 2-dimensional histogram, where the x and y directions represent two color components (e.g., saturation and hue). (2) Note that here a 32 bpp pixs has pixel values that are simply numbers. They are not 8 bpp components in a colorspace.
Input: ccb (unfilled) pixs (for the component at hand) box (for the component, in global coords) Return: 0 if OK, 1 on error
Notes: (1) the border is saved in relative coordinates within the c.c. (pixs). Because the calculation is done in pixb with added 1 pixel border, we must subtract 1 from each pixel value before storing it. (2) the stopping condition is that after the first pixel is returned to, the next pixel is the second pixel. Having these 2 pixels recur in sequence proves the path is closed, and we do not store the second pixel again.
LEPT_DLL PTA* pixGetOuterBorderPta | ( | PIX * | pixs, |
BOX * | box | ||
) |
Input: pixs (1 bpp, one 8-connected component) box (<optional> of pixs, in global coordinates) Return: pta (of outer border, in global coords), or null on error
Notes: (1) We are finding the exterior border of a single 8-connected component. (2) If box is NULL, the outline returned is in the local coords of the input pix. Otherwise, box is assumed to give the location of the pix in global coordinates, and the returned pta will be in those global coordinates.
LEPT_DLL PTAA* pixGetOuterBordersPtaa | ( | PIX * | pixs | ) |
Input: pixs (1 bpp) Return: ptaa (of outer borders, in global coords), or null on error
Input: pix (x,y) pixel coords &val (<return> pixel value) Return: 0 if OK; 1 on error
Notes: (1) This returns the value in the data array. If the pix is colormapped, it returns the colormap index, not the rgb value. (2) Because of the function overhead and the parameter checking, this is much slower than using the GET_DATA_*() macros directly. Speed on a 1 Mpixel RGB image, using a 3 GHz machine: * pixGet/pixSet: ~25 Mpix/sec * GET_DATA/SET_DATA: ~350 MPix/sec If speed is important and you're doing random access into the pix, use pixGetLinePtrs() and the array access macros.
Input: pix1, pix2 (8 or 32 bpp; no colormap) factor (sampling factor; >= 1) &psnr (<return> power signal/noise ratio difference) Return: 0 if OK, 1 on error
Notes: (1) This computes the power S/N ratio, in dB, for the difference between two images. By convention, the power S/N for a grayscale image is ('log' == log base 10, and 'ln == log base e): PSNR = 10 * log((255/MSE)^2) = 4.3429 * ln((255/MSE)^2) = -4.3429 * ln((MSE/255)^2) where MSE is the mean squared error.
Input: pix (any depth; can be colormapped) &val (<return> pixel value) &x (<optional return>=""> x coordinate chosen; can be null) &y (<optional return>=""> y coordinate chosen; can be null) Return: 0 if OK; 1 on error
Notes: (1) If the pix is colormapped, it returns the rgb value.
LEPT_DLL l_int32 pixGetRankColorArray | ( | PIX * | pixs, |
l_int32 | nbins, | ||
l_int32 | type, | ||
l_int32 | factor, | ||
l_uint32 ** | pcarray, | ||
l_int32 | debugflag | ||
) |
Input: pixs (32 bpp or cmapped) nbins (number of equal population bins; must be > 1) type (color selection flag) factor (subsampling factor; integer >= 1) &carray (<return> array of colors, ranked by intensity) debugflag (1 to display color squares and plots of color components; 2 to write them as png to file) Return: 0 if OK, 1 on error
Notes: (1) The color selection flag is one of: L_SELECT_RED, L_SELECT_GREEN, L_SELECT_BLUE, L_SELECT_MIN, L_SELECT_MAX. (2) Then it finds the histogram of the selected component in each RGB pixel. For each of the sets of pixels, ordered by this component value, find the average color, and return this as a "rank color" array. The output array has colors. (3) Set the subsampling factor > 1 to reduce the amount of computation. Typically you want at least 10,000 pixels for reasonable statistics. (4) The rank color as a function of rank can then be found from rankint = (l_int32)(rank * (nbins - 1) + 0.5); extractRGBValues(array[rankint], &rval, &gval, &bval); where the rank is in [0.0 ... 1.0]. This function is meant to be simple and approximate. (5) Compare this with pixGetBinnedColor(), which generates equal width intensity bins and finds the average color in each bin.
Input: pixs (8 bpp, 32 bpp or colormapped) factor (subsampling factor; integer >= 1) rank (between 0.0 and 1.0; 1.0 is brightest, 0.0 is darkest) &value (<return> pixel value corresponding to input rank) Return: 0 if OK, 1 on error
Notes: (1) Simple function to get rank values of an image. For a color image, the median value (rank = 0.5) can be used to linearly remap the colors based on the median of a target image, using pixLinearMapToTargetColor().
LEPT_DLL l_int32 pixGetRankValueMasked | ( | PIX * | pixs, |
PIX * | pixm, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | factor, | ||
l_float32 | rank, | ||
l_float32 * | pval, | ||
NUMA ** | pna | ||
) |
Input: pixs (8 bpp, or colormapped) pixm (<optional> 1 bpp mask over which rank val is to be taken; use all pixels if null) x, y (UL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null) factor (subsampling factor; integer >= 1) rank (between 0.0 and 1.0; 1.0 is brightest, 0.0 is darkest) &val (<return> pixel value corresponding to input rank) &na (<optional return>=""> of histogram) Return: 0 if OK, 1 on error
Notes: (1) Computes the rank value of pixels in pixs that are under the fg of the optional mask. If the mask is null, it computes the average of the pixels in pixs. (2) Set the subsampling > 1 to reduce the amount of computation. (3) Clipping of pixm (if it exists) to pixs is done in the inner loop. (4) Input x,y are ignored unless pixm exists. (5) The rank must be in [0.0 ... 1.0], where the brightest pixel has rank 1.0. For the median pixel value, use 0.5. (6) The histogram can optionally be returned, so that other rank values can be extracted without recomputing the histogram. In that case, just use numaHistogramGetValFromRank(na, rank, &val); on the returned Numa for additional rank values.
LEPT_DLL l_int32 pixGetRankValueMaskedRGB | ( | PIX * | pixs, |
PIX * | pixm, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | factor, | ||
l_float32 | rank, | ||
l_float32 * | prval, | ||
l_float32 * | pgval, | ||
l_float32 * | pbval | ||
) |
Input: pixs (32 bpp) pixm (<optional> 1 bpp mask over which rank val is to be taken; use all pixels if null) x, y (UL corner of pixm relative to the UL corner of pixs; can be < 0; these values are ignored if pixm is null) factor (subsampling factor; integer >= 1) rank (between 0.0 and 1.0; 1.0 is brightest, 0.0 is darkest) &rval (<optional return>=""> red component val for to input rank) &gval (<optional return>=""> green component val for to input rank) &bval (<optional return>=""> blue component val for to input rank) Return: 0 if OK, 1 on error
Notes: (1) Computes the rank component values of pixels in pixs that are under the fg of the optional mask. If the mask is null, it computes the average of the pixels in pixs. (2) Set the subsampling > 1 to reduce the amount of computation. (4) Input x,y are ignored unless pixm exists. (5) The rank must be in [0.0 ... 1.0], where the brightest pixel has rank 1.0. For the median pixel value, use 0.5.
LEPT_DLL l_int32 pixGetRasterData | ( | PIX * | pixs, |
l_uint8 ** | pdata, | ||
size_t * | pnbytes | ||
) |
Input: pixs (1, 8, 32 bpp) &data (<return> raster data in memory) &nbytes (<return> number of bytes in data string) Return: 0 if OK, 1 on error
Notes: (1) This returns the raster data as a byte string, padded to the byte. For 1 bpp, the first pixel is the MSbit in the first byte. For rgb, the bytes are in (rgb) order. This is the format required for flate encoding of pixels in a PostScript file.
LEPT_DLL l_int32 pixGetRefcount | ( | PIX * | pix | ) |
LEPT_DLL l_int32 pixGetRegionsBinary | ( | PIX * | pixs, |
PIX ** | ppixhm, | ||
PIX ** | ppixtm, | ||
PIX ** | ppixtb, | ||
l_int32 | debug | ||
) |
Input: pixs (1 bpp, assumed to be 300 to 400 ppi) &pixhm (<optional return>=""> halftone mask) &pixtm (<optional return>=""> textline mask) &pixtb (<optional return>=""> textblock mask) debug (flag: set to 1 for debug output) Return: 0 if OK, 1 on error
Notes: (1) It is best to deskew the image before segmenting. (2) The debug flag enables a number of outputs. These are included to show how to generate and save/display these results.
Input: pix &xres, &yres (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
LEPT_DLL PIX* pixGetRGBComponent | ( | PIX * | pixs, |
l_int32 | color | ||
) |
Input: pixs (32 bpp) color (one of {COLOR_RED, COLOR_GREEN, COLOR_BLUE, L_ALPHA_CHANNEL}) Return: pixd, the selected 8 bpp component image of the input 32 bpp image, or null on error
Notes: (1) The alpha channel (in the 4th byte of each RGB pixel) is mostly ignored in leptonica. (2) Three calls to this function generate the three 8 bpp component images. This is much faster than generating the three images in parallel, by extracting a src pixel and setting the pixels of each component image from it. The reason is there are many more cache misses when writing to three output images simultaneously.
LEPT_DLL PIX* pixGetRGBComponentCmap | ( | PIX * | pixs, |
l_int32 | color | ||
) |
Input: pixs (colormapped) color (one of {COLOR_RED, COLOR_GREEN, COLOR_BLUE}) Return: pixd (the selected 8 bpp component image of the input cmapped image), or null on error
LEPT_DLL l_int32 pixGetRGBLine | ( | PIX * | pixs, |
l_int32 | row, | ||
l_uint8 * | bufr, | ||
l_uint8 * | bufg, | ||
l_uint8 * | bufb | ||
) |
Input: pixs (32 bpp) row bufr (array of red samples; size w bytes) bufg (array of green samples; size w bytes) bufb (array of blue samples; size w bytes) Return: 0 if OK; 1 on error
Notes: (1) This puts rgb components from the input line in pixs into the given buffers.
LEPT_DLL l_int32 pixGetRGBPixel | ( | PIX * | pix, |
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 * | prval, | ||
l_int32 * | pgval, | ||
l_int32 * | pbval | ||
) |
Input: pix (32 bpp rgb, not colormapped) (x,y) pixel coords &rval (<optional return>=""> red component) &gval (<optional return>=""> green component) &bval (<optional return>=""> blue component) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 pixGetRowStats | ( | PIX * | pixs, |
l_int32 | type, | ||
l_int32 | nbins, | ||
l_int32 | thresh, | ||
l_float32 * | colvect | ||
) |
Input: pixs (8 bpp; not cmapped) type (L_MEAN_ABSVAL, L_MEDIAN_VAL, L_MODE_VAL, L_MODE_COUNT) nbins (of histogram for median and mode; ignored for mean) thresh (on histogram for mode; ignored for mean and median) colvect (vector of results gathered across the rows of pixs) Return: 0 if OK, 1 on error
Notes: (1) This computes a column vector of statistics using each row of a Pix. The result is put in . (2) The parameter works with L_MODE_VAL only, and sets a minimum occupancy of the mode bin. If the occupancy of the mode bin is less than , the mode value is returned as 0. To always return the actual mode value, set = 0. (3) What is the meaning of this parameter? For each row, the total count in the histogram is w, the image width. So , relative to w, gives a measure of the ratio of the bin width to the width of the distribution. The larger , the narrower the distribution must be for the mode value to be returned (instead of returning 0). (4) If the Pix consists of a set of corresponding columns, one for each Pix in a Pixa, the width of the Pix is the number of Pix in the Pixa and the column vector can be stored as a column in a Pix of the same size as each Pix in the Pixa.
Input: pixs (1 bpp) x, y (set one of these to -1; see notes) minlength (minimum length of acceptable run) Return: numa of fg runs, or null on error
Notes: (1) Action: this function computes the fg (black) and bg (white) pixel runlengths along the specified horizontal or vertical line, and returns a Numa of the "center" pixels of each fg run whose length equals or exceeds the minimum length. (2) This only works on horizontal and vertical lines. (3) For horizontal runs, set x = -1 and y to the value for all points along the raster line. For vertical runs, set y = -1 and x to the value for all points along the pixel column. (4) For horizontal runs, the points in the Numa are the x values in the center of fg runs that are of length at least 'minlength'. For vertical runs, the points in the Numa are the y values in the center of fg runs, again of length 'minlength' or greater. (5) If there are no fg runs along the line that satisfy the minlength constraint, the returned Numa is empty. This is not an error.
Input: pixs (1 bpp) x1, y1, x2, y2 Return: numa, or null on error
Notes: (1) Action: this function uses the bresenham algorithm to compute the pixels along the specified line. It returns a Numa of the runlengths of the fg (black) and bg (white) runs, always starting with a white run. (2) If the first pixel on the line is black, the length of the first returned run (which is white) is 0.
LEPT_DLL char* pixGetText | ( | PIX * | pix | ) |
Input: pix Return: ptr to existing text string
Notes: (1) The text string belongs to the pix. The caller must NOT free it!
LEPT_DLL l_int32 pixGetWidth | ( | PIX * | pix | ) |
LEPT_DLL l_int32 pixGetWordBoxesInTextlines | ( | PIX * | pixs, |
l_int32 | reduction, | ||
l_int32 | minwidth, | ||
l_int32 | minheight, | ||
l_int32 | maxwidth, | ||
l_int32 | maxheight, | ||
BOXA ** | pboxad, | ||
NUMA ** | pnai | ||
) |
Input: pixs (1 bpp, 300 ppi) reduction (1 for full res; 2 for half-res) minwidth, minheight (of saved components; smaller are discarded) maxwidth, maxheight (of saved components; larger are discarded) &boxad (<return> word boxes sorted in textline line order) &naindex (<return> index of textline for each word) Return: 0 if OK, 1 on error
Notes: (1) The input should be at a resolution of about 300 ppi. The word masks can be computed at either 150 ppi or 300 ppi. For the former, set reduction = 2. (2) In an actual application, it may be desirable to pre-filter the input image to remove large components, to extract single columns of text, and to deskew them. (3) This is a special version that just finds the word boxes in line order, with a numa giving the textline index for each word. See pixGetWordsInTextlines() for more details.
LEPT_DLL l_int32 pixGetWordsInTextlines | ( | PIX * | pixs, |
l_int32 | reduction, | ||
l_int32 | minwidth, | ||
l_int32 | minheight, | ||
l_int32 | maxwidth, | ||
l_int32 | maxheight, | ||
BOXA ** | pboxad, | ||
PIXA ** | ppixad, | ||
NUMA ** | pnai | ||
) |
Input: pixs (1 bpp, 300 ppi) reduction (1 for full res; 2 for half-res) minwidth, minheight (of saved components; smaller are discarded) maxwidth, maxheight (of saved components; larger are discarded) &boxad (<return> word boxes sorted in textline line order) &pixad (<return> word images sorted in textline line order) &naindex (<return> index of textline for each word) Return: 0 if OK, 1 on error
Notes: (1) The input should be at a resolution of about 300 ppi. The word masks can be computed at either 150 ppi or 300 ppi. For the former, set reduction = 2. (2) The four size constraints on saved components are all used at 2x reduction. (3) The result are word images (and their b.b.), extracted in textline order, all at 2x reduction, and with a numa giving the textline index for each word. (4) The pixa and boxa interfaces should make this type of application simple to put together. The steps are:
LEPT_DLL l_int32 pixGetXRes | ( | PIX * | pix | ) |
LEPT_DLL l_int32 pixGetYRes | ( | PIX * | pix | ) |
LEPT_DLL PIX* pixGlobalNormNoSatRGB | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval, | ||
l_int32 | factor, | ||
l_float32 | rank | ||
) |
Input: pixd (<optional> null, existing or equal to pixs) pixs (32 bpp rgb) rval, gval, bval (pixel values in pixs that are linearly mapped to mapval; but see below) factor (subsampling factor; integer >= 1) rank (between 0.0 and 1.0; typ. use a value near 1.0) Return: pixd (32 bpp rgb), or null on error
Notes: (1) This is a version of pixGlobalNormRGB(), where the output intensity is scaled back so that a controlled fraction of pixel components is allowed to saturate. See comments in pixGlobalNormRGB(). (2) The value of pixd determines if the results are written to a new pix (use NULL), in-place to pixs (use pixs), or to some other existing pix. (3) This does a global normalization of an image where the r,g,b color components are not balanced. Thus, white in pixs is represented by a set of r,g,b values that are not all 255. (4) The input values (rval, gval, bval) can be chosen to be the color that, after normalization, becomes white background. For images that are mostly background, the closer these values are to the median component values, the closer the resulting background will be to gray, becoming white at the brightest places. (5) The mapval used in pixGlobalNormRGB() is computed here to avoid saturation of any component in the image (save for a fraction of the pixels given by the input rank value).
LEPT_DLL PIX* pixGlobalNormRGB | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval, | ||
l_int32 | mapval | ||
) |
Input: pixd (<optional> null, existing or equal to pixs) pixs (32 bpp rgb, or colormapped) rval, gval, bval (pixel values in pixs that are linearly mapped to mapval) mapval (use 255 for mapping to white) Return: pixd (32 bpp rgb or colormapped), or null on error
Notes: (1) The value of pixd determines if the results are written to a new pix (use NULL), in-place to pixs (use pixs), or to some other existing pix. (2) This does a global normalization of an image where the r,g,b color components are not balanced. Thus, white in pixs is represented by a set of r,g,b values that are not all 255. (3) The input values (rval, gval, bval) should be chosen to represent the gray color (mapval, mapval, mapval) in src. Thus, this function will map (rval, gval, bval) to that gray color. (4) Typically, mapval = 255, so that (rval, gval, bval) corresponds to the white point of src. In that case, these parameters should be chosen so that few pixels have higher values. (5) In all cases, we do a linear TRC separately on each of the components, saturating at 255. (6) If the input pix is 8 bpp without a colormap, you can get this functionality with mapval = 255 by calling: pixGammaTRC(pixd, pixs, 1.0, 0, bgval); where bgval is the value you want to be mapped to 255. Or more generally, if you want bgval to be mapped to mapval: pixGammaTRC(pixd, pixs, 1.0, 0, 255 * bgval / mapval);
LEPT_DLL PIX* pixGrayMorphSequence | ( | PIX * | pixs, |
const char * | sequence, | ||
l_int32 | dispsep, | ||
l_int32 | dispy | ||
) |
Input: pixs sequence (string specifying sequence) dispsep (controls debug display of each result in the sequence: 0: no output > 0: gives horizontal separation in pixels between successive displays < 0: pdf output; abs(dispsep) is used for naming) dispy (if dispsep > 0, this gives the y-value of the UL corner for display; otherwise it is ignored) Return: pixd, or null on error
Notes: (1) This works on 8 bpp grayscale images. (2) This runs a pipeline of operations; no branching is allowed. (3) This only uses brick SELs. (4) A new image is always produced; the input image is not changed. (5) This contains an interpreter, allowing sequences to be generated and run. (6) The format of the sequence string is defined below. (7) In addition to morphological operations, the composite morph/subtract tophat can be performed. (8) Sel sizes (width, height) must each be odd numbers. (9) Intermediate results can optionally be displayed (10) The sequence string is formatted as follows:
Input: pixs (8 bpp grayscale without cmap) cmap (to quantize to; of dest pix) mindepth (minimum depth of pixd: can be 2, 4 or 8 bpp) Return: pixd (2, 4 or 8 bpp, colormapped), or null on error
Notes: (1) In use, pixs is an 8 bpp grayscale image without a colormap. If there is an existing colormap, a warning is issued and a copy of the input pixs is returned.
LEPT_DLL PIX* pixGrayQuantFromHisto | ( | PIX * | pixd, |
PIX * | pixs, | ||
PIX * | pixm, | ||
l_float32 | minfract, | ||
l_int32 | maxsize | ||
) |
Input: pixd (<optional> quantized pix with cmap; can be null) pixs (8 bpp gray input pix; not cmapped) pixm (<optional> mask over pixels in pixs to quantize) minfract (minimum fraction of pixels in a set of adjacent histo bins that causes the set to be automatically set aside as a color in the colormap; must be at least 0.01) maxsize (maximum number of adjacent bins allowed to represent a color, regardless of the population of pixels in the bins; must be at least 2) Return: pixd (8 bpp, cmapped), or null on error
Notes: (1) This is useful for quantizing images with relatively few colors, but which may have both color and gray pixels. If there are color pixels, it is assumed that an input rgb image has been color quantized first so that:
LEPT_DLL PIX* pixHalfEdgeByBandpass | ( | PIX * | pixs, |
l_int32 | sm1h, | ||
l_int32 | sm1v, | ||
l_int32 | sm2h, | ||
l_int32 | sm2v | ||
) |
Input: pixs (8 bpp gray or 32 bpp rgb) sm1h, sm1v ("half-widths" of smoothing filter sm1) sm2h, sm2v ("half-widths" of smoothing filter sm2) (require sm2 != sm1) Return: pixd, or null on error
Notes: (1) We use symmetric smoothing filters of odd dimension, typically use 3, 5, 7, etc. The smoothing parameters for these are 1, 2, 3, etc. The filter size is related to the smoothing parameter by size = 2 * smoothing + 1 (2) Because we take the difference of two lowpass filters, this is actually a bandpass filter. (3) We allow both filters to be anisotropic. (4) Consider either the h or v component of the 2 filters. Depending on whether sm1 > sm2 or sm2 > sm1, we get different halves of the smoothed gradients (or "edges"). This difference of smoothed signals looks more like a second derivative of a transition, which we rectify by not allowing the signal to go below zero. If sm1 < sm2, the sm2 transition is broader, so the difference between sm1 and sm2 signals is positive on the upper half of the transition. Likewise, if sm1 > sm2, the sm1 - sm2 signal difference is positive on the lower half of the transition.
LEPT_DLL l_int32 pixHaustest | ( | PIX * | pix1, |
PIX * | pix2, | ||
PIX * | pix3, | ||
PIX * | pix4, | ||
l_float32 | delx, | ||
l_float32 | dely, | ||
l_int32 | maxdiffw, | ||
l_int32 | maxdiffh | ||
) |
Input: pix1 (new pix, not dilated) pix2 (new pix, dilated) pix3 (exemplar pix, not dilated) pix4 (exemplar pix, dilated) delx (x comp of centroid difference) dely (y comp of centroid difference) maxdiffw (max width difference of pix1 and pix2) maxdiffh (max height difference of pix1 and pix2) Return: 0 (FALSE) if no match, 1 (TRUE) if the new pix is in the same class as the exemplar.
Note: we check first that the two pix are roughly the same size. Only if they meet that criterion do we compare the bitmaps. The Hausdorff is a 2-way check. The centroid difference is used to align the two images to the nearest integer for each of the checks. These check that the dilated image of one contains ALL the pixels of the undilated image of the other. Checks are done in both direction. A single pixel not contained in either direction results in failure of the test.
Input: pixs (8 bpp, filling mask) height (of seed below the filling maskhdome; must be >= 0) connectivity (4 or 8) Return: pixd (8 bpp), or null on error
Notes: (1) It is more efficient to use a connectivity of 4 for the fill. (2) This fills bumps to some level, and extracts the unfilled part of the bump. To extract the troughs of basins, first invert pixs and then apply pixHDome(). (3) It is useful to compare the HDome operation with the TopHat. The latter extracts peaks or valleys that have a width not exceeding the size of the structuring element used in the opening or closing, rsp. The height of the peak is irrelevant. By contrast, for the HDome, the gray seedfill is used to extract all peaks that have a height not exceeding a given value, regardless of their width! (4) Slightly more precisely, suppose you set 'height' = 40. Then all bumps in pixs with a height greater than or equal to 40 become, in pixd, bumps with a max value of exactly 40. All shorter bumps have a max value in pixd equal to the height of the bump. (5) The method: the filling mask, pixs, is the image whose peaks are to be extracted. The height of a peak is the distance between the top of the peak and the highest "leak" to the outside -- think of a sombrero, where the leak occurs at the highest point on the rim. (a) Generate a seed, pixd, by subtracting some value, p, from each pixel in the filling mask, pixs. The value p is the 'height' input to this function. (b) Fill in pixd starting with this seed, clipping by pixs, in the way described in seedfillGrayLow(). The filling stops before the peaks in pixs are filled. For peaks that have a height > p, pixd is filled to the level equal to the (top-of-the-peak - p). For peaks of height < p, the peak is left unfilled from its highest saddle point (the leak to the outside). (c) Subtract the filled seed (pixd) from the filling mask (pixs). Note that in this procedure, everything is done starting with the filling mask, pixs. (6) For segmentation, the resulting image, pixd, can be thresholded and used as a seed for another filling operation.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) sel Return: pixd
Notes: (1) The hit-miss transform erodes the src, using both hits and misses in the Sel. It ANDs the shifted src for hits and ANDs the inverted shifted src for misses. (2) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (3) For clarity, if the case is known, use these patterns: (a) pixd = pixHMT(NULL, pixs, ...); (b) pixHMT(pixs, pixs, ...); (c) pixHMT(pixd, pixs, ...); (4) The size of the result is determined by pixs.
PIX * pixHMTDwa_1 | ( | PIX * | pixd, |
PIX * | pixs, | ||
char * | selname | ||
) |
Input: pixd (usual 3 choices: null, == pixs, != pixs) pixs (1 bpp) sel name Return: pixd
Notes: (1) This simply adds a 32 pixel border, calls the appropriate pixFHMTGen_*(), and removes the border. See notes below for that function.
Top-level fast hit-miss transform with auto-generated sels
PIX *pixHMTDwa_1() PIX *pixFHMTGen_1()
Input: pixd (usual 3 choices: null, == pixs, != pixs) pixs (1 bpp) sel name Return: pixd
Notes: (1) This simply adds a 32 pixel border, calls the appropriate pixFHMTGen_*(), and removes the border. See notes below for that function.
LEPT_DLL PIX* pixHolesByFilling | ( | PIX * | pixs, |
l_int32 | connectivity | ||
) |
Input: pixs (1 bpp) connectivity (4 or 8) Return: pixd (inverted image of all holes), or null on error
Action: (1) Start with 1-pixel black border on otherwise white pixd (2) Use the inverted pixs as the filling mask to fill in all the pixels from the border to the pixs foreground (3) OR the result with pixs to have an image with all ON pixels except for the holes. (4) Invert the result to get the holes as foreground
Notes: (1) To get 4-c.c. holes of the 8-c.c. as foreground, use 4-connected filling; to get 8-c.c. holes of the 4-c.c. as foreground, use 8-connected filling.
LEPT_DLL PIX* pixHShear | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_int32 | liney, | ||
l_float32 | radang, | ||
l_int32 | incolor | ||
) |
Input: pixd (<optional>, this can be null, equal to pixs, or different from pixs) pixs (no restrictions on depth) liney (location of horizontal line, measured from origin) angle (in radians) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK); Return: pixd, always
Notes: (1) There are 3 cases: (a) pixd == null (make a new pixd) (b) pixd == pixs (in-place) (c) pixd != pixs (2) For these three cases, use these patterns, respectively: pixd = pixHShear(NULL, pixs, ...); pixHShear(pixs, pixs, ...); pixHShear(pixd, pixs, ...); (3) This shear leaves the horizontal line of pixels at y = liney invariant. For a positive shear angle, pixels above this line are shoved to the right, and pixels below this line move to the left. (4) With positive shear angle, this can be used, along with pixVShear(), to perform a cw rotation, either with 2 shears (for small angles) or in the general case with 3 shears. (5) Changing the value of liney is equivalent to translating the result horizontally. (6) This brings in 'incolor' pixels from outside the image. (7) For in-place operation, pixs cannot be colormapped, because the in-place operation only blits in 0 or 1 bits, not an arbitrary colormap index. (8) The angle is brought into the range [-pi, -pi]. It is not permitted to be within MIN_DIFF_FROM_HALF_PI radians from either -pi/2 or pi/2.
Input: pixd (<optional>, if not null, must be equal to pixs) pixs angle (in radians) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK); Return: pixd, or null on error.
Notes: (1) See pixHShear() for usage. (2) This does a horizontal shear about the center, with (+) shear pushing increasingly leftward (-x) with increasing y.
Input: pixd (<optional>, if not null, must be equal to pixs) pixs angle (in radians) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK); Return: pixd, or null on error.
Notes: (1) See pixHShear() for usage. (2) This does a horizontal shear about the UL corner, with (+) shear pushing increasingly leftward (-x) with increasing y.
Input: pixs liney (location of horizontal line, measured from origin) angle (in radians) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK); Return: 0 if OK; 1 on error
Notes: (1) This is an in-place version of pixHShear(); see comments there. (2) This brings in 'incolor' pixels from outside the image. (3) pixs cannot be colormapped, because the in-place operation only blits in 0 or 1 bits, not an arbitrary colormap index. (4) Does a horizontal full-band shear about the line with (+) shear pushing increasingly leftward (-x) with increasing y.
Input: pixs (8 bpp or 32 bpp, or colormapped) liney (location of horizontal line, measured from origin) angle (in radians, in range (-pi/2 ... pi/2)) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK); Return: pixd (sheared), or null on error
Notes: (1) This does horizontal shear with linear interpolation for accurate results on 8 bpp gray, 32 bpp rgb, or cmapped images. It is relatively slow compared to the sampled version implemented by rasterop, but the result is much smoother. (2) This shear leaves the horizontal line of pixels at y = liney invariant. For a positive shear angle, pixels above this line are shoved to the right, and pixels below this line move to the left. (3) Any colormap is removed. (4) The angle is brought into the range [-pi/2 + del, pi/2 - del], where del == MIN_DIFF_FROM_HALF_PI.
LEPT_DLL l_int32 pixHtmlViewer | ( | const char * | dirin, |
const char * | dirout, | ||
const char * | rootname, | ||
l_int32 | thumbwidth, | ||
l_int32 | viewwidth, | ||
l_int32 | copyorig | ||
) |
Input: dirin: directory of input image files dirout: directory for output files rootname: root name for output files thumbwidth: width of thumb images (in pixels; use 0 for default) viewwidth: maximum width of view images (no up-scaling) (in pixels; use 0 for default) copyorig: 1 to copy originals to dirout; 0 otherwise Return: 0 if OK; 1 on error
Notes: (1) The thumb and view reduced images are generated, along with two html files: <rootname>.html and <rootname>-links.html (2) The thumb and view files are named <rootname>_thumb_xxx.jpg <rootname>_view_xxx.jpg With this naming scheme, any number of input directories of images can be processed into views and thumbs and placed in the same output directory.
Input: w, h (of accumulate array) offset (initialize the 32 bpp to have this value; not more than 0x40000000) Return: pixd (32 bpp), or null on error
Notes: (1) The offset must be >= 0. (2) The offset is used so that we can do arithmetic with negative number results on l_uint32 data; it prevents the l_uint32 data from going negative. (3) Because we use l_int32 intermediate data results, these should never exceed the max of l_int32 (0x7fffffff). We do not permit the offset to be above 0x40000000, which is half way between 0 and the max of l_int32. (4) The same offset should be used for initialization, multiplication by a constant, and final extraction! (5) If you're only adding positive values, offset can be 0.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs Return: pixd, or null on error
Notes: (1) This inverts pixs, for all pixel depths. (2) There are 3 cases: (a) pixd == null, ~src --> new pixd (b) pixd == pixs, ~src --> src (in-place) (c) pixd != pixs, ~src --> input pixd (3) For clarity, if the case is known, use these patterns: (a) pixd = pixInvert(NULL, pixs); (b) pixInvert(pixs, pixs); (c) pixInvert(pixd, pixs);
LEPT_DLL l_int32 pixItalicWords | ( | PIX * | pixs, |
BOXA * | boxaw, | ||
PIX * | pixw, | ||
BOXA ** | pboxa, | ||
l_int32 | debugflag | ||
) |
Input: pixs (1 bpp) boxaw (<optional> word bounding boxes; can be NULL) pixw (<optional> word box mask; can be NULL) &boxa (<return> boxa of italian words) debugflag (1 for debug output; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) You can input the bounding boxes for the words in one of two forms: as bounding boxes () or as a word mask with the word bounding boxes filled (). For example, to compute , you can use pixWordMaskByDilation(). (2) Alternatively, you can set both of these inputs to NULL, in which case the word mask is generated here. This is done by dilating and closing the input image to connect letters within a word, while leaving the words separated. The parameters are chosen under the assumption that the input is 10 to 12 pt text, scanned at about 300 ppi. (3) sel_ital1 and sel_ital2 detect the right edges that are nearly vertical, at approximately the angle of italic strokes. We use the right edge to avoid getting seeds from lower-case 'y'. The typical italic slant has a smaller angle with the vertical than the 'W', so in most cases we will not trigger on the slanted lines in the 'W'. (4) Note that sel_ital2 is shorter than sel_ital1. It is more appropriate for a typical font scanned at 200 ppi.
LEPT_DLL PIX* pixLinearMapToTargetColor | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_uint32 | srcval, | ||
l_uint32 | dstval | ||
) |
Input: pixd (<optional>; either NULL or equal to pixs for in-place) pixs (32 bpp rgb) srcval (source color: 0xrrggbb00) dstval (target color: 0xrrggbb00) Return: pixd (with all pixels mapped based on the srcval/destval mapping), or pixd on error
Notes: (1) For each component (r, b, g) separately, this does a piecewise linear mapping of the colors in pixs to colors in pixd. If rs and rd are the red src and dest components in and , then the range [0 ... rs] in pixs is mapped to [0 ... rd] in pixd. Likewise, the range [rs ... 255] in pixs is mapped to [rd ... 255] in pixd. And similarly for green and blue. (2) The mapping will in general change the hue of the pixels. However, if the src and dst targets are related by a transformation given by pixelFractionalShift(), the hue is invariant. (3) For inplace operation, call it this way: pixLinearMapToTargetColor(pixs, pixs, ... ) (4) For generating a new pixd: pixd = pixLinearMapToTargetColor(NULL, pixs, ...)
LEPT_DLL PIX* pixLinearTRCTiled | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_int32 | sx, | ||
l_int32 | sy, | ||
PIX * | pixmin, | ||
PIX * | pixmax | ||
) |
Input: pixd (<optional> 8 bpp) pixs (8 bpp, not colormapped) sx, sy (tile dimensions) pixmin (pix of min values in tiles) pixmax (pix of max values in tiles) Return: pixd always
Notes: (1) pixd can be equal to pixs (in-place operation) or null (makes a new pixd). (2) sx and sy give the tile size; they are typically at least 20. (3) pixmin and pixmax are generated by pixMinMaxTiles() (4) For each tile, this does a linear expansion of the dynamic range so that the min value in the tile becomes 0 and the max value in the tile becomes 255. (5) The LUTs that do the mapping are generated as needed and stored for reuse in an integer array within the ptr array iaa[].
LEPT_DLL l_int32 pixLocalExtrema | ( | PIX * | pixs, |
l_int32 | maxmin, | ||
l_int32 | minmax, | ||
PIX ** | ppixmin, | ||
PIX ** | ppixmax | ||
) |
Input: pixs (8 bpp) maxmin (max allowed for the min in a 3x3 neighborhood; use 0 for default which is to have no upper bound) minmax (min allowed for the max in a 3x3 neighborhood; use 0 for default which is to have no lower bound) &ppixmin (<optional return>=""> mask of local minima) &ppixmax (<optional return>=""> mask of local maxima) Return: 0 if OK, 1 on error
Notes: (1) This gives the actual local minima and maxima. A local minimum is a pixel whose surrounding pixels all have values at least as large, and likewise for a local maximum. For the local minima, is the upper bound for the value of pixs. Likewise, for the local maxima, is the lower bound for the value of pixs. (2) The minima are found by starting with the erosion-and-equality approach of pixSelectedLocalExtrema. This is followed by a qualification step, where each c.c. in the resulting minimum mask is extracted, the pixels bordering it are located, and they are queried. If all of those pixels are larger than the value of that minimum, it is a true minimum and its c.c. is saved; otherwise the c.c. is rejected. Note that if a bordering pixel has the same value as the minimum, it must then have a neighbor that is smaller, so the component is not a true minimum. (3) The maxima are found by inverting the image and looking for the minima there. (4) The generated masks can be used as markers for further operations.
Input: pixs (any depth) thresh (for binarization of edge filter output; typ. 20) &pixb (<optional return>=""> binarized edge filtered input image) &pixm (<optional return>=""> mask over barcodes) Return: boxa (location of barcodes), or null if none found or on error
Input: pixs (HSV colorspace) factor (subsampling factor; integer) &nahue (<optional return>=""> hue histogram) &nasat (<optional return>=""> saturation histogram) Return: pixd (32 bpp histogram in hue and saturation), or null on error
Notes: (1) pixs is a 32 bpp image in HSV colorspace; hue is in the "red" byte, saturation is in the "green" byte. (2) In pixd, hue is displayed vertically; saturation horizontally. The dimensions of pixd are w = 256, h = 240, and the depth is 32 bpp. The value at each point is simply the number of pixels found at that value of hue and saturation.
Input: pixs (HSV colorspace) factor (subsampling factor; integer) &nahue (<optional return>=""> hue histogram) &naval (<optional return>=""> max intensity (value) histogram) Return: pixd (32 bpp histogram in hue and value), or null on error
Notes: (1) pixs is a 32 bpp image in HSV colorspace; hue is in the "red" byte, max intensity ("value") is in the "blue" byte. (2) In pixd, hue is displayed vertically; intensity horizontally. The dimensions of pixd are w = 256, h = 240, and the depth is 32 bpp. The value at each point is simply the number of pixels found at that value of hue and intensity.
Input: pixs (HSV colorspace) factor (subsampling factor; integer) &nasat (<optional return>=""> sat histogram) &naval (<optional return>=""> max intensity (value) histogram) Return: pixd (32 bpp histogram in sat and value), or null on error
Notes: (1) pixs is a 32 bpp image in HSV colorspace; sat is in the "green" byte, max intensity ("value") is in the "blue" byte. (2) In pixd, sat is displayed vertically; intensity horizontally. The dimensions of pixd are w = 256, h = 256, and the depth is 32 bpp. The value at each point is simply the number of pixels found at that value of saturation and intensity.
LEPT_DLL PIX* pixMakeMaskFromLUT | ( | PIX * | pixs, |
l_int32 * | tab | ||
) |
Input: pixs (2, 4 or 8 bpp; can be colormapped) tab (256-entry LUT; 1 means to write to mask) Return: pixd (1 bpp mask), or null on error
Notes: (1) This generates a 1 bpp mask image, where a 1 is written in the mask for each pixel in pixs that has a value corresponding to a 1 in the LUT. (2) The LUT should be of size 256.
LEPT_DLL PIX* pixMakeRangeMaskHS | ( | PIX * | pixs, |
l_int32 | huecenter, | ||
l_int32 | huehw, | ||
l_int32 | satcenter, | ||
l_int32 | sathw, | ||
l_int32 | regionflag | ||
) |
Input: pixs (32 bpp rgb) huecenter (center value of hue range) huehw (half-width of hue range) satcenter (center value of saturation range) sathw (half-width of saturation range) regionflag (L_INCLUDE_REGION, L_EXCLUDE_REGION) Return: pixd (1 bpp mask over selected pixels), or null on error
Notes: (1) The pixels are selected based on the specified ranges of hue and saturation. For selection or exclusion, the pixel HS component values must be within both ranges. Care must be taken in finding the hue range because of wrap-around. (2) Use == L_INCLUDE_REGION to take only those pixels within the rectangular region specified in HS space. Use == L_EXCLUDE_REGION to take all pixels except those within the rectangular region specified in HS space.
LEPT_DLL PIX* pixMakeRangeMaskHV | ( | PIX * | pixs, |
l_int32 | huecenter, | ||
l_int32 | huehw, | ||
l_int32 | valcenter, | ||
l_int32 | valhw, | ||
l_int32 | regionflag | ||
) |
Input: pixs (32 bpp rgb) huecenter (center value of hue range) huehw (half-width of hue range) valcenter (center value of max intensity range) valhw (half-width of max intensity range) regionflag (L_INCLUDE_REGION, L_EXCLUDE_REGION) Return: pixd (1 bpp mask over selected pixels), or null on error
Notes: (1) The pixels are selected based on the specified ranges of hue and max intensity values. For selection or exclusion, the pixel HV component values must be within both ranges. Care must be taken in finding the hue range because of wrap-around. (2) Use == L_INCLUDE_REGION to take only those pixels within the rectangular region specified in HV space. Use == L_EXCLUDE_REGION to take all pixels except those within the rectangular region specified in HV space.
LEPT_DLL PIX* pixMakeRangeMaskSV | ( | PIX * | pixs, |
l_int32 | satcenter, | ||
l_int32 | sathw, | ||
l_int32 | valcenter, | ||
l_int32 | valhw, | ||
l_int32 | regionflag | ||
) |
Input: pixs (32 bpp rgb) satcenter (center value of saturation range) sathw (half-width of saturation range) valcenter (center value of max intensity range) valhw (half-width of max intensity range) regionflag (L_INCLUDE_REGION, L_EXCLUDE_REGION) Return: pixd (1 bpp mask over selected pixels), or null on error
Notes: (1) The pixels are selected based on the specified ranges of saturation and max intensity (val). For selection or exclusion, the pixel SV component values must be within both ranges. (2) Use == L_INCLUDE_REGION to take only those pixels within the rectangular region specified in SV space. Use == L_EXCLUDE_REGION to take all pixels except those within the rectangular region specified in SV space.
Input: pixd (<optional> may be null) pixs (any depth; not cmapped) boxa (of boxes, to paint) op (L_SET_PIXELS, L_CLEAR_PIXELS, L_FLIP_PIXELS) Return: pixd (with masking op over the boxes), or null on error
Notes: (1) This can be used with: pixd = NULL (makes a new pixd) pixd = pixs (in-place) (2) If pixd == NULL, this first makes a copy of pixs, and then bit-twiddles over the boxes. Otherwise, it operates directly on pixs. (3) This simple function is typically used with 1 bpp images. It uses the 1-image rasterop function, rasteropUniLow(), to set, clear or flip the pixels in pixd. (4) If you want to generate a 1 bpp mask of ON pixels from the boxes in a Boxa, in a pix of size (w,h): pix = pixCreate(w, h, 1); pixMaskBoxa(pix, pix, boxa, L_SET_PIXELS);
Input: pixs (1 bpp) connectivity (4 or 8) &boxa (<optional return>=""> bounding boxes of c.c.) Return: pixd (1 bpp mask over the c.c.), or null on error
Notes: (1) This generates a mask image with ON pixels over the b.b. of the c.c. in pixs. If there are no ON pixels in pixs, pixd will also have no ON pixels.
LEPT_DLL PIX* pixMaskedThreshOnBackgroundNorm | ( | PIX * | pixs, |
PIX * | pixim, | ||
l_int32 | sx, | ||
l_int32 | sy, | ||
l_int32 | thresh, | ||
l_int32 | mincount, | ||
l_int32 | smoothx, | ||
l_int32 | smoothy, | ||
l_float32 | scorefract, | ||
l_int32 * | pthresh | ||
) |
pixMaskedThreshOnBackgroundNorm()
Input: pixs (8 bpp grayscale; not colormapped) pixim (<optional> 1 bpp 'image' mask; can be null) sx, sy (tile size in pixels) thresh (threshold for determining foreground) mincount (min threshold on counts in a tile) smoothx (half-width of block convolution kernel width) smoothy (half-width of block convolution kernel height) scorefract (fraction of the max Otsu score; typ. ~ 0.1) &thresh (<optional return>=""> threshold value that was used on the normalized image) Return: pixd (1 bpp thresholded image), or null on error
Notes: (1) This begins with a standard background normalization. Additionally, there is a flexible background norm, that will adapt to a rapidly varying background, and this puts white pixels in the background near regions with significant foreground. The white pixels are turned into a 1 bpp selection mask by binarization followed by dilation. Otsu thresholding is performed on the input image to get an estimate of the threshold in the non-mask regions. The background normalized image is thresholded with two different values, and the result is combined using the selection mask. (2) Note that the numbers 255 (for bgval target) and 190 (for thresholding on pixn) are tied together, and explicitly defined in this function. (3) See pixBackgroundNorm() for meaning and typical values of input parameters. For a start, you can try: sx, sy = 10, 15 thresh = 100 mincount = 50 smoothx, smoothy = 2
Input: pixs (32 bpp rgb or 8 bpp colormapped) threshdiff (threshold for minimum of the max difference between components) mindist (minimum allowed distance from nearest non-color pixel) Return: pixd (1 bpp, mask over color pixels), or null on error
Notes: (1) The generated mask identifies each pixel as either color or non-color. For a pixel to be color, it must satisfy two constraints: (a) The max difference between the r,g and b components must equal or exceed a threshold . (b) It must be at least (in an 8-connected way) from the nearest non-color pixel. (2) The distance constraint (b) is only applied if > 1. For example, if == 2, the color pixels identified by (a) are eroded by a 3x3 Sel. In general, the Sel size for erosion is 2 * ( - 1) + 1. Why have this constraint? In scanned images that are essentially gray, color artifacts are typically introduced in transition regions near sharp edges that go from dark to light, so this allows these transition regions to be removed.
LEPT_DLL PIX* pixMaxDynamicRange | ( | PIX * | pixs, |
l_int32 | type | ||
) |
Input: pixs (4, 8, 16 or 32 bpp source) type (L_LINEAR_SCALE or L_LOG_SCALE) Return: pixd (8 bpp), or null on error
Notes: (1) Scales pixel values to fit maximally within the dest 8 bpp pixd (2) Uses a LUT for log scaling
Input: pix (8 bpp) box (region to compute mean value) pixma (mean accumulator) &val (<return> mean value Return: 0 if OK, 1 on error
Notes: (1) This function is intended to be used for many rectangles on the same image. It can find the mean within a rectangle in O(1), independent of the size of the rectangle.
LEPT_DLL DPIX* pixMeanSquareAccum | ( | PIX * | pixs | ) |
Input: pixs (8 bpp grayscale) Return: dpix (64 bit array), or null on error
Notes: (1) Similar to pixBlockconvAccum(), this computes the sum of the squares of the pixel values in such a way that the value at (i,j) is the sum of all squares in the rectangle from the origin to (i,j). (2) The general recursion relation (v are squared pixel values) is a(i,j) = v(i,j) + a(i-1, j) + a(i, j-1) - a(i-1, j-1) For the first line, this reduces to the special case a(i,j) = v(i,j) + a(i, j-1) For the first column, the special case is a(i,j) = v(i,j) + a(i-1, j)
LEPT_DLL l_int32 pixMeasureEdgeSmoothness | ( | PIX * | pixs, |
l_int32 | side, | ||
l_int32 | minjump, | ||
l_int32 | minreversal, | ||
l_float32 * | pjpl, | ||
l_float32 * | pjspl, | ||
l_float32 * | prpl, | ||
const char * | debugfile | ||
) |
Input: pixs (1 bpp) side (L_FROM_LEFT, L_FROM_RIGHT, L_FROM_TOP, L_FROM_BOTTOM) minjump (minimum jump to be counted; >= 1) minreversal (minimum reversal size for new peak or valley) &jpl (<optional return>=""> jumps/length: number of jumps, normalized to length of component side) &jspl (<optional return>=""> jumpsum/length: sum of all sufficiently large jumps, normalized to length of component side) &rpl (<optional return>=""> reversals/length: number of peak-to-valley or valley-to-peak reversals, normalized to length of component side) debugfile (<optional> displays constructed edge; use NULL for no output) Return: 0 if OK, 1 on error
Notes: (1) This computes three measures of smoothness of the edge of a connected component: * jumps/length: (jpl) the number of jumps of size >= , normalized to the length of the side * jump sum/length: (jspl) the sum of all jump lengths of size >= , normalized to the length of the side * reversals/length: (rpl) the number of peak <--> valley reversals, using as a minimum deviation of the peak or valley from its preceeding extremum, normalized to the length of the side (2) The input pix should be a single connected component, but this is not required.
Input: pixs (32 bpp rgb) factor (subsampling factor; integer >= 1) &sat (<return> average saturation) Return: pixd, or null on error
Input: pixs (32 bpp; rgb color) sigbits (valid: 5 or 6) subsample (integer > 0) Return: histo (1-d array, giving the number of pixels in each quantized region of color space), or null on error
Notes: (1) Array is indexed by (3 * sigbits) bits. The array size is 2^(3 * sigbits). (2) Indexing into the array from rgb uses red sigbits as most significant and blue as least.
LEPT_DLL PIX* pixMedianCutQuant | ( | PIX * | pixs, |
l_int32 | ditherflag | ||
) |
Input: pixs (32 bpp; rgb color) ditherflag (1 for dither; 0 for no dither) Return: pixd (8 bit with colormap), or null on error
Notes: (1) Simple interface. See pixMedianCutQuantGeneral() for use of defaulted parameters.
LEPT_DLL PIX* pixMedianCutQuantGeneral | ( | PIX * | pixs, |
l_int32 | ditherflag, | ||
l_int32 | outdepth, | ||
l_int32 | maxcolors, | ||
l_int32 | sigbits, | ||
l_int32 | maxsub, | ||
l_int32 | checkbw | ||
) |
Input: pixs (32 bpp; rgb color) ditherflag (1 for dither; 0 for no dither) outdepth (output depth; valid: 0, 1, 2, 4, 8) maxcolors (between 2 and 256) sigbits (valid: 5 or 6; use 0 for default) maxsub (max subsampling, integer; use 0 for default; 1 for no subsampling) checkbw (1 to check if color content is very small, 0 to assume there is sufficient color) Return: pixd (8 bit with colormap), or null on error
Notes: (1) must be in the range [2 ... 256]. (2) Use = 0 to have the output depth computed as the minimum required to hold the actual colors found, given the constraint. (3) Use = 1, 2, 4 or 8 to specify the output depth. In that case, must not exceed 2^(outdepth). (4) If there are fewer quantized colors in the image than , the colormap is simply generated from those colors. (5) is the maximum allowed subsampling to be used in the computation of the color histogram and region of occupied color space. The subsampling is chosen internally for efficiency, based on the image size, but this parameter limits it. Use = 0 for the internal default, which is the maximum allowed subsampling. Use = 1 to prevent subsampling. In general use >= 1 to specify the maximum subsampling to be allowed, where the actual subsampling will be the minimum of this value and the internally determined default value. (6) If the image appears gray because either most of the pixels are gray or most of the pixels are essentially black or white, the image is trivially quantized with a grayscale colormap. The reason is that median cut divides the color space into rectangular regions, and it does a very poor job if all the pixels are near the diagonal of the color space cube.
LEPT_DLL PIX* pixMedianCutQuantMixed | ( | PIX * | pixs, |
l_int32 | ncolor, | ||
l_int32 | ngray, | ||
l_int32 | darkthresh, | ||
l_int32 | lightthresh, | ||
l_int32 | diffthresh | ||
) |
Input: pixs (32 bpp; rgb color) ncolor (maximum number of colors assigned to pixels with significant color) ngray (number of gray colors to be used; must be >= 2) darkthresh (threshold near black; if the lightest component is below this, the pixel is not considered to be gray or color; uses 0 for default) lightthresh (threshold near white; if the darkest component is above this, the pixel is not considered to be gray or color; use 0 for default) diffthresh (thresh for the max difference between component values; for differences below this, the pixel is considered to be gray; use 0 for default) Return: pixd (8 bpp cmapped), or null on error
Notes: (1) ncolor + ngray must not exceed 255. (2) The method makes use of pixMedianCutQuantGeneral() with minimal addition. (a) Preprocess the image, setting all pixels with little color to black, and populating an auxiliary 8 bpp image with the expected colormap values corresponding to the set of quantized gray values. (b) Color quantize the altered input image to n + 1 colors. (c) Augment the colormap with the gray indices, and substitute the gray quantized values from the auxiliary image for those in the color quantized output that had been quantized as black. (3) Median cut color quantization is relatively poor for grayscale images with many colors, when compared to octcube quantization. Thus, for images with both gray and color, it is important to quantize the gray pixels by another method. Here, we are conservative in detecting color, preferring to use a few extra bits to encode colorful pixels that push them to gray. This is particularly reasonable with this function, because it handles the gray and color pixels separately, using median cut color quantization for the color pixels and equal-bin grayscale quantization for the non-color pixels.
Input: pixs (8 or 32 bpp; no colormap) wf, hf (width and height of filter; each is >= 1) Return: pixd (of median values), or null on error
LEPT_DLL l_int32 pixMinMaxTiles | ( | PIX * | pixs, |
l_int32 | sx, | ||
l_int32 | sy, | ||
l_int32 | mindiff, | ||
l_int32 | smoothx, | ||
l_int32 | smoothy, | ||
PIX ** | ppixmin, | ||
PIX ** | ppixmax | ||
) |
Input: pixs (8 bpp grayscale; not colormapped) sx, sy (tile dimensions) mindiff (minimum difference to accept as valid) smoothx, smoothy (half-width of convolution kernel applied to min and max arrays: use 0 for no smoothing) &pixmin (<return> tiled minima) &pixmax (<return> tiled maxima) Return: 0 if OK, 1 on error
Notes: (1) This computes filtered and smoothed values for the min and max pixel values in each tile of the image. (2) See pixContrastNorm() for usage.
Input: pixd (<optional> destination: this can be null, equal to pixs1, or different from pixs1) pixs1 (can be == to pixd) pixs2 type (L_CHOOSE_MIN, L_CHOOSE_MAX) Return: pixd always
Notes: (1) This gives the min or max of two images. (2) The depth can be 8 or 16 bpp. (3) There are 3 cases:
Input: pixs (1 bpp, deskewed, English text) &conf (<return> confidence that text is not LR mirror reversed) mincount (min number of left + right; use 0 for default) debug (1 for debug output; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) For this test, it is necessary that the text is horizontally oriented, with ascenders going up. (2) conf is the normalized difference between the number of right and left facing characters with ascenders. Left-facing are {d}; right-facing are {b, h, k}. At least that was the expectation. In practice, we can really just say that it is the normalized difference in hits using two specific hit-miss filters, textsel1 and textsel2, after the image has been suitably pre-filtered so that these filters are effective. See (4) for what's really happening. (3) A large positive conf value indicates normal text, whereas a large negative conf value means the page is mirror reversed. (4) The implementation is a bit tricky. The general idea is to fill the x-height part of characters, but not the space between them, before doing the HMT. This is done by finding pixels added using two different operations -- a horizontal close and a vertical dilation -- and adding the intersection of these sets to the original. It turns out that the original intuition about the signal was largely in error: much of the signal for right-facing characters comes from the lower part of common x-height characters, like the e and c, that remain open after these operations. So it's important that the operations to close the x-height parts of the characters are purposely weakened sufficiently to allow these characters to remain open. The wonders of morphology!
LEPT_DLL l_int32 pixMirrorDetectDwa | ( | PIX * | pixs, |
l_float32 * | pconf, | ||
l_int32 | mincount, | ||
l_int32 | debug | ||
) |
Input: pixs (1 bpp, deskewed, English text) &conf (<return> confidence that text is not LR mirror reversed) mincount (min number of left + right; use 0 for default) debug (1 for debug output; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) We assume the text is horizontally oriented, with ascenders going up. (2) See notes in pixMirrorDetect().
Input: pixs (8 or 32 bpp, small tile; to be replicated) w, h (dimensions of output pix) Return: pixd (usually larger pix, mirror-tiled with pixs), or null on error
Notes: (1) This uses mirrored tiling, where each row alternates with LR flips and every column alternates with TB flips, such that the result is a tiling with identical 2 x 2 tiles, each of which is composed of these transforms: ----------------- | 1 | LR | ----------------- | TB | LR/TB | -----------------
Input: pixd (<optional> can be null or equal to pixs) pixs (32 bpp rgb) fract (between -1.0 and 1.0) Return: pixd, or null on error
Notes: (1) pixd must either be null or equal to pixs. For in-place operation, set pixd == pixs: pixEqualizeTRC(pixs, pixs, ...); To get a new image, set pixd == null: pixd = pixEqualizeTRC(NULL, pixs, ...); (1) Use fract > 0.0 to increase hue value; < 0.0 to decrease it. 1.0 (or -1.0) represents a 360 degree rotation; i.e., no change. (2) If no modification is requested (fract = -1.0 or 0 or 1.0), return a copy unless in-place, in which case this is a no-op.
Input: pixd (<optional> can be null, existing or equal to pixs) pixs (32 bpp rgb) fract (between -1.0 and 1.0) Return: pixd, or null on error
Notes: (1) If fract > 0.0, it gives the fraction that the pixel saturation is moved from its initial value toward 255. If fract < 0.0, it gives the fraction that the pixel saturation is moved from its initial value toward 0. The limiting values for fract = -1.0 (1.0) thus set the saturation to 0 (255). (2) If fract = 0, no modification is requested; return a copy unless in-place, in which case this is a no-op.
LEPT_DLL PIX* pixMorphCompSequence | ( | PIX * | pixs, |
const char * | sequence, | ||
l_int32 | dispsep | ||
) |
Input: pixs sequence (string specifying sequence) dispsep (controls debug display of each result in the sequence: 0: no output > 0: gives horizontal separation in pixels between successive displays < 0: pdf output; abs(dispsep) is used for naming) Return: pixd, or null on error
Notes: (1) This does rasterop morphology on binary images, using composite operations for extra speed on large Sels. (2) Safe closing is used atomically. However, if you implement a closing as a sequence with a dilation followed by an erosion, it will not be safe, and to ensure that you have no boundary effects you must add a border in advance and remove it at the end. (3) For other usage details, see the notes for pixMorphSequence(). (4) The sequence string is formatted as follows:
LEPT_DLL PIX* pixMorphCompSequenceDwa | ( | PIX * | pixs, |
const char * | sequence, | ||
l_int32 | dispsep | ||
) |
Input: pixs sequence (string specifying sequence) dispsep (controls debug display of each result in the sequence: 0: no output > 0: gives horizontal separation in pixels between successive displays < 0: pdf output; abs(dispsep) is used for naming) Return: pixd, or null on error
Notes: (1) This does dwa morphology on binary images, using brick Sels. (2) This runs a pipeline of operations; no branching is allowed. (3) It implements all brick Sels that have dimensions up to 63 on each side, using a composite (linear + comb) when useful. (4) A new image is always produced; the input image is not changed. (5) This contains an interpreter, allowing sequences to be generated and run. (6) See pixMorphSequence() for further information about usage.
PIX * pixMorphDwa_1 | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_int32 | operation, | ||
char * | selname | ||
) |
Input: pixd (usual 3 choices: null, == pixs, != pixs) pixs (1 bpp) operation (L_MORPH_DILATE, L_MORPH_ERODE, L_MORPH_OPEN, L_MORPH_CLOSE) sel name Return: pixd
Notes: (1) This simply adds a border, calls the appropriate pixFMorphopGen_*(), and removes the border. See the notes for that function. (2) The size of the border depends on the operation and the boundary conditions.
Top-level fast binary morphology with auto-generated sels
PIX *pixMorphDwa_1() PIX *pixFMorphopGen_1()
Input: pixd (usual 3 choices: null, == pixs, != pixs) pixs (1 bpp) operation (L_MORPH_DILATE, L_MORPH_ERODE, L_MORPH_OPEN, L_MORPH_CLOSE) sel name Return: pixd
Notes: (1) This simply adds a border, calls the appropriate pixFMorphopGen_*(), and removes the border. See the notes for that function. (2) The size of the border depends on the operation and the boundary conditions.
PIX * pixMorphDwa_2 | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_int32 | operation, | ||
char * | selname | ||
) |
Input: pixd (usual 3 choices: null, == pixs, != pixs) pixs (1 bpp) operation (L_MORPH_DILATE, L_MORPH_ERODE, L_MORPH_OPEN, L_MORPH_CLOSE) sel name Return: pixd
Notes: (1) This simply adds a border, calls the appropriate pixFMorphopGen_*(), and removes the border. See the notes for that function. (2) The size of the border depends on the operation and the boundary conditions.
Top-level fast binary morphology with auto-generated sels
PIX *pixMorphDwa_2() PIX *pixFMorphopGen_2()
Input: pixd (usual 3 choices: null, == pixs, != pixs) pixs (1 bpp) operation (L_MORPH_DILATE, L_MORPH_ERODE, L_MORPH_OPEN, L_MORPH_CLOSE) sel name Return: pixd
Notes: (1) This simply adds a border, calls the appropriate pixFMorphopGen_*(), and removes the border. See the notes for that function. (2) The size of the border depends on the operation and the boundary conditions.
Input: pixs hsize (of Sel; must be odd; origin implicitly in center) vsize (ditto) smoothing (half-width of convolution smoothing filter. The width is (2 * smoothing + 1), so 0 is no-op. Return: pixd, or null on error
LEPT_DLL PIX* pixMorphSequence | ( | PIX * | pixs, |
const char * | sequence, | ||
l_int32 | dispsep | ||
) |
Input: pixs sequence (string specifying sequence) dispsep (controls debug display of each result in the sequence: 0: no output > 0: gives horizontal separation in pixels between successive displays < 0: pdf output; abs(dispsep) is used for naming) Return: pixd, or null on error
Notes: (1) This does rasterop morphology on binary images. (2) This runs a pipeline of operations; no branching is allowed. (3) This only uses brick Sels, which are created on the fly. In the future this will be generalized to extract Sels from a Sela by name. (4) A new image is always produced; the input image is not changed. (5) This contains an interpreter, allowing sequences to be generated and run. (6) The format of the sequence string is defined below. (7) In addition to morphological operations, rank order reduction and replicated expansion allow operations to take place downscaled by a power of 2. (8) Intermediate results can optionally be displayed. (9) Thanks to Dar-Shyang Lee, who had the idea for this and built the first implementation. (10) The sequence string is formatted as follows:
LEPT_DLL PIX* pixMorphSequenceByComponent | ( | PIX * | pixs, |
const char * | sequence, | ||
l_int32 | connectivity, | ||
l_int32 | minw, | ||
l_int32 | minh, | ||
BOXA ** | pboxa | ||
) |
Input: pixs (1 bpp) sequence (string specifying sequence) connectivity (4 or 8) minw (minimum width to consider; use 0 or 1 for any width) minh (minimum height to consider; use 0 or 1 for any height) &boxa (<optional> return boxa of c.c. in pixs) Return: pixd, or null on error
Notes: (1) See pixMorphSequence() for composing operation sequences. (2) This operates separately on each c.c. in the input pix. (3) The dilation does NOT increase the c.c. size; it is clipped to the size of the original c.c. This is necessary to keep the c.c. independent after the operation. (4) You can specify that the width and/or height must equal or exceed a minimum size for the operation to take place. (5) Use NULL for boxa to avoid returning the boxa.
LEPT_DLL PIX* pixMorphSequenceByRegion | ( | PIX * | pixs, |
PIX * | pixm, | ||
const char * | sequence, | ||
l_int32 | connectivity, | ||
l_int32 | minw, | ||
l_int32 | minh, | ||
BOXA ** | pboxa | ||
) |
Input: pixs (1 bpp) pixm (mask specifying regions) sequence (string specifying sequence) connectivity (4 or 8, used on mask) minw (minimum width to consider; use 0 or 1 for any width) minh (minimum height to consider; use 0 or 1 for any height) &boxa (<optional> return boxa of c.c. in pixm) Return: pixd, or null on error
Notes: (1) See pixMorphCompSequence() for composing operation sequences. (2) This operates separately on the region in pixs corresponding to each c.c. in the mask pixm. It differs from pixMorphSequenceByComponent() in that the latter does not have a pixm (mask), but instead operates independently on each component in pixs. (3) Dilation will NOT increase the region size; the result is clipped to the size of the mask region. This is necessary to make regions independent after the operation. (4) You can specify that the width and/or height of a region must equal or exceed a minimum size for the operation to take place. (5) Use NULL for to avoid returning the boxa.
LEPT_DLL PIX* pixMorphSequenceDwa | ( | PIX * | pixs, |
const char * | sequence, | ||
l_int32 | dispsep | ||
) |
Input: pixs sequence (string specifying sequence) dispsep (controls debug display of each result in the sequence: 0: no output > 0: gives horizontal separation in pixels between successive displays < 0: pdf output; abs(dispsep) is used for naming) Return: pixd, or null on error
Notes: (1) This does dwa morphology on binary images. (2) This runs a pipeline of operations; no branching is allowed. (3) This only uses brick Sels that have been pre-compiled with dwa code. (4) A new image is always produced; the input image is not changed. (5) This contains an interpreter, allowing sequences to be generated and run. (6) See pixMorphSequence() for further information about usage.
LEPT_DLL PIX* pixMorphSequenceMasked | ( | PIX * | pixs, |
PIX * | pixm, | ||
const char * | sequence, | ||
l_int32 | dispsep | ||
) |
Input: pixs (1 bpp) pixm (<optional> 1 bpp mask) sequence (string specifying sequence of operations) dispsep (horizontal separation in pixels between successive displays; use zero to suppress display) Return: pixd, or null on error
Notes: (1) This applies the morph sequence to the image, but only allows changes in pixs for pixels under the background of pixm. (5) If pixm is NULL, this is just pixMorphSequence().
Input: pixs (32 bpp) factor offset (same as used for initialization) Return: 0 if OK; 1 on error
Notes: (1) The offset must be >= 0 and should not exceed 0x40000000. (2) This multiplies each pixel, relative to offset, by the input factor (3) The result is returned with the offset back in place.
LEPT_DLL PIX* pixMultConstantColor | ( | PIX * | pixs, |
l_float32 | rfact, | ||
l_float32 | gfact, | ||
l_float32 | bfact | ||
) |
LEPT_DLL l_int32 pixMultConstantGray | ( | PIX * | pixs, |
l_float32 | val | ||
) |
Input: pixs (8, 16 or 32 bpp) val (>= 0.0; amount to multiply by each pixel) Return: 0 if OK, 1 on error
Notes: (1) In-place operation; val must be >= 0. (2) No clipping for 32 bpp. (3) For 8 and 16 bpp, the result is clipped to 0xff and 0xffff, rsp.
Input: pixd (can be NULL or pixs) pixs (32 bpp rgb) box (region for filtering; can be NULL)) color (32 bit color in 0xrrggbb00 format) Return: pixd always
Notes: (1) This filters all pixels in the specified region by multiplying each component by the input color. This leaves black invariant and transforms white to the input color. (2) If pixd == pixs, this is done in-place. (3) If box == NULL, this is performed on all of pixs.
LEPT_DLL PIX* pixMultMatrixColor | ( | PIX * | pixs, |
L_KERNEL * | kel | ||
) |
LEPT_DLL l_int32 pixNumberOccupiedOctcubes | ( | PIX * | pix, |
l_int32 | level, | ||
l_int32 | mincount, | ||
l_float32 | minfract, | ||
l_int32 * | pncolors | ||
) |
Input: pix (32 bpp) level (of octcube) mincount (minimum num pixels in an octcube to be counted; -1 to not use) minfract (minimum fract of pixels in an octcube to be counted; -1 to not use) &ncolors (<return> number of occupied octcubes) Return: 0 if OK, 1 on error
Notes: (1) Exactly one of (, ) must be -1, so, e.g., if == -1, then we use . (2) If all occupied octcubes are to count, set == 1. Setting == 0.0 is taken to mean the same thing.
pixNumColors() Input: pixs (2, 4, 8, 32 bpp) factor (subsampling factor; integer) &ncolors (<return> the number of colors found, or 0 if there are more than 256) Return: 0 if OK, 1 on error.
Notes: (1) This returns the actual number of colors found in the image, even if there is a colormap. If == 1 and the number of colors differs from the number of entries in the colormap, a warning is issued. (2) Use == 1 to find the actual number of colors. Use > 1 to quickly find the approximate number of colors. (3) For d = 2, 4 or 8 bpp grayscale, this returns the number of colors found in the image in 'ncolors'. (4) For d = 32 bpp (rgb), if the number of colors is greater than 256, this returns 0 in 'ncolors'.
LEPT_DLL l_int32 pixNumSignificantGrayColors | ( | PIX * | pixs, |
l_int32 | darkthresh, | ||
l_int32 | lightthresh, | ||
l_float32 | minfract, | ||
l_int32 | factor, | ||
l_int32 * | pncolors | ||
) |
Input: pixs (8 bpp gray) darkthresh (dark threshold for minimum intensity to be considered; typ. 20) lightthresh (threshold near white, for maximum intensity to be considered; typ. 236) minfract (minimum fraction of all pixels to include a level as significant; typ. 0.0001; should be < 0.001) factor (subsample factor; integer >= 1) &ncolors (<return> number of significant colors; 0 on error) Return: 0 if OK, 1 on error
Notes: (1) This function is asking the question: how many perceptually significant gray color levels is in this pix? A color level must meet 3 criteria to be significant:
Input: pixs (32 bpp rgb) level (significant bits for each of RGB; valid in [1...6]) &ncolors (<optional return>=""> number of occupied cubes) Return: numa (histogram of color pixels, or null on error)
Notes: (1) Input NULL for &ncolors to prevent computation and return value.
LEPT_DLL PIX* pixOctcubeQuantFromCmap | ( | PIX * | pixs, |
PIXCMAP * | cmap, | ||
l_int32 | mindepth, | ||
l_int32 | level, | ||
l_int32 | metric | ||
) |
Input: pixs (32 bpp rgb) cmap (to quantize to; insert copy into dest pix) mindepth (minimum depth of pixd: can be 2, 4 or 8 bpp) level (of octcube used for finding nearest color in cmap) metric (L_MANHATTAN_DISTANCE, L_EUCLIDEAN_DISTANCE) Return: pixd (2, 4 or 8 bpp, colormapped), or null on error
Notes: (1) In typical use, we are doing an operation, such as interpolative scaling, on a colormapped pix, where it is necessary to remove the colormap before the operation. We then want to re-quantize the RGB result using the same colormap. (2) The level is used to divide the color space into octcubes. Each input pixel is, in effect, placed at the center of an octcube at the given level, and it is mapped into the exact color (given in the colormap) that is the closest to that location. We need to know that distance, for each color in the colormap. The higher the level of the octtree, the smaller the octcubes in the color space, and hence the more accurately we can determine the closest color in the colormap; however, the size of the LUT, which is the total number of octcubes, increases by a factor of 8 for each increase of 1 level. The time required to acquire a level 4 mapping table, which has about 4K entries, is less than 1 msec, so that is the recommended minimum size to be used. At that size, the octcubes have their centers 16 units apart in each (r,g,b) direction. If two colors are in the same octcube, the one closest to the center will always be chosen. The maximum error for any component occurs when the correct color is at a cube corner and there is an incorrect color just inside the cube next to the opposite corner, giving an error of 14 units (out of 256) for each component. Using a level 5 mapping table reduces the maximum error to 6 units. (3) Typically you should use the Euclidean metric, because the resulting voronoi cells (which are generated using the actual colormap values as seeds) are convex for Euclidean distance but not for Manhattan distance. In terms of the octcubes, convexity of the voronoi cells means that if the 8 corners of any cube (of which the octcubes are special cases) are all within a cell, then every point in the cube will lie within the cell. (4) The depth of the output pixd is equal to the maximum of (a) and (b) the minimum (2, 4 or 8 bpp) necessary to hold the indices in the colormap. (5) We build a mapping table from octcube to colormap index so that this function can run in a time (otherwise) independent of the number of colors in the colormap. This avoids a brute-force search for the closest colormap color to each pixel in the image. (6) This is similar to the function pixAssignToNearestColor() used for color segmentation. (7) Except for very small images or when using level > 4, it takes very little time to generate the tables, compared to the generation of the colormapped dest pix, so one would not typically use the low-level version.
LEPT_DLL PIX* pixOctcubeQuantFromCmapLUT | ( | PIX * | pixs, |
PIXCMAP * | cmap, | ||
l_int32 | mindepth, | ||
l_int32 * | cmaptab, | ||
l_uint32 * | rtab, | ||
l_uint32 * | gtab, | ||
l_uint32 * | btab | ||
) |
Input: pixs (32 bpp rgb) cmap (to quantize to; insert copy into dest pix) mindepth (minimum depth of pixd: can be 2, 4 or 8 bpp) cmaptab (table mapping from octindex to colormap index) rtab, gtab, btab (tables mapping from RGB to octindex) Return: pixd (2, 4 or 8 bpp, colormapped), or null on error
Notes: (1) See the notes in the higher-level function pixOctcubeQuantFromCmap(). The octcube level for the generated octree is specified there, along with the distance metric for determining the closest color in the colormap to each octcube. (2) If the colormap, level and metric information have already been used to construct the set of mapping tables, this low-level function can be used directly (i.e., independently of pixOctcubeQuantFromCmap()) to build a colormapped pix that uses the specified colormap.
LEPT_DLL PIX* pixOctcubeQuantMixedWithGray | ( | PIX * | pixs, |
l_int32 | depth, | ||
l_int32 | graylevels, | ||
l_int32 | delta | ||
) |
pixOctcubeQuantMixedWithGray()
Input: pixs (32 bpp rgb) depth (of output pix) graylevels (grayscale) delta (threshold for deciding if a pix is color or grayscale) Return: pixd (quantized to octcube and gray levels) or null on error
Notes: (1) Generates a colormapped image, where the colormap table values have two components: octcube values representing pixels with color content, and grayscale values for the rest. (2) The threshold (delta) is the maximum allowable difference of the max abs value of | r - g |, | r - b | and | g - b |. (3) The octcube values are the averages of all pixels that are found in the octcube, and that are far enough from gray to be considered color. This can roughly be visualized as all the points in the rgb color cube that are not within a "cylinder" of diameter approximately 'delta' along the main diagonal. (4) We want to guarantee full coverage of the rgb color space; thus, if the output depth is 4, the octlevel is 1 (2 x 2 x 2 = 8 cubes) and if the output depth is 8, the octlevel is 2 (4 x 4 x 4 = 64 cubes). (5) Consequently, we have the following constraint on the number of allowed gray levels: for 4 bpp, 8; for 8 bpp, 192.
Input: pixs (32 bpp; 24-bit color) colors (in colormap; some number in range [128 ... 256]; the actual number of colors used will be smaller) ditherflag (1 to dither, 0 otherwise) Return: pixd (8 bpp with colormap), or null on error
I found one description in the literature of octree color quantization, using progressive truncation of the octree, by M. Gervautz and W. Purgathofer in Graphics Gems, pp. 287-293, ed. A. Glassner, Academic Press, 1990. Rather than setting up a fixed partitioning of the color space ab initio, as we do here, they allow the octree to be progressively truncated as new pixels are added. They need to set up some data structures that are traversed with the addition of each 24 bit pixel, in order to decide either (1) in which cluster (sub-branch of the octree) to put the pixel, or (2) whether to truncate the octree further to place the pixel in an existing cluster, or (3) which two existing clusters should be merged so that the pixel can be left to start a truncated leaf of the octree. Such dynamic truncation is considerably more complicated, and Gervautz et al. did not explain how they did it in anywhere near the detail required to check their implementation.
The simple method in pixFixedOctcubeQuant256() is very fast, and with dithering the results are good, but you can do better if the color clusters are selected adaptively from the image. We want a method that makes much better use of color samples in regions of color space with high pixel density, while also fairly representing small numbers of color pixels in low density regions. Such adaptation requires two passes through the image: the first for generating the pruned tree of color cubes and the second for computing the index into the color table for each pixel.
A relatively simple adaptive method is pixOctreeQuantByPopulation(). That function first determines if the image has very few colors, and, if so, quantizes to those colors. If there are more than 256 colors, it generates a histogram of octcube leaf occupancy at level 4, chooses the 192 most populated such leaves as the first 192 colors, and sets the remaining 64 colors to the residual average pixel values in each of the 64 level 2 octcubes. This is a bit faster than pixOctreeColorQuant(), and does very well without dithering, but for most images with dithering it is clearly inferior.
We now describe pixOctreeColorQuant(). The first pass is done on a subsampled image, because we do not need to use all the pixels in the image to generate the tree. Subsampling down to 0.25 (1/16 of the pixels) makes the program run about 1.3 times faster.
Instead of dividing the color space into 256 equal-sized regions, we initially divide it into 2^12 or 2^15 or 2^18 equal-sized octcubes. Suppose we choose to use 2^18 octcubes. This gives us 6 octree levels. We then prune back, starting from level 6. For every cube at level 6, there are 8 cubes at level 5. Call the operation of putting a cube aside as a color table entry (CTE) a "saving." We use a (in general) level-dependent threshold, and save those level 6 cubes that are above threshold. The rest are combined into the containing level 5 cube. If between 1 and 7 level 6 cubes within a level 5 cube have been saved by thresholding, then the remaining level 6 cubes in that level 5 cube are automatically saved as well, without applying a threshold. This greatly simplifies both the description of the CTEs and the later classification of each pixel as belonging to a CTE. This procedure is iterated through every cube, starting at level 5, and then 4, 3, and 2, successively. The result is that each CTE contains the entirety of a set of from 1 to 7 cubes from a given level that all belong to a single cube at the level above. We classify the CTEs in terms of the condition in which they are made as either being "threshold" or "residual." They are "threshold" CTEs if no subcubes are CTEs (that is, they contain every pixel within the cube) and the number of pixels exceeds the threshold for making a CTE. They are "residual" CTEs if at least one but not more than 7 of the subcubes have already been determined to be CTEs; this happens automatically -- no threshold is applied. If all 8 subcubes are determined to be CTEs, the cube is marked as having all pixels accounted for ('bleaf' = 1) but is not saved as a CTE.
We stop the pruning at level 2, at which there are 64 sub-cubes. Any pixels not already claimed in a CTE are put in these cubes.
As the cubes are saved as color samples in the color table, the number of remaining pixels P and the number of remaining colors in the color table N are recomputed, along with the average number of pixels P/N (ppc) to go in each of the remaining colors. This running average number is used to set the threshold at the current level.
Because we are going to very small cubes at levels 6 or 5, and will dither the colors for errors, it is not necessary to compute the color center of each cluster; we can simply use the center of the cube. This gives us a minimax error condition: the maximum error is half the width of the level 2 cubes -- 32 color values out of 256 -- for each color sample. In practice, most of the pixels will be very much closer to the center of their cells. And with dithering, the average pixel color in a small region will be closer still. Thus with the octree quantizer, we are able to capture regions of high color pdf (probability density function) in small but accurate CTEs, and to have only a small number of pixels that end up a significant distance (with a guaranteed maximum) from their true color.
How should the threshold factor vary? Threshold factors are required for levels 2, 3, 4 and 5 in the pruning stage. The threshold for level 5 is actually applied to cubes at level 6, etc. From various experiments, it appears that the results do not vary appreciably for threshold values near 1.0. If you want more colors in smaller cubes, the threshold factors can be set lower than 1.0 for cubes at levels 4 and 5. However, if the factor is set much lower than 1.0 for levels 2 and 3, we can easily run out of colors. We put aside 64 colors in the calculation of the threshold values, because we must have 64 color centers at level 2, that will have very few pixels in most of them. If we reduce the factor for level 5 to 0.4, this will generate many level 6 CTEs, and consequently many residual cells will be formed up from those leaves, resulting in the possibility of running out of colors. Remember, the residual CTEs are mandatory, and are formed without using the threshold, regardless of the number of pixels that are absorbed.
The implementation logically has four parts:
(1) accumulation into small, fixed cells (2) pruning back into selected CTE cubes (3) organizing the CTEs for fast search to find the CTE to which any image pixel belongs (4) doing a second scan to code the image pixels by CTE
Step (1) is straightforward; we use 2^15 cells.
We've already discussed how the pruning step (2) will be performed.
Steps (3) and (4) are related, in that the organization used by step (3) determines how the search actually takes place for each pixel in step (4).
There are many ways to do step (3). Let's explore a few.
(a) The simplest is to order the cubes from highest occupancy to lowest, and traverse the list looking for the deepest match. To make this more efficient, so that we know when to stop looking, any cube that has separate CTE subcubes would be marked as such, so that we know when we hit a true leaf.
(b) Alternatively, we can order the cubes by highest occupancy separately each level, and work upward, starting at level 5, so that when we find a match we know that it will be correct.
(c) Another approach would be to order the cubes by "address" and use a hash table to find the cube corresponding to a pixel color. I don't know how to do this with a variable length address, as each CTE will have 3*n bits, where n is the level.
(d) Another approach entirely is to put the CTE cubes into a tree, in such a way that starting from the root, and using 3 bits of address at a time, the correct branch of each octree can be taken until a leaf is found. Because a given cube can be both a leaf and also have branches going to sub-cubes, the search stops only when no marked subcubes have addresses that match the given pixel.
In the tree method, we can start with a dense infrastructure, and place the leaves corresponding to the N colors in the tree, or we can grow from the root only those branches that end directly on leaves.
What we do here is to take approach (d), and implement the tree "virtually", as a set of arrays, one array for each level of the tree. Initially we start at level 5, an array with 2^15 cubes, each with 8 subcubes. We then build nodes at levels closer to the root; at level 4 there are 2^12 nodes each with 8 subcubes; etc. Using these arrays has several advantages:
Canonical addressing guarantees that the i-th node at level k has 8 subnodes given by the 8*i ... 8*i+7 nodes at level k+1.
The pruning step works as follows. We go from the lowest level up. At each level, the threshold is found from the product of a factor near 1.0 and the ratio of unmarked pixels to remaining colors (minus the 64). We march through the space, sequentially considering a cube and its 8 subcubes. We first check those subcubes that are not already marked as CTE to see if any are above threshold, and if so, generate a CTE and mark them as such. We then determine if any of the subcubes have been marked. If so, and there are subcubes that are not marked, we generate a CTE for the cube from the remaining unmarked subcubes; this is mandatory and does not depend on how many pixels are in the set of subcubes. If none of the subcubes are marked, we aggregate their pixels into the cube containing them, but do not mark it as a CTE; that will be determined when iterating through the next level up.
When all the pixels in a cube are accounted for in one or more colors, we set the boolean 'bleaf' to true. This is the flag used to mark the cubes in the pruning step. If a cube is marked, and all 8 subcubes are marked, then it is not itself given a CTE because all pixels have already been accounted for.
Note that the pruning of the tree and labelling of the CTEs (step 2) accomplishes step 3 implicitly, because the marked and pruned tree is ready for use in labelling each pixel in step 4. We now, for every pixel in the image, traverse the tree from the root, looking for the lowest cube that is a leaf. At each level we have a cube and subcube. If we reach a subcube leaf that is marked 0, we know that the color is stored in the cube above, and we've found the CTE. Otherwise, the subcube leaf is marked 1. If we're at the last level, we've reached the final leaf and must use it. Otherwise, continue the process at the next level down.
For robustness, efficiency and high quality output, we do the following:
(1) Measure the color content of the image. If there is very little color, quantize in grayscale. (2) For efficiency, build the octree with a subsampled image if the image is larger than some threshold size. (3) Reserve an extra set of colors to prevent running out of colors when pruning the octree; specifically, during the assignment of those level 2 cells (out of the 64) that have unassigned pixels. The problem of running out is more likely to happen with small images, because the estimation we use for the number of pixels available is not accurate. (4) In the unlikely event that we run out of colors, the dithered image can be very poor. As this would only happen with very small images, and dithering is not particularly noticeable with such images, turn it off.
LEPT_DLL PIX* pixOctreeColorQuantGeneral | ( | PIX * | pixs, |
l_int32 | colors, | ||
l_int32 | ditherflag, | ||
l_float32 | validthresh, | ||
l_float32 | colorthresh | ||
) |
Input: pixs (32 bpp; 24-bit color) colors (in colormap; some number in range [128 ... 240]; the actual number of colors used will be smaller) ditherflag (1 to dither, 0 otherwise) validthresh (minimum fraction of pixels neither near white nor black, required for color quantization; typically ~0.01, but smaller for images that have color but are nearly all white) colorthresh (minimum fraction of pixels with color that are not near white or black, that are required for color quantization; typ. ~0.01, but smaller for images that have color along with a significant fraction of gray) Return: pixd (8 bit with colormap), or null on error
Notes: (1) The parameters and are used to determine if color quantization should be used on an image, or whether, instead, it should be quantized in grayscale. If the image has very few non-white and non-black pixels, or if those pixels that are non-white and non-black are all very close to either white or black, it is usually better to treat the color as accidental and to quantize the image to gray only. These parameters are useful if you know something a priori about the image. Perhaps you know that there is only a very small fraction of color pixels, but they're important to preserve; then you want to use a smaller value for these parameters. To disable conversion to gray and force color quantization, use = 0.0 and = 0.0. (2) See pixOctreeColorQuant() for algorithmic and implementation details. This function has a more general interface. (3) See pixColorFraction() for computing the fraction of pixels that are neither white nor black, and the fraction of those pixels that have little color. From the documentation there: If pixfract is very small, there are few pixels that are neither black nor white. If colorfract is very small, the pixels that are neither black nor white have very little color content. The product 'pixfract * colorfract' gives the fraction of pixels with significant color content. We test against the product * to find color in images that have either very few intermediate gray pixels or that have many such gray pixels.
Input: pixs (32 bpp rgb) level (significant bits for each of RGB; valid for {3,4}, Use 0 for default (level 4; recommended) ditherflag (1 to dither, 0 otherwise) Return: pixd (quantized to octcubes) or null on error
Notes: (1) This color quantization method works very well without dithering, using octcubes at two different levels: (a) the input , which is either 3 or 4 (b) level 2 (64 octcubes to cover the entire color space) (2) For best results, using = 4 is recommended. Why do we provide an option for using level 3? Because there are 512 octcubes at level 3, and for many images not more than 256 are filled. As a result, on some images a very accurate quantized representation is possible using = 3. (3) This first breaks up the color space into octcubes at the input , and computes, for each octcube, the average value of the pixels that are in it. (4) Then there are two possible situations: (a) If there are not more than 256 populated octcubes, it returns a cmapped pix with those values assigned. (b) Otherwise, it selects 192 octcubes containing the largest number of pixels and quantizes pixels within those octcubes to their average. Then, to handle the residual pixels that are not in those 192 octcubes, it generates a level 2 octree consisting of 64 octcubes, and within each octcube it quantizes the residual pixels to their average within each of those level 2 octcubes. (5) Unpopulated level 2 octcubes are represented in the colormap by their centers. This, of course, has no effect unless dithering is used for the output image. (6) The depth of pixd is the minumum required to suppport the number of colors found at ; namely, 2, 4 or 8. (7) This function works particularly well on images such as maps, where there are a relatively small number of well-populated colors, but due to antialiasing and compression artifacts there may be a large number of different colors. This will pull out and represent accurately the highly populated colors, while still making a reasonable approximation for the others. (8) The highest level of octcubes allowed is 4. Use of higher levels typically results in having a small fraction of pixels in the most populated 192 octcubes. As a result, most of the pixels are represented at level 2, which is not sufficiently accurate. (9) Dithering shows artifacts on some images. If you plan to dither, pixOctreeColorQuant() and pixFixedOctcubeQuant256() usually give better results.
Input: pixs (32 bpp rgb) maxcolors (8 to 256; the actual number of colors used may be less than this) subsample (factor for computing color distribution; use 0 for default) Return: pixd (4 or 8 bpp, colormapped), or null on error
pixOctreeColorQuant() is very flexible in terms of the relative depth of different cubes of the octree. By contrast, this function, pixOctreeQuantNumColors() is also adaptive, but it supports octcube leaves at only two depths: a smaller depth that guarantees full coverage of the color space and octcubes at one level deeper for more accurate colors. Its main virutes are simplicity and speed, which are both derived from the natural indexing of the octcubes from the RGB values.
Before describing pixOctreeQuantNumColors(), consider an even simpler approach for 4 bpp with either 8 or 16 colors. With 8 colors, you simply go to level 1 octcubes and use the average color found in each cube. For 16 colors, you find which of the three colors has the largest variance at the second level, and use two indices for that color. The result is quite poor, because (1) some of the cubes are nearly empty and (2) you don't get much color differentiation for the extra 8 colors. Trust me, this method may be simple, but it isn't worth anything.
In pixOctreeQuantNumColors(), we generate colormapped images at either 4 bpp or 8 bpp. For 4 bpp, we have a minimum of 8 colors for the level 1 octcubes, plus up to 8 additional colors that are determined from the level 2 popularity. If the number of colors is between 8 and 16, the output is a 4 bpp image. If the number of colors is greater than 16, the output is a 8 bpp image.
We use a priority queue, implemented with a heap, to select the requisite number of most populated octcubes at the deepest level (level 2 for 64 or fewer colors; level 3 for more than 64 colors). These are combined with one color for each octcube one level above, which is used to span the color space of octcubes that were not included at the deeper level.
If the deepest level is 2, we combine the popular level 2 octcubes (out of a total of 64) with the 8 level 1 octcubes. If the deepest level is 3, we combine the popular level 3 octcubes (out of a total 512) with the 64 level 2 octcubes that span the color space. In the latter case, we require a minimum of 64 colors for the level 2 octcubes, plus up to 192 additional colors determined from level 3 popularity.
The parameter 'maxlevel' is the deepest octcube level that is used. The implementation also uses two LUTs, which are employed in two successive traversals of the dest image. The first maps from the src octindex at 'maxlevel' to the color table index, which is the value that is stored in the 4 or 8 bpp dest pixel. The second LUT maps from that colormap value in the dest to a new colormap value for a minimum sized colormap, stored back in the dest. It is used to remove any color map entries that correspond to color space regions that have no pixels in the source image. These regions can be either from the higher level (e.g., level 1 for 4 bpp), or from octcubes at 'maxlevel' that are unoccupied. This remapping results in the minimum number of colors used according to the constraints induced by the input 'maxcolors'. We also compute the average R, G and B color values in each region of the color space represented by a colormap entry, and store them in the colormap.
The maximum number of colors is input, which determines the following properties of the dest image and octcube regions used:
Number of colors dest image depth maxlevel ---------------- ---------------- -------- 8 to 16 4 bpp 2 17 to 64 8 bpp 2 65 to 256 8 bpp 3
It may turn out that the number of extra colors, beyond the minimum (8 and 64 for maxlevel 2 and 3, respectively), is larger than the actual number of occupied cubes at these levels In that case, all the pixels are contained in this subset of cubes at maxlevel, and no colormap colors are needed to represent the remainder pixels one level above. Thus, for example, in use one often finds that the pixels in an image occupy less than 192 octcubes at level 3, so they can be represented by a colormap for octcubes at level 3 only.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) sel Return: pixd
Notes: (1) Generic morphological opening, using hits in the Sel. (2) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (3) For clarity, if the case is known, use these patterns: (a) pixd = pixOpen(NULL, pixs, ...); (b) pixOpen(pixs, pixs, ...); (c) pixOpen(pixd, pixs, ...); (4) The size of the result is determined by pixs.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd, or null on error
Notes: (1) Sel is a brick with all elements being hits (2) The origin is at (x, y) = (hsize/2, vsize/2) (3) Do separably if both hsize and vsize are > 1. (4) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (5) For clarity, if the case is known, use these patterns: (a) pixd = pixOpenBrick(NULL, pixs, ...); (b) pixOpenBrick(pixs, pixs, ...); (c) pixOpenBrick(pixd, pixs, ...); (6) The size of the result is determined by pixs.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
Notes: (1) These implement 2D brick Sels, using linear Sels generated with selaAddBasic(). (2) A brick Sel has hits for all elements. (3) The origin of the Sel is at (x, y) = (hsize/2, vsize/2) (4) Do separably if both hsize and vsize are > 1. (5) It is necessary that both horizontal and vertical Sels of the input size are defined in the basic sela. (6) Note that we must always set or clear the border pixels before each operation, depending on the the b.c. (symmetric or asymmetric). (7) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (8) For clarity, if the case is known, use these patterns: (a) pixd = pixOpenBrickDwa(NULL, pixs, ...); (b) pixOpenBrickDwa(pixs, pixs, ...); (c) pixOpenBrickDwa(pixd, pixs, ...); (9) The size of the result is determined by pixs. (10) If either linear Sel is not found, this calls the appropriate decomposible function.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd, or null on error
Notes: (1) Sel is a brick with all elements being hits (2) The origin is at (x, y) = (hsize/2, vsize/2) (3) Do compositely for each dimension > 1. (4) Do separably if both hsize and vsize are > 1. (5) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (6) For clarity, if the case is known, use these patterns: (a) pixd = pixOpenCompBrick(NULL, pixs, ...); (b) pixOpenCompBrick(pixs, pixs, ...); (c) pixOpenCompBrick(pixd, pixs, ...); (7) The dimensions of the resulting image are determined by pixs. (8) CAUTION: both hsize and vsize are being decomposed. The decomposer chooses a product of sizes (call them 'terms') for each that is close to the input size, but not necessarily equal to it. It attempts to optimize: (a) for consistency with the input values: the product of terms is close to the input size (b) for efficiency of the operation: the sum of the terms is small; ideally about twice the square root of the input size. So, for example, if the input hsize = 37, which is a prime number, the decomposer will break this into two terms, 6 and 6, so that the net result is a dilation with hsize = 36.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
Notes: (1) These implement a separable composite opening with 2D brick Sels. (2) For efficiency, it may decompose each linear morphological operation into two (brick + comb). (3) A brick Sel has hits for all elements. (4) The origin of the Sel is at (x, y) = (hsize/2, vsize/2) (5) Do separably if both hsize and vsize are > 1. (6) It is necessary that both horizontal and vertical Sels of the input size are defined in the basic sela. (7) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (8) For clarity, if the case is known, use these patterns: (a) pixd = pixOpenCompBrickDwa(NULL, pixs, ...); (b) pixOpenCompBrickDwa(pixs, pixs, ...); (c) pixOpenCompBrickDwa(pixd, pixs, ...); (9) The size of pixd is determined by pixs. (10) CAUTION: both hsize and vsize are being decomposed. The decomposer chooses a product of sizes (call them 'terms') for each that is close to the input size, but not necessarily equal to it. It attempts to optimize: (a) for consistency with the input values: the product of terms is close to the input size (b) for efficiency of the operation: the sum of the terms is small; ideally about twice the square root of the input size. So, for example, if the input hsize = 37, which is a prime number, the decomposer will break this into two terms, 6 and 6, so that the net result is a dilation with hsize = 36.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) hsize (width of brick Sel) vsize (height of brick Sel) Return: pixd
(1) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (2) There is no need to call this directly: pixOpenCompBrickDwa() calls this function if either brick dimension exceeds 63.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs) pixs (1 bpp) sel Return: pixd
Notes: (1) Generalized morphological opening, using both hits and misses in the Sel. (2) This does a hit-miss transform, followed by a dilation using the hits. (3) There are three cases: (a) pixd == null (result into new pixd) (b) pixd == pixs (in-place; writes result back to pixs) (c) pixd != pixs (puts result into existing pixd) (4) For clarity, if the case is known, use these patterns: (a) pixd = pixOpenGeneralized(NULL, pixs, ...); (b) pixOpenGeneralized(pixs, pixs, ...); (c) pixOpenGeneralized(pixd, pixs, ...); (5) The size of the result is determined by pixs.
Input: pixs (8 bpp, not cmapped) hsize (1 or 3) vsize (1 or 3) Return: pixd, or null on error
Notes: (1) Special case for 1x3, 3x1 or 3x3 brick sel (all hits) (2) If hsize = vsize = 1, just returns a copy. (3) It would be nice not to add a border, but it is required to get the same results as for the general case.
Input: pixd (<optional>; this can be null, equal to pixs1, different from pixs1) pixs1 (can be == pixd) pixs2 (must be != pixd) Return: pixd always
Notes: (1) This gives the union of two images with equal depth, aligning them to the the UL corner. pixs1 and pixs2 need not have the same width and height. (2) There are 3 cases: (a) pixd == null, (src1 | src2) --> new pixd (b) pixd == pixs1, (src1 | src2) --> src1 (in-place) (c) pixd != pixs1, (src1 | src2) --> input pixd (3) For clarity, if the case is known, use these patterns: (a) pixd = pixOr(NULL, pixs1, pixs2); (b) pixOr(pixs1, pixs1, pixs2); (c) pixOr(pixd, pixs1, pixs2); (4) The size of the result is determined by pixs1. (5) The depths of pixs1 and pixs2 must be equal. (6) Note carefully that the order of pixs1 and pixs2 only matters for the in-place case. For in-place, you must have pixd == pixs1. Setting pixd == pixs2 gives an incorrect result: the copy puts pixs1 image data in pixs2, and the rasterop is then between pixs2 and pixs2 (a no-op).
LEPT_DLL l_int32 pixOrientDetect | ( | PIX * | pixs, |
l_float32 * | pupconf, | ||
l_float32 * | pleftconf, | ||
l_int32 | mincount, | ||
l_int32 | debug | ||
) |
Input: pixs (1 bpp, deskewed, English text, 150 - 300 ppi) &upconf (<optional return>=""> ; may be null) &leftconf (<optional return>=""> ; may be null) mincount (min number of up + down; use 0 for default) debug (1 for debug output; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) See "Measuring document image skew and orientation" Dan S. Bloomberg, Gary E. Kopec and Lakshmi Dasari IS&T/SPIE EI'95, Conference 2422: Document Recognition II pp 302-316, Feb 6-7, 1995, San Jose, CA (2) upconf is the normalized difference between up ascenders and down ascenders. The image is analyzed without rotation for being rightside-up or upside-down. Set &upconf to null to skip this operation. (3) leftconf is the normalized difference between up ascenders and down ascenders in the image after it has been rotated 90 degrees clockwise. With that rotation, ascenders projecting to the left in the source image will project up in the rotated image. We compute this by rotating 90 degrees clockwise and testing for up and down ascenders. Set &leftconf to null to skip this operation. (4) Note that upconf and leftconf are not linear measures of confidence, e.g., in a range between 0 and 100. They measure how far you are out on the tail of a (presumably) normal distribution. For example, a confidence of 10 means that it is nearly certain that the difference did not happen at random. However, these values must be interpreted cautiously, taking into consideration the estimated prior for a particular orientation or mirror flip. The up-down signal is very strong if applied to text with ascenders up and down, and relatively weak for text at 90 degrees, but even at 90 degrees, the difference can look significant. For example, suppose the ascenders are oriented horizontally, but the test is done vertically. Then upconf can be < -MIN_CONF_FOR_UP_DOWN, suggesting the text may be upside-down. However, if instead the test were done horizontally, leftconf will be very much larger (in absolute value), giving the correct orientation. (5) If you compute both upconf and leftconf, and there is sufficient signal, the following table determines the cw angle necessary to rotate pixs so that the text is rightside-up: 0 deg : upconf >> 1, abs(upconf) >> abs(leftconf) 90 deg : leftconf >> 1, abs(leftconf) >> abs(upconf) 180 deg : upconf << -1, abs(upconf) >> abs(leftconf) 270 deg : leftconf << -1, abs(leftconf) >> abs(upconf) (6) One should probably not interpret the direction unless there are a sufficient number of counts for both orientations, in which case neither upconf nor leftconf will be 0.0. (7) Uses rasterop implementation of HMT.
LEPT_DLL l_int32 pixOrientDetectDwa | ( | PIX * | pixs, |
l_float32 * | pupconf, | ||
l_float32 * | pleftconf, | ||
l_int32 | mincount, | ||
l_int32 | debug | ||
) |
Input: pixs (1 bpp, deskewed, English text) &upconf (<optional return>=""> ; may be null) &leftconf (<optional return>=""> ; may be null) mincount (min number of up + down; use 0 for default) debug (1 for debug output; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) Same interface as for pixOrientDetect(). See notes there for usage. (2) Uses auto-gen'd code for the Sels defined at the top of this file, with some renaming of functions. The auto-gen'd code is in fliphmtgen.c, and can be generated by a simple executable; see prog/flipselgen.c. (3) This runs about 2.5 times faster than the pixOrientDetect().
LEPT_DLL l_int32 pixOtsuAdaptiveThreshold | ( | PIX * | pixs, |
l_int32 | sx, | ||
l_int32 | sy, | ||
l_int32 | smoothx, | ||
l_int32 | smoothy, | ||
l_float32 | scorefract, | ||
PIX ** | ppixth, | ||
PIX ** | ppixd | ||
) |
Input: pixs (8 bpp) sx, sy (desired tile dimensions; actual size may vary) smoothx, smoothy (half-width of convolution kernel applied to threshold array: use 0 for no smoothing) scorefract (fraction of the max Otsu score; typ. 0.1; use 0.0 for standard Otsu) &pixth (<optional return>=""> array of threshold values found for each tile) &pixd (<optional return>=""> thresholded input pixs, based on the threshold array) Return: 0 if OK, 1 on error
Notes: (1) The Otsu method finds a single global threshold for an image. This function allows a locally adapted threshold to be found for each tile into which the image is broken up. (2) The array of threshold values, one for each tile, constitutes a highly downscaled image. This array is optionally smoothed using a convolution. The full width and height of the convolution kernel are (2 * + 1) and (2 * + 1). (3) The minimum tile dimension allowed is 16. If such small tiles are used, it is recommended to use smoothing, because without smoothing, each small tile determines the splitting threshold independently. A tile that is entirely in the image bg will then hallucinate fg, resulting in a very noisy binarization. The smoothing should be large enough that no tile is only influenced by one type (fg or bg) of pixels, because it will force a split of its pixels. (4) To get a single global threshold for the entire image, use input values of and that are larger than the image. For this situation, the smoothing parameters are ignored. (5) The threshold values partition the image pixels into two classes: one whose values are less than the threshold and another whose values are greater than or equal to the threshold. This is the same use of 'threshold' as in pixThresholdToBinary(). (6) The scorefract is the fraction of the maximum Otsu score, which is used to determine the range over which the histogram minimum is searched. See numaSplitDistribution() for details on the underlying method of choosing a threshold. (7) This uses enables a modified version of the Otsu criterion for splitting the distribution of pixels in each tile into a fg and bg part. The modification consists of searching for a minimum in the histogram over a range of pixel values where the Otsu score is within a defined fraction, , of the max score. To get the original Otsu algorithm, set == 0.
LEPT_DLL PIX* pixOtsuThreshOnBackgroundNorm | ( | PIX * | pixs, |
PIX * | pixim, | ||
l_int32 | sx, | ||
l_int32 | sy, | ||
l_int32 | thresh, | ||
l_int32 | mincount, | ||
l_int32 | bgval, | ||
l_int32 | smoothx, | ||
l_int32 | smoothy, | ||
l_float32 | scorefract, | ||
l_int32 * | pthresh | ||
) |
pixOtsuThreshOnBackgroundNorm()
Input: pixs (8 bpp grayscale; not colormapped) pixim (<optional> 1 bpp 'image' mask; can be null) sx, sy (tile size in pixels) thresh (threshold for determining foreground) mincount (min threshold on counts in a tile) bgval (target bg val; typ. > 128) smoothx (half-width of block convolution kernel width) smoothy (half-width of block convolution kernel height) scorefract (fraction of the max Otsu score; typ. 0.1) &thresh (<optional return>=""> threshold value that was used on the normalized image) Return: pixd (1 bpp thresholded image), or null on error
Notes: (1) This does background normalization followed by Otsu thresholding. Otsu binarization attempts to split the image into two roughly equal sets of pixels, and it does a very poor job when there are large amounts of dark background. By doing a background normalization first, to get the background near 255, we remove this problem. Then we use a modified Otsu to estimate the best global threshold on the normalized image. (2) See pixBackgroundNorm() for meaning and typical values of input parameters. For a start, you can try: sx, sy = 10, 15 thresh = 100 mincount = 50 bgval = 255 smoothx, smoothy = 2
Input: pixs (any depth, can be cmapped) boxa (of boxes, to paint) val (rgba color to paint) Return: pixd (with painted boxes), or null on error
Notes: (1) If pixs is 1 bpp or is colormapped, it is converted to 8 bpp and the boxa is painted using a colormap; otherwise, it is converted to 32 bpp rgb. (2) There are several ways to display a box on an image: * Paint it as a solid color * Draw the outline * Blend the outline or region with the existing image We provide painting and drawing here; blending is in blend.c. When painting or drawing, the result can be either a cmapped image or an rgb image. The dest will be cmapped if the src is either 1 bpp or has a cmap that is not full. To force RGB output, use pixConvertTo8(pixs, FALSE) before calling any of these paint and draw functions.
LEPT_DLL PIX* pixPaintBoxaRandom | ( | PIX * | pixs, |
BOXA * | boxa | ||
) |
Input: pixs (any depth, can be cmapped) boxa (of boxes, to paint) Return: pixd (with painted boxes), or null on error
Notes: (1) If pixs is 1 bpp, we paint the boxa using a colormap; otherwise, we convert to 32 bpp. (2) We use up to 254 different colors for painting the regions. (3) If boxes overlap, the later ones paint over earlier ones.
LEPT_DLL l_int32 pixPaintSelfThroughMask | ( | PIX * | pixd, |
PIX * | pixm, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | tilesize, | ||
l_int32 | searchdir | ||
) |
Input: pixd (8 bpp gray or 32 bpp rgb; not colormapped) pixm (1 bpp mask) x, y (origin of pixm relative to pixd; must not be negative) tilesize (requested size for tiling) searchdir (L_HORIZ, L_VERT) Return: 0 if OK; 1 on error
Notes: (1) In-place operation; pixd is changed. (2) If pixm == NULL, it's a no-op. (3) The mask origin is placed at (x,y) on pixd, and the operation is clipped to the intersection of pixd and the fg of the mask. (4) The tilesize is the the requested size for tiling. The actual size for each c.c. will be bounded by the minimum dimension of the c.c. and the distance at which the tile center is located. (5) searchdir is the direction with respect to the b.b. of each mask component, from which the square patch is chosen and tiled onto the image, clipped by the mask component. (6) Specifically, a mirrored tiling, generated from pixd, is used to construct the pixels that are painted onto pixd through pixm.
Input: pixd (1, 2, 4, 8, 16 or 32 bpp; or colormapped) pixm (<optional> 1 bpp mask) x, y (origin of pixm relative to pixd; can be negative) val (pixel value to set at each masked pixel) Return: 0 if OK; 1 on error
Notes: (1) In-place operation. Calls pixSetMaskedCmap() for colormapped images. (2) For 1, 2, 4, 8 and 16 bpp gray, we take the appropriate number of least significant bits of val. (3) If pixm == NULL, it's a no-op. (4) The mask origin is placed at (x,y) on pixd, and the operation is clipped to the intersection of rectangles. (5) For rgb, the components in val are in the canonical locations, with red in location COLOR_RED, etc. (6) Implementation detail 1: For painting with val == 0 or val == maxval, you can use rasterop. If val == 0, invert the mask so that it's 0 over the region into which you want to write, and use PIX_SRC & PIX_DST to clear those pixels. To write with val = maxval (all 1's), use PIX_SRC | PIX_DST to set all bits under the mask. (7) Implementation detail 2: The rasterop trick can be used for depth > 1 as well. For val == 0, generate the mask for depth d from the binary mask using pixmd = pixUnpackBinary(pixm, d, 1); and use pixRasterop() with PIX_MASK. For val == maxval, pixmd = pixUnpackBinary(pixm, d, 0); and use pixRasterop() with PIX_PAINT. But note that if d == 32 bpp, it is about 3x faster to use the general implementation (not pixRasterop()). (8) Implementation detail 3: It might be expected that the switch in the inner loop will cause large branching delays and should be avoided. This is not the case, because the entrance is always the same and the compiler can correctly predict the jump.
Input: pixs (any depth) pta (set of points on which to plot) outformat (GPLOT_PNG, GPLOT_PS, GPLOT_EPS, GPLOT_X11, GPLOT_LATEX) title (<optional> for plot; can be null) Return: 0 if OK, 1 on error
Notes: (1) We remove any existing colormap and clip the pta to the input pixs. (2) This is a debugging function, and does not remove temporary plotting files that it generates. (3) If the image is RGB, three separate plots are generated.
LEPT_DLL l_int32 pixPrintStreamInfo | ( | FILE * | fp, |
PIX * | pix, | ||
const char * | text | ||
) |
Input: fp (file stream) pix text (<optional> identifying string; can be null) Return: 0 if OK, 1 on error
LEPT_DLL SARRAY* pixProcessBarcodes | ( | PIX * | pixs, |
l_int32 | format, | ||
l_int32 | method, | ||
SARRAY ** | psaw, | ||
l_int32 | debugflag | ||
) |
Input: pixs (any depth) format (L_BF_ANY, L_BF_CODEI2OF5, L_BF_CODE93, ...) method (L_USE_WIDTHS, L_USE_WINDOWS) &saw (<optional return>=""> sarray of bar widths) debugflag (use 1 to generate debug output) Return: sarray (text of barcodes), or null if none found or on error
Input: pixs (all depths; colormap ok) vc (vector of 8 coefficients for projective transformation) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Brings in either black or white pixels from the boundary (2) Removes any existing colormap, if necessary, before transforming
Input: pixs (32 bpp) vc (vector of 8 coefficients for projective transformation) colorval (e.g., 0 to bring in BLACK, 0xffffff00 for WHITE) Return: pixd, or null on error
Input: pixs (8 bpp) vc (vector of 8 coefficients for projective transformation) grayval (0 to bring in BLACK, 255 for WHITE) Return: pixd, or null on error
Input: pixs (all depths; colormap ok) ptad (4 pts of final coordinate space) ptas (4 pts of initial coordinate space) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Brings in either black or white pixels from the boundary (2) Removes any existing colormap, if necessary, before transforming
Input: pixs (32 bpp) ptad (4 pts of final coordinate space) ptas (4 pts of initial coordinate space) colorval (e.g., 0 to bring in BLACK, 0xffffff00 for WHITE) Return: pixd, or null on error
LEPT_DLL PIX* pixProjectivePtaGammaXform | ( | PIX * | pixs, |
l_float32 | gamma, | ||
PTA * | ptad, | ||
PTA * | ptas, | ||
l_float32 | fract, | ||
l_int32 | border | ||
) |
Input: pixs (32 bpp rgb) gamma (gamma correction; must be > 0.0) ptad (3 pts of final coordinate space) ptas (3 pts of initial coordinate space) fract (between 0.0 and 1.0, with 1.0 fully transparent) border (of pixels to capture transformed source pixels) Return: pixd, or null on error
Notes: (1) This wraps a gamma/inverse-gamma photometric transform around pixProjectivePtaWithAlpha(). (2) For usage, see notes in pixProjectivePtaWithAlpha() and pixGammaTRCWithAlpha(). (3) The basic idea of a gamma/inverse-gamma transform is to remove any gamma correction before the projective transform, and restore it afterward. The effects can be subtle, but important for some applications. For example, using gamma > 1.0 will cause the dark areas to become somewhat lighter and slightly reduce aliasing effects when blending using the alpha channel.
Input: pixs (8 bpp) ptad (4 pts of final coordinate space) ptas (4 pts of initial coordinate space) grayval (0 to bring in BLACK, 255 for WHITE) Return: pixd, or null on error
LEPT_DLL PIX* pixProjectivePtaWithAlpha | ( | PIX * | pixs, |
PTA * | ptad, | ||
PTA * | ptas, | ||
PIX * | pixg, | ||
l_float32 | fract, | ||
l_int32 | border | ||
) |
Input: pixs (32 bpp rgb) ptad (4 pts of final coordinate space) ptas (4 pts of initial coordinate space) pixg (<optional> 8 bpp, for alpha channel, can be null) fract (between 0.0 and 1.0, with 0.0 fully transparent and 1.0 fully opaque) border (of pixels added to capture transformed source pixels) Return: pixd, or null on error
Notes: (1) The alpha channel is transformed separately from pixs, and aligns with it, being fully transparent outside the boundary of the transformed pixs. For pixels that are fully transparent, a blending function like pixBlendWithGrayMask() will give zero weight to corresponding pixels in pixs. (2) If pixg is NULL, it is generated as an alpha layer that is partially opaque, using . Otherwise, it is cropped to pixs if required and is ignored. The alpha channel in pixs is never used. (3) Colormaps are removed. (4) When pixs is transformed, it doesn't matter what color is brought in because the alpha channel will be transparent (0) there. (5) To avoid losing source pixels in the destination, it may be necessary to add a border to the source pix before doing the projective transformation. This can be any non-negative number. (6) The input and are in a coordinate space before the border is added. Internally, we compensate for this before doing the projective transform on the image after the border is added. (7) The default setting for the border values in the alpha channel is 0 (transparent) for the outermost ring of pixels and (0.5 * fract * 255) for the second ring. When blended over a second image, this (a) shrinks the visible image to make a clean overlap edge with an image below, and (b) softens the edges by weakening the aliasing there. Use l_setAlphaMaskBorder() to change these values.
Input: pixs (all depths) vc (vector of 8 coefficients for projective transformation) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Brings in either black or white pixels from the boundary. (2) Retains colormap, which you can do for a sampled transform.. (3) For 8 or 32 bpp, much better quality is obtained by the somewhat slower pixProjective(). See that function for relative timings between sampled and interpolated.
Input: pixs (all depths) ptad (4 pts of final coordinate space) ptas (4 pts of initial coordinate space) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Brings in either black or white pixels from the boundary. (2) Retains colormap, which you can do for a sampled transform.. (3) No 3 of the 4 points may be collinear. (4) For 8 and 32 bpp pix, better quality is obtained by the somewhat slower pixProjectivePta(). See that function for relative timings between sampled and interpolated.
LEPT_DLL PIX* pixQuadraticVShear | ( | PIX * | pixs, |
l_int32 | dir, | ||
l_int32 | vmaxt, | ||
l_int32 | vmaxb, | ||
l_int32 | operation, | ||
l_int32 | incolor | ||
) |
LEPT_DLL PIX* pixQuadraticVShearLI | ( | PIX * | pixs, |
l_int32 | dir, | ||
l_int32 | vmaxt, | ||
l_int32 | vmaxb, | ||
l_int32 | incolor | ||
) |
Input: pixs (8 or 32 bpp, or colormapped) dir (L_WARP_TO_LEFT or L_WARP_TO_RIGHT) vmaxt (max vertical displacement at edge and at top) vmaxb (max vertical displacement at edge and at bottom) incolor (L_BRING_IN_WHITE or L_BRING_IN_BLACK) Return: pixd (stretched), or null on error
Notes: (1) See pixQuadraticVShear() for details.
LEPT_DLL PIX* pixQuadraticVShearSampled | ( | PIX * | pixs, |
l_int32 | dir, | ||
l_int32 | vmaxt, | ||
l_int32 | vmaxb, | ||
l_int32 | incolor | ||
) |
Input: pixs (1, 8 or 32 bpp) dir (L_WARP_TO_LEFT or L_WARP_TO_RIGHT) vmaxt (max vertical displacement at edge and at top) vmaxb (max vertical displacement at edge and at bottom) incolor (L_BRING_IN_WHITE or L_BRING_IN_BLACK) Return: pixd (stretched), or null on error
Notes: (1) See pixQuadraticVShear() for details.
Input: pixs (8 bpp, no colormap) nlevels (in quadtree; max allowed depends on image size) *pix_ma (input mean accumulator; can be null) *pfpixa (<return> mean values in quadtree) Return: 0 if OK, 1 on error
Notes: (1) The returned fpixa has of fpix, each containing the mean values at its level. Level 0 has a single value; level 1 has 4 values; level 2 has 16; etc.
LEPT_DLL l_int32 pixQuadtreeVariance | ( | PIX * | pixs, |
l_int32 | nlevels, | ||
PIX * | pix_ma, | ||
DPIX * | dpix_msa, | ||
FPIXA ** | pfpixa_v, | ||
FPIXA ** | pfpixa_rv | ||
) |
Input: pixs (8 bpp, no colormap) nlevels (in quadtree) *pix_ma (input mean accumulator; can be null) *dpix_msa (input mean square accumulator; can be null) *pfpixa_v (<optional return>=""> variance values in quadtree) *pfpixa_rv (<optional return>=""> root variance values in quadtree) Return: 0 if OK, 1 on error
Notes: (1) The returned fpixav and fpixarv have of fpix, each containing at the respective levels the variance and root variance values.
LEPT_DLL PIX* pixQuantFromCmap | ( | PIX * | pixs, |
PIXCMAP * | cmap, | ||
l_int32 | mindepth, | ||
l_int32 | level, | ||
l_int32 | metric | ||
) |
Input: pixs (8 bpp grayscale without cmap, or 32 bpp rgb) cmap (to quantize to; insert copy into dest pix) mindepth (minimum depth of pixd: can be 2, 4 or 8 bpp) level (of octcube used for finding nearest color in cmap) metric (L_MANHATTAN_DISTANCE, L_EUCLIDEAN_DISTANCE) Return: pixd (2, 4 or 8 bpp, colormapped), or null on error
Notes: (1) This is a top-level wrapper for quantizing either grayscale or rgb images to a specified colormap. (2) The actual output depth is constrained by and by the number of colors in . (3) For grayscale, and are ignored. (4) If the cmap has color and pixs is grayscale, the color is removed from the cmap before quantizing pixs.
LEPT_DLL l_int32 pixQuantizeIfFewColors | ( | PIX * | pixs, |
l_int32 | maxcolors, | ||
l_int32 | mingraycolors, | ||
l_int32 | octlevel, | ||
PIX ** | ppixd | ||
) |
Input: pixs (8 bpp gray or 32 bpp rgb) maxcolors (max number of colors allowed to be returned from pixColorsForQuantization(); use 0 for default) mingraycolors (min number of gray levels that a grayscale image is quantized to; use 0 for default) octlevel (for octcube quantization: 3 or 4) &pixd (2, 4 or 8 bpp quantized; null if too many colors) Return: 0 if OK, 1 on error or if pixs can't be quantized into a small number of colors.
Notes: (1) This is a wrapper that tests if the pix can be quantized with good quality using a small number of colors. If so, it does the quantization, defining a colormap and using pixels whose value is an index into the colormap. (2) If the image has color, it is quantized with 8 bpp pixels. If the image is essentially grayscale, the pixels are either 4 or 8 bpp, depending on the size of the required colormap. (3) = 3 works well for most images. However, for best quality, at a cost of more colors in the colormap, use = 4. (4) If the image already has a colormap, it returns a clone.
LEPT_DLL PIX* pixRandomHarmonicWarp | ( | PIX * | pixs, |
l_float32 | xmag, | ||
l_float32 | ymag, | ||
l_float32 | xfreq, | ||
l_float32 | yfreq, | ||
l_int32 | nx, | ||
l_int32 | ny, | ||
l_uint32 | seed, | ||
l_int32 | grayval | ||
) |
Input: pixs (8 bpp; no colormap) xmag, ymag (maximum magnitude of x and y distortion) xfreq, yfreq (maximum magnitude of x and y frequency) nx, ny (number of x and y harmonic terms) seed (of random number generator) grayval (color brought in from the outside; 0 for black, 255 for white) Return: pixd (8 bpp; no colormap), or null on error
Notes: (1) To generate the warped image p(x',y'), set up the transforms that are in getWarpTransform(). For each (x',y') in the dest, the warp function computes the originating location (x, y) in the src. The differences (x - x') and (y - y') are given as a sum of products of sinusoidal terms. Each term is multiplied by a maximum amplitude (in pixels), and the angle is determined by a frequency and phase, and depends on the (x', y') value of the dest. Random numbers with a variable input seed are used to allow the warping to be unpredictable. A linear interpolation is used to find the value for the source at (x, y); this value is written into the dest. (2) This can be used to generate 'captcha's, which are somewhat randomly distorted images of text. A typical set of parameters for a captcha are: xmag = 4.0 ymag = 6.0 xfreq = 0.10 yfreq = 0.13 nx = 3 ny = 3 Other examples can be found in prog/warptest.c.
LEPT_DLL PIX* pixRankColumnTransform | ( | PIX * | pixs | ) |
Input: pixs (8 bpp; no colormap) Return: pixd (with pixels sorted in each column, from min to max value)
Notes: (1) The time is O(n) in the number of pixels and runs about 50 Mpixels/sec on a 3 GHz machine.
Input: pixs (8 or 32 bpp; no colormap) wf, hf (width and height of filter; each is >= 1) rank (in [0.0 ... 1.0]) Return: pixd (of rank values), or null on error
Notes: (1) This defines, for each pixel in pixs, a neighborhood of pixels given by a rectangle "centered" on the pixel. This set of wf*hf pixels has a distribution of values. For each component, if the values are sorted in increasing order, we choose the component such that rank*(wf*hf-1) pixels have a lower or equal value and (1-rank)*(wf*hf-1) pixels have an equal or greater value. (2) See notes in pixRankFilterGray() for further details.
Input: pixs (8 bpp; no colormap) wf, hf (width and height of filter; each is >= 1) rank (in [0.0 ... 1.0]) Return: pixd (of rank values), or null on error
Notes: (1) This defines, for each pixel in pixs, a neighborhood of pixels given by a rectangle "centered" on the pixel. This set of wf*hf pixels has a distribution of values, and if they are sorted in increasing order, we choose the pixel such that rank*(wf*hf-1) pixels have a lower or equal value and (1-rank)*(wf*hf-1) pixels have an equal or greater value. (2) By this definition, the rank = 0.0 pixel has the lowest value, and the rank = 1.0 pixel has the highest value. (3) We add mirrored boundary pixels to avoid boundary effects, and put the filter center at (0, 0). (4) This dispatches to grayscale erosion or dilation if the filter dimensions are odd and the rank is 0.0 or 1.0, rsp. (5) Returns a copy if both wf and hf are 1. (6) Uses row-major or column-major incremental updates to the histograms depending on whether hf > wf or hv <= wf, rsp.
Input: pixs (32 bpp) wf, hf (width and height of filter; each is >= 1) rank (in [0.0 ... 1.0]) Return: pixd (of rank values), or null on error
Notes: (1) This defines, for each pixel in pixs, a neighborhood of pixels given by a rectangle "centered" on the pixel. This set of wf*hf pixels has a distribution of values. For each component, if the values are sorted in increasing order, we choose the component such that rank*(wf*hf-1) pixels have a lower or equal value and (1-rank)*(wf*hf-1) pixels have an equal or greater value. (2) Apply gray rank filtering to each component independently. (3) See notes in pixRankFilterGray() for further details.
LEPT_DLL PIX* pixRankFilterWithScaling | ( | PIX * | pixs, |
l_int32 | wf, | ||
l_int32 | hf, | ||
l_float32 | rank, | ||
l_float32 | scalefactor | ||
) |
Input: pixs (8 or 32 bpp; no colormap) wf, hf (width and height of filter; each is >= 1) rank (in [0.0 ... 1.0]) scalefactor (scale factor; must be >= 0.2 and <= 0.7) Return: pixd (of rank values), or null on error
Notes: (1) This is a convenience function that downscales, does the rank filtering, and upscales. Because the down- and up-scaling functions are very fast compared to rank filtering, the time it takes is reduced from that for the simple rank filtering operation by approximately the square of the scaling factor.
LEPT_DLL l_int32 pixRankHaustest | ( | PIX * | pix1, |
PIX * | pix2, | ||
PIX * | pix3, | ||
PIX * | pix4, | ||
l_float32 | delx, | ||
l_float32 | dely, | ||
l_int32 | maxdiffw, | ||
l_int32 | maxdiffh, | ||
l_int32 | area1, | ||
l_int32 | area3, | ||
l_float32 | rank, | ||
l_int32 * | tab8 | ||
) |
Input: pix1 (new pix, not dilated) pix2 (new pix, dilated) pix3 (exemplar pix, not dilated) pix4 (exemplar pix, dilated) delx (x comp of centroid difference) dely (y comp of centroid difference) maxdiffw (max width difference of pix1 and pix2) maxdiffh (max height difference of pix1 and pix2) area1 (fg pixels in pix1) area3 (fg pixels in pix3) rank (rank value of test, each way) tab8 (table of pixel sums for byte) Return: 0 (FALSE) if no match, 1 (TRUE) if the new pix is in the same class as the exemplar.
Note: we check first that the two pix are roughly the same size. Only if they meet that criterion do we compare the bitmaps. We convert the rank value to a number of pixels by multiplying the rank fraction by the number of pixels in the undilated image. The Hausdorff is a 2-way check. The centroid difference is used to align the two images to the nearest integer for each of the checks. The rank hausdorff checks that the dilated image of one contains the rank fraction of the pixels of the undilated image of the other. Checks are done in both direction. Failure of the test in either direction results in failure of the test.
LEPT_DLL PIX* pixRankRowTransform | ( | PIX * | pixs | ) |
Input: pixs (8 bpp; no colormap) Return: pixd (with pixels sorted in each row, from min to max value)
Notes: (1) The time is O(n) in the number of pixels and runs about 100 Mpixels/sec on a 3 GHz machine.
LEPT_DLL l_int32 pixRasterop | ( | PIX * | pixd, |
l_int32 | dx, | ||
l_int32 | dy, | ||
l_int32 | dw, | ||
l_int32 | dh, | ||
l_int32 | op, | ||
PIX * | pixs, | ||
l_int32 | sx, | ||
l_int32 | sy | ||
) |
Input: pixd (dest pix) dx (x val of UL corner of dest rectangle) dy (y val of UL corner of dest rectangle) dw (width of dest rectangle) dh (height of dest rectangle) op (op code) pixs (src pix) sx (x val of UL corner of src rectangle) sy (y val of UL corner of src rectangle) Return: 0 if OK; 1 on error.
Notes: (1) This has the standard set of 9 args for rasterop. This function is your friend; it is worth memorizing! (2) If the operation involves only dest, this calls rasteropUniLow(). Otherwise, checks depth of the src and dest, and if they match, calls rasteropLow(). (3) For the two-image operation, where both pixs and pixd are defined, they are typically different images. However there are cases, such as pixSetMirroredBorder(), where in-place operations can be done, blitting pixels from one part of pixd to another. Consequently, we permit such operations. If you use them, be sure that there is no overlap between the source and destination rectangles in pixd (!)
Background: -----------
There are 18 operations, described by the op codes in pix.h.
One, PIX_DST, is a no-op.
Three, PIX_CLR, PIX_SET, and PIX_NOT(PIX_DST) operate only on the dest. These are handled by the low-level rasteropUniLow().
The other 14 involve the both the src and the dest, and depend on the bit values of either just the src or the bit values of both src and dest. They are handled by rasteropLow():
PIX_SRC s PIX_NOT(PIX_SRC) ~s PIX_SRC | PIX_DST s | d PIX_SRC & PIX_DST s & d PIX_SRC ^ PIX_DST s ^ d PIX_NOT(PIX_SRC) | PIX_DST ~s | d PIX_NOT(PIX_SRC) & PIX_DST ~s & d PIX_NOT(PIX_SRC) ^ PIX_DST ~s ^ d PIX_SRC | PIX_NOT(PIX_DST) s | ~d PIX_SRC & PIX_NOT(PIX_DST) s & ~d PIX_SRC ^ PIX_NOT(PIX_DST) s ^ ~d PIX_NOT(PIX_SRC | PIX_DST) ~(s | d) PIX_NOT(PIX_SRC & PIX_DST) ~(s & d) PIX_NOT(PIX_SRC ^ PIX_DST) ~(s ^ d)
Each of these is implemented with one of three low-level functions, depending on the alignment of the left edge of the src and dest rectangles: * a fastest implementation if both left edges are (32-bit) word aligned * a very slightly slower implementation if both left edges have the same relative (32-bit) word alignment * the general routine that is invoked when both left edges have different word alignment
Of the 14 binary rasterops above, only 12 are unique logical combinations (out of a possible 16) of src and dst bits:
(sd) (11) (10) (01) (00) ----------------------------------------------- s 1 1 0 0 ~s 0 1 0 1 s | d 1 1 1 0 s & d 1 0 0 0 s ^ d 0 1 1 0 ~s | d 1 0 1 1 ~s & d 0 0 1 0 ~s ^ d 1 0 0 1 s | ~d 1 1 0 1 s & ~d 0 1 0 0 s ^ ~d 1 0 0 1 ~(s | d) 0 0 0 1 ~(s & d) 0 1 1 1 ~(s ^ d) 1 0 0 1
Note that the following three operations are equivalent: ~(s ^ d) ~s ^ d s ^ ~d and in the implementation, we call them out with the first form; namely, ~(s ^ d).
Of the 16 possible binary combinations of src and dest bits, the remaining 4 unique ones are independent of the src bit. They depend on either just the dest bit or on neither the src nor dest bits:
d 1 0 1 0 (indep. of s) ~d 0 1 0 1 (indep. of s) CLR 0 0 0 0 (indep. of both s & d) SET 1 1 1 1 (indep. of both s & d)
As mentioned above, three of these are implemented by rasteropUniLow(), and one is a no-op.
How can these operation codes be represented by bits in such a way that when the basic operations are performed on the bits the results are unique for unique operations, and mimic the logic table given above?
The answer is to choose a particular order of the pairings: (sd) (11) (10) (01) (00) (which happens to be the same as in the above table) and to translate the result into 4-bit representations of s and d. For example, the Sun rasterop choice (omitting the extra bit for clipping) is
PIX_SRC 0xc PIX_DST 0xa
This corresponds to our pairing order given above: (sd) (11) (10) (01) (00) where for s = 1 we get the bit pattern PIX_SRC: 1 1 0 0 (0xc) and for d = 1 we get the pattern PIX_DST: 1 0 1 0 (0xa)
OK, that's the pairing order that Sun chose. How many different ways can we assign bit patterns to PIX_SRC and PIX_DST to get the boolean ops to work out? Any of the 4 pairs can be put in the first position, any of the remaining 3 pairs can go in the second; and one of the remaining 2 pairs can go the the third. There is a total of 4*3*2 = 24 ways these pairs can be permuted.
Input: pixd pixs op (any of the op-codes) Return: 0 if OK; 1 on error
Notes:
LEPT_DLL l_int32 pixRasteropHip | ( | PIX * | pixd, |
l_int32 | by, | ||
l_int32 | bh, | ||
l_int32 | hshift, | ||
l_int32 | incolor | ||
) |
Input: pixd (in-place operation) by (top of horizontal band) bh (height of horizontal band) hshift (horizontal shift of band; hshift > 0 is to right) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: 0 if OK; 1 on error
Notes: (1) This rasterop translates a horizontal band of the image either left or right, bringing in either white or black pixels from outside the image. (2) The horizontal band extends the full width of pixd. (3) If a colormap exists, the nearest color to white or black is brought in.
Input: pixd (in-place translation) hshift (horizontal shift; hshift > 0 is to right) vshift (vertical shift; vshift > 0 is down) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 pixRasteropVip | ( | PIX * | pixd, |
l_int32 | bx, | ||
l_int32 | bw, | ||
l_int32 | vshift, | ||
l_int32 | incolor | ||
) |
Input: pixd (in-place) bx (left edge of vertical band) bw (width of vertical band) vshift (vertical shift of band; vshift > 0 is down) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: 0 if OK; 1 on error
Notes: (1) This rasterop translates a vertical band of the image either up or down, bringing in either white or black pixels from outside the image. (2) The vertical band extends the full height of pixd. (3) If a colormap exists, the nearest color to white or black is brought in.
Input: filename (with full pathname or in local directory) Return: pix if OK; null on error
LEPT_DLL SARRAY* pixReadBarcodes | ( | PIXA * | pixa, |
l_int32 | format, | ||
l_int32 | method, | ||
SARRAY ** | psaw, | ||
l_int32 | debugflag | ||
) |
Input: pixa (of 8 bpp deskewed and cropped barcodes) format (L_BF_ANY, L_BF_CODEI2OF5, L_BF_CODE93, ...) method (L_USE_WIDTHS, L_USE_WINDOWS); &saw (<optional return>=""> sarray of bar widths) debugflag (use 1 to generate debug output) Return: sa (sarray of widths, one string for each barcode found), or null on error
Input: pixs (of 8 bpp deskewed and cropped barcode) method (L_USE_WIDTHS, L_USE_WINDOWS); debugflag (use 1 to generate debug output) Return: na (numa of widths (each in set {1,2,3,4}), or null on error
LEPT_DLL l_int32 pixReadHeader | ( | const char * | filename, |
l_int32 * | pformat, | ||
l_int32 * | pw, | ||
l_int32 * | ph, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp, | ||
l_int32 * | piscmap | ||
) |
Input: filename (with full pathname or in local directory) &format (<optional return>=""> file format) &w, &h (<optional returns>=""> width and height) &bps <optional return>=""> bits/sample &spp <optional return>=""> samples/pixel (1, 3 or 4) &iscmap (<optional return>=""> 1 if cmap exists; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) This reads the actual headers for jpeg, png, tiff and pnm. For bmp and gif, we cheat and read the entire file into a pix, from which we extract the "header" information.
LEPT_DLL l_int32 pixReadHeaderMem | ( | const l_uint8 * | data, |
size_t | size, | ||
l_int32 * | pformat, | ||
l_int32 * | pw, | ||
l_int32 * | ph, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp, | ||
l_int32 * | piscmap | ||
) |
Input: data (const; encoded) datasize (size of data) &format (<optional returns>=""> image format) &w, &h (<optional returns>=""> width and height) &bps <optional return>=""> bits/sample &spp <optional return>=""> samples/pixel (1, 3 or 4) &iscmap (<optional return>=""> 1 if cmap exists; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) This reads the actual headers for jpeg, png, tiff and pnm. For bmp and gif, we cheat and read all the data into a pix, from which we extract the "header" information. (2) On windows, this will only read tiff formatted files from memory. For other formats, it requires fmemopen(3). Attempts to read those formats will fail at runtime. (3) findFileFormatBuffer() requires up to 8 bytes to decide on the format. That determines the constraint here.
LEPT_DLL PIX* pixReadIndexed | ( | SARRAY * | sa, |
l_int32 | index | ||
) |
Input: sarray (of full pathnames) index (into pathname array) Return: pix if OK; null if not found
Notes: (1) This function is useful for selecting image files from a directory, where the integer is embedded into the file name. (2) This is typically done by generating the sarray using getNumberedPathnamesInDirectory(), so that the pathname would have the number in it. The size of the sarray should be the largest number (plus 1) appearing in the file names, respecting the constraints in the call to getNumberedPathnamesInDirectory(). (3) Consequently, for some indices into the sarray, there may be no pathnames in the directory containing that number. By convention, we place empty C strings ("") in those locations in the sarray, and it is not an error if such a string is encountered and no pix is returned. Therefore, the caller must verify that a pix is returned. (4) See convertSegmentedPagesToPS() in src/psio1.c for an example of usage.
LEPT_DLL PIX* pixReadJpeg | ( | const char * | filename, |
l_int32 | cmflag, | ||
l_int32 | reduction, | ||
l_int32 * | pnwarn | ||
) |
Input: filename colormap flag (0 means return RGB image if color; 1 means create colormap and return 8 bpp palette image if color) reduction (scaling factor: 1, 2, 4 or 8) &pnwarn (<optional return>=""> number of warnings about corrupted data) Return: pix, or null on error
Images reduced by factors of 2, 4 or 8 can be returned significantly faster than full resolution images.
The jpeg library will return warnings (or exit) if the jpeg data is bad. Use this function if you want the jpeg library to create an 8 bpp palette image, or to tell if the jpeg data has been corrupted. For corrupt jpeg data, there are two possible outcomes: (1) a damaged pix will be returned, along with a nonzero number of warnings, or (2) for sufficiently serious problems, the library will attempt to exit (caught by our error handler) and no pix will be returned.
LEPT_DLL PIX* pixReadMem | ( | const l_uint8 * | data, |
size_t | size | ||
) |
Input: data (const; encoded) datasize (size of data) Return: pix, or null on error
Notes: (1) This is a variation of pixReadStream(), where the data is read from a memory buffer rather than a file. (2) On windows, this will only read tiff formatted files from memory. For other formats, it requires fmemopen(3). Attempts to read those formats will fail at runtime. (3) findFileFormatBuffer() requires up to 8 bytes to decide on the format. That determines the constraint here.
LEPT_DLL PIX* pixReadMemBmp | ( | const l_uint8 * | cdata, |
size_t | size | ||
) |
LEPT_DLL PIX* pixReadMemGif | ( | const l_uint8 * | cdata, |
size_t | size | ||
) |
LEPT_DLL PIX* pixReadMemJpeg | ( | const l_uint8 * | cdata, |
size_t | size, | ||
l_int32 | cmflag, | ||
l_int32 | reduction, | ||
l_int32 * | pnwarn, | ||
l_int32 | hint | ||
) |
Input: cdata (const; jpeg-encoded) size (of data) colormap flag (0 means return RGB image if color; 1 means create colormap and return 8 bpp palette image if color) reduction (scaling factor: 1, 2, 4 or 8) &pnwarn (<optional return>=""> number of warnings) hint (bitwise OR of L_HINT_* values; use 0 for no hint) Return: pix, or null on error
Notes: (1) We are cheating here -- writing the data out to file in jpeg format and then reading it back.
LEPT_DLL PIX* pixReadMemPng | ( | const l_uint8 * | cdata, |
size_t | size | ||
) |
LEPT_DLL PIX* pixReadMemPnm | ( | const l_uint8 * | cdata, |
size_t | size | ||
) |
LEPT_DLL PIX* pixReadMemSpix | ( | const l_uint8 * | data, |
size_t | size | ||
) |
Input: data (const; uncompressed) size (of data) Return: pix, or null on error
LEPT_DLL PIX* pixReadMemTiff | ( | const l_uint8 * | cdata, |
size_t | size, | ||
l_int32 | n | ||
) |
Input: data (const; tiff-encoded) datasize (size of data) n (page image number: 0-based) Return: pix, or null on error
Notes: (1) This is a version of pixReadTiff(), where the data is read from a memory buffer and uncompressed. (2) Use TIFFClose(); TIFFCleanup() doesn't free internal memstream.
LEPT_DLL PIX* pixReadRGBAPng | ( | const char * | filename | ) |
Input: filename (of png file) Return: pix, or null on error
Notes: (1) Wrapper to keep the alpha channel of a png, if it exists. (2) The default behavior of pix read functions is to ignore the alpha channel. (3) This always leaves alpha stripping in the same mode as when this function begins. So if alpha stripping is in default mode, this disables it, reads the file (including the alpha channel), and resets back to stripping. Otherwise, it leaves stripping disabled.
LEPT_DLL PIX* pixReadStream | ( | FILE * | fp, |
l_int32 | hint | ||
) |
Input: fp (file stream) hint (bitwise OR of L_HINT_* values for jpeg; use 0 for no hint) Return: pix if OK; null on error
Notes: (1) The hint only applies to jpeg.
LEPT_DLL PIX* pixReadStreamBmp | ( | FILE * | fp | ) |
Input: stream opened for read Return: pix, or null on error
Notes: (1) Here are references on the bmp file format: http://en.wikipedia.org/wiki/BMP_file_format http://www.fortunecity.com/skyscraper/windows/364/bmpffrmt.html
LEPT_DLL PIX* pixReadStreamGif | ( | FILE * | fp | ) |
LEPT_DLL PIX* pixReadStreamJpeg | ( | FILE * | fp, |
l_int32 | cmflag, | ||
l_int32 | reduction, | ||
l_int32 * | pnwarn, | ||
l_int32 | hint | ||
) |
Input: stream colormap flag (0 means return RGB image if color; 1 means create colormap and return 8 bpp palette image if color) reduction (scaling factor: 1, 2, 4 or 8) &pnwarn (<optional return>=""> number of warnings) hint: (a bitwise OR of L_HINT_* values); use 0 for no hints Return: pix, or null on error
Usage: see pixReadJpeg()
LEPT_DLL PIX* pixReadStreamPng | ( | FILE * | fp | ) |
Input: stream Return: pix, or null on error
Notes: (1) If called from pixReadStream(), the stream is positioned at the beginning of the file. (2) To do sequential reads of png format images from a stream, use pixReadStreamPng()
LEPT_DLL PIX* pixReadStreamPnm | ( | FILE * | fp | ) |
Input: stream opened for read Return: pix, or null on error
LEPT_DLL PIX* pixReadStreamSpix | ( | FILE * | fp | ) |
Input: stream Return: pix, or null on error.
Notes: (1) If called from pixReadStream(), the stream is positioned at the beginning of the file.
LEPT_DLL PIX* pixReadStreamTiff | ( | FILE * | fp, |
l_int32 | n | ||
) |
Input: stream n (page number: 0 based) Return: pix, or null on error (e.g., if the page number is invalid)
LEPT_DLL PIX* pixReadStreamWebP | ( | FILE * | fp | ) |
LEPT_DLL PIX* pixReadTiff | ( | const char * | filename, |
l_int32 | n | ||
) |
Input: filename page number (0 based) Return: pix, or null on error
Notes: (1) This is a version of pixRead(), specialized for tiff files, that allows specification of the page to be returned
LEPT_DLL PIX* pixReadWithHint | ( | const char * | filename, |
l_int32 | hint | ||
) |
Input: filename (with full pathname or in local directory) hint (bitwise OR of L_HINT_* values for jpeg; use 0 for no hint) Return: pix if OK; null on error
Notes: (1) The hint is not binding, but may be used to optimize jpeg decoding. Use 0 for no hinting.
LEPT_DLL PIX* pixReduceBinary2 | ( | PIX * | pixs, |
l_uint8 * | intab | ||
) |
Input: pixs tab (<optional>; if null, a table is made here and destroyed before exit) Return: pixd (2x subsampled), or null on error
Input: pixs (1 bpp) level (rank threshold: 1, 2, 3, 4) intab (<optional>; if null, a table is made here and destroyed before exit) Return: pixd (1 bpp, 2x rank threshold reduced), or null on error
Notes: (1) pixd is downscaled by 2x from pixs. (2) The rank threshold specifies the minimum number of ON pixels in each 2x2 region of pixs that are required to set the corresponding pixel ON in pixd.
LEPT_DLL PIX* pixReduceRankBinaryCascade | ( | PIX * | pixs, |
l_int32 | level1, | ||
l_int32 | level2, | ||
l_int32 | level3, | ||
l_int32 | level4 | ||
) |
Input: pixs (1 bpp) level1, ... level 4 (thresholds, in the set {0, 1, 2, 3, 4}) Return: pixd, or null on error
Notes: (1) This performs up to four cascaded 2x rank reductions. (2) Use level = 0 to truncate the cascade.
LEPT_DLL PIX* pixRemoveBorder | ( | PIX * | pixs, |
l_int32 | npix | ||
) |
Input: pixs (all depths; colormap ok) npix (number to be removed from each of the 4 sides) Return: pixd (with pixels removed around border), or null on error
LEPT_DLL PIX* pixRemoveBorderConnComps | ( | PIX * | pixs, |
l_int32 | connectivity | ||
) |
Input: pixs (1 bpp) filling connectivity (4 or 8) Return: pixd (all pixels in the src that are not touching the border) or null on error
LEPT_DLL PIX* pixRemoveBorderGeneral | ( | PIX * | pixs, |
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot | ||
) |
Input: pixs (all depths; colormap ok) left, right, top, bot (number of pixels added) Return: pixd (with pixels removed around border), or null on error
LEPT_DLL PIX* pixRemoveColormap | ( | PIX * | pixs, |
l_int32 | type | ||
) |
Input: pixs (see restrictions below) type (REMOVE_CMAP_TO_BINARY, REMOVE_CMAP_TO_GRAYSCALE, REMOVE_CMAP_TO_FULL_COLOR, REMOVE_CMAP_BASED_ON_SRC) Return: new pix, or null on error
Notes: (1) If there is no colormap, a clone is returned. (2) Otherwise, the input pixs is restricted to 1, 2, 4 or 8 bpp. (3) Use REMOVE_CMAP_TO_BINARY only on 1 bpp pix. (4) For grayscale conversion from RGB, use a weighted average of RGB values, and always return an 8 bpp pix, regardless of whether the input pixs depth is 2, 4 or 8 bpp.
LEPT_DLL l_int32 pixRemoveMatchedPattern | ( | PIX * | pixs, |
PIX * | pixp, | ||
PIX * | pixe, | ||
l_int32 | x0, | ||
l_int32 | y0, | ||
l_int32 | dsize | ||
) |
Input: pixs (input image, 1 bpp) pixp (pattern to be removed from image, 1 bpp) pixe (image after erosion by Sel that approximates pixp, 1 bpp) x0, y0 (center of Sel) dsize (number of pixels on each side by which pixp is dilated before being subtracted from pixs; valid values are {0, 1, 2, 3, 4}) Return: 0 if OK, 1 on error
Notes: (1) This is in-place. (2) You can use various functions in selgen to create a Sel that is used to generate pixe from pixs. (3) This function is applied after pixe has been computed. It finds the centroid of each c.c., and subtracts (the appropriately dilated version of) pixp, with the center of the Sel used to align pixp with pixs.
LEPT_DLL PIX* pixRemoveSeededComponents | ( | PIX * | pixd, |
PIX * | pixs, | ||
PIX * | pixm, | ||
l_int32 | connectivity, | ||
l_int32 | bordersize | ||
) |
Input: pixd (<optional>; this can be null or equal to pixm; 1 bpp) pixs (1 bpp seed) pixm (1 bpp filling mask) connectivity (4 or 8) bordersize (amount of border clearing) Return: pixd, or null on error
Notes: (1) This removes each component in pixm for which there is at least one seed in pixs. If pixd == NULL, this returns the result in a new pixd. Otherwise, it is an in-place operation on pixm. In no situation is pixs altered, because we do the filling with a copy of pixs. (2) If bordersize > 0, it also clears all pixels within a distance of the edge of pixd. This is here because pixLocalExtrema() typically finds local minima at the border. Use >= 2 to remove these.
LEPT_DLL l_int32 pixRemoveUnusedColors | ( | PIX * | pixs | ) |
Input: pixs (colormapped) Return: 0 if OK, 1 on error
Notes: (1) This is an in-place operation. (2) If the image doesn't have a colormap, returns without error. (3) Unusued colors are removed from the colormap, and the image pixels are re-numbered.
Input: pixs (1 bpp pix from which components are removed; in-place) pixa (of connected components in pixs) na (numa indicator: remove components corresponding to 1s) Return: 0 if OK, 1 on error
Notes: (1) This complements pixAddWithIndicator(). Here, the selected components are set subtracted from pixs.
Input: pix box width (thickness of box lines) op (one of L_SET_PIXELS, L_CLEAR_PIXELS, L_FLIP_PIXELS) Return: 0 if OK, 1 on error
Input: pix boxa width (thickness of line) op (one of L_SET_PIXELS, L_CLEAR_PIXELS, L_FLIP_PIXELS) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixRenderBoxaArb | ( | PIX * | pix, |
BOXA * | boxa, | ||
l_int32 | width, | ||
l_uint8 | rval, | ||
l_uint8 | gval, | ||
l_uint8 | bval | ||
) |
Input: pix boxa width (thickness of line) rval, gval, bval Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixRenderBoxaBlend | ( | PIX * | pix, |
BOXA * | boxa, | ||
l_int32 | width, | ||
l_uint8 | rval, | ||
l_uint8 | gval, | ||
l_uint8 | bval, | ||
l_float32 | fract, | ||
l_int32 | removedups | ||
) |
Input: pix boxa width (thickness of line) rval, gval, bval fract (in [0.0 - 1.0]; complete transparency (no effect) if 0.0; no transparency if 1.0) removedups (1 to remove; 0 otherwise) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixRenderBoxArb | ( | PIX * | pix, |
BOX * | box, | ||
l_int32 | width, | ||
l_uint8 | rval, | ||
l_uint8 | gval, | ||
l_uint8 | bval | ||
) |
Input: pix (any depth, cmapped ok) box width (thickness of box lines) rval, gval, bval Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixRenderBoxBlend | ( | PIX * | pix, |
BOX * | box, | ||
l_int32 | width, | ||
l_uint8 | rval, | ||
l_uint8 | gval, | ||
l_uint8 | bval, | ||
l_float32 | fract | ||
) |
Input: pix box width (thickness of box lines) rval, gval, bval fract (in [0.0 - 1.0]; complete transparency (no effect) if 0.0; no transparency if 1.0) Return: 0 if OK, 1 on error
Input: pixs (8 or 16 bpp; no colormap) startval (value of lowest contour; must be in [0 ... maxval]) incr (increment to next contour; must be > 0) outdepth (either 1 or depth of pixs) Return: pixd, or null on error
Notes: (1) The output can be either 1 bpp, showing just the contour lines, or a copy of the input pixs with the contour lines superposed.
LEPT_DLL l_int32 pixRenderHashBox | ( | PIX * | pix, |
BOX * | box, | ||
l_int32 | spacing, | ||
l_int32 | width, | ||
l_int32 | orient, | ||
l_int32 | outline, | ||
l_int32 | op | ||
) |
Input: pix box spacing (spacing between lines; must be > 1) width (thickness of box and hash lines) orient (orientation of lines: L_HORIZONTAL_LINE, ...) outline (0 to skip drawing box outline) op (one of L_SET_PIXELS, L_CLEAR_PIXELS, L_FLIP_PIXELS) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixRenderHashBoxArb | ( | PIX * | pix, |
BOX * | box, | ||
l_int32 | spacing, | ||
l_int32 | width, | ||
l_int32 | orient, | ||
l_int32 | outline, | ||
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval | ||
) |
Input: pix box spacing (spacing between lines; must be > 1) width (thickness of box and hash lines) orient (orientation of lines: L_HORIZONTAL_LINE, ...) outline (0 to skip drawing box outline) rval, gval, bval Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixRenderHashBoxBlend | ( | PIX * | pix, |
BOX * | box, | ||
l_int32 | spacing, | ||
l_int32 | width, | ||
l_int32 | orient, | ||
l_int32 | outline, | ||
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval, | ||
l_float32 | fract | ||
) |
Input: pix box spacing (spacing between lines; must be > 1) width (thickness of box and hash lines) orient (orientation of lines: L_HORIZONTAL_LINE, ...) outline (0 to skip drawing box outline) rval, gval, bval fract (in [0.0 - 1.0]; complete transparency (no effect) if 0.0; no transparency if 1.0) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixRenderLine | ( | PIX * | pix, |
l_int32 | x1, | ||
l_int32 | y1, | ||
l_int32 | x2, | ||
l_int32 | y2, | ||
l_int32 | width, | ||
l_int32 | op | ||
) |
Input: pix x1, y1 x2, y2 width (thickness of line) op (one of L_SET_PIXELS, L_CLEAR_PIXELS, L_FLIP_PIXELS) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixRenderLineArb | ( | PIX * | pix, |
l_int32 | x1, | ||
l_int32 | y1, | ||
l_int32 | x2, | ||
l_int32 | y2, | ||
l_int32 | width, | ||
l_uint8 | rval, | ||
l_uint8 | gval, | ||
l_uint8 | bval | ||
) |
Input: pix x1, y1 x2, y2 width (thickness of line) rval, gval, bval Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixRenderLineBlend | ( | PIX * | pix, |
l_int32 | x1, | ||
l_int32 | y1, | ||
l_int32 | x2, | ||
l_int32 | y2, | ||
l_int32 | width, | ||
l_uint8 | rval, | ||
l_uint8 | gval, | ||
l_uint8 | bval, | ||
l_float32 | fract | ||
) |
Input: pix x1, y1 x2, y2 width (thickness of line) rval, gval, bval fract Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixRenderPolyline | ( | PIX * | pix, |
PTA * | ptas, | ||
l_int32 | width, | ||
l_int32 | op, | ||
l_int32 | closeflag | ||
) |
Input: pix ptas width (thickness of line) op (one of L_SET_PIXELS, L_CLEAR_PIXELS, L_FLIP_PIXELS) closeflag (1 to close the contour; 0 otherwise) Return: 0 if OK, 1 on error
Note: this renders a closed contour.
LEPT_DLL l_int32 pixRenderPolylineArb | ( | PIX * | pix, |
PTA * | ptas, | ||
l_int32 | width, | ||
l_uint8 | rval, | ||
l_uint8 | gval, | ||
l_uint8 | bval, | ||
l_int32 | closeflag | ||
) |
Input: pix ptas width (thickness of line) rval, gval, bval closeflag (1 to close the contour; 0 otherwise) Return: 0 if OK, 1 on error
Note: this renders a closed contour.
LEPT_DLL l_int32 pixRenderPolylineBlend | ( | PIX * | pix, |
PTA * | ptas, | ||
l_int32 | width, | ||
l_uint8 | rval, | ||
l_uint8 | gval, | ||
l_uint8 | bval, | ||
l_float32 | fract, | ||
l_int32 | closeflag, | ||
l_int32 | removedups | ||
) |
Input: pix ptas width (thickness of line) rval, gval, bval fract (in [0.0 - 1.0]; complete transparency (no effect) if 0.0; no transparency if 1.0) closeflag (1 to close the contour; 0 otherwise) removedups (1 to remove; 0 otherwise) Return: 0 if OK, 1 on error
Input: pix pta (arbitrary set of points) op (one of L_SET_PIXELS, L_CLEAR_PIXELS, L_FLIP_PIXELS) Return: 0 if OK, 1 on error
Notes: (1) L_SET_PIXELS puts all image bits in each pixel to 1 (black for 1 bpp; white for depth > 1) (2) L_CLEAR_PIXELS puts all image bits in each pixel to 0 (white for 1 bpp; black for depth > 1) (3) L_FLIP_PIXELS reverses all image bits in each pixel (4) This function clips the rendering to the pix. It performs clipping for functions such as pixRenderLine(), pixRenderBox() and pixRenderBoxa(), that call pixRenderPta().
Input: pix (any depth, cmapped ok) pta (arbitrary set of points) rval, gval, bval Return: 0 if OK, 1 on error
Notes: (1) If pix is colormapped, render this color on each pixel. (2) If pix is not colormapped, do the best job you can using the input colors:
LEPT_DLL l_int32 pixRenderPtaBlend | ( | PIX * | pix, |
PTA * | pta, | ||
l_uint8 | rval, | ||
l_uint8 | gval, | ||
l_uint8 | bval, | ||
l_float32 | fract | ||
) |
Input: pix (32 bpp rgb) pta (arbitrary set of points) rval, gval, bval Return: 0 if OK, 1 on error
Notes: (1) This function clips the rendering to the pix.
LEPT_DLL PIX* pixRenderRandomCmapPtaa | ( | PIX * | pix, |
PTAA * | ptaa, | ||
l_int32 | polyflag, | ||
l_int32 | width, | ||
l_int32 | closeflag | ||
) |
Input: pix (1, 2, 4, 8, 16, 32 bpp) ptaa polyflag (1 to interpret each Pta as a polyline; 0 to simply render the Pta as a set of pixels) width (thickness of line; use only for polyline) closeflag (1 to close the contour; 0 otherwise; use only for polyline mode) Return: pixd (cmapped, 8 bpp) or null on error
Notes: (1) This is a debugging routine, that displays a set of pixels, selected by the set of Ptas in a Ptaa, in a random color in a pix. (2) If == 1, each Pta is considered to be a polyline, and is rendered using and . Each polyline is rendered in a random color. (3) If == 0, all points in each Pta are rendered in a random color. The and parameters are ignored. (4) The output pix is 8 bpp and colormapped. Up to 254 different, randomly selected colors, can be used. (5) The rendered pixels replace the input pixels. They will be clipped silently to the input pix.
LEPT_DLL l_int32 pixResizeImageData | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
Input: pixd (gets new uninitialized buffer for image data) pixs (determines the size of the buffer; not changed) Return: 0 if OK, 1 on error
Notes: (1) This removes any existing image data from pixd and allocates an uninitialized buffer that will hold the amount of image data that is in pixs.
Input: pixs (1, 2, 4, 8, 16, 32 bpp; colormap ok) pixt (can be null; we use only the size) w, h (ignored if pixt is defined) Return: pixd (resized to match) or null on error
Notes: (1) This resizes pixs to make pixd, without scaling, by either cropping or extending separately in both width and height. Extension is done by replicating the last row or column. This is useful in a situation where, due to scaling operations, two images that are expected to be the same size can differ slightly in each dimension. (2) You can use either an existing pixt or specify both and . If pixt is defined, the values in and are ignored. (3) If pixt is larger than pixs (or if w and/or d is larger than the dimension of pixs, replicate the outer row and column of pixels in pixs into pixd.
LEPT_DLL NUMA* pixReversalProfile | ( | PIX * | pixs, |
l_float32 | fract, | ||
l_int32 | dir, | ||
l_int32 | first, | ||
l_int32 | last, | ||
l_int32 | minreversal, | ||
l_int32 | factor1, | ||
l_int32 | factor2 | ||
) |
LEPT_DLL PIX* pixRotate | ( | PIX * | pixs, |
l_float32 | angle, | ||
l_int32 | type, | ||
l_int32 | incolor, | ||
l_int32 | width, | ||
l_int32 | height | ||
) |
Input: pixs (1, 2, 4, 8, 32 bpp rgb) angle (radians; clockwise is positive) type (L_ROTATE_AREA_MAP, L_ROTATE_SHEAR, L_ROTATE_SAMPLING) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) width (original width; use 0 to avoid embedding) height (original height; use 0 to avoid embedding) Return: pixd, or null on error
Notes: (1) Rotation is about the center of the image. (2) For very small rotations, just return a clone. (3) Rotation brings either white or black pixels in from outside the image. (4) Above 20 degrees, if rotation by shear is requested, we rotate by sampling. (5) Colormaps are removed for rotation by area map and shear. (6) The dest can be expanded so that no image pixels are lost. To invoke expansion, input the original width and height. For repeated rotation, use of the original width and height allows the expansion to stop at the maximum required size, which is a square with side = sqrt(w*w + h*h).
*** Warning: implicit assumption about RGB component ordering ***
LEPT_DLL PIX* pixRotate180 | ( | PIX * | pixd, |
PIX * | pixs | ||
) |
Input: pixd (<optional>; can be null, equal to pixs, or different from pixs) pixs (all depths) Return: pixd, or null on error
Notes: (1) This does a 180 rotation of the image about the center, which is equivalent to a left-right flip about a vertical line through the image center, followed by a top-bottom flip about a horizontal line through the image center. (2) There are 3 cases for input: (a) pixd == null (creates a new pixd) (b) pixd == pixs (in-place operation) (c) pixd != pixs (existing pixd) (3) For clarity, use these three patterns, respectively: (a) pixd = pixRotate180(NULL, pixs); (b) pixRotate180(pixs, pixs); (c) pixRotate180(pixd, pixs);
LEPT_DLL PIX* pixRotate2Shear | ( | PIX * | pixs, |
l_int32 | xcen, | ||
l_int32 | ycen, | ||
l_float32 | angle, | ||
l_int32 | incolor | ||
) |
Input: pixs xcen, ycen (center of rotation) angle (radians) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK); Return: pixd, or null on error.
Notes: (1) This rotates the image about the given point, using the 2-shear method. It should only be used for angles smaller than MAX_2_SHEAR_ANGLE. (2) A positive angle gives a clockwise rotation. (3) 2-shear rotation by a specified angle is equivalent to the sequential transformations x' = x + tan(angle) * (y - ycen) for x-shear y' = y + tan(angle) * (x - xcen) for y-shear (4) Computation of tan(angle) is performed within the shear operation. (5) This brings in 'incolor' pixels from outside the image.
LEPT_DLL PIX* pixRotate3Shear | ( | PIX * | pixs, |
l_int32 | xcen, | ||
l_int32 | ycen, | ||
l_float32 | angle, | ||
l_int32 | incolor | ||
) |
Input: pixs xcen, ycen (center of rotation) angle (radians) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK); Return: pixd, or null on error.
Notes: (1) This rotates the image about the image center, using the 3-shear method. It can be used for any angle, and should be used for angles larger than MAX_2_SHEAR_ANGLE. (2) A positive angle gives a clockwise rotation. (3) 3-shear rotation by a specified angle is equivalent to the sequential transformations y' = y + tan(angle/2) * (x - xcen) for first y-shear x' = x + sin(angle) * (y - ycen) for x-shear y' = y + tan(angle/2) * (x - xcen) for second y-shear (4) Computation of tan(angle) is performed in the shear operations. (5) This brings in 'incolor' pixels from outside the image. (6) The algorithm was published by Alan Paeth: "A Fast Algorithm for General Raster Rotation," Graphics Interface '86, pp. 77-81, May 1986. A description of the method, along with an implementation, can be found in Graphics Gems, p. 179, edited by Andrew Glassner, published by Academic Press, 1990.
LEPT_DLL PIX* pixRotate90 | ( | PIX * | pixs, |
l_int32 | direction | ||
) |
Input: pixs (all depths) direction (1 = clockwise, -1 = counter-clockwise) Return: pixd, or null on error
Notes: (1) This does a 90 degree rotation of the image about the center, either cw or ccw, returning a new pix. (2) The direction must be either 1 (cw) or -1 (ccw).
Input: pixs (2, 4, 8 bpp gray or colormapped, or 32 bpp RGB) angle (radians; clockwise is positive) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Rotates about image center. (2) A positive angle gives a clockwise rotation. (3) Brings in either black or white pixels from the boundary.
Input: pixs (32 bpp) angle (radians; clockwise is positive) colorval (e.g., 0 to bring in BLACK, 0xffffff00 for WHITE) Return: pixd, or null on error
Notes: (1) Rotates about image center. (2) A positive angle gives a clockwise rotation. (3) Specify the color to be brought in from outside the image.
Input: pixs angle (radians; clockwise is positive) colorval (e.g., 0 to bring in BLACK, 0xffffff00 for WHITE) Return: pixd, or null on error
Notes: (1) Rotates the image about the UL corner. (2) A positive angle gives a clockwise rotation. (3) Specify the color to be brought in from outside the image.
Input: pixs angle (radians; clockwise is positive) colorval (e.g., 0 to bring in BLACK, 0xffffff00 for WHITE) Return: pixd, or null on error
Notes: (1) This rotates a color image about the image center. (2) A positive angle gives a clockwise rotation. (3) It uses area mapping, dividing each pixel into 16 subpixels. (4) It is about 10% to 20% faster than the more accurate linear interpolation function pixRotateAMColor(), which uses 256 subpixels.
*** Warning: implicit assumption about RGB component ordering ***
Input: pixs (1, 2, 4, 8 bpp gray or colormapped, or 32 bpp RGB) angle (radians; clockwise is positive) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) Rotates about the UL corner of the image. (2) A positive angle gives a clockwise rotation. (3) Brings in either black or white pixels from the boundary.
Input: pixs (8 bpp) angle (radians; clockwise is positive) grayval (0 to bring in BLACK, 255 for WHITE) Return: pixd, or null on error
Notes: (1) Rotates about image center. (2) A positive angle gives a clockwise rotation. (3) Specify the grayvalue to be brought in from outside the image.
Input: pixs angle (radians; clockwise is positive) grayval (0 to bring in BLACK, 255 for WHITE) Return: pixd, or null on error
Notes: (1) Rotates the image about the UL corner. (2) A positive angle gives a clockwise rotation. (3) Specify the grayvalue to be brought in from outside the image.
Input: pixs (1 bpp) angle (radians; clockwise is positive; about the center) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) For very small rotations, just return a clone. (2) This does a computationally expensive rotation of 1 bpp images. The fastest rotators (using shears or subsampling) leave visible horizontal and vertical shear lines across which the image shear changes by one pixel. To ameliorate the visual effect one can introduce random dithering. One way to do this in a not-too-random fashion is given here. We convert to 8 bpp, do a very small blur, rotate using linear interpolation (same as area mapping), do a small amount of sharpening to compensate for the initial blur, and threshold back to binary. The shear lines are magically removed. (3) This operation is about 5x slower than rotation by sampling.
LEPT_DLL PIX* pixRotateBySampling | ( | PIX * | pixs, |
l_int32 | xcen, | ||
l_int32 | ycen, | ||
l_float32 | angle, | ||
l_int32 | incolor | ||
) |
Input: pixs (1, 2, 4, 8, 16, 32 bpp rgb; can be cmapped) xcen (x value of center of rotation) ycen (y value of center of rotation) angle (radians; clockwise is positive) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Notes: (1) For very small rotations, just return a clone. (2) Rotation brings either white or black pixels in from outside the image. (3) Colormaps are retained.
Input: pixs (32 bpp rgb) gamma (gamma correction; must be > 0.0) angle (radians; clockwise is positive) fract (between 0.0 and 1.0, with 1.0 fully transparent) Return: pixd, or null on error
Notes: (1) This wraps a gamma/inverse-gamma photometric transform around pixRotateWithAlpha(). (2) For usage, see notes in pixRotateWithAlpha() and pixGammaTRCWithAlpha(). (3) The basic idea of a gamma/inverse-gamma transform is to remove gamma correction before rotating and restore it afterward. The effects can be subtle, but important for some applications. For example, using gamma > 1.0 will cause the dark areas to become somewhat lighter and slightly reduce aliasing effects when blending using the alpha channel.
LEPT_DLL PIX* pixRotateOrth | ( | PIX * | pixs, |
l_int32 | quads | ||
) |
Input: pixs (all depths) quads (0-3; number of 90 degree cw rotations) Return: pixd, or null on error
LEPT_DLL PIX* pixRotateShear | ( | PIX * | pixs, |
l_int32 | xcen, | ||
l_int32 | ycen, | ||
l_float32 | angle, | ||
l_int32 | incolor | ||
) |
Input: pixs xcen (x value for which there is no horizontal shear) ycen (y value for which there is no vertical shear) angle (radians) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK); Return: pixd, or null on error.
Notes: (1) This rotates an image about the given point, using either 2 or 3 shears. (2) A positive angle gives a clockwise rotation. (3) This brings in 'incolor' pixels from outside the image.
Input: pixs angle (radians) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error
Input: pixs angle (radians) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixRotateShearIP | ( | PIX * | pixs, |
l_int32 | xcen, | ||
l_int32 | ycen, | ||
l_float32 | angle, | ||
l_int32 | incolor | ||
) |
Input: pixs (any depth; not colormapped) xcen, ycen (center of rotation) angle (radians) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: 0 if OK; 1 on error
Notes: (1) This does an in-place rotation of the image about the image center, using the 3-shear method. (2) A positive angle gives a clockwise rotation. (3) 3-shear rotation by a specified angle is equivalent to the sequential transformations y' = y + tan(angle/2) * (x - xcen) for first y-shear x' = x + sin(angle) * (y - ycen) for x-shear y' = y + tan(angle/2) * (x - xcen) for second y-shear (4) Computation of tan(angle) is performed in the shear operations. (5) This brings in 'incolor' pixels from outside the image. (6) The pix cannot be colormapped, because the in-place operation only blits in 0 or 1 bits, not an arbitrary colormap index.
Input: pixs (32 bpp rgb) angle (radians; clockwise is positive) pixg (<optional> 8 bpp, can be null) fract (between 0.0 and 1.0, with 0.0 fully transparent and 1.0 fully opaque) Return: pixd, or null on error
Notes: (1) The alpha channel is transformed separately from pixs, and aligns with it, being fully transparent outside the boundary of the transformed pixs. For pixels that are fully transparent, a blending function like pixBlendWithGrayMask() will give zero weight to corresponding pixels in pixs. (2) Rotation is about the center of the image; for very small rotations, just return a clone. The dest is automatically expanded so that no image pixels are lost. (3) Rotation is by area mapping. It doesn't matter what color is brought in because the alpha channel will be transparent (black) there. (4) If pixg is NULL, it is generated as an alpha layer that is partially opaque, using . Otherwise, it is cropped to pixs if required and is ignored. The alpha channel in pixs is never used. (4) Colormaps are removed. (5) The default setting for the border values in the alpha channel is 0 (transparent) for the outermost ring of pixels and (0.5 * fract * 255) for the second ring. When blended over a second image, this (a) shrinks the visible image to make a clean overlap edge with an image below, and (b) softens the edges by weakening the aliasing there. Use l_setAlphaMaskBorder() to change these values.
*** Warning: implicit assumption about RGB component ordering ***
LEPT_DLL l_int32 pixRowStats | ( | PIX * | pixs, |
NUMA ** | pnamean, | ||
NUMA ** | pnamedian, | ||
NUMA ** | pnamode, | ||
NUMA ** | pnamodecount, | ||
NUMA ** | pnavar, | ||
NUMA ** | pnarootvar | ||
) |
Input: pixs (8 bpp; not cmapped) &namean (<optional return>=""> numa of mean values) &namedian (<optional return>=""> numa of median values) &namode (<optional return>=""> numa of mode intensity values) &namodecount (<optional return>=""> numa of mode counts) &navar (<optional return>=""> numa of variance) &narootvar (<optional return>=""> numa of square root of variance) Return: na (numa of requested statistic for each row), or null on error
Notes: (1) This computes numas that represent column vectors of statistics, with each of its values derived from the corresponding row of a Pix. (2) Use NULL on input to prevent computation of any of the 5 numas. (3) Other functions that compute pixel row statistics are: pixCountPixelsByRow() pixSumPixelsByRow() pixGetRowStats()
LEPT_DLL NUMA* pixRunHistogramMorph | ( | PIX * | pixs, |
l_int32 | runtype, | ||
l_int32 | direction, | ||
l_int32 | maxsize | ||
) |
Input: pixs runtype (L_RUN_OFF, L_RUN_ON) direction (L_HORIZ, L_VERT) maxsize (size of largest runlength counted) Return: numa of run-lengths
Input: pixs (1 bpp) color (0 for white runs, 1 for black runs) direction (L_HORIZONTAL_RUNS, L_VERTICAL_RUNS) depth (8 or 16 bpp) Return: pixd (8 or 16 bpp), or null on error
Notes: (1) The dest Pix is 8 or 16 bpp, with the pixel values equal to the runlength in which it is a member. The length is clipped to the max pixel value if necessary. (2) The color determines if we're labelling white or black runs. (3) A pixel that is not a member of the chosen color gets value 0; it belongs to a run of length 0 of the chosen color. (4) To convert for maximum dynamic range, either linear or log, use pixMaxDynamicRange().
LEPT_DLL l_int32 pixSauvolaBinarize | ( | PIX * | pixs, |
l_int32 | whsize, | ||
l_float32 | factor, | ||
l_int32 | addborder, | ||
PIX ** | ppixm, | ||
PIX ** | ppixsd, | ||
PIX ** | ppixth, | ||
PIX ** | ppixd | ||
) |
Input: pixs (8 bpp grayscale; not colormapped) whsize (window half-width for measuring local statistics) factor (factor for reducing threshold due to variance; >= 0) addborder (1 to add border of width ( + 1) on all sides) &pixm (<optional return>=""> local mean values) &pixsd (<optional return>=""> local standard deviation values) &pixth (<optional return>=""> threshold values) &pixd (<optional return>=""> thresholded image) Return: 0 if OK, 1 on error
Notes: (1) The window width and height are 2 * + 1. The minimum value for is 2; typically it is >= 7.. (2) The local statistics, measured over the window, are the average and standard deviation. (3) The measurements of the mean and standard deviation are performed inside a border of ( + 1) pixels. If pixs does not have these added border pixels, use = 1 to add it here; otherwise use = 0. (4) The Sauvola threshold is determined from the formula: t = m * (1 - k * (1 - s / 128)) where: t = local threshold m = local mean k = (>= 0) [ typ. 0.35 ] s = local standard deviation, which is maximized at 127.5 when half the samples are 0 and half are 255. (5) The basic idea of Niblack and Sauvola binarization is that the local threshold should be less than the median value, and the larger the variance, the closer to the median it should be chosen. Typical values for k are between 0.2 and 0.5.
LEPT_DLL l_int32 pixSauvolaBinarizeTiled | ( | PIX * | pixs, |
l_int32 | whsize, | ||
l_float32 | factor, | ||
l_int32 | nx, | ||
l_int32 | ny, | ||
PIX ** | ppixth, | ||
PIX ** | ppixd | ||
) |
Input: pixs (8 bpp grayscale, not colormapped) whsize (window half-width for measuring local statistics) factor (factor for reducing threshold due to variance; >= 0) nx, ny (subdivision into tiles; >= 1) &pixth (<optional return>=""> Sauvola threshold values) &pixd (<optional return>=""> thresholded image) Return: 0 if OK, 1 on error
Notes: (1) The window width and height are 2 * + 1. The minimum value for is 2; typically it is >= 7.. (2) For nx == ny == 1, this defaults to pixSauvolaBinarize(). (3) Why a tiled version? (a) Because the mean value accumulator is a uint32, overflow can occur for an image with more than 16M pixels. (b) The mean value accumulator array for 16M pixels is 64 MB. The mean square accumulator array for 16M pixels is 128 MB. Using tiles reduces the size of these arrays. (c) Each tile can be processed independently, in parallel, on a multicore processor. (4) The Sauvola threshold is determined from the formula: t = m * (1 - k * (1 - s / 128)) See pixSauvolaBinarize() for details.
Input: pixm (8 bpp grayscale; not colormapped) pixms (32 bpp) factor (factor for reducing threshold due to variance; >= 0) &pixsd (<optional return>=""> local standard deviation) Return: pixd (8 bpp, sauvola threshold values), or null on error
Notes: (1) The Sauvola threshold is determined from the formula: t = m * (1 - k * (1 - s / 128)) where: t = local threshold m = local mean k = (>= 0) [ typ. 0.35 ] s = local standard deviation, which is maximized at 127.5 when half the samples are 0 and half are 255. (2) See pixSauvolaBinarize() for other details. (3) Important definitions and relations for computing averages: v == pixel value E(p) == expected value of p == average of p over some pixel set S(v) == square of v == v * v mv == E(v) == expected pixel value == mean value ms == E(S(v)) == expected square of pixel values == mean square value var == variance == expected square of deviation from mean == E(S(v - mv)) = E(S(v) - 2 * S(v * mv) + S(mv)) = E(S(v)) - S(mv) = ms - mv * mv s == standard deviation = sqrt(var) So for evaluating the standard deviation in the Sauvola threshold, we take s = sqrt(ms - mv * mv)
LEPT_DLL l_int32 pixSaveTiled | ( | PIX * | pixs, |
PIXA * | pixa, | ||
l_int32 | reduction, | ||
l_int32 | newrow, | ||
l_int32 | space, | ||
l_int32 | dp | ||
) |
Input: pixs (1, 2, 4, 8, 32 bpp) pixa (the pix are accumulated here) reduction (0 to disable; otherwise this is a reduction factor) newrow (0 if placed on the same row as previous; 1 otherwise) space (horizontal and vertical spacing, in pixels) dp (depth of pixa; 8 or 32 bpp; only used on first call) Return: 0 if OK, 1 on error.
LEPT_DLL l_int32 pixSaveTiledOutline | ( | PIX * | pixs, |
PIXA * | pixa, | ||
l_int32 | reduction, | ||
l_int32 | newrow, | ||
l_int32 | space, | ||
l_int32 | linewidth, | ||
l_int32 | dp | ||
) |
Input: pixs (1, 2, 4, 8, 32 bpp) pixa (the pix are accumulated here) reduction (0 to disable; otherwise this is a reduction factor) newrow (0 if placed on the same row as previous; 1 otherwise) space (horizontal and vertical spacing, in pixels) linewidth (width of added outline for image; 0 for no outline) dp (depth of pixa; 8 or 32 bpp; only used on first call) Return: 0 if OK, 1 on error.
Notes: (1) Before calling this function for the first time, use pixaCreate() to make the that will accumulate the pix. This is passed in each time pixSaveTiled() is called. (2) is the integer reduction factor for the input image. After reduction and possible depth conversion, the image is saved in the input pixa, along with a box that specifies the location to place it when tiled later. Disable saving the pix by setting reduction == 0. (3) and specify the location of the new pix with respect to the last one(s) that were entered. (4) specifies the depth at which all pix are saved. It can be only 8 or 32 bpp. Any colormap is removed. This is only used at the first invocation. (5) This function uses two variables from call to call. If they were static, the function would not be .so or thread safe, and furthermore, there would be interference with two or more pixa accumulating images at a time. Consequently, we use the first pix in the pixa to store and obtain both the depth and the current position of the bottom (one pixel below the lowest image raster line when laid out using the boxa). The bottom variable is stored in the input format field, which is the only field available for storing an int.
LEPT_DLL l_int32 pixSaveTiledWithText | ( | PIX * | pixs, |
PIXA * | pixa, | ||
l_int32 | outwidth, | ||
l_int32 | newrow, | ||
l_int32 | space, | ||
l_int32 | linewidth, | ||
L_BMF * | bmf, | ||
const char * | textstr, | ||
l_uint32 | val, | ||
l_int32 | location | ||
) |
Input: pixs (1, 2, 4, 8, 32 bpp) pixa (the pix are accumulated here; as 32 bpp) outwidth (in pixels; use 0 to disable entirely) newrow (1 to start a new row; 0 to go on same row as previous) space (horizontal and vertical spacing, in pixels) linewidth (width of added outline for image; 0 for no outline) bmf (<optional> font struct) textstr (<optional> text string to be added) val (color to set the text) location (L_ADD_ABOVE, L_ADD_AT_TOP, L_ADD_AT_BOTTOM, L_ADD_BELOW) Return: 0 if OK, 1 on error.
Notes: (1) Before calling this function for the first time, use pixaCreate() to make the that will accumulate the pix. This is passed in each time pixSaveTiled() is called. (2) is the scaled width. After scaling, the image is saved in the input pixa, along with a box that specifies the location to place it when tiled later. Disable saving the pix by setting == 0. (3) and specify the location of the new pix with respect to the last one(s) that were entered. (4) All pix are saved as 32 bpp RGB. (5) If both and are defined, this generates a pix with the additional text; otherwise, no text is written. (6) The text is written before scaling, so it is properly antialiased in the scaled pix. However, if the pix on different calls have different widths, the size of the text will vary. (7) See pixSaveTiledOutline() for other implementation details.
Input: pixs (1, 2, 4, 8, 16 and 32 bpp) scalex, scaley Return: pixd, or null on error
This function scales 32 bpp RGB; 2, 4 or 8 bpp palette color; 2, 4, 8 or 16 bpp gray; and binary images.
When the input has palette color, the colormap is removed and the result is either 8 bpp gray or 32 bpp RGB, depending on whether the colormap has color entries. Images with 2, 4 or 16 bpp are converted to 8 bpp.
Because pixScale() is meant to be a very simple interface to a number of scaling functions, including the use of unsharp masking, the type of scaling and the sharpening parameters are chosen by default. Grayscale and color images are scaled using one of four methods, depending on the scale factors: (1) antialiased subsampling (lowpass filtering followed by subsampling, implemented here by area mapping), for scale factors less than 0.2 (2) antialiased subsampling with sharpening, for scale factors between 0.2 and 0.7 (3) linear interpolation with sharpening, for scale factors between 0.7 and 1.4 (4) linear interpolation without sharpening, for scale factors >= 1.4.
One could use subsampling for scale factors very close to 1.0, because it preserves sharp edges. Linear interpolation blurs edges because the dest pixels will typically straddle two src edge pixels. Subsmpling removes entire columns and rows, so the edge is not blurred. However, there are two reasons for not doing this. First, it moves edges, so that a straight line at a large angle to both horizontal and vertical will have noticable kinks where horizontal and vertical rasters are removed. Second, although it is very fast, you get good results on sharp edges by applying a sharpening filter.
For images with sharp edges, sharpening substantially improves the image quality for scale factors between about 0.2 and about 2.0. However, the generic sharpening operation is about 3 times slower than linear interpolation, so there is a speed-vs-quality tradeoff. (Note: the cases where the sharpening halfwidth is 1 or 2 have special implementations and are about twice as fast as the general case). When the scale factor is larger than 1.4, the cost, which is proportional to image area, is very large for the incremental quality improvement, so we cut off the use of sharpening at 1.4. For scale factors greater than 1.4, these high-level scaling functions only do linear interpolation.
Because sharpening is computationally expensive, we provide the option of not doing it. To avoid sharpening, call pixScaleGeneral() with = 0.0. pixScale() uses a small amount of of sharpening because it strengthens edge pixels that are weak due to anti-aliasing. The sharpening factors are: * for scaling factors < 0.7: sharpfract = 0.2 sharpwidth = 1 * for scaling factors >= 0.7: sharpfract = 0.4 sharpwidth = 2
The constraints that tie sharpening to the scale factor in pixScaleGeneral() can be circumvented by calling with = 0.0. This can be followed by the sharpening of choice; e.g., pixUnsharpMasking().
Binary images are scaled by sampling the closest pixel, without any low-pass filtering (averaging of neighboring pixels). This will introduce aliasing for reductions, which can be prevented by using pixScaleToGray() instead.
*** Warning: implicit assumption about RGB component order for LI color scaling
Input: pixs (2, 4, 8 or 32 bpp; and 2, 4, 8 bpp with colormap) scalex, scaley (must both be <= 0.7) Return: pixd, or null on error
Notes: (1) This function should only be used when the scale factors are less than or equal to 0.7 (i.e., more than about 1.42x reduction). If either scale factor is larger than 0.7, we issue a warning and invoke pixScale(). (2) This works only on 2, 4, 8 and 32 bpp images. If there is a colormap, it is removed by converting to RGB. In other cases, we issue a warning and invoke pixScale(). (3) It does a relatively expensive area mapping computation, to avoid antialiasing. It is about 2x slower than pixScaleSmooth(), but the results are much better on fine text. (4) This is typically about 20% faster for the special cases of 2x, 4x, 8x and 16x reduction. (5) Surprisingly, there is no speedup (and a slight quality impairment) if you do as many successive 2x reductions as possible, ending with a reduction with a scale factor larger than 0.5.
*** Warning: implicit assumption about RGB component ordering ***
LEPT_DLL PIX* pixScaleAreaMap2 | ( | PIX * | pix | ) |
Input: pixs (2, 4, 8 or 32 bpp; and 2, 4, 8 bpp with colormap) Return: pixd, or null on error
Notes: (1) This function does an area mapping (average) for 2x reduction. (2) This works only on 2, 4, 8 and 32 bpp images. If there is a colormap, it is removed by converting to RGB. (3) Speed on 3 GHz processor: Color: 160 Mpix/sec Gray: 700 Mpix/sec This contrasts with the speed of the general pixScaleAreaMap(): Color: 35 Mpix/sec Gray: 50 Mpix/sec (4) From (3), we see that this special function is about 4.5x faster for color and 14x faster for grayscale (5) Consequently, pixScaleAreaMap2() is incorporated into the general area map scaling function, for the special cases of 2x, 4x, 8x and 16x reduction.
Input: pixs (1 bpp) scalex, scaley (both > 0.0) Return: pixd, or null on error
Notes: (1) This function samples from the source without filtering. As a result, aliasing will occur for subsampling (scalex and scaley < 1.0).
LEPT_DLL PIX* pixScaleByIntSubsampling | ( | PIX * | pixs, |
l_int32 | factor | ||
) |
Input: pixs (1, 2, 4, 8, 16, 32 bpp) factor (integer subsampling) Return: pixd, or null on error
Notes: (1) Simple interface to pixScaleBySampling(), for isotropic integer reduction. (2) If == 1, returns a copy.
Input: pixs (1, 2, 4, 8, 16, 32 bpp) scalex, scaley (both > 0.0) Return: pixd, or null on error
Notes: (1) This function samples from the source without filtering. As a result, aliasing will occur for subsampling ( and/or < 1.0). (2) If == 1.0 and == 1.0, returns a copy.
LEPT_DLL PIX* pixScaleColor2xLI | ( | PIX * | pixs | ) |
Input: pixs (32 bpp, representing rgb) Return: pixd, or null on error
Notes: (1) This is a special case of linear interpolated scaling, for 2x upscaling. It is about 8x faster than using the generic pixScaleColorLI(), and about 4x faster than using the special 2x scale function pixScaleGray2xLI() on each of the three components separately. (2) The speed on intel hardware is about 80 * 10^6 dest-pixels/sec/GHz (!!)
*** Warning: implicit assumption about RGB component ordering ***
LEPT_DLL PIX* pixScaleColor4xLI | ( | PIX * | pixs | ) |
Input: pixs (32 bpp, representing rgb) Return: pixd, or null on error
Notes: (1) This is a special case of color linear interpolated scaling, for 4x upscaling. It is about 3x faster than using the generic pixScaleColorLI(). (2) The speed on intel hardware is about 30 * 10^6 dest-pixels/sec/GHz (3) This scales each component separately, using pixScaleGray4xLI(). It would be about 4x faster to inline the color code properly, in analogy to scaleColor4xLILow(), and I leave this as an exercise for someone who really needs it.
Input: pixs (32 bpp, representing rgb) scalex, scaley (must both be >= 0.7) Return: pixd, or null on error
Notes: (1) If this is used for scale factors less than 0.7, it will suffer from antialiasing. A warning is issued. Particularly for document images with sharp edges, use pixScaleSmooth() or pixScaleAreaMap() instead. (2) For the general case, it's about 4x faster to manipulate the color pixels directly, rather than to make images out of each of the 3 components, scale each component using the pixScaleGrayLI(), and combine the results back into an rgb image. (3) The speed on intel hardware for the general case (not 2x) is about 10 * 10^6 dest-pixels/sec/GHz. (The special 2x case runs at about 80 * 10^6 dest-pixels/sec/GHz.)
LEPT_DLL PIX* pixScaleGammaXform | ( | PIX * | pixs, |
l_float32 | gamma, | ||
l_float32 | scalex, | ||
l_float32 | scaley, | ||
l_float32 | fract | ||
) |
Input: pixs (32 bpp rgb) gamma (gamma correction; must be > 0.0) scalex, scaley (must be > 0.0) fract (between 0.0 and 1.0, with 1.0 fully transparent) Return: pixd, or null on error
Notes: (1) This wraps a gamma/inverse-gamma photometric transform around pixScaleWithAlpha(). (2) For usage, see notes in pixScaleWithAlpha() and pixGammaTRCWithAlpha(). (3) The basic idea of a gamma/inverse-gamma transform is to remove gamma correction before scaling and restore it afterward. The effects can be subtle, but important for some applications. For example, using gamma > 1.0 will cause the dark areas to become somewhat lighter and slightly reduce aliasing effects when blending using the alpha channel.
LEPT_DLL PIX* pixScaleGeneral | ( | PIX * | pixs, |
l_float32 | scalex, | ||
l_float32 | scaley, | ||
l_float32 | sharpfract, | ||
l_int32 | sharpwidth | ||
) |
Input: pixs (1, 2, 4, 8, 16 and 32 bpp) scalex, scaley (both > 0.0) sharpfract (use 0.0 to skip sharpening) sharpwidth (halfwidth of low-pass filter; typ. 1 or 2) Return: pixd, or null on error
Notes: (1) See pixScale() for usage. (2) This interface may change in the future, as other special cases are added. (3) The actual sharpening factors used depend on the maximum of the two scale factors (maxscale): maxscale <= 0.2: no sharpening 0.2 < maxscale < 1.4: uses the input parameters maxscale >= 1.4: no sharpening (4) To avoid sharpening for grayscale and color images with scaling factors between 0.2 and 1.4, call this function with == 0.0. (5) To use arbitrary sharpening in conjunction with scaling, call this function with = 0.0, and follow this with a call to pixUnsharpMasking() with your chosen parameters.
LEPT_DLL PIX* pixScaleGray2xLI | ( | PIX * | pixs | ) |
Input: pixs (8 bpp grayscale) Return: pixd, or null on error
Notes: (1) This is a special case of gray linear interpolated scaling, for 2x upscaling. It is about 6x faster than using the generic pixScaleGrayLI(). (2) The speed on intel hardware is about 100 * 10^6 dest-pixels/sec/GHz
LEPT_DLL PIX* pixScaleGray2xLIDither | ( | PIX * | pixs | ) |
Input: pixs (8 bpp) Return: pixd (1 bpp), or null on error
Notes: (1) This does 2x upscale on pixs, using linear interpolation, followed by Floyd-Steinberg dithering to binary. (2) Buffers are used to avoid making a large grayscale image.
LEPT_DLL PIX* pixScaleGray2xLIThresh | ( | PIX * | pixs, |
l_int32 | thresh | ||
) |
Input: pixs (8 bpp) thresh (between 0 and 256) Return: pixd (1 bpp), or null on error
Notes: (1) This does 2x upscale on pixs, using linear interpolation, followed by thresholding to binary. (2) Buffers are used to avoid making a large grayscale image.
LEPT_DLL PIX* pixScaleGray4xLI | ( | PIX * | pixs | ) |
Input: pixs (8 bpp grayscale) Return: pixd, or null on error
Notes: (1) This is a special case of gray linear interpolated scaling, for 4x upscaling. It is about 12x faster than using the generic pixScaleGrayLI(). (2) The speed on intel hardware is about 160 * 10^6 dest-pixels/sec/GHz (!!)
LEPT_DLL PIX* pixScaleGray4xLIDither | ( | PIX * | pixs | ) |
Input: pixs (8 bpp) Return: pixd (1 bpp), or null on error
Notes: (1) This does 4x upscale on pixs, using linear interpolation, followed by Floyd-Steinberg dithering to binary. (2) Buffers are used to avoid making a large grayscale image.
LEPT_DLL PIX* pixScaleGray4xLIThresh | ( | PIX * | pixs, |
l_int32 | thresh | ||
) |
Input: pixs (8 bpp) thresh (between 0 and 256) Return: pixd (1 bpp), or null on error
Notes: (1) This does 4x upscale on pixs, using linear interpolation, followed by thresholding to binary. (2) Buffers are used to avoid making a large grayscale image. (3) If a full 4x expanded grayscale image can be kept in memory, this function is only about 10% faster than separately doing a linear interpolation to a large grayscale image, followed by thresholding to binary.
Input: pixs (8 bpp grayscale) scalex, scaley (must both be >= 0.7) Return: pixd, or null on error
This function is appropriate for upscaling (magnification: scale factors > 1), and for a small amount of downscaling (reduction: scale factors > 0.5). For scale factors less than 0.5, the best result is obtained by area mapping, but this is very expensive. So for such large reductions, it is more appropriate to do low pass filtering followed by subsampling, a combination which is effectively a cheap form of area mapping.
Some details follow.
For each pixel in the dest, this does a linear interpolation of 4 neighboring pixels in the src. Specifically, consider the UL corner of src and dest pixels. The UL corner of the dest falls within a src pixel, whose four corners are the UL corners of 4 adjacent src pixels. The value of the dest is taken by linear interpolation using the values of the four src pixels and the distance of the UL corner of the dest from each corner.
If the image is expanded so that the dest pixel is smaller than the src pixel, such interpolation is a reasonable approach. This interpolation is also good for a small image reduction factor that is not more than a 2x reduction.
Note that the linear interpolation algorithm for scaling is identical in form to the area-mapping algorithm for grayscale rotation. The latter corresponds to a translation of each pixel without scaling.
This function is NOT optimal if the scaling involves a large reduction. If the image is significantly reduced, so that the dest pixel is much larger than the src pixels, this interpolation, which is over src pixels only near the UL corner of the dest pixel, is not going to give a good area-mapping average. Because area mapping for image scaling is considerably more computationally intensive than linear interpolation, we choose not to use it. For large image reduction, linear interpolation over adjacent src pixels degenerates asymptotically to subsampling. But subsampling without a low-pass pre-filter causes aliasing by the nyquist theorem. To avoid aliasing, a low-pass filter (e.g., an averaging filter) of size roughly equal to the dest pixel (i.e., the reduction factor) should be applied to the src before subsampling.
As an alternative to low-pass filtering and subsampling for large reduction factors, linear interpolation can also be done between the (widely separated) src pixels in which the corners of the dest pixel lie. This also is not optimal, as it samples src pixels only near the corners of the dest pixel, and it is not implemented.
Summary: (1) If this is used for scale factors less than 0.7, it will suffer from antialiasing. A warning is issued. Particularly for document images with sharp edges, use pixScaleSmooth() or pixScaleAreaMap() instead. (2) The speed on intel hardware for the general case (not 2x) is about 13 * 10^6 dest-pixels/sec/GHz. (The special 2x case runs at about 100 * 10^6 dest-pixels/sec/GHz.)
Input: pixs (8 bpp) xfact (x downscaling factor; integer) yfact (y downscaling factor; integer) type (L_CHOOSE_MIN, L_CHOOSE_MAX, L_CHOOSE_MAX_MIN_DIFF) Return: pixd (8 bpp)
Notes: (1) The downscaled pixels in pixd are the min, max or (max - min) of the corresponding set of xfact * yfact pixels in pixs. (2) Using L_CHOOSE_MIN is equivalent to a grayscale erosion, using a brick Sel of size (xfact * yfact), followed by subsampling within each (xfact * yfact) cell. Using L_CHOOSE_MAX is equivalent to the corresponding dilation. (3) Using L_CHOOSE_MAX_MIN_DIFF finds the difference between max and min values in each cell. (4) For the special case of downscaling by 2x in both directions, pixScaleGrayMinMax2() is about 2x more efficient.
LEPT_DLL PIX* pixScaleGrayMinMax2 | ( | PIX * | pixs, |
l_int32 | type | ||
) |
Input: pixs (8 bpp) type (L_CHOOSE_MIN, L_CHOOSE_MAX, L_CHOOSE_MAX_MIN_DIFF) Return: pixd (8 bpp downscaled by 2x)
Notes: (1) Special version for 2x reduction. The downscaled pixels in pixd are the min, max or (max - min) of the corresponding set of 4 pixels in pixs. (2) The max and min operations are a special case (for levels 1 and 4) of grayscale analog to the binary rank scaling operation pixReduceRankBinary2(). Note, however, that because of the photometric definition that higher gray values are lighter, the erosion-like L_CHOOSE_MIN will darken the resulting image, corresponding to a threshold level 1 in the binary case. Likewise, L_CHOOSE_MAX will lighten the pixd, corresponding to a threshold level of 4. (3) To choose any of the four rank levels in a 2x grayscale reduction, use pixScaleGrayRank2(). (4) This runs at about 70 MPix/sec/GHz of source data for erosion and dilation.
LEPT_DLL PIX* pixScaleGrayRank2 | ( | PIX * | pixs, |
l_int32 | rank | ||
) |
Input: pixs (8 bpp) rank (1 (darkest), 2, 3, 4 (lightest)) Return: pixd (8 bpp, downscaled by 2x)
Notes: (1) Rank 2x reduction. If rank == 1(4), the downscaled pixels in pixd are the min(max) of the corresponding set of 4 pixels in pixs. Values 2 and 3 are intermediate. (2) This is the grayscale analog to the binary rank scaling operation pixReduceRankBinary2(). Here, because of the photometric definition that higher gray values are lighter, rank 1 gives the darkest pixel, whereas rank 4 gives the lightest pixel. This is opposite to the binary rank operation. (3) For rank = 1 and 4, this calls pixScaleGrayMinMax2(), which runs at about 70 MPix/sec/GHz of source data. For rank 2 and 3, this runs 3x slower, at about 25 MPix/sec/GHz.
LEPT_DLL PIX* pixScaleGrayRankCascade | ( | PIX * | pixs, |
l_int32 | level1, | ||
l_int32 | level2, | ||
l_int32 | level3, | ||
l_int32 | level4 | ||
) |
Input: pixs (8 bpp) level1, ... level4 (rank thresholds, in set {0, 1, 2, 3, 4}) Return: pixd (8 bpp, downscaled by up to 16x)
Notes: (1) This performs up to four cascaded 2x rank reductions. (2) Use level = 0 to truncate the cascade.
Input: pixs (8 bpp grayscale) factor (integer reduction factor >= 1) thresh (binarization threshold) Return: pixd (1 bpp), or null on error
Notes: (1) This does simultaneous subsampling by an integer factor and thresholding from gray to binary. (2) It is designed for maximum speed, and is used for quickly generating a downsized binary image from a higher resolution gray image. This would typically be used for image analysis.
Input: pixs (2, 4, 8 or 32 bpp; with or without colormap) scalex, scaley (must both be >= 0.7) Return: pixd, or null on error
Notes: (1) This function should only be used when the scale factors are greater than or equal to 0.7, and typically greater than 1. If either scale factor is smaller than 0.7, we issue a warning and invoke pixScale(). (2) This works on 2, 4, 8, 16 and 32 bpp images, as well as on 2, 4 and 8 bpp images that have a colormap. If there is a colormap, it is removed to either gray or RGB, depending on the colormap. (3) The does a linear interpolation on the src image. (4) It dispatches to much faster implementations for the special cases of 2x and 4x expansion.
*** Warning: implicit assumption about RGB component ordering ***
Input: pixs1 (high res 8 bpp) pixs2 (low res -- 2x reduced -- 8 bpp) scale (reduction with respect to high res image, > 0.5) Return: 8 bpp pix, scaled down by reduction in each direction, or NULL on error.
Notes: (1) See notes in pixScaleToGrayMipmap(). (2) This function suffers from aliasing effects that are easily seen in document images.
Input: pixs (32 bpp RGB) factor (integer reduction factor >= 1) thresh (binarization threshold) Return: pixd (1 bpp), or null on error
Notes: (1) This does simultaneous subsampling by an integer factor and conversion from RGB to gray to binary. (2) It is designed for maximum speed, and is used for quickly generating a downsized binary image from a higher resolution RGB image. This would typically be used for image analysis. (3) It uses the green channel to represent the RGB pixel intensity.
Input: pixs (32 bpp rgb) rwt, gwt, bwt (must sum to 1.0) Return: pixd, (8 bpp, 2x reduced), or null on error
Input: pixs (32 bpp rgb) factor (integer reduction factor >= 1) color (one of COLOR_RED, COLOR_GREEN, COLOR_BLUE) Return: pixd (8 bpp), or null on error
Notes: (1) This does simultaneous subsampling by an integer factor and extraction of the color from the RGB pix. (2) It is designed for maximum speed, and is used for quickly generating a downsized grayscale image from a higher resolution RGB image. This would typically be used for image analysis. (3) The standard color byte order (RGBA) is assumed.
Input: pixs (2, 4, 8 or 32 bpp; and 2, 4, 8 bpp with colormap) scalex, scaley (must both be < 0.7) Return: pixd, or null on error
Notes: (1) This function should only be used when the scale factors are less than or equal to 0.7 (i.e., more than about 1.42x reduction). If either scale factor is larger than 0.7, we issue a warning and invoke pixScale(). (2) This works only on 2, 4, 8 and 32 bpp images, and if there is a colormap, it is removed by converting to RGB. In other cases, we issue a warning and invoke pixScale(). (3) It does simple (flat filter) convolution, with a filter size commensurate with the amount of reduction, to avoid antialiasing. (4) It does simple subsampling after smoothing, which is appropriate for this range of scaling. Linear interpolation gives essentially the same result with more computation for these scale factors, so we don't use it. (5) The result is the same as doing a full block convolution followed by subsampling, but this is faster because the results of the block convolution are only computed at the subsampling locations. In fact, the computation time is approximately independent of the scale factor, because the convolution kernel is adjusted so that each source pixel is summed approximately once.
*** Warning: implicit assumption about RGB component ordering ***
LEPT_DLL PIX* pixScaleToGray | ( | PIX * | pixs, |
l_float32 | scalefactor | ||
) |
Input: pixs (1 bpp) scalefactor (reduction: must be > 0.0 and < 1.0) Return: pixd (8 bpp), scaled down by scalefactor in each direction, or NULL on error.
Notes:
For faster scaling in the range of scalefactors from 0.0625 to 0.5, with very little difference in quality, use pixScaleToGrayFast().
Binary images have sharp edges, so they intrinsically have very high frequency content. To avoid aliasing, they must be low-pass filtered, which tends to blur the edges. How can we keep relatively crisp edges without aliasing? The trick is to do binary upscaling followed by a power-of-2 scaleToGray. For large reductions, where you don't end up with much detail, some corners can be cut.
The intent here is to get high quality reduced grayscale images with relatively little computation. We do binary pre-scaling followed by scaleToGrayN() for best results, esp. to avoid excess blur when the scale factor is near an inverse power of 2. Where a low-pass filter is required, we use simple convolution kernels: either the hat filter for linear interpolation or a flat filter for larger downscaling. Other choices, such as a perfect bandpass filter with infinite extent (the sinc) or various approximations to it (e.g., lanczos), are unnecessarily expensive.
The choices made are as follows: (1) Do binary upscaling before scaleToGrayN() for scalefactors > 1/8 (2) Do binary downscaling before scaleToGray8() for scalefactors between 1/16 and 1/8. (3) Use scaleToGray16() before grayscale downscaling for scalefactors less than 1/16 Another reasonable choice would be to start binary downscaling for scalefactors below 1/4, rather than below 1/8 as we do here.
The general scaling rules, not all of which are used here, go as follows: (1) For grayscale upscaling, use pixScaleGrayLI(). However, note that edges will be visibly blurred for scalefactors near (but above) 1.0. Replication will avoid edge blur, and should be considered for factors very near 1.0. (2) For grayscale downscaling with a scale factor larger than about 0.7, use pixScaleGrayLI(). For scalefactors near (but below) 1.0, you tread between Scylla and Charybdis. pixScaleGrayLI() again gives edge blurring, but pixScaleBySampling() gives visible aliasing. (3) For grayscale downscaling with a scale factor smaller than about 0.7, use pixScaleSmooth() (4) For binary input images, do as much scale to gray as possible using the special integer functions (2, 3, 4, 8 and 16). (5) It is better to upscale in binary, followed by scaleToGrayN() than to do scaleToGrayN() followed by an upscale using either LI or oversampling. (6) It may be better to downscale in binary, followed by scaleToGrayN() than to first use scaleToGrayN() followed by downscaling. For downscaling between 8x and 16x, this is a reasonable option. (7) For reductions greater than 16x, it's reasonable to use scaleToGray16() followed by further grayscale downscaling.
LEPT_DLL PIX* pixScaleToGray16 | ( | PIX * | pixs | ) |
Input: pixs (1 bpp) Return: pixd (8 bpp), scaled down by 16x in each direction, or null on error.
LEPT_DLL PIX* pixScaleToGray2 | ( | PIX * | pixs | ) |
Input: pixs (1 bpp) Return: pixd (8 bpp), scaled down by 2x in each direction, or null on error.
LEPT_DLL PIX* pixScaleToGray3 | ( | PIX * | pixs | ) |
Input: pixs (1 bpp) Return: pixd (8 bpp), scaled down by 3x in each direction, or null on error.
Notes: (1) Speed is about 100 x 10^6 src-pixels/sec/GHz. Another way to express this is it processes 1 src pixel in about 10 cycles. (2) The width of pixd is truncated is truncated to a factor of 8.
LEPT_DLL PIX* pixScaleToGray4 | ( | PIX * | pixs | ) |
Input: pixs (1 bpp) Return: pixd (8 bpp), scaled down by 4x in each direction, or null on error.
Notes: (1) The width of pixd is truncated is truncated to a factor of 2.
LEPT_DLL PIX* pixScaleToGray6 | ( | PIX * | pixs | ) |
Input: pixs (1 bpp) Return: pixd (8 bpp), scaled down by 6x in each direction, or null on error.
Notes: (1) The width of pixd is truncated is truncated to a factor of 8.
LEPT_DLL PIX* pixScaleToGray8 | ( | PIX * | pixs | ) |
Input: pixs (1 bpp) Return: pixd (8 bpp), scaled down by 8x in each direction, or null on error
LEPT_DLL PIX* pixScaleToGrayFast | ( | PIX * | pixs, |
l_float32 | scalefactor | ||
) |
Input: pixs (1 bpp) scalefactor (reduction: must be > 0.0 and < 1.0) Return: pixd (8 bpp), scaled down by scalefactor in each direction, or NULL on error.
Notes: (1) See notes in pixScaleToGray() for the basic approach. (2) This function is considerably less expensive than pixScaleToGray() for scalefactor in the range (0.0625 ... 0.5), and the quality is nearly as good. (3) Unlike pixScaleToGray(), which does binary upscaling before downscaling for scale factors >= 0.0625, pixScaleToGrayFast() first downscales in binary for all scale factors < 0.5, and then does a 2x scale-to-gray as the final step. For scale factors < 0.0625, both do a 16x scale-to-gray, followed by further grayscale reduction.
LEPT_DLL PIX* pixScaleToGrayMipmap | ( | PIX * | pixs, |
l_float32 | scalefactor | ||
) |
Input: pixs (1 bpp) scalefactor (reduction: must be > 0.0 and < 1.0) Return: pixd (8 bpp), scaled down by scalefactor in each direction, or NULL on error.
Notes:
This function is here mainly for pedagogical reasons. Mip-mapping is widely used in graphics for texture mapping, because the texture changes smoothly with scale. This is accomplished by constructing a multiresolution pyramid and, for each pixel, doing a linear interpolation between corresponding pixels in the two planes of the pyramid that bracket the desired resolution. The computation is very efficient, and is implemented in hardware in high-end graphics cards.
We can use mip-mapping for scale-to-gray by using two scale-to-gray reduced images (we don't need the entire pyramid) selected from the set {2x, 4x, ... 16x}, and interpolating. However, we get severe aliasing, probably because we are subsampling from the higher resolution image. The method is very fast, but the result is very poor. In fact, the results don't look any better than either subsampling off the higher-res grayscale image or oversampling on the lower-res image. Consequently, this method should NOT be used for generating reduced images, scale-to-gray or otherwise.
Input: pixs (1, 2, 4, 8, 16 and 32 bpp) wd (target width; use 0 if using height as target) hd (target height; use 0 if using width as target) Return: pixd, or null on error
Notes: (1) The guarantees that the output scaled image has the dimension(s) you specify.
LEPT_DLL PIX* pixScaleWithAlpha | ( | PIX * | pixs, |
l_float32 | scalex, | ||
l_float32 | scaley, | ||
PIX * | pixg, | ||
l_float32 | fract | ||
) |
Input: pixs (32 bpp rgb) scalex, scaley (must be > 0.0) pixg (<optional> 8 bpp, can be null) fract (between 0.0 and 1.0, with 0.0 fully transparent and 1.0 fully opaque) Return: pixd, or null on error
Notes: (1) The alpha channel is transformed separately from pixs, and aligns with it, being fully transparent outside the boundary of the transformed pixs. For pixels that are fully transparent, a blending function like pixBlendWithGrayMask() will give zero weight to corresponding pixels in pixs. (2) Scaling is done with area mapping or linear interpolation, depending on the scale factors. Default sharpening is done. (3) If pixg is NULL, it is generated as an alpha layer that is partially opaque, using . Otherwise, it is cropped to pixs if required, and is ignored. The alpha channel in pixs is never used. (4) Colormaps are removed. (5) The default setting for the border values in the alpha channel is 0 (transparent) for the outermost ring of pixels and (0.5 * fract * 255) for the second ring. When blended over a second image, this (a) shrinks the visible image to make a clean overlap edge with an image below, and (b) softens the edges by weakening the aliasing there. Use l_setAlphaMaskBorder() to change these values.
*** Warning: implicit assumption about RGB component ordering ***
LEPT_DLL l_int32 pixScanForEdge | ( | PIX * | pixs, |
BOX * | box, | ||
l_int32 | lowthresh, | ||
l_int32 | highthresh, | ||
l_int32 | maxwidth, | ||
l_int32 | factor, | ||
l_int32 | scanflag, | ||
l_int32 * | ploc | ||
) |
Input: pixs (1 bpp) box (<optional> within which the search is conducted) lowthresh (threshold to choose clipping location) highthresh (threshold required to find an edge) maxwidth (max allowed width between low and high thresh locs) factor (sampling factor along pixel counting direction) scanflag (direction of scan; e.g., L_FROM_LEFT) &loc (location in scan direction of first black pixel) Return: 0 if OK; 1 on error or if the edge is not found
Notes: (1) If there are no fg pixels, the position is set to 0. Caller must check the return value! (2) Use == NULL to scan from edge of pixs (3) As the scan progresses, the location where the sum of pixels equals or excees is noted (loc). The scan is stopped when the sum of pixels equals or exceeds . If the scan distance between loc and that point does not exceed , an edge is found and its position is taken to be loc. implicitly sets a minimum on the required gradient of the edge. (4) The thresholds must be at least 1, and the low threshold cannot be larger than the high threshold.
Input: pixs (1 bpp) box (<optional> within which the search is conducted) scanflag (direction of scan; e.g., L_FROM_LEFT) &loc (location in scan direction of first black pixel) Return: 0 if OK; 1 on error or if no fg pixels are found
Notes: (1) If there are no fg pixels, the position is set to 0. Caller must check the return value! (2) Use == NULL to scan from edge of pixs
LEPT_DLL PTA* pixSearchBinaryMaze | ( | PIX * | pixs, |
l_int32 | xi, | ||
l_int32 | yi, | ||
l_int32 | xf, | ||
l_int32 | yf, | ||
PIX ** | ppixd | ||
) |
Input: pixs (1 bpp, maze) xi, yi (beginning point; use same initial point that was used to generate the maze) xf, yf (end point, or close to it) &ppixd (<optional return>=""> maze with path illustrated, or if no path possible, the part of the maze that was searched) Return: pta (shortest path), or null if either no path exists or on error
Notes: (1) Because of the overhead in calling pixGetPixel() and pixSetPixel(), we have used raster line pointers and the GET_DATA* and SET_DATA* macros for many of the pix accesses. (2) Commentary: The goal is to find the shortest path between beginning and end points, without going through walls, and there are many ways to solve this problem. We use a queue to implement a breadth-first search. Two auxiliary "image" data structures can be used: one to mark the visited pixels and one to give the direction to the parent for each visited pixels. The first structure is used to avoid putting pixels on the queue more than once, and the second is used for retracing back to the origin, like the breadcrumbs in Hansel and Gretel. Each pixel taken off the queue is destroyed after it is used to locate the allowed neighbors. In fact, only one distance image is required, if you initialize it to some value that signifies "not yet visited." (We use a binary image for marking visited pixels because it is clearer.) This method for a simple search of a binary maze is implemented in searchBinaryMaze(). An alternative method would store the (manhattan) distance from the start point with each pixel on the queue. The children of each pixel get a distance one larger than the parent. These values can be stored in an auxiliary distance map image that is constructed simultaneously with the search. Once the end point is reached, the distance map is used to backtrack along a minimum path. There may be several equal length minimum paths, any one of which can be chosen this way.
LEPT_DLL PTA* pixSearchGrayMaze | ( | PIX * | pixs, |
l_int32 | xi, | ||
l_int32 | yi, | ||
l_int32 | xf, | ||
l_int32 | yf, | ||
PIX ** | ppixd | ||
) |
Input: pixs (1 bpp, maze) xi, yi (beginning point; use same initial point that was used to generate the maze) xf, yf (end point, or close to it) &ppixd (<optional return>=""> maze with path illustrated, or if no path possible, the part of the maze that was searched) Return: pta (shortest path), or null if either no path exists or on error
Commentary: Consider first a slight generalization of the binary maze search problem. Suppose that you can go through walls, but the cost is higher (say, an increment of 3 to go into a wall pixel rather than 1)? You're still trying to find the shortest path. One way to do this is with an ordered queue, and a simple way to visualize an ordered queue is as a set of stacks, each stack being marked with the distance of each pixel in the stack from the start. We place the start pixel in stack 0, pop it, and process its 4 children. Each pixel is given a distance that is incremented from that of its parent (0 in this case), depending on if it is a wall pixel or not. That value may be recorded on a distance map, according to the algorithm below. For children of the first pixel, those not on a wall go in stack 1, and wall children go in stack 3. Stack 0 being emptied, the process then continues with pixels being popped from stack 1. Here is the algorithm for each child pixel. The pixel's distance value, were it to be placed on a stack, is compared with the value for it that is on the distance map. There are three possible cases: (1) If the pixel has not yet been registered, it is pushed on its stack and the distance is written to the map. (2) If it has previously been registered with a higher distance, the distance on the map is relaxed to that of the current pixel, which is then placed on its stack. (3) If it has previously been registered with an equal or lower value, the pixel is discarded. The pixels are popped and processed successively from stack 1, and when stack 1 is empty, popping starts on stack 2. This continues until the destination pixel is popped off a stack. The minimum path is then derived from the distance map, going back from the end point as before. This is just Dijkstra's algorithm for a directed graph; here, the underlying graph (consisting of the pixels and four edges connecting each pixel to its 4-neighbor) is a special case of a directed graph, where each edge is bi-directional. The implementation of this generalized maze search is left as an exercise to the reader.
Let's generalize a bit further. Suppose the "maze" is just a grayscale image -- think of it as an elevation map. The cost of moving on this surface depends on the height, or the gradient, or whatever you want. All that is required is that the cost is specified and non-negative on each link between adjacent pixels. Now the problem becomes: find the least cost path moving on this surface between two specified end points. For example, if the cost across an edge between two pixels depends on the "gradient", you can use: cost = 1 + L_ABS(deltaV) where deltaV is the difference in value between two adjacent pixels. If the costs are all integers, we can still use an array of stacks to avoid ordering the queue (e.g., by using a heap sort.) This is a neat problem, because you don't even have to build a maze -- you can can use it on any grayscale image!
Rather than using an array of stacks, a more practical approach is to implement with a priority queue, which is a queue that is sorted so that the elements with the largest (or smallest) key values always come off first. The priority queue is efficiently implemented as a heap, and this is how we do it. Suppose you run the algorithm using a priority queue, doing the bookkeeping with an auxiliary image data structure that saves the distance of each pixel put on the queue as before, according to the method described above. We implement it as a 2-way choice by initializing the distance array to a large value and putting a pixel on the queue if its distance is less than the value found on the array. When you finally pop the end pixel from the queue, you're done, and you can trace the path backward, either always going downhill or using an auxiliary image to give you the direction to go at each step. This is implemented here in searchGrayMaze().
Do we really have to use a sorted queue? Can we solve this generalized maze with an unsorted queue of pixels? (Or even an unsorted stack, doing a depth-first search (DFS)?) Consider a different algorithm for this generalized maze, where we travel again breadth first, but this time use a single, unsorted queue. An auxiliary image is used as before to store the distances and to determine if pixels get pushed on the stack or dropped. As before, we must allow pixels to be revisited, with relaxation of the distance if a shorter path arrives later. As a result, we will in general have multiple instances of the same pixel on the stack with different distances. However, because the queue is not ordered, some of these pixels will be popped when another instance with a lower distance is still on the stack. Here, we're just popping them in the order they go on, rather than setting up a priority based on minimum distance. Thus, unlike the priority queue, when a pixel is popped we have to check the distance map to see if a pixel with a lower distance has been put on the queue, and, if so, we discard the pixel we just popped. So the "while" loop looks like this:
How does this loop terminate? Before, with an ordered queue, it terminates when you pop the end pixel. But with an unordered queue (or stack), the first time you hit the end pixel, the distance is not guaranteed to be correct, because the pixels along the shortest path may not have yet been visited and relaxed. Because the shortest path can theoretically go anywhere, we must keep going. How do we know when to stop? Dijkstra uses an ordered queue to systematically remove nodes from further consideration. (Each time a pixel is popped, we're done with it; it's "finalized" in the Dijkstra sense because we know the shortest path to it.) However, with an unordered queue, the brute force answer is: stop when the queue (or stack) is empty, because then every pixel in the image has been assigned its minimum "distance" from the start pixel.
This is similar to the situation when you use a stack for the simpler uniform-step problem: with breadth-first search (BFS) the pixels on the queue are automatically ordered, so you are done when you locate the end pixel as a neighbor of a popped pixel; whereas depth-first search (DFS), using a stack, requires, in general, a search of every accessible pixel. Further, if a pixel is revisited with a smaller distance, that distance is recorded and the pixel is put on the stack again.
But surely, you ask, can't we stop sooner? What if the start and end pixels are very close to each other? OK, suppose they are, and you have very high walls and a long snaking level path that is actually the minimum cost. That long path can wind back and forth across the entire maze many times before ending up at the end point, which could be just over a wall from the start. With the unordered queue, you very quickly get a high distance for the end pixel, which will be relaxed to the minimum distance only after all the pixels of the path have been visited and placed on the queue, multiple times for many of them. So that's the price for not ordering the queue!
LEPT_DLL l_int32 pixSeedfill | ( | PIX * | pixs, |
L_STACK * | stack, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | connectivity | ||
) |
Input: pixs (1 bpp) stack (for holding fillsegs) x,y (location of seed pixel) connectivity (4 or 8) Return: 0 if OK, 1 on error
Notes: (1) This removes the component from pixs with a fg pixel at (x,y). (2) See pixSeedfill4() and pixSeedfill8() for details.
Input: pixs (1 bpp) stack (for holding fillsegs) x,y (location of seed pixel) Return: 0 if OK, 1 on error
Notes: (1) This is Paul Heckbert's stack-based 4-cc seedfill algorithm. (2) This operates on the input 1 bpp pix to remove the fg seed pixel, at (x,y), and all pixels that are 4-connected to it. The seed pixel at (x,y) must initially be ON. (3) Reference: see pixSeedFill4BB()
Input: pixs (1 bpp) stack (for holding fillsegs) x,y (location of seed pixel) Return: box or null on error.
Notes: (1) This is Paul Heckbert's stack-based 4-cc seedfill algorithm. (2) This operates on the input 1 bpp pix to remove the fg seed pixel, at (x,y), and all pixels that are 4-connected to it. The seed pixel at (x,y) must initially be ON. (3) Returns the bounding box of the erased 4-cc component. (4) Reference: see Paul Heckbert's stack-based seed fill algorithm in "Graphic Gems", ed. Andrew Glassner, Academic Press, 1990. The algorithm description is given on pp. 275-277; working C code is on pp. 721-722.) The code here follows Heckbert's exactly, except we use function calls instead of macros for pushing data on and popping data off the stack. This makes sense to do because Heckbert's fixed-size stack with macros is dangerous: images exist that will overrun the stack and crash. The stack utility here grows dynamically as needed, and the fillseg structures that are not in use are stored in another stack for reuse. It should be noted that the overhead in the function calls (vs. macros) is negligible.
Input: pixs (1 bpp) stack (for holding fillsegs) x,y (location of seed pixel) Return: 0 if OK, 1 on error
Notes: (1) This is Paul Heckbert's stack-based 8-cc seedfill algorithm. (2) This operates on the input 1 bpp pix to remove the fg seed pixel, at (x,y), and all pixels that are 8-connected to it. The seed pixel at (x,y) must initially be ON. (3) Reference: see pixSeedFill8BB()
Input: pixs (1 bpp) stack (for holding fillsegs) x,y (location of seed pixel) Return: box or null on error.
Notes: (1) This is Paul Heckbert's stack-based 8-cc seedfill algorithm. (2) This operates on the input 1 bpp pix to remove the fg seed pixel, at (x,y), and all pixels that are 8-connected to it. The seed pixel at (x,y) must initially be ON. (3) Returns the bounding box of the erased 8-cc component. (4) Reference: see Paul Heckbert's stack-based seed fill algorithm in "Graphic Gems", ed. Andrew Glassner, Academic Press, 1990. The algorithm description is given on pp. 275-277; working C code is on pp. 721-722.) The code here follows Heckbert's closely, except the leak checks are changed for 8 connectivity. See comments on pixSeedfill4BB() for more details.
LEPT_DLL BOX* pixSeedfillBB | ( | PIX * | pixs, |
L_STACK * | stack, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | connectivity | ||
) |
Input: pixs (1 bpp) stack (for holding fillsegs) x,y (location of seed pixel) connectivity (4 or 8) Return: box or null on error
Notes: (1) This is the high-level interface to Paul Heckbert's stack-based seedfill algorithm.
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs; 1 bpp) pixs (1 bpp seed) pixm (1 bpp filling mask) connectivity (4 or 8) Return: pixd always
Notes: (1) This is for binary seedfill (aka "binary reconstruction"). (2) There are 3 cases: (a) pixd == null (make a new pixd) (b) pixd == pixs (in-place) (c) pixd != pixs (3) If you know the case, use these patterns for clarity: (a) pixd = pixSeedfillBinary(NULL, pixs, ...); (b) pixSeedfillBinary(pixs, pixs, ...); (c) pixSeedfillBinary(pixd, pixs, ...); (4) The resulting pixd contains the filled seed. For some applications you want to OR it with the inverse of the filling mask. (5) The input seed and mask images can be different sizes, but in typical use the difference, if any, would be only a few pixels in each direction. If the sizes differ, the clipping is handled by the low-level function seedfillBinaryLow().
LEPT_DLL PIX* pixSeedfillBinaryRestricted | ( | PIX * | pixd, |
PIX * | pixs, | ||
PIX * | pixm, | ||
l_int32 | connectivity, | ||
l_int32 | xmax, | ||
l_int32 | ymax | ||
) |
Input: pixd (<optional>; this can be null, equal to pixs, or different from pixs; 1 bpp) pixs (1 bpp seed) pixm (1 bpp filling mask) connectivity (4 or 8) xmax (max distance in x direction of fill into the mask) ymax (max distance in y direction of fill into the mask) Return: pixd always
Notes: (1) See usage for pixSeedfillBinary(), which has unrestricted fill. In pixSeedfillBinary(), the filling distance is unrestricted and can be larger than pixs, depending on the topology of th mask. (2) There are occasions where it is useful not to permit the fill to go more than a certain distance into the mask. specifies the maximum horizontal distance allowed in the fill; does likewise in the vertical direction. (3) Operationally, the max "distance" allowed for the fill is a linear distance from the original seed, independent of the actual mask topology. (4) Another formulation of this problem, not implemented, would use the manhattan distance from the seed, as determined by a breadth-first search starting at the seed boundaries and working outward where the mask fg allows. How this might use the constraints of separate xmax and ymax is not clear.
Input: pixs (8 bpp seed; filled in place) pixm (8 bpp filling mask) connectivity (4 or 8) Return: 0 if OK, 1 on error
Notes: (1) This is an in-place filling operation on the seed, pixs, where the clipping mask is always above or at the level of the seed as it is filled. (2) For details of the operation, see the description in seedfillGrayLow() and the code there. (3) As an example of use, see the description in pixHDome(). There, the seed is an image where each pixel is a fixed amount smaller than the corresponding mask pixel. (4) Reference paper : L. Vincent, Morphological grayscale reconstruction in image analysis: applications and efficient algorithms, IEEE Transactions on Image Processing, vol. 2, no. 2, pp. 176-201, 1993.
Input: pixb (binary mask giving seed locations) pixm (8 bpp basin-type filling mask) delta (amount of seed value above mask) connectivity (4 or 8) Return: pixd (filled seed) if OK, null on error
Notes: (1) This fills from a seed within basins defined by a filling mask. The seed value(s) are greater than the corresponding filling mask value, and the result has the bottoms of the basins raised by the initial seed value. (2) The seed has value 255 except where pixb has fg (1), which are the seed 'locations'. At the seed locations, the seed value is the corresponding value of the mask pixel in pixm plus . If == 0, we return a copy of pixm. (3) The actual filling is done using the standard grayscale filling operation on the inverse of the mask and using the inverse of the seed image. After filling, we return the inverse of the filled seed. (4) As an example of use: pixm can describe a grayscale image of text, where the (dark) text pixels are basins of low values; pixb can identify the local minima in pixm (say, at the bottom of the basins); and delta is the amount that we wish to raise (lighten) the basins. We construct the seed (a.k.a marker) image from pixb, pixm and .
Input: pixs (8 bpp seed; filled in place) pixm (8 bpp filling mask) connectivity (4 or 8) Return: 0 if OK, 1 on error
Notes: (1) This is an in-place filling operation on the seed, pixs, where the clipping mask is always below or at the level of the seed as it is filled. Think of filling up a basin to a particular level, given by the maximum seed value in the basin. Outside the filled region, the mask is above the filling level. (2) Contrast this with pixSeedfillGray(), where the clipping mask is always above or at the level of the fill. An example of its use is the hdome fill, where the seed is an image where each pixel is a fixed amount smaller than the corresponding mask pixel. (3) The basin fill, pixSeedfillGrayBasin(), is a special case where the seed pixel values are generated from the mask, and where the implementation uses pixSeedfillGray() by inverting both the seed and mask.
Input: pixs (8 bpp seed; filled in place) pixm (8 bpp filling mask) connectivity (4 or 8) Return: 0 if OK, 1 on error
Notes: (1) This is an in-place filling operation on the seed, pixs, where the clipping mask is always below or at the level of the seed as it is filled. Think of filling up a basin to a particular level, given by the maximum seed value in the basin. Outside the filled region, the mask is above the filling level. (2) Contrast this with pixSeedfillGraySimple(), where the clipping mask is always above or at the level of the fill. An example of its use is the hdome fill, where the seed is an image where each pixel is a fixed amount smaller than the corresponding mask pixel.
Input: pixs (8 bpp seed; filled in place) pixm (8 bpp filling mask) connectivity (4 or 8) Return: 0 if OK, 1 on error
Notes: (1) This is an in-place filling operation on the seed, pixs, where the clipping mask is always above or at the level of the seed as it is filled. (2) For details of the operation, see the description in seedfillGrayLowSimple() and the code there. (3) As an example of use, see the description in pixHDome(). There, the seed is an image where each pixel is a fixed amount smaller than the corresponding mask pixel. (4) Reference paper : L. Vincent, Morphological grayscale reconstruction in image analysis: applications and efficient algorithms, IEEE Transactions on Image Processing, vol. 2, no. 2, pp. 176-201, 1993.
Input: pixs (seed) pixm (mask) connectivity (4 or 8) Return: pix where seed has been grown to completion into the mask, or null on error
Notes: (1) This is in general a very inefficient method for filling from a seed into a mask. I've included it here for pedagogical reasons, but it should NEVER be used if efficiency is any consideration -- use pixSeedfillBinary()! (2) We use a 3x3 brick SEL for 8-cc filling and a 3x3 plus SEL for 4-cc.
LEPT_DLL PIX* pixSeedspread | ( | PIX * | pixs, |
l_int32 | connectivity | ||
) |
Input: pixs (8 bpp source) connectivity (4 or 8) Return: pixd, or null on error
Notes: (1) The raster/anti-raster method for implementing this filling operation was suggested by Ray Smith. (2) This takes an arbitrary set of nonzero pixels in pixs, which can be sparse, and spreads (extrapolates) the values to fill all the pixels in pixd with the nonzero value it is closest to in pixs. This is similar (though not completely equivalent) to doing a Voronoi tiling of the image, with a tile surrounding each pixel that has a nonzero value. All pixels within a tile are then closer to its "central" pixel than to any others. Then assign the value of the "central" pixel to each pixel in the tile. (3) This is implemented by computing a distance function in parallel with the fill. The distance function uses free boundary conditions (assumed maxval outside), and it controls the propagation of the pixels in pixd away from the nonzero (seed) values. This is done in 2 traversals (raster/antiraster). In the raster direction, whenever the distance function is nonzero, the spread pixel takes on the value of its predecessor that has the minimum distance value. In the antiraster direction, whenever the distance function is nonzero and its value is replaced by a smaller value, the spread pixel takes the value of the predecessor with the minimum distance value. (4) At boundaries where a pixel is equidistant from two nearest nonzero (seed) pixels, the decision of which value to use is arbitrary (greedy in search for minimum distance). This can give rise to strange-looking results, particularly for 4-connectivity where the L1 distance is computed from steps in N,S,E and W directions (no diagonals).
LEPT_DLL PIX* pixSelectByAreaFraction | ( | PIX * | pixs, |
l_float32 | thresh, | ||
l_int32 | connectivity, | ||
l_int32 | type, | ||
l_int32 * | pchanged | ||
) |
Input: pixs (1 bpp) thresh (threshold ratio of fg pixels to (w * h)) connectivity (4 or 8) type (L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE) &changed (<optional return>=""> 1 if changed; 0 if clone returned) Return: pixd, or null on error
Notes: (1) The args specify constraints on the amount of foreground coverage of the components that are kept. (2) If unchanged, returns a copy of pixs. Otherwise, returns a new pix with the filtered components. (3) This filters components based on the fraction of fg pixels of the component in its bounding box. (4) Use L_SELECT_IF_LT or L_SELECT_IF_LTE to save components with less than the threshold fraction of foreground, and L_SELECT_IF_GT or L_SELECT_IF_GTE to remove them.
LEPT_DLL PIX* pixSelectByAreaPerimRatio | ( | PIX * | pixs, |
l_float32 | thresh, | ||
l_int32 | connectivity, | ||
l_int32 | type, | ||
l_int32 * | pchanged | ||
) |
Input: pixs (1 bpp) thresh (threshold ratio of interior/boundary pixels) connectivity (4 or 8) type (L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE) &changed (<optional return>=""> 1 if changed; 0 if clone returned) Return: pixd, or null on error
Notes: (1) The args specify constraints on the size of the components that are kept. (2) If unchanged, returns a copy of pixs. Otherwise, returns a new pix with the filtered components. (3) This filters "thin" components, where a thin component is defined to have a ratio of interior to boundary pixels that is smaller than a given threshold value. (4) Use L_SELECT_IF_LT or L_SELECT_IF_LTE to save the thin components, and L_SELECT_IF_GT or L_SELECT_IF_GTE to remove them.
LEPT_DLL PIX* pixSelectBySize | ( | PIX * | pixs, |
l_int32 | width, | ||
l_int32 | height, | ||
l_int32 | connectivity, | ||
l_int32 | type, | ||
l_int32 | relation, | ||
l_int32 * | pchanged | ||
) |
Input: pixs (1 bpp) width, height (threshold dimensions) connectivity (4 or 8) type (L_SELECT_WIDTH, L_SELECT_HEIGHT, L_SELECT_IF_EITHER, L_SELECT_IF_BOTH) relation (L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE) &changed (<optional return>=""> 1 if changed; 0 otherwise) Return: filtered pixd, or null on error
Notes: (1) The args specify constraints on the size of the components that are kept. (2) If unchanged, returns a copy of pixs. Otherwise, returns a new pix with the filtered components. (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.
LEPT_DLL PIX* pixSelectByWidthHeightRatio | ( | PIX * | pixs, |
l_float32 | thresh, | ||
l_int32 | connectivity, | ||
l_int32 | type, | ||
l_int32 * | pchanged | ||
) |
Input: pixs (1 bpp) thresh (threshold ratio of width/height) connectivity (4 or 8) type (L_SELECT_IF_LT, L_SELECT_IF_GT, L_SELECT_IF_LTE, L_SELECT_IF_GTE) &changed (<optional return>=""> 1 if changed; 0 if clone returned) Return: pixd, or null on error
Notes: (1) The args specify constraints on the width-to-height ratio for components that are kept. (2) If unchanged, returns a copy of pixs. Otherwise, returns a new pix with the filtered components. (3) This filters components based on the width-to-height ratios. (4) Use L_SELECT_IF_LT or L_SELECT_IF_LTE to save components with less than the threshold ratio, and L_SELECT_IF_GT or L_SELECT_IF_GTE to remove them.
LEPT_DLL l_int32 pixSelectedLocalExtrema | ( | PIX * | pixs, |
l_int32 | mindist, | ||
PIX ** | ppixmin, | ||
PIX ** | ppixmax | ||
) |
Input: pixs (8 bpp) mindist (-1 for keeping all pixels; >= 0 specifies distance) &ppixmin (<return> mask of local minima) &ppixmax (<return> mask of local maxima) Return: 0 if OK, 1 on error
Notes: (1) This selects those local 3x3 minima that are at least a specified distance from the nearest local 3x3 maxima, and v.v. for the selected set of local 3x3 maxima. The local 3x3 minima is the set of pixels whose value equals the value after a 3x3 brick erosion, and the local 3x3 maxima is the set of pixels whose value equals the value after a 3x3 brick dilation. (2) mindist is the minimum distance allowed between local 3x3 minima and local 3x3 maxima, in an 8-connected sense. mindist == 1 keeps all pixels found in step 1. mindist == 0 removes all pixels from each mask that are both a local 3x3 minimum and a local 3x3 maximum. mindist == 1 removes any local 3x3 minimum pixel that touches a local 3x3 maximum pixel, and likewise for the local maxima. To make the decision, visualize each local 3x3 minimum pixel as being surrounded by a square of size (2 * mindist + 1) on each side, such that no local 3x3 maximum pixel is within that square; and v.v. (3) The generated masks can be used as markers for further operations.
LEPT_DLL PIX* pixSelectiveConnCompFill | ( | PIX * | pixs, |
l_int32 | connectivity, | ||
l_int32 | minw, | ||
l_int32 | minh | ||
) |
Input: pixs (binary) connectivity (4 or 8) minw (minimum width to consider; use 0 or 1 for any width) minh (minimum height to consider; use 0 or 1 for any height) Return: pix (with holes filled in selected c.c.), or null on error
Input: pixs (8 bpp) pixm (1 bpp) &nav (<optional return>=""> numa of minima values) Return: pta (of min pixels), or null on error
Notes: (1) For each 8 connected component in pixm, this finds a pixel in pixs that has the lowest value, and saves it in a Pta. If several pixels in pixs have the same minimum value, it picks the first one found. (2) For a mask pixm of true local minima, all pixels in each connected component have the same value in pixs, so it is fastest to select one of them using a special seedfill operation. Not yet implemented.
LEPT_DLL l_int32 pixSerializeToMemory | ( | PIX * | pixs, |
l_uint32 ** | pdata, | ||
size_t * | pnbytes | ||
) |
Input: pixs (all depths, colormap OK) &data (<return> serialized data in memory) &nbytes (<return> number of bytes in data string) Return: 0 if OK, 1 on error
Notes: (1) This does a fast serialization of the principal elements of the pix, as follows: "spix" (4 bytes) -- ID for file type w (4 bytes) h (4 bytes) d (4 bytes) wpl (4 bytes) ncolors (4 bytes) -- in colormap; 0 if there is no colormap cdatasize (4 bytes) -- size of serialized colormap = 4 * (num colors) cdata (cdatasize) rdatasize (4 bytes) -- size of serialized raster data = 4 * wpl * h rdata (rdatasize)
Input: pix (all depths; use cmapped with caution) Return: 0 if OK, 1 on error
Notes: (1) Sets all data to 1. For 1 bpp, this is black; for grayscale or color, this is white. (2) Caution: for colormapped pix, this sets the pixel value to the maximum value supported by the colormap: 2^d - 1. However, this color may not be defined, because the colormap may not be full.
LEPT_DLL l_int32 pixSetAllArbitrary | ( | PIX * | pix, |
l_uint32 | val | ||
) |
Input: pix (all depths; use cmapped with caution) val (value to set all pixels) Return: 0 if OK; 1 on error
Notes: (1) For colormapped pix, be sure the value is the intended one in the colormap. (2) Caution: for colormapped pix, this sets each pixel to the color at the index equal to val. Be sure that this index exists in the colormap and that it is the intended one!
LEPT_DLL PIX* pixSetAlphaOverWhite | ( | PIX * | pixs | ) |
Input: pixs (colormapped or 32 bpp rgb; no alpha) Return: pixd (new pix with meaningful alpha component), or null on error
Notes: (1) The generated alpha component is transparent over white (background) pixels in pixs, and quickly grades to opaque away from the transparent parts. This is a cheap and dirty alpha generator. (2) The alpha component bits in pixs are ignored.
LEPT_DLL l_int32 pixSetBlackOrWhite | ( | PIX * | pixs, |
l_int32 | op | ||
) |
Input: pixs (all depths; cmap ok) op (L_SET_BLACK, L_SET_WHITE) Return: 0 if OK; 1 on error
Notes: (1) Function for setting all pixels in an image to either black or white. (2) If pixs is colormapped, it adds black or white to the colormap if it's not there and there is room. If the colormap is full, it finds the closest color in intensity. This index is written to all pixels.
Input: pixs (any depth, can be cmapped) boxa (<optional> of boxes, to clear or set) op (L_SET_BLACK, L_SET_WHITE) Return: pixd (with boxes filled with white or black), or null on error
Input: pixs (any depth; cmap OK) dist (distance from outside; must be > 0; first ring is 1) val (value to set at each border pixel) Return: 0 if OK; 1 on error
Notes: (1) The rings are single-pixel-wide rectangular sets of pixels at a given distance from the edge of the pix. This sets all pixels in a given ring to a value.
LEPT_DLL l_int32 pixSetBorderVal | ( | PIX * | pixs, |
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot, | ||
l_uint32 | val | ||
) |
Input: pixs (8, 16 or 32 bpp) left, right, top, bot (amount to set) val (value to set at each border pixel) Return: 0 if OK; 1 on error
Notes: (1) The border region is defined to be the region in the image within a specific distance of each edge. Here, we allow the pixels within a specified distance of each edge to be set independently. This sets the pixels in the border region to the given input value. (2) For efficiency, use pixSetOrClearBorder() if you're setting the border to either black or white. (3) If d != 32, the input value should be masked off to the appropriate number of least significant bits. (4) The code is easily generalized for 2 or 4 bpp.
LEPT_DLL l_int32 pixSetColormap | ( | PIX * | pix, |
PIXCMAP * | colormap | ||
) |
Input: pix colormap (to be assigned) Return: 0 if OK, 1 on error.
Notes: (1) Unlike with the pix data field, pixSetColormap() destroys any existing colormap before assigning the new one. Because colormaps are not ref counted, it is important that the new colormap does not belong to any other pix.
LEPT_DLL l_int32 pixSetData | ( | PIX * | pix, |
l_uint32 * | data | ||
) |
Notes: (1) This does not free any existing data. To free existing data, use pixFreeData() before pixSetData().
LEPT_DLL l_int32 pixSetDepth | ( | PIX * | pix, |
l_int32 | depth | ||
) |
Input: pix w, h, d (use 0 to skip the setting for any of these) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pixSetHeight | ( | PIX * | pix, |
l_int32 | height | ||
) |
LEPT_DLL l_int32 pixSetInputFormat | ( | PIX * | pix, |
l_int32 | informat | ||
) |
LEPT_DLL l_int32 pixSetInRect | ( | PIX * | pix, |
BOX * | box | ||
) |
Input: pix (all depths, can be cmapped) box (in which all pixels will be set) Return: 0 if OK, 1 on error
Notes: (1) Sets all data in rect to 1. For 1 bpp, this is black; for grayscale or color, this is white. (2) Caution: for colormapped pix, this sets the pixel value to the maximum value supported by the colormap: 2^d - 1. However, this color may not be defined, because the colormap may not be full.
Input: pix (all depths; can be cmapped) box (in which all pixels will be set to val) val (value to set all pixels) Return: 0 if OK; 1 on error
Notes: (1) For colormapped pix, be sure the value is the intended one in the colormap. (2) Caution: for colormapped pix, this sets each pixel in the rect to the color at the index equal to val. Be sure that this index exists in the colormap and that it is the intended one!
Input: pixs1 (8 bpp) pixs2 (8 bpp) mindiff (minimum difference to accept as valid) Return: 0 if OK; 1 if no pixel diffs are large enough, or on error
Notes: (1) This compares corresponding pixels in pixs1 and pixs2. When they differ by less than , set the pixel values to 0 in each. Each pixel typically represents a tile in a larger image, and a very small difference between the min and max in the tile indicates that the min and max values are not to be trusted. (2) If contrast (pixel difference) detection is expected to fail, caller should check return value.
Input: pixd (1, 2, 4, 8, 16 or 32 bpp; or colormapped) pixm (<optional> 1 bpp mask; no operation if NULL) val (value to set at each masked pixel) Return: 0 if OK; 1 on error
Notes: (1) In-place operation. (2) NOTE: For cmapped images, this calls pixSetMaskedCmap(). must be the 32-bit color representation of the RGB pixel. It is not the index into the colormap! (2) If pixm == NULL, a warning is given. (3) This is an implicitly aligned operation, where the UL corners of pixd and pixm coincide. A warning is issued if the two image sizes differ significantly, but the operation proceeds. (4) Each pixel in pixd that co-locates with an ON pixel in pixm is set to the specified input value. Other pixels in pixd are not changed. (5) You can visualize this as painting the color through the mask, as a stencil. (6) If you do not want to have the UL corners aligned, use the function pixSetMaskedGeneral(), which requires you to input the UL corner of pixm relative to pixd. (7) Implementation details: see comments in pixPaintThroughMask() for when we use rasterop to do the painting.
LEPT_DLL l_int32 pixSetMaskedCmap | ( | PIX * | pixs, |
PIX * | pixm, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval | ||
) |
Input: pixs (2, 4 or 8 bpp, colormapped) pixm (<optional> 1 bpp mask; no-op if NULL) x, y (origin of pixm relative to pixs; can be negative) rval, gval, bval (new color to set at each masked pixel) Return: 0 if OK; 1 on error
Notes: (1) This is an in-place operation. (2) It paints a single color through the mask (as a stencil). (3) The mask origin is placed at (x,y) on pixs, and the operation is clipped to the intersection of the mask and pixs. (4) If pixm == NULL, a warning is given. (5) Typically, pixm is a small binary mask located somewhere on the larger pixs. (6) If the color is in the colormap, it is used. Otherwise, it is added if possible; an error is returned if the colormap is already full.
Input: pixd (8, 16 or 32 bpp) pixm (<optional> 1 bpp mask; no operation if null) val (value to set at each masked pixel) x, y (location of UL corner of pixm relative to pixd; can be negative) Return: 0 if OK; 1 on error
Notes: (1) This is an in-place operation. (2) Alignment is explicit. If you want the UL corners of the two images to be aligned, use pixSetMasked(). (3) A typical use would be painting through the foreground of a small binary mask pixm, located somewhere on a larger pixd. Other pixels in pixd are not changed. (4) You can visualize this as painting the color through the mask, as a stencil. (5) This uses rasterop to handle clipping and different depths of pixd. (6) If pixd has a colormap, you should call pixPaintThroughMask(). (7) Why is this function here, if pixPaintThroughMask() does the same thing, and does it more generally? I've retained it here to show how one can paint through a mask using only full image rasterops, rather than pixel peeking in pixm and poking in pixd. It's somewhat baroque, but I found it amusing.
LEPT_DLL l_int32 pixSetMirroredBorder | ( | PIX * | pixs, |
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot | ||
) |
Input: pixs (all depths; colormap ok) left, right, top, bot (number of pixels to set) Return: 0 if OK, 1 on error
Notes: (1) This applies what is effectively mirror boundary conditions to a border region in the image. It is in-place. (2) This is useful for setting pixels near the border to a value representative of the near pixels to the interior. (3) The general pixRasterop() is used for an in-place operation here because there is no overlap between the src and dest rectangles.
LEPT_DLL l_int32 pixSetOrClearBorder | ( | PIX * | pixs, |
l_int32 | left, | ||
l_int32 | right, | ||
l_int32 | top, | ||
l_int32 | bot, | ||
l_int32 | op | ||
) |
Input: pixs (all depths) left, right, top, bot (amount to set or clear) operation (PIX_SET or PIX_CLR) Return: 0 if OK; 1 on error
Notes: (1) The border region is defined to be the region in the image within a specific distance of each edge. Here, we allow the pixels within a specified distance of each edge to be set independently. This either sets or clears all pixels in the border region. (2) For binary images, use PIX_SET for black and PIX_CLR for white. (3) For grayscale or color images, use PIX_SET for white and PIX_CLR for black.
LEPT_DLL l_int32 pixSetPadBits | ( | PIX * | pix, |
l_int32 | val | ||
) |
Input: pix (1, 2, 4, 8, 16, 32 bpp) val (0 or 1) Return: 0 if OK; 1 on error
Notes: (1) The pad bits are the bits that expand each scanline to a multiple of 32 bits. They are usually not used in image processing operations. When boundary conditions are important, as in seedfill, they must be set properly. (2) This sets the value of the pad bits (if any) in the last 32-bit word in each scanline. (3) For 32 bpp pix, there are no pad bits, so this is a no-op.
Input: pix (1, 2, 4, 8, 16, 32 bpp) by (starting y value of band) bh (height of band) val (0 or 1) Return: 0 if OK; 1 on error
Notes: (1) The pad bits are the bits that expand each scanline to a multiple of 32 bits. They are usually not used in image processing operations. When boundary conditions are important, as in seedfill, they must be set properly. (2) This sets the value of the pad bits (if any) in the last 32-bit word in each scanline, within the specified band of raster lines. (3) For 32 bpp pix, there are no pad bits, so this is a no-op.
Input: pix (x,y) pixel coords val (value to be inserted) Return: 0 if OK; 1 on error
Notes: (1) Warning: the input value is not checked for overflow with respect the the depth of , and the sign bit (if any) is ignored. * For d == 1, > 0 sets the bit on. * For d == 2, 4, 8 and 16, is masked to the maximum allowable pixel value, and any (invalid) higher order bits are discarded. (2) See pixGetPixel() for information on performance.
Input: pix (8 bpp; not cmapped) col (column index) colvect (vector of floats) Return: 0 if OK, 1 on error
Input: pix xres, yres (use 0 to skip the setting for either of these) Return: 0 if OK, 1 on error
Input: pixd (32 bpp) pixs (8 bpp) color (one of {COLOR_RED, COLOR_GREEN, COLOR_BLUE, L_ALPHA_CHANNEL}) Return: 0 if OK; 1 on error
Notes: (1) This places the 8 bpp pixel in pixs into the specified color component (properly interleaved) in pixd. (2) The alpha channel component mostly ignored in leptonica.
LEPT_DLL l_int32 pixSetRGBPixel | ( | PIX * | pix, |
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval | ||
) |
Input: pix (32 bpp rgb) (x,y) pixel coords rval (red component) gval (green component) bval (blue component) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 pixSetSelectCmap | ( | PIX * | pixs, |
BOX * | box, | ||
l_int32 | sindex, | ||
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval | ||
) |
Input: pixs (1, 2, 4 or 8 bpp, with colormap) box (<optional> region to set color; can be NULL) sindex (colormap index of pixels to be changed) rval, gval, bval (new color to paint) Return: 0 if OK, 1 on error
Note: (1) This is an in-place operation. (2) It sets all pixels in region that have the color specified by the colormap index 'sindex' to the new color. (3) sindex must be in the existing colormap; otherwise an error is returned. (4) If the new color exists in the colormap, it is used; otherwise, it is added to the colormap. If it cannot be added because the colormap is full, an error is returned. (5) If box is NULL, applies function to the entire image; otherwise, clips the operation to the intersection of the box and pix. (6) An example of use would be to set to a specific color all the light (background) pixels within a certain region of a 3-level 2 bpp image, while leaving light pixels outside this region unchanged.
LEPT_DLL l_int32 pixSetSelectMaskedCmap | ( | PIX * | pixs, |
PIX * | pixm, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 | sindex, | ||
l_int32 | rval, | ||
l_int32 | gval, | ||
l_int32 | bval | ||
) |
Input: pixs (2, 4 or 8 bpp, with colormap) pixm (<optional> 1 bpp mask; no-op if NULL) x, y (UL corner of mask relative to pixs) sindex (colormap index of pixels in pixs to be changed) rval, gval, bval (new color to substitute) Return: 0 if OK, 1 on error
Note: (1) This is an in-place operation. (2) This paints through the fg of pixm and replaces all pixels in pixs that have a particular value (sindex) with the new color. (3) If pixm == NULL, a warning is given. (4) sindex must be in the existing colormap; otherwise an error is returned. (5) If the new color exists in the colormap, it is used; otherwise, it is added to the colormap. If the colormap is full, an error is returned.
LEPT_DLL l_int32 pixSetText | ( | PIX * | pix, |
const char * | textstring | ||
) |
Input: pix textstring (can be null) Return: 0 if OK, 1 on error
Notes: (1) This removes any existing textstring and puts a copy of the input textstring there.
LEPT_DLL l_int32 pixSetTextblock | ( | PIX * | pixs, |
L_BMF * | bmf, | ||
const char * | textstr, | ||
l_uint32 | val, | ||
l_int32 | x0, | ||
l_int32 | y0, | ||
l_int32 | wtext, | ||
l_int32 | firstindent, | ||
l_int32 * | poverflow | ||
) |
Input: pixs (input image) bmf (bitmap font data) textstr (block text string to be set) val (color to set the text) x0 (left edge for each line of text) y0 (baseline location for the first text line) wtext (max width of each line of generated text) firstindent (indentation of first line, in x-widths) &overflow (<optional return>=""> 0 if text is contained in input pix; 1 if it is clipped) Return: 0 if OK, 1 on error
Notes: (1) This function paints a set of lines of text over an image. (2) is the pixel value to be painted through the font mask. It should be chosen to agree with the depth of pixs. If it is out of bounds, an intermediate value is chosen. For RGB, use hex notation: 0xRRGGBB00, where RR is the hex representation of the red intensity, etc. The last two hex digits are 00 (byte value 0), assigned to the A component. Note that, as usual, RGBA proceeds from left to right in the order from MSB to LSB (see pix.h for details). (3) If there is a colormap, this does the best it can to use the requested color, or something similar to it.
LEPT_DLL l_int32 pixSetTextline | ( | PIX * | pixs, |
L_BMF * | bmf, | ||
const char * | textstr, | ||
l_uint32 | val, | ||
l_int32 | x0, | ||
l_int32 | y0, | ||
l_int32 * | pwidth, | ||
l_int32 * | poverflow | ||
) |
Input: pixs (input image) bmf (bitmap font data) textstr (text string to be set on the line) val (color to set the text) x0 (left edge for first char) y0 (baseline location for all text on line) &width (<optional return>=""> width of generated text) &overflow (<optional return>=""> 0 if text is contained in input pix; 1 if it is clipped) Return: 0 if OK, 1 on error
Notes: (1) This function paints a line of text over an image. (2) is the pixel value to be painted through the font mask. It should be chosen to agree with the depth of pixs. If it is out of bounds, an intermediate value is chosen. For RGB, use hex notation: 0xRRGGBB00, where RR is the hex representation of the red intensity, etc. The last two hex digits are 00 (byte value 0), assigned to the A component. Note that, as usual, RGBA proceeds from left to right in the order from MSB to LSB (see pix.h for details). (3) If there is a colormap, this does the best it can to use the requested color, or something similar to it.
Input: pixs (32 bpp rgba) val (32 bit unsigned color to use where alpha == 0) debugflag (generates intermediate images) Return: pixd (32 bpp rgba), or null on error
Notes: (1) This is one of the few operations in leptonica that uses the alpha blending component in rgba images. It sets the r, g and b components under every fully transparent alpha component to . (2) Full transparency is denoted by alpha == 0. By setting all pixels to where alpha == 0, this can improve compressibility by reducing the entropy. (3) The visual result depends on how the image is displayed. (a) For display devices that respect the use of the alpha layer, this will not affect the appearance. (b) For typical leptonica operations, alpha is ignored, so there will be a change in appearance because this resets the rgb values in the fully transparent region. (4) For reading and writing rgba pix in png format, use pixReadRGBAPng() and pixWriteRGBAPng(). (5) For example, if you want to rewrite all fully transparent pixels in a png file to white: pixs = pixReadRGBAPng(<infile>); // special read pixd = pixSetUnderTransparency(pixs, 0xffffff00, 0); Then either use a normal write if you won't be using transparency: pixWrite(<outfile>, pixd, IFF_PNG); or an RGBA write if you want to preserve the transparency layer pixWriteRGBAPng(<outfile>, pixd); // special write (6) Caution. Because rgb images in leptonica typically have value 0 in the alpha channel, this function would interpret the entire image as fully transparent, and set every pixel to . Because this is not desirable, instead we issue a warning and return a copy of the input pix. If you really want to set every pixel to the same value, use pixSetAllArbitrary(). (7) This is useful for compressing an RGBA image where the part of the image that is fully transparent is random; compression is typically improved by setting that region to a constant. For rendering as a 3 component RGB image over a uniform background, use pixAlphaBlendUniform().
Input: pix (8 bpp, no colormap) &w (<optional return>=""> width) &h (<optional return>=""> height) Return: line ptr array, or null on error
Notes: (1) This is a simple helper for processing 8 bpp images with direct byte access. It can swap byte order within each word. (2) After processing, you must call pixCleanupByteProcessing(), which frees the lineptr array and restores byte order. (3) Usage: l_uint8 **lineptrs = pixSetupByteProcessing(pix, &w, &h); for (i = 0; i < h; i++) { l_uint8 *line = lineptrs[i]; for (j = 0; j < w; j++) { val = line[j]; ... } } pixCleanupByteProcessing(pix, lineptrs);
LEPT_DLL l_int32 pixSetWidth | ( | PIX * | pix, |
l_int32 | width | ||
) |
LEPT_DLL l_int32 pixSetXRes | ( | PIX * | pix, |
l_int32 | res | ||
) |
LEPT_DLL l_int32 pixSetYRes | ( | PIX * | pix, |
l_int32 | res | ||
) |
Input: pixd (<optional>; either NULL or equal to pixs for in-place) pixs (32 bpp rgb) srcval (source color: 0xrrggbb00) dstval (target color: 0xrrggbb00) Return: pixd (with all pixels mapped based on the srcval/destval mapping), or pixd on error
Notes: (1) For each component (r, b, g) separately, this does a linear mapping of the colors in pixs to colors in pixd. Let rs and rd be the red src and dest components in and , and rval is the red component of the src pixel. Then for all pixels in pixs, the mapping for the red component from pixs to pixd is: if (rd <= rs) (shift toward black) rval --> (rd/rs) * rval if (rd > rs) (shift toward white) (255 - rval) --> ((255 - rs)/(255 - rd)) * (255 - rval) Thus if rd <= rs, the red component of all pixels is mapped by the same fraction toward white, and if rd > rs, they are mapped by the same fraction toward black. This is essentially a different linear TRC (gamma = 1) for each component. The source and target color inputs are just used to generate the three fractions. (2) Note that this mapping differs from that in pixLinearMapToTargetColor(), which maps rs --> rd and does a piecewise stretching in between. (3) For inplace operation, call it this way: pixFractionalShiftByComponent(pixs, pixs, ... ) (4) For generating a new pixd: pixd = pixLinearMapToTargetColor(NULL, pixs, ...) (5) A simple application is to color a grayscale image. A light background can be colored using srcval = 0xffffff00 and picking a target background color for dstval. A dark foreground can be colored by using srcval = 0x0 and choosing a target foreground color for dstval.
LEPT_DLL PIX* pixSimpleCaptcha | ( | PIX * | pixs, |
l_int32 | border, | ||
l_int32 | nterms, | ||
l_uint32 | seed, | ||
l_uint32 | color, | ||
l_int32 | cmapflag | ||
) |
Input: pixs (8 bpp; no colormap) border (added white pixels on each side) nterms (number of x and y harmonic terms) seed (of random number generator) color (for colorizing; in 0xrrggbb00 format; use 0 for black) cmapflag (1 for colormap output; 0 for rgb) Return: pixd (8 bpp cmap or 32 bpp rgb), or null on error
Notes: (1) This uses typical default values for generating captchas. The magnitudes of the harmonic warp are typically to be smaller when more terms are used, even though the phases are random. See, for example, prog/warptest.c.
LEPT_DLL l_int32 pixSizesEqual | ( | PIX * | pix1, |
PIX * | pix2 | ||
) |
Input: two pix Return: 1 if the two pix have same {h, w, d}; 0 otherwise.
Input: pixs (8 bpp grayscale; no colormap) pixm (<optional> 1 bpp; if null, this is a no-op) factor (subsampling factor for getting average; >= 1) Return: 0 if OK, 1 on error
Notes: (1) The pixels in pixs corresponding to those in each 8-connected region in the mask are set to the average value. (2) This is required for adaptive mapping to avoid the generation of stripes in the background map, due to variations in the pixel values near the edges of mask regions. (3) This function is optimized for background smoothing, where there are a relatively small number of components. It will be inefficient if used where there are many small components.
LEPT_DLL PIX* pixSnapColor | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_uint32 | srcval, | ||
l_uint32 | dstval, | ||
l_int32 | diff | ||
) |
Input: pixd (<optional>; either NULL or equal to pixs for in-place) pixs (colormapped or 8 bpp gray or 32 bpp rgb) srcval (color center to be selected for change: 0xrrggbb00) dstval (target color for pixels: 0xrrggbb00) diff (max absolute difference, applied to all components) Return: pixd (with all pixels within diff of pixval set to pixval), or pixd on error
Notes: (1) For inplace operation, call it this way: pixSnapColor(pixs, pixs, ... ) (2) For generating a new pixd: pixd = pixSnapColor(NULL, pixs, ...) (3) If pixs has a colormap, it is handled by pixSnapColorCmap(). (4) All pixels within 'diff' of 'srcval', componentwise, will be changed to 'dstval'.
LEPT_DLL PIX* pixSnapColorCmap | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_uint32 | srcval, | ||
l_uint32 | dstval, | ||
l_int32 | diff | ||
) |
Input: pixd (<optional>; either NULL or equal to pixs for in-place) pixs (colormapped) srcval (color center to be selected for change: 0xrrggbb00) dstval (target color for pixels: 0xrrggbb00) diff (max absolute difference, applied to all components) Return: pixd (with all pixels within diff of srcval set to dstval), or pixd on error
Notes: (1) For inplace operation, call it this way: pixSnapCcmap(pixs, pixs, ... ) (2) For generating a new pixd: pixd = pixSnapCmap(NULL, pixs, ...) (3) pixs must have a colormap. (4) All colors within 'diff' of 'srcval', componentwise, will be changed to 'dstval'.
LEPT_DLL PIX* pixSobelEdgeFilter | ( | PIX * | pixs, |
l_int32 | orientflag | ||
) |
Input: pixs (8 bpp; no colormap) orientflag (L_HORIZONTAL_EDGES, L_VERTICAL_EDGES, L_ALL_EDGES) Return: pixd (8 bpp, edges are brighter), or null on error
Notes: (1) Invert pixd to see larger gradients as darker (grayscale). (2) To generate a binary image of the edges, threshold the result using pixThresholdToBinary(). If the high edge values are to be fg (1), invert after running pixThresholdToBinary(). (3) Label the pixels as follows: 1 4 7 2 5 8 3 6 9 Read the data incrementally across the image and unroll the loop. (4) This runs at about 45 Mpix/sec on a 3 GHz processor.
LEPT_DLL BOXA* pixSplitComponentIntoBoxa | ( | PIX * | pix, |
BOX * | box, | ||
l_int32 | minsum, | ||
l_int32 | skipdist, | ||
l_int32 | delta, | ||
l_int32 | maxbg, | ||
l_int32 | maxcomps, | ||
l_int32 | remainder | ||
) |
Input: pixs (1 bpp) box (<optional> location of pixs w/rt an origin) minsum (minimum pixels to trigger propagation) skipdist (distance before computing sum for propagation) delta (difference required to stop propagation) maxbg (maximum number of allowed bg pixels in ref scan) maxcomps (use 0 for unlimited number of subdivided components) remainder (set to 1 to get b.b. of remaining stuff) Return: boxa (of rectangles covering the fg of pixs), or null on error
Notes: (1) This generates a boxa of rectangles that covers the fg of a mask. It does so by a greedy partitioning of the mask, choosing the largest rectangle found from each of the four directions at each step. (2) The input parameters give some flexibility for boundary noise. The resulting set of rectangles must cover all the fg pixels and, in addition, may cover some bg pixels. Using small input parameters on a noiseless mask (i.e., one that has only large vertical and horizontal edges) will result in a proper covering of only the fg pixels of the mask. (3) The input is assumed to be a single connected component, that may have holes. From each side, sweep inward, counting the pixels. If the count becomes greater than , and we have moved forward a further amount , record that count ('countref'), but don't accept if the scan contains more than bg pixels. Continue the scan until we reach a count that differs from countref by at least , at which point the propagation stops. The box swept out gets a score, which is the sum of fg pixels minus a penalty. The penalty is the number of bg pixels in the box. This is done from all four sides, and the side with the largest score is saved as a rectangle. The process repeats until there is either no rectangle left, or there is one that can't be captured from any direction. For the latter case, we simply accept the last rectangle. (4) The input box is only used to specify the location of the UL corner of pixs, with respect to an origin that typically represents the UL corner of an underlying image, of which pixs is one component. If is null, the UL corner is taken to be (0, 0). (5) The parameter gives the maximum number of allowed rectangles extracted from any single connected component. Use 0 if no limit is to be applied. (6) The flag specifies whether we take a final bounding box for anything left after the maximum number of allowed rectangle is extracted. (7) So if > 0, it specifies that we want no more than the first rectangles that satisfy the input criteria. After this, we can get a final rectangle that bounds everything left over by setting == 1. If == 0, we only get rectangles that satisfy the input criteria. (8) It should be noted that the removal of rectangles can break the original c.c. into several c.c. (9) Summing up: * If == 0, the splitting proceeds as far as possible. * If > 0, the splitting stops when are found, or earlier if no more components can be selected. * If == 1 and components remain that cannot be selected, they are returned as a single final rectangle; otherwise, they are ignored.
LEPT_DLL l_int32 pixSplitDistributionFgBg | ( | PIX * | pixs, |
l_float32 | scorefract, | ||
l_int32 | factor, | ||
l_int32 * | pthresh, | ||
l_int32 * | pfgval, | ||
l_int32 * | pbgval, | ||
l_int32 | debugflag | ||
) |
Input: pixs (any depth; cmapped ok) scorefract (fraction of the max score, used to determine the range over which the histogram min is searched) factor (subsampling factor; integer >= 1) &thresh (<optional return>=""> best threshold for separating) &fgval (<optional return>=""> average foreground value) &bgval (<optional return>=""> average background value) debugflag (1 for plotting of distribution and split point) Return: 0 if OK, 1 on error
Notes: (1) See numaSplitDistribution() for details on the underlying method of choosing a threshold.
LEPT_DLL BOXA* pixSplitIntoBoxa | ( | PIX * | pixs, |
l_int32 | minsum, | ||
l_int32 | skipdist, | ||
l_int32 | delta, | ||
l_int32 | maxbg, | ||
l_int32 | maxcomps, | ||
l_int32 | remainder | ||
) |
Input: pixs (1 bpp) minsum (minimum pixels to trigger propagation) skipdist (distance before computing sum for propagation) delta (difference required to stop propagation) maxbg (maximum number of allowed bg pixels in ref scan) maxcomps (use 0 for unlimited number of subdivided components) remainder (set to 1 to get b.b. of remaining stuff) Return: boxa (of rectangles covering the fg of pixs), or null on error
Notes: (1) This generates a boxa of rectangles that covers the fg of a mask. For each 8-connected component in pixs, it does a greedy partitioning, choosing the largest rectangle found from each of the four directions at each iter. See pixSplitComponentsIntoBoxa() for details. (2) The input parameters give some flexibility for boundary noise. The resulting set of rectangles may cover some bg pixels. (3) This should be used when there are a small number of mask components, each of which has sides that are close to horizontal and vertical. The input parameters and determine whether or not holes in the mask are covered. (4) The parameter gives the maximum number of allowed rectangles extracted from any single connected component. Use 0 if no limit is to be applied. (5) The flag specifies whether we take a final bounding box for anything left after the maximum number of allowed rectangle is extracted.
LEPT_DLL PIX* pixStereoFromPair | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_float32 | rwt, | ||
l_float32 | gwt, | ||
l_float32 | bwt | ||
) |
Input: pix1 (32 bpp rgb) pix2 (32 bpp rgb) rwt, gwt, bwt (weighting factors used for each component in pix1 to determine the output red channel) Return: pixd (stereo enhanced), or null on error
Notes: (1) pix1 and pix2 are a pair of stereo images, ideally taken concurrently in the same plane, with some lateral translation. (2) The output red channel is determined from . The output green and blue channels are taken from the green and blue channels, respectively, of . (3) The weights determine how much of each component in goes into the output red channel. The sum of weights must be 1.0. If it's not, we scale the weights to satisfy this criterion. (4) The most general pixel mapping allowed here is: rval = rwt * r1 + gwt * g1 + bwt * b1 (from pix1) gval = g2 (from pix2) bval = b2 (from pix2) (5) The simplest method is to use rwt = 1.0, gwt = 0.0, bwt = 0.0, but this causes unpleasant visual artifacts with red in the image. Use of green and blue from in the red channel, instead of red, tends to fix that problem.
LEPT_DLL PIX* pixStretchHorizontal | ( | PIX * | pixs, |
l_int32 | dir, | ||
l_int32 | type, | ||
l_int32 | hmax, | ||
l_int32 | operation, | ||
l_int32 | incolor | ||
) |
LEPT_DLL PIX* pixStretchHorizontalLI | ( | PIX * | pixs, |
l_int32 | dir, | ||
l_int32 | type, | ||
l_int32 | hmax, | ||
l_int32 | incolor | ||
) |
Input: pixs (1, 8 or 32 bpp) dir (L_WARP_TO_LEFT or L_WARP_TO_RIGHT) type (L_LINEAR_WARP or L_QUADRATIC_WARP) hmax (horizontal displacement at edge) incolor (L_BRING_IN_WHITE or L_BRING_IN_BLACK) Return: pixd (stretched/compressed), or null on error
Notes: (1) See pixStretchHorizontal() for details.
LEPT_DLL PIX* pixStretchHorizontalSampled | ( | PIX * | pixs, |
l_int32 | dir, | ||
l_int32 | type, | ||
l_int32 | hmax, | ||
l_int32 | incolor | ||
) |
Input: pixs (1, 8 or 32 bpp) dir (L_WARP_TO_LEFT or L_WARP_TO_RIGHT) type (L_LINEAR_WARP or L_QUADRATIC_WARP) hmax (horizontal displacement at edge) incolor (L_BRING_IN_WHITE or L_BRING_IN_BLACK) Return: pixd (stretched/compressed), or null on error
Notes: (1) See pixStretchHorizontal() for details.
LEPT_DLL PTA* pixSubsampleBoundaryPixels | ( | PIX * | pixs, |
l_int32 | skip | ||
) |
Input: pixs (1 bpp, with only boundary pixels in fg) skip (number to skip between samples as you traverse boundary) Return: pta, or null on error
Notes: (1) If skip = 0, we take all the fg pixels. (2) We try to traverse the boundaries in a regular way. Some pixels may be missed, and these are then subsampled randomly with a fraction determined by 'skip'. (3) The most natural approach is to use a depth first (stack-based) method to find the fg pixels. However, the pixel runs are 4-connected and there are relatively few branches. So instead of doing a proper depth-first search, we get nearly the same result using two nested while loops: the outer one continues a raster-based search for the next fg pixel, and the inner one does a reasonable job running along each 4-connected coutour.
Input: pixd (<optional>; this can be null, equal to pixs1, equal to pixs2, or different from both pixs1 and pixs2) pixs1 (can be == pixd) pixs2 (can be == pixd) Return: pixd always
Notes: (1) This gives the set subtraction of two images with equal depth, aligning them to the the UL corner. pixs1 and pixs2 need not have the same width and height. (2) Source pixs2 is always subtracted from source pixs1. The result is pixs1 \ pixs2 = pixs1 & (~pixs2) (3) There are 4 cases: (a) pixd == null, (src1 - src2) --> new pixd (b) pixd == pixs1, (src1 - src2) --> src1 (in-place) (c) pixd == pixs2, (src1 - src2) --> src2 (in-place) (d) pixd != pixs1 && pixd != pixs2), (src1 - src2) --> input pixd (4) For clarity, if the case is known, use these patterns: (a) pixd = pixSubtract(NULL, pixs1, pixs2); (b) pixSubtract(pixs1, pixs1, pixs2); (c) pixSubtract(pixs2, pixs1, pixs2); (d) pixSubtract(pixd, pixs1, pixs2); (5) The size of the result is determined by pixs1. (6) The depths of pixs1 and pixs2 must be equal.
Input: pixd (<optional>; this can be null, equal to pixs1, or different from pixs1) pixs1 (can be == to pixd) pixs2 Return: pixd always
Notes: (1) Arithmetic subtraction of two 8, 16 or 32 bpp images. (2) Source pixs2 is always subtracted from source pixs1. (3) Do explicit clipping to 0. (4) Alignment is to UL corner. (5) There are 3 cases. The result can go to a new dest, in-place to pixs1, or to an existing input dest: (a) pixd == null (src1 - src2) --> new pixd (b) pixd == pixs1 (src1 - src2) --> src1 (in-place) (d) pixd != pixs1 (src1 - src2) --> input pixd (6) pixs2 must be different from both pixd and pixs1.
LEPT_DLL NUMA* pixSumPixelsByColumn | ( | PIX * | pix | ) |
Input: pix (1, 8 or 16 bpp; no colormap) Return: na of pixel sums by column, or null on error
Notes: (1) To resample for a bin size different from 1, use numaUniformSampling() on the result of this function.
LEPT_DLL NUMA* pixSumPixelsByRow | ( | PIX * | pix, |
l_int32 * | tab8 | ||
) |
Input: pix (1, 8 or 16 bpp; no colormap) tab8 (<optional> lookup table for 1 bpp; use null for 8 bpp) Return: na of pixel sums by row, or null on error
Notes: (1) To resample for a bin size different from 1, use numaUniformSampling() on the result of this function.
Input: pix (1, 2, 4, 8, 16, 32 bpp; not cmapped) box (<optional> if null, use entire image) &sum (<return> sum of pixel values in region) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 pixSwapAndDestroy | ( | PIX ** | ppixd, |
PIX ** | ppixs | ||
) |
Input: &pixd (<optional, return> input pixd can be null, and it must be different from pixs) &pixs (will be nulled after the swap) Return: 0 if OK, 1 on error
Notes: (1) Simple operation to change the handle name safely. After this operation, the original image in pixd has been destroyed, pixd points to what was pixs, and the input pixs ptr has been nulled. (2) This works safely whether or not pixs and pixd are cloned. If pixs is cloned, the other handles still point to the original image, with the ref count reduced by 1. (3) Usage example: Pix *pix1 = pixRead("..."); Pix *pix2 = function(pix1, ...); pixSwapAndDestroy(&pix1, &pix2); pixDestroy(&pix1); // holds what was in pix2 Example with clones ([] shows ref count of image generated by the function): Pix *pixs = pixRead("..."); Pix *pix1 = pixClone(pixs); Pix *pix2 = function(pix1, ...); [1] Pix *pix3 = pixClone(pix2); [1] --> [2] pixSwapAndDestroy(&pix1, &pix2); pixDestroy(&pixs); // still holds read image pixDestroy(&pix1); // holds what was in pix2 [2] --> [1] pixDestroy(&pix3); // holds what was in pix2 [1] --> [0]
LEPT_DLL l_int32 pixTestForSimilarity | ( | PIX * | pix1, |
PIX * | pix2, | ||
l_int32 | factor, | ||
l_int32 | mindiff, | ||
l_float32 | maxfract, | ||
l_float32 | maxave, | ||
l_int32 * | psimilar, | ||
l_int32 | printstats | ||
) |
Input: pix1 (8 bpp gray or 32 bpp rgb, or colormapped) pix2 (8 bpp gray or 32 bpp rgb, or colormapped) factor (subsampling factor; use 0 or 1 for no subsampling) mindiff (minimum pixel difference to be counted; > 0) maxfract (maximum fraction of pixels allowed to have diff greater than or equal to mindiff) maxave (maximum average difference of pixels allowed for pixels with diff greater than or equal to mindiff, after subtracting mindiff) &similar (<return> 1 if similar, 0 otherwise) printstats (use 1 to print normalized histogram to stderr) Return: 0 if OK, 1 on error
Notes: (1) This takes 2 pix that are the same size and determines using 3 input parameters if they are "similar". The first parameter establishes a criterion of pixel-to-pixel similarity: two pixels are not similar if their difference in value is at least mindiff. Then and are thresholds on the number and distribution of dissimilar pixels allowed for the two pix to be similar. If the pix are to be similar, neither threshold can be exceeded. (2) In setting the and thresholds, you have these options: (a) Base the comparison only on . Then set = 0.0 or 256.0. (If 0, we always ignore it.) (b) Base the comparison only on . Then set = 1.0. (c) Base the comparison on both thresholds. (3) Example of values that can be expected at mindiff = 15 when comparing lossless png encoding with jpeg encoding, q=75: (smoothish bg) fractdiff = 0.01, avediff = 2.5 (natural scene) fractdiff = 0.13, avediff = 3.5 To identify these images as 'similar', select maxfract and maxave to be upper bounds of what you expect. (4) See pixGetDifferenceStats() for a discussion of why we subtract mindiff from the computed average diff of the nonsimilar pixels to get the 'avediff' returned by that function. (5) If there is a colormap, it is removed and the result is either gray or RGB depending on the colormap. (6) If RGB, the maximum difference between pixel components is saved in the histogram.
Input: pixs (1 bpp) type (L_THIN_FG, L_THIN_BG) connectivity (4 or 8) maxiters (max number of iters allowed; use 0 to iterate until completion) Return: pixd, or null on error
Notes: (1) See "Connectivity-preserving morphological image transformations," Dan S. Bloomberg, in SPIE Visual Communications and Image Processing, Conference 1606, pp. 320-334, November 1991, Boston, MA. A web version is available at http://www.leptonica.com/papers/conn.pdf (2) We implement here two of the best iterative morphological thinning algorithms, for 4 c.c and 8 c.c. Each iteration uses a mixture of parallel operations (using several different 3x3 Sels) and serial operations. Specifically, each thinning iteration consists of four sequential thinnings from each of four directions. Each of these thinnings is a parallel composite operation, where the union of a set of HMTs are set subtracted from the input. For 4-cc thinning, we use 3 HMTs in parallel, and for 8-cc thinning we use 4 HMTs. (3) A "good" thinning algorithm is one that generates a skeleton that is near the medial axis and has neither pruned real branches nor left extra dendritic branches. (4) To thin the foreground, which is the usual situation, use type == L_THIN_FG. Thickening the foreground is equivalent to thinning the background (type == L_THIN_BG), where the opposite connectivity gets preserved. For example, to thicken the fg using 4-connectivity, we thin the bg using Sels that preserve 8-connectivity.
LEPT_DLL PIX* pixThinExamples | ( | PIX * | pixs, |
l_int32 | type, | ||
l_int32 | index, | ||
l_int32 | maxiters, | ||
const char * | selfile | ||
) |
Input: pixs (1 bpp) type (L_THIN_FG, L_THIN_BG) index (into specific examples; valid 1-9; see notes) maxiters (max number of iters allowed; use 0 to iterate until completion) selfile (<optional> filename for output sel display) Return: pixd, or null on error
Notes: (1) See notes in pixThin(). The examples are taken from the paper referenced there. (2) Here we allow specific sets of HMTs to be used in parallel for thinning from each of four directions. One iteration consists of four such parallel thins. (3) The examples are indexed as follows: Thinning (e.g., run to completion): index = 1 sel_4_1, sel_4_5, sel_4_6 index = 2 sel_4_1, sel_4_7, sel_4_7_rot index = 3 sel_48_1, sel_48_1_rot, sel_48_2 index = 4 sel_8_2, sel_8_3, sel_48_2 index = 5 sel_8_1, sel_8_5, sel_8_6 index = 6 sel_8_2, sel_8_3, sel_8_8, sel_8_9 index = 7 sel_8_5, sel_8_6, sel_8_7, sel_8_7_rot Thickening: index = 8 sel_4_2, sel_4_3 (e.g,, do just a few iterations) index = 9 sel_8_4 (e.g., do just a few iterations)
Input: pixs (1 bpp) type (L_THIN_FG, L_THIN_BG) sela (of Sels for parallel composite HMTs) maxiters (max number of iters allowed; use 0 to iterate until completion) Return: pixd, or null on error
Notes: (1) See notes in pixThin(). That function chooses among the best of the Sels for thinning. (2) This is a general function that takes a Sela of HMTs that are used in parallel for thinning from each of four directions. One iteration consists of four such parallel thins.
Input: pix (8 bpp grayscale) d (destination depth: 1, 2, 4 or 8) nlevels (number of levels to be used for colormap) cmapflag (1 if makes colormap; 0 otherwise) Return: pixd (thresholded with standard dest thresholds), or null on error
Notes: (1) This uses, by default, equally spaced "target" values that depend on the number of levels, with thresholds halfway between. For N levels, with separation (N-1)/255, there are N-1 fixed thresholds. (2) For 1 bpp destination, the number of levels can only be 2 and if a cmap is made, black is (0,0,0) and white is (255,255,255), which is opposite to the convention without a colormap. (3) For 1, 2 and 4 bpp, the nlevels arg is used if a colormap is made; otherwise, we take the most significant bits from the src that will fit in the dest. (4) For 8 bpp, the input pixs is quantized to nlevels. The dest quantized with that mapping, either through a colormap table or directly with 8 bit values. (5) Typically you should not use make a colormap for 1 bpp dest. (6) This is not dithering. Each pixel is treated independently.
LEPT_DLL l_int32 pixThresholdForFgBg | ( | PIX * | pixs, |
l_int32 | factor, | ||
l_int32 | thresh, | ||
l_int32 * | pfgval, | ||
l_int32 * | pbgval | ||
) |
Input: pixs (any depth; cmapped ok) factor (subsampling factor; integer >= 1) thresh (threshold for generating foreground mask) &fgval (<optional return>=""> average foreground value) &bgval (<optional return>=""> average background value) Return: 0 if OK, 1 on error
LEPT_DLL PIX* pixThresholdGrayArb | ( | PIX * | pixs, |
const char * | edgevals, | ||
l_int32 | outdepth, | ||
l_int32 | use_average, | ||
l_int32 | setblack, | ||
l_int32 | setwhite | ||
) |
Input: pixs (8 bpp grayscale; can have colormap) edgevals (string giving edge value of each bin) outdepth (0, 2, 4 or 8 bpp; 0 is default for min depth) use_average (1 if use the average pixel value in colormap) setblack (1 if darkest color is set to black) setwhite (1 if lightest color is set to white) Return: pixd (2, 4 or 8 bpp quantized image with colormap), or null on error
Notes: (1) This function allows exact specification of the quantization bins. The string is a space-separated set of values specifying the dividing points between output quantization bins. These threshold values are assigned to the bin with higher values, so that each of them is the smallest value in their bin. (2) The output image (pixd) depth is specified by . The number of bins is the number of edgevals + 1. The relation between outdepth and the number of bins is: outdepth = 2 nbins <= 4 outdepth = 4 nbins <= 16 outdepth = 8 nbins <= 256 With == 0, the minimum required depth for the given number of bins is used. The output pixd has a colormap. (3) The last 3 args determine the specific values that go into the colormap. (4) For :
Input: pixs (8 bpp, can have colormap) nlevels (equally spaced; must be between 2 and 256) cmapflag (1 to build colormap; 0 otherwise) Return: pixd (8 bpp, optionally with colormap), or null on error
Notes: (1) Valid values for nlevels is the set {2,...,256}. (2) Any colormap on the input pixs is removed to 8 bpp grayscale. (3) If cmapflag == 1, a colormap of size 'nlevels' is made, and the pixel values in pixs are replaced by their appropriate color indices. Otherwise, the pixel values are the actual thresholded (i.e., quantized) grayscale values. (4) If you don't want the thresholding to be equally spaced, first transform the input 8 bpp src using pixGammaTRC().
LEPT_DLL l_int32 pixThresholdPixelSum | ( | PIX * | pix, |
l_int32 | thresh, | ||
l_int32 * | pabove, | ||
l_int32 * | tab8 | ||
) |
Input: pix (1 bpp) threshold &above (<return> 1 if above threshold; 0 if equal to or less than threshold) tab8 (<optional> 8-bit pixel lookup table) Return: 0 if OK; 1 on error
Notes: (1) This sums the ON pixels and returns immediately if the count goes above threshold. It is therefore more efficient for matching images (by running this function on the xor of the 2 images) than using pixCountPixels(), which counts all pixels before returning.
LEPT_DLL l_int32 pixThresholdSpreadNorm | ( | PIX * | pixs, |
l_int32 | filtertype, | ||
l_int32 | edgethresh, | ||
l_int32 | smoothx, | ||
l_int32 | smoothy, | ||
l_float32 | gamma, | ||
l_int32 | minval, | ||
l_int32 | maxval, | ||
l_int32 | targetthresh, | ||
PIX ** | ppixth, | ||
PIX ** | ppixb, | ||
PIX ** | ppixd | ||
) |
Input: pixs (8 bpp grayscale; not colormapped) filtertype (L_SOBEL_EDGE or L_TWO_SIDED_EDGE); edgethresh (threshold on magnitude of edge filter; typ 10-20) smoothx, smoothy (half-width of convolution kernel applied to spread threshold: use 0 for no smoothing) gamma (gamma correction; typ. about 0.7) minval (input value that gives 0 for output; typ. -25) maxval (input value that gives 255 for output; typ. 255) targetthresh (target threshold for normalization) &pixth (<optional return>=""> computed local threshold value) &pixb (<optional return>=""> thresholded normalized image) &pixd (<optional return>=""> normalized image) Return: 0 if OK, 1 on error
Notes: (1) The basis of this approach is the use of seed spreading on a (possibly) sparse set of estimates for the local threshold. The resulting dense estimates are smoothed by convolution and used to either threshold the input image or normalize it with a local transformation that linearly maps the pixels so that the local threshold estimate becomes constant over the resulting image. This approach is one of several that have been suggested (and implemented) by Ray Smith. (2) You can use either the Sobel or TwoSided edge filters. The results appear to be similar, using typical values of edgethresh in the rang 10-20. (3) To skip the trc enhancement, use gamma = 1.0, minval = 0 and maxval = 255. (4) For the normalized image pixd, each pixel is linearly mapped in such a way that the local threshold is equal to targetthresh. (5) The full width and height of the convolution kernel are (2 * smoothx + 1) and (2 * smoothy + 1). (6) This function can be used with the pixtiling utility if the images are too large. See pixOtsuAdaptiveThreshold() for an example of this.
Input: pixs (8 bpp) nlevels (equally spaced; must be between 2 and 4) cmapflag (1 to build colormap; 0 otherwise) Return: pixd (2 bpp, optionally with colormap), or null on error
Notes: (1) Valid values for nlevels is the set {2, 3, 4}. (2) Any colormap on the input pixs is removed to 8 bpp grayscale. (3) This function is typically invoked with cmapflag == 1. In the situation where no colormap is desired, nlevels is ignored and pixs is thresholded to 4 levels. (4) The target output colors are equally spaced, with the darkest at 0 and the lightest at 255. The thresholds are chosen halfway between adjacent output values. A table is built that specifies the mapping from src to dest. (5) If cmapflag == 1, a colormap of size 'nlevels' is made, and the pixel values in pixs are replaced by their appropriate color indices. The number of holdouts, 4 - nlevels, will be between 0 and 2. (6) If you don't want the thresholding to be equally spaced, either first transform the 8 bpp src using pixGammaTRC(). or, if cmapflag == 1, after calling this function you can use pixcmapResetColor() to change any individual colors. (7) If a colormap is generated, it will specify (to display programs) exactly how each level is to be represented in RGB space. When representing text, 3 levels is far better than 2 because of the antialiasing of the single gray level, and 4 levels (black, white and 2 gray levels) is getting close to the perceptual quality of a (nearly continuous) grayscale image. With 2 bpp, you can set up a colormap and allocate from 2 to 4 levels to represent antialiased text. Any left over colormap entries can be used for coloring regions. For the same number of levels, the file size of a 2 bpp image is about 10% smaller than that of a 4 bpp result for the same number of levels. For both 2 bpp and 4 bpp, using 4 levels you get compression far better than that of jpeg, because the quantization to 4 levels will remove the jpeg ringing in the background near character edges.
Input: pixs (8 bpp, can have colormap) nlevels (equally spaced; must be between 2 and 16) cmapflag (1 to build colormap; 0 otherwise) Return: pixd (4 bpp, optionally with colormap), or null on error
Notes: (1) Valid values for nlevels is the set {2, ... 16}. (2) Any colormap on the input pixs is removed to 8 bpp grayscale. (3) This function is typically invoked with cmapflag == 1. In the situation where no colormap is desired, nlevels is ignored and pixs is thresholded to 16 levels. (4) The target output colors are equally spaced, with the darkest at 0 and the lightest at 255. The thresholds are chosen halfway between adjacent output values. A table is built that specifies the mapping from src to dest. (5) If cmapflag == 1, a colormap of size 'nlevels' is made, and the pixel values in pixs are replaced by their appropriate color indices. The number of holdouts, 16 - nlevels, will be between 0 and 14. (6) If you don't want the thresholding to be equally spaced, either first transform the 8 bpp src using pixGammaTRC(). or, if cmapflag == 1, after calling this function you can use pixcmapResetColor() to change any individual colors. (7) If a colormap is generated, it will specify, to display programs, exactly how each level is to be represented in RGB space. When representing text, 3 levels is far better than 2 because of the antialiasing of the single gray level, and 4 levels (black, white and 2 gray levels) is getting close to the perceptual quality of a (nearly continuous) grayscale image. Therefore, with 4 bpp, you can set up a colormap, allocate a relatively small fraction of the 16 possible values to represent antialiased text, and use the other colormap entries for other things, such as coloring text or background. Two other reasons for using a small number of gray values for antialiased text are (1) PNG compression gets worse as the number of levels that are used is increased, and (2) using a small number of levels will filter out most of the jpeg ringing that is typically introduced near sharp edges of text. This filtering is partly responsible for the improved compression.
LEPT_DLL PIX* pixThresholdToBinary | ( | PIX * | pixs, |
l_int32 | thresh | ||
) |
Input: pixs (4 or 8 bpp) threshold value Return: pixd (1 bpp), or null on error
Notes: (1) If the source pixel is less than the threshold value, the dest will be 1; otherwise, it will be 0
Input: pixd (<optional>; if not null, must be equal to pixs) pixs (8, 16, 32 bpp) threshval setval Return: pixd always
Notes:
LEPT_DLL PIXTILING* pixTilingCreate | ( | PIX * | pixs, |
l_int32 | nx, | ||
l_int32 | ny, | ||
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | xoverlap, | ||
l_int32 | yoverlap | ||
) |
Input: pixs (pix to be tiled; any depth; colormap OK) nx (number of tiles across image) ny (number of tiles down image) w (desired width of each tile) h (desired height of each tile) overlap (amount of overlap into neighboring tile on each side) Return: pixtiling, or null on error
Notes: (1) We put a clone of pixs in the PixTiling. (2) The input to pixTilingCreate() for horizontal tiling can be either the number of tiles across the image or the approximate width of the tiles. If the latter, the actual width will be determined by making all tiles but the last of equal width, and making the last as close to the others as possible. The same consideration is applied independently to the vertical tiling. To specify tile width, set nx = 0; to specify the number of tiles horizontally across the image, set w = 0. (3) If pixs is to be tiled in one-dimensional strips, use ny = 1 for vertical strips and nx = 1 for horizontal strips. (4) The overlap must not be larger than the width or height of the leftmost or topmost tile(s).
LEPT_DLL void pixTilingDestroy | ( | PIXTILING ** | ppt | ) |
Input: &pt (<will be="" set="" to="" null="" before="" returning>="">) Return: void
Input: pt (pixtiling) &nx (<optional return>=""> nx; can be null) &ny (<optional return>=""> ny; can be null) Return: 0 if OK, 1 on error
Input: pt (pixtiling) &w (<optional return>=""> tile width; can be null) &h (<optional return>=""> tile height; can be null) Return: 0 if OK, 1 on error
Input: pt (pixtiling) i (tile row index) j (tile column index) Return: pixd (tile with appropriate boundary (overlap) pixels added), or null on error
Input: pt (pixtiling) Return: 0 if OK, 1 on error
Notes: (1) The default for paint is to strip out the overlap pixels that are added by pixTilingGetTile(). However, some operations will generate an image with these pixels stripped off. This tells the paint operation not to strip the added boundary pixels when painting.
LEPT_DLL l_int32 pixTilingPaintTile | ( | PIX * | pixd, |
l_int32 | i, | ||
l_int32 | j, | ||
PIX * | pixs, | ||
PIXTILING * | pt | ||
) |
Input: pixd (dest: paint tile onto this, without overlap) i (tile row index) j (tile column index) pixs (source: tile to be painted from) pt (pixtiling struct) Return: 0 if OK, 1 on error
Input: pixs hsize (of Sel; must be odd; origin implicitly in center) vsize (ditto) type (L_TOPHAT_WHITE: image - opening L_TOPHAT_BLACK: closing - image) Return: pixd, or null on error
Notes: (1) Sel is a brick with all elements being hits (2) If hsize = vsize = 1, returns an image with all 0 data. (3) The L_TOPHAT_WHITE flag emphasizes small bright regions, whereas the L_TOPHAT_BLACK flag emphasizes small dark regions. The L_TOPHAT_WHITE tophat can be accomplished by doing a L_TOPHAT_BLACK tophat on the inverse, or v.v.
LEPT_DLL l_int32 pixTransferAllData | ( | PIX * | pixd, |
PIX ** | ppixs, | ||
l_int32 | copytext, | ||
l_int32 | copyformat | ||
) |
Input: pixd (must be different from pixs) &pixs (will be nulled if refcount goes to 0) copytext (1 to copy the text field; 0 to skip) copyformat (1 to copy the informat field; 0 to skip) Return: 0 if OK, 1 on error
Notes: (1) This does a complete data transfer from pixs to pixd, followed by the destruction of pixs (refcount permitting). (2) If the refcount of pixs is 1, pixs is destroyed. Otherwise, the data in pixs is copied (rather than transferred) to pixd. (3) This operation, like all others with a pre-existing pixd, will side-effect any existing clones of pixd. The pixd refcount does not change. (4) When might you use this? Suppose you have an in-place Pix function (returning void) with the typical signature: void function-inplace(PIX *pix, ...) where "..." are non-pointer input parameters, and suppose further that you sometimes want to return an arbitrary Pix in place of the input Pix. There are two ways you can do this: (a) The straightforward way is to change the function signature to take the address of the Pix ptr: void function-inplace(PIX **ppix, ...) { PIX *pixt = function-makenew(*ppix); pixDestroy(ppix); *ppix = pixt; return; } Here, the input and returned pix are different, as viewed by the calling function, and the inplace function is expected to destroy the input pix to avoid a memory leak. (b) Keep the signature the same and use pixTransferAllData() to return the new Pix in the input Pix struct: void function-inplace(PIX *pix, ...) { PIX *pixt = function-makenew(pix); pixTransferAllData(pix, &pixt, 0, 0); // pixDestroy() is called on pixt return; } Here, the input and returned pix are the same, as viewed by the calling function, and the inplace function must never destroy the input pix, because the calling function maintains an unchanged handle to it.
LEPT_DLL PIX* pixTranslate | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_int32 | hshift, | ||
l_int32 | vshift, | ||
l_int32 | incolor | ||
) |
Input: pixd (<optional> destination: this can be null, equal to pixs, or different from pixs) pixs hshift (horizontal shift; hshift > 0 is to right) vshift (vertical shift; vshift > 0 is down) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK) Return: pixd, or null on error.
Notes: (1) The general pattern is: pixd = pixTranslate(pixd, pixs, ...); For clarity, when you know the case, use one of these: pixd = pixTranslate(NULL, pixs, ...); // new pixTranslate(pixs, pixs, ...); // in-place pixTranslate(pixd, pixs, ...); // to existing pixd (2) If an existing pixd is not the same size as pixs, the image data will be reallocated.
Input: pixs (8 grayscale or 32 bpp rgb; not colormapped) pixm (<optional> 1 bpp mask) na (mapping array) Return: pixd, or null on error
Notes: (1) This operation is in-place on pixs. (2) For 32 bpp, this applies the same map to each of the r,g,b components. (3) The mapping array is of size 256, and it maps the input index into values in the range [0, 255]. (4) If defined, the optional 1 bpp mask pixm has its origin aligned with pixs, and the map function is applied only to pixels in pixs under the fg of pixm. (5) For 32 bpp, this does not save the alpha channel.
LEPT_DLL PIX* pixTwoSidedEdgeFilter | ( | PIX * | pixs, |
l_int32 | orientflag | ||
) |
Input: pixs (8 bpp; no colormap) orientflag (L_HORIZONTAL_EDGES, L_VERTICAL_EDGES) Return: pixd (8 bpp, edges are brighter), or null on error
Notes: (1) For detecting vertical edges, this considers the difference of the central pixel from those on the left and right. For situations where the gradient is the same sign on both sides, this computes and stores the minimum (absolute value of the) difference. The reason for checking the sign is that we are looking for pixels within a transition. By contrast, for single pixel noise, the pixel value is either larger than or smaller than its neighbors, so the gradient would change direction on each side. Horizontal edges are handled similarly, looking for vertical gradients. (2) To generate a binary image of the edges, threshold the result using pixThresholdToBinary(). If the high edge values are to be fg (1), invert after running pixThresholdToBinary(). (3) This runs at about 60 Mpix/sec on a 3 GHz processor. It is about 30% faster than Sobel, and the results are similar.
Input: pixs (1 bpp) depth (of destination: 2, 4, 8, 16 or 32 bpp) invert (0: binary 0 --> grayscale 0 binary 1 --> grayscale 0xff... 1: binary 0 --> grayscale 0xff... binary 1 --> grayscale 0) Return: pixd (2, 4, 8, 16 or 32 bpp), or null on error
Notes: (1) This function calls special cases of pixConvert1To*(), for 2, 4, 8, 16 and 32 bpp destinations.
Input: pixs (all depths except 1 bpp; with or without colormaps) halfwidth ("half-width" of smoothing filter) fract (fraction of edge added back into image) Return: pixd, or null on error
Notes: (1) We use symmetric smoothing filters of odd dimension, typically use sizes of 3, 5, 7, etc. The parameter for these is (size - 1)/2; i.e., 1, 2, 3, etc. (2) The fract parameter is typically taken in the range: 0.2 < fract < 0.7 (3) Returns a clone if no sharpening is requested.
LEPT_DLL PIX* pixUnsharpMaskingFast | ( | PIX * | pixs, |
l_int32 | halfwidth, | ||
l_float32 | fract, | ||
l_int32 | direction | ||
) |
Input: pixs (all depths except 1 bpp; with or without colormaps) halfwidth ("half-width" of smoothing filter; 1 and 2 only) fract (fraction of high frequency added to image) direction (L_HORIZ, L_VERT, L_BOTH_DIRECTIONS) Return: pixd, or null on error
Notes: (1) The fast version uses separable 1-D filters directly on the input image. The halfwidth is either 1 (full width = 3) or 2 (full width = 5). (2) The fract parameter is typically taken in the range: 0.2 < fract < 0.7 (3) To skip horizontal sharpening, use = 0.0; ditto for (4) For one dimensional filtering (as an example): For = 1, the low-pass filter is L: 1/3 1/3 1/3 and the high-pass filter is H = I - L: -1/3 2/3 -1/3 For = 2, the low-pass filter is L: 1/5 1/5 1/5 1/5 1/5 and the high-pass filter is H = I - L: -1/5 -1/5 4/5 -1/5 -1/5 The new sharpened pixel value is found by adding some fraction of the high-pass filter value (which sums to 0) to the initial pixel value: N = I + fract * H (5) For 2D, the sharpening filter is not separable, because the vertical filter depends on the horizontal location relative to the filter origin, and v.v. So we either do the full 2D filter (for == 1) or do the low-pass convolution separably and then compose with the original pix. (6) Returns a clone if no sharpening is requested.
Input: pixs (8 bpp; no colormap) halfwidth ("half-width" of smoothing filter) fract (fraction of edge added back into image) Return: pixd, or null on error
Notes: (1) We use symmetric smoothing filters of odd dimension, typically use sizes of 3, 5, 7, etc. The parameter for these is (size - 1)/2; i.e., 1, 2, 3, etc. (2) The fract parameter is typically taken in the range: 0.2 < fract < 0.7 (3) Returns a clone if no sharpening is requested.
LEPT_DLL PIX* pixUnsharpMaskingGray1D | ( | PIX * | pixs, |
l_int32 | halfwidth, | ||
l_float32 | fract, | ||
l_int32 | direction | ||
) |
Input: pixs (8 bpp; no colormap) halfwidth ("half-width" of smoothing filter: 1 or 2) fract (fraction of high frequency added to image) direction (of filtering; use L_HORIZ or L_VERT) Return: pixd, or null on error
Notes: (1) For usage and explanation of the algorithm, see notes in pixUnsharpMaskingFast(). (2) Returns a clone if no sharpening is requested.
Input: pixs (8 bpp; no colormap) halfwidth ("half-width" of smoothing filter: 1 or 2) fract (fraction of high frequency added to image) Return: pixd, or null on error
Notes: (1) For halfwidth == 1, we implement the full sharpening filter directly. For halfwidth == 2, we implement the the lowpass filter separably and then compute the sharpening result locally. (2) Returns a clone if no sharpening is requested.
LEPT_DLL PIX* pixUnsharpMaskingGrayFast | ( | PIX * | pixs, |
l_int32 | halfwidth, | ||
l_float32 | fract, | ||
l_int32 | direction | ||
) |
Input: pixs (8 bpp; no colormap) halfwidth ("half-width" of smoothing filter: 1 or 2) fract (fraction of high frequency added to image) direction (L_HORIZ, L_VERT, L_BOTH_DIRECTIONS) Return: pixd, or null on error
Notes: (1) For usage and explanation of the algorithm, see notes in pixUnsharpMaskingFast(). (2) Returns a clone if no sharpening is requested.
Input: pixs (1 bpp, deskewed, English text, 150 - 300 ppi) &conf (<return> confidence that text is rightside-up) mincount (min number of up + down; use 0 for default) debug (1 for debug output; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) Special (typical, slightly faster) case, where the pixels identified through the HMT (hit-miss transform) are not clipped by a truncated word mask pixm. See pixOrientDetect() and pixUpDownDetectGeneral() for details. (2) The returned confidence is the normalized difference between the number of detected up and down ascenders, assuming that the text is either rightside-up or upside-down and not rotated at a 90 degree angle.
LEPT_DLL l_int32 pixUpDownDetectDwa | ( | PIX * | pixs, |
l_float32 * | pconf, | ||
l_int32 | mincount, | ||
l_int32 | debug | ||
) |
Input: pixs (1 bpp, deskewed, English text, 150 - 300 ppi) &conf (<return> confidence that text is rightside-up) mincount (min number of up + down; use 0 for default) debug (1 for debug output; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) Faster (DWA) version of pixUpDownDetect(). (2) This is a special case (but typical and slightly faster) of pixUpDownDetectGeneralDwa(), where the pixels identified through the HMT (hit-miss transform) are not clipped by a truncated word mask pixm. See pixUpDownDetectGeneral() for usage and other details. (3) The returned confidence is the normalized difference between the number of detected up and down ascenders, assuming that the text is either rightside-up or upside-down and not rotated at a 90 degree angle.
LEPT_DLL l_int32 pixUpDownDetectGeneral | ( | PIX * | pixs, |
l_float32 * | pconf, | ||
l_int32 | mincount, | ||
l_int32 | npixels, | ||
l_int32 | debug | ||
) |
Input: pixs (1 bpp, deskewed, English text, 150 - 300 ppi) &conf (<return> confidence that text is rightside-up) mincount (min number of up + down; use 0 for default) npixels (number of pixels removed from each side of word box) debug (1 for debug output; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) See pixOrientDetect() for other details. (2) is the normalized difference between the number of detected up and down ascenders, assuming that the text is either rightside-up or upside-down and not rotated at a 90 degree angle. (3) The typical mode of operation is == 0. If > 0, this removes HMT matches at the beginning and ending of "words." This is useful for pages that may have mostly digits, because if npixels == 0, leading "1" and "3" digits can register as having ascenders or descenders, and "7" digits can match descenders. Consequently, a page image of only digits may register as being upside-down. (4) We want to count the number of instances found using the HMT. An expensive way to do this would be to count the number of connected components. A cheap way is to do a rank reduction cascade that reduces each component to a single pixel, and results (after two or three 2x reductions) in one pixel for each of the original components. After the reduction, you have a much smaller pix over which to count pixels. We do only 2 reductions, because this function is designed to work for input pix between 150 and 300 ppi, and an 8x reduction on a 150 ppi image is going too far -- components will get merged.
LEPT_DLL l_int32 pixUpDownDetectGeneralDwa | ( | PIX * | pixs, |
l_float32 * | pconf, | ||
l_int32 | mincount, | ||
l_int32 | npixels, | ||
l_int32 | debug | ||
) |
Input: pixs (1 bpp, deskewed, English text) &conf (<return> confidence that text is rightside-up) mincount (min number of up + down; use 0 for default) npixels (number of pixels removed from each side of word box) debug (1 for debug output; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) See the notes in pixUpDownDetectGeneral() for usage.
LEPT_DLL l_int32 pixUsesCmapColor | ( | PIX * | pixs, |
l_int32 * | pcolor | ||
) |
Input: pixs &color (<return>) Return: 0 if OK, 1 on error
Notes: (1) This returns color = TRUE if three things are obtained: (a) the pix has a colormap (b) the colormap has at least one color entry (c) a color entry is actually used (2) It is used in pixEqual() for comparing two images, in a situation where it is required to know if the colormap has color entries that are actually used in the image.
LEPT_DLL l_int32 pixVarianceInRectangle | ( | PIX * | pixs, |
BOX * | box, | ||
PIX * | pix_ma, | ||
DPIX * | dpix_msa, | ||
l_float32 * | pvar, | ||
l_float32 * | prvar | ||
) |
Input: pix (8 bpp) box (region to compute variance and/or root variance) pix_ma (mean accumulator) dpix_msa (mean square accumulator) &var (<optional return>=""> variance) &rvar (<optional return>=""> root variance) Return: 0 if OK, 1 on error
Notes: (1) This function is intended to be used for many rectangles on the same image. It can find the variance and/or the square root of the variance within a rectangle in O(1), independent of the size of the rectangle.
LEPT_DLL PIX* pixVarThresholdToBinary | ( | PIX * | pixs, |
PIX * | pixg | ||
) |
Input: pixs (8 bpp) pixg (8 bpp; contains threshold values for each pixel) Return: pixd (1 bpp), or null on error
Notes: (1) If the pixel in pixs is less than the corresponding pixel in pixg, the dest will be 1; otherwise it will be 0.
LEPT_DLL PIX* pixVShear | ( | PIX * | pixd, |
PIX * | pixs, | ||
l_int32 | linex, | ||
l_float32 | radang, | ||
l_int32 | incolor | ||
) |
Input: pixd (<optional>, this can be null, equal to pixs, or different from pixs) pixs (no restrictions on depth) linex (location of vertical line, measured from origin) angle (in radians; not too close to +-(pi / 2)) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK); Return: pixd, or null on error
Notes: (1) There are 3 cases: (a) pixd == null (make a new pixd) (b) pixd == pixs (in-place) (c) pixd != pixs (2) For these three cases, use these patterns, respectively: pixd = pixVShear(NULL, pixs, ...); pixVShear(pixs, pixs, ...); pixVShear(pixd, pixs, ...); (3) This shear leaves the vertical line of pixels at x = linex invariant. For a positive shear angle, pixels to the right of this line are shoved downward, and pixels to the left of the line move upward. (4) With positive shear angle, this can be used, along with pixHShear(), to perform a cw rotation, either with 2 shears (for small angles) or in the general case with 3 shears. (5) Changing the value of linex is equivalent to translating the result vertically. (6) This brings in 'incolor' pixels from outside the image. (7) For in-place operation, pixs cannot be colormapped, because the in-place operation only blits in 0 or 1 bits, not an arbitrary colormap index. (8) The angle is brought into the range [-pi, -pi]. It is not permitted to be within MIN_DIFF_FROM_HALF_PI radians from either -pi/2 or pi/2.
Input: pixd (<optional>, if not null, must be equal to pixs) pixs angle (in radians) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK); Return: pixd, or null on error.
Notes: (1) See pixVShear() for usage. (2) This does a vertical shear about the center, with (+) shear pushing increasingly downward (+y) with increasing x.
Input: pixd (<optional>, if not null, must be equal to pixs) pixs angle (in radians) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK); Return: pixd, or null on error.
Notes: (1) See pixVShear() for usage. (2) This does a vertical shear about the UL corner, with (+) shear pushing increasingly downward (+y) with increasing x.
Input: pixs (all depths; not colormapped) linex (location of vertical line, measured from origin) angle (in radians) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK); Return: 0 if OK; 1 on error
Notes: (1) This is an in-place version of pixVShear(); see comments there. (2) This brings in 'incolor' pixels from outside the image. (3) pixs cannot be colormapped, because the in-place operation only blits in 0 or 1 bits, not an arbitrary colormap index. (4) Does a vertical full-band shear about the line with (+) shear pushing increasingly downward (+y) with increasing x.
Input: pixs (8 bpp or 32 bpp, or colormapped) linex (location of vertical line, measured from origin) angle (in radians, in range (-pi/2 ... pi/2)) incolor (L_BRING_IN_WHITE, L_BRING_IN_BLACK); Return: pixd (sheared), or null on error
Notes: (1) This does vertical shear with linear interpolation for accurate results on 8 bpp gray, 32 bpp rgb, or cmapped images. It is relatively slow compared to the sampled version implemented by rasterop, but the result is much smoother. (2) This shear leaves the vertical line of pixels at x = linex invariant. For a positive shear angle, pixels to the right of this line are shoved downward, and pixels to the left of the line move upward. (3) Any colormap is removed. (4) The angle is brought into the range [-pi/2 + del, pi/2 - del], where del == MIN_DIFF_FROM_HALF_PI.
LEPT_DLL PIX* pixWarpStereoscopic | ( | PIX * | pixs, |
l_int32 | zbend, | ||
l_int32 | zshiftt, | ||
l_int32 | zshiftb, | ||
l_int32 | ybendt, | ||
l_int32 | ybendb, | ||
l_int32 | redleft | ||
) |
Input: pixs (any depth, colormap ok) zbend (horizontal separation in pixels of red and cyan at the left and right sides, that gives rise to quadratic curvature out of the image plane) zshiftt (uniform pixel translation difference between red and cyan, that pushes the top of the image plane away from the viewer (zshiftt > 0) or towards the viewer (zshiftt < 0)) zshiftb (uniform pixel translation difference between red and cyan, that pushes the bottom of the image plane away from the viewer (zshiftb > 0) or towards the viewer (zshiftb < 0)) ybendt (multiplicative parameter for in-plane vertical displacement at the left or right edge at the top: y = ybendt * (2x/w - 1)^2 ) ybendb (same as ybendt, except at the left or right edge at the bottom) redleft (1 if the red filter is on the left; 0 otherwise) Return: pixd (32 bpp), or null on error
Notes: (1) This function splits out the red channel, mucks around with it, then recombines with the unmolested cyan channel. (2) By using a quadratically increasing shift of the red pixels horizontally and away from the vertical centerline, the image appears to bend quadratically out of the image plane, symmetrically with respect to the vertical center line. A positive value of causes the plane to be curved away from the viewer. We use linearly interpolated stretching to avoid the appearance of kinks in the curve. (3) The parameters and tilt the image plane about a horizontal line through the center, and at the same time move that line either in toward the viewer or away. This is implemented by a combination of horizontal shear about the center line (for the tilt) and horizontal translation (to move the entire plane in or out). A positive value of moves the top of the plane away from the viewer, and a positive value of moves the bottom of the plane away. We use linear interpolated shear to avoid visible vertical steps in the tilted image. (4) The image can be bent in the plane and about the vertical centerline. The centerline does not shift, and the parameter gives the relative shift at left and right edges, with a downward shift for positive values of . (6) When writing out a steroscopic (red/cyan) image in jpeg, first call l_jpegSetNoChromaSampling() to get sufficient resolution in the red channel. (7) Typical values are: zbend = 20 zshiftt = 15 zshiftb = -15 ybendt = 30 ybendb = 0 If the disparity z-values are too large, it is difficult for the brain to register the two images. (8) This function has been cleverly reimplemented by Jeff Breidenbach. The original implementation used two 32 bpp rgb images, and merged them at the end. The result is somewhat faded, and has a parameter "thresh" that controls the amount of color in the result. (The present implementation avoids these two problems, skipping both the colorization and the alpha blending at the end, and is about 3x faster) The basic operations with 32 bpp are as follows: // Immediate conversion to 32 bpp Pix *pixt1 = pixConvertTo32(pixs); // Do vertical shear Pix *pixr = pixQuadraticVerticalShear(pixt1, L_WARP_TO_RIGHT, ybendt, ybendb, L_BRING_IN_WHITE); // Colorize two versions, toward red and cyan Pix *pixc = pixCopy(NULL, pixr); l_int32 thresh = 150; // if higher, get less original color pixColorGray(pixr, NULL, L_PAINT_DARK, thresh, 255, 0, 0); pixColorGray(pixc, NULL, L_PAINT_DARK, thresh, 0, 255, 255); // Shift the red pixels; e.g., by stretching Pix *pixrs = pixStretchHorizontal(pixr, L_WARP_TO_RIGHT, L_QUADRATIC_WARP, zbend, L_INTERPOLATED, L_BRING_IN_WHITE); // Blend the shifted red and unshifted cyan 50:50 Pix *pixg = pixCreate(w, h, 8); pixSetAllArbitrary(pixg, 128); pixd = pixBlendWithGrayMask(pixrs, pixc, pixg, 0, 0);
LEPT_DLL PIX* pixWindowedMean | ( | PIX * | pixs, |
l_int32 | wc, | ||
l_int32 | hc, | ||
l_int32 | hasborder, | ||
l_int32 | normflag | ||
) |
Input: pixs (8 or 32 bpp grayscale) wc, hc (half width/height of convolution kernel) hasborder (use 1 if it already has (wc + 1) border pixels on left and right, and (hc + 1) on top and bottom; use 0 to add kernel-dependent border) normflag (1 for normalization to get average in window; 0 for the sum in the window (un-normalized)) Return: pixd (8 or 32 bpp, average over kernel window)
Notes: (1) The input and output depths are the same. (2) A set of border pixels of width (wc + 1) on left and right, and of height (hc + 1) on top and bottom, must be on the pix before the accumulator is found. The output pixd (after convolution) has this border removed. If = 0, the required border is added. (3) Typically, == 1. However, if you want the sum within the window, rather than a normalized convolution, use == 0. (4) This builds a block accumulator pix, uses it here, and destroys it. (5) The added border, along with the use of an accumulator array, allows computation without special treatment of pixels near the image boundary, and runs in a time that is independent of the size of the convolution kernel.
Input: pixs (8 bpp grayscale) wc, hc (half width/height of convolution kernel) hasborder (use 1 if it already has (wc + 1) border pixels on left and right, and (hc + 1) on top and bottom; use 0 to add kernel-dependent border) Return: pixd (32 bpp, average over rectangular window of width = 2 * wc + 1 and height = 2 * hc + 1)
Notes: (1) A set of border pixels of width (wc + 1) on left and right, and of height (hc + 1) on top and bottom, must be on the pix before the accumulator is found. The output pixd (after convolution) has this border removed. If = 0, the required border is added. (2) The advantage is that we are unaffected by the boundary, and it is not necessary to treat pixels within and of the border differently. This is because processing for pixd only takes place for pixels in pixs for which the kernel is entirely contained in pixs. (3) Why do we have an added border of width ( + 1) and height ( + 1), when we only need and pixels to satisfy this condition? Answer: the accumulators are asymmetric, requiring an extra row and column of pixels at top and left to work accurately. (4) The added border, along with the use of an accumulator array, allows computation without special treatment of pixels near the image boundary, and runs in a time that is independent of the size of the convolution kernel.
LEPT_DLL l_int32 pixWindowedStats | ( | PIX * | pixs, |
l_int32 | wc, | ||
l_int32 | hc, | ||
l_int32 | hasborder, | ||
PIX ** | ppixm, | ||
PIX ** | ppixms, | ||
FPIX ** | pfpixv, | ||
FPIX ** | pfpixrv | ||
) |
Input: pixs (8 bpp grayscale) wc, hc (half width/height of convolution kernel) hasborder (use 1 if it already has (wc + 1) border pixels on left and right, and (hc + 1) on top and bottom; use 0 to add kernel-dependent border) &pixm (<optional return>=""> 8 bpp mean value in window) &pixms (<optional return>=""> 32 bpp mean square value in window) &fpixv (<optional return>=""> float variance in window) &fpixrv (<optional return>=""> float rms deviation from the mean) Return: 0 if OK, 1 on error
Notes: (1) This is a high-level convenience function for calculating any or all of these derived images. (2) If = 0, a border is added and the result is computed over all pixels in pixs. Otherwise, no border is added and the border pixels are removed from the output images. (3) These statistical measures over the pixels in the rectangular window are:
(pixm)
)*(p -
)> = <p*p> -
*
(pixv)
Input: pixm (mean over window; 8 or 32 bpp grayscale) pixms (mean square over window; 32 bpp) &fpixv (<optional return>=""> float variance -- the ms deviation from the mean) &fpixrv (<optional return>=""> float rms deviation from the mean) Return: 0 if OK, 1 on error
Notes: (1) The mean and mean square values are precomputed, using pixWindowedMean() and pixWindowedMeanSquare(). (2) Either or both of the variance and square-root of variance are returned as an fpix, where the variance is the average over the window of the mean square difference of the pixel value from the mean: <(p -
)*(p -
)> = <p*p> -
*
(3) To visualize the results:
Input: pixs (1 bpp; typ. at 75 to 150 ppi) maxsize (use 0 for default; not to exceed 14) &size (<optional return>=""> size of optimal horiz Sel) Return: pixd (dilated word mask), or null on error
Notes: (1) For 75 to 150 ppi, the optimal dilation should not exceed 7. This is the default size chosen if maxsize <= 0. (2) To run this on images at resolution between 200 and 300, it is advisable to use a larger maxsize, say between 10 and 14. (3) The best size for dilating to get word masks is optionally returned.
Input: filename pix format (defined in imageio.h) Return: 0 if OK; 1 on error
Notes: (1) Open for write using binary mode (with the "b" flag) to avoid having Windows automatically translate the NL into CRLF, which corrupts image files. On non-windows systems this flag should be ignored, per ISO C90. Thanks to Dave Bryan for pointing this out. (2) If the default image format is requested, we use the input format; if the input format is unknown, a lossless format is assigned. (3) There are two modes with respect to file naming. (a) The default code writes to . (b) If WRITE_AS_NAMED is defined to 0, it's a bit fancier. Then, if does not have a file extension, one is automatically appended, depending on the requested format. The original intent for providing option (b) was to insure that filenames on Windows have an extension that matches the image compression. However, this is not the default.
LEPT_DLL l_int32 pixWriteImpliedFormat | ( | const char * | filename, |
PIX * | pix, | ||
l_int32 | quality, | ||
l_int32 | progressive | ||
) |
Input: filename pix quality (iff JPEG; 1 - 100, 0 for default) progressive (iff JPEG; 0 for baseline seq., 1 for progressive) Return: 0 if OK; 1 on error
Notes: (1) This determines the output format from the filename extension. (2) The last two args are ignored except for requests for jpeg files. (3) The jpeg default quality is 75.
LEPT_DLL l_int32 pixWriteJpeg | ( | const char * | filename, |
PIX * | pix, | ||
l_int32 | quality, | ||
l_int32 | progressive | ||
) |
Input: filename pix quality (1 - 100; 75 is default) progressive (0 for baseline sequential; 1 for progressive) Return: 0 if OK; 1 on error
Input: &data (<return> data of tiff compressed image) &size (<return> size of returned data) pix format (defined in imageio.h) Return: 0 if OK, 1 on error
Notes: (1) On windows, this will only write tiff and PostScript to memory. For other formats, it requires open_memstream(3). (2) PostScript output is uncompressed, in hex ascii. Most printers support level 2 compression (tiff_g4 for 1 bpp, jpeg for 8 and 32 bpp).
LEPT_DLL l_int32 pixWriteMemBmp | ( | l_uint8 ** | pdata, |
size_t * | psize, | ||
PIX * | pix | ||
) |
LEPT_DLL l_int32 pixWriteMemGif | ( | l_uint8 ** | pdata, |
size_t * | psize, | ||
PIX * | pix | ||
) |
LEPT_DLL l_int32 pixWriteMemJpeg | ( | l_uint8 ** | pdata, |
size_t * | psize, | ||
PIX * | pix, | ||
l_int32 | quality, | ||
l_int32 | progressive | ||
) |
Input: &data (<return> data of jpeg compressed image) &size (<return> size of returned data) pix quality (1 - 100; 75 is default value; 0 is also default) progressive (0 for baseline sequential; 1 for progressive) Return: 0 if OK, 1 on error
Notes: (1) We are cheating here -- writing the data out to file in jpeg format and then reading it back.
LEPT_DLL l_int32 pixWriteMemPnm | ( | l_uint8 ** | pdata, |
size_t * | psize, | ||
PIX * | pix | ||
) |
LEPT_DLL l_int32 pixWriteMemPS | ( | l_uint8 ** | pdata, |
size_t * | psize, | ||
PIX * | pix, | ||
BOX * | box, | ||
l_int32 | res, | ||
l_float32 | scale | ||
) |
Input: &data (<return> data of tiff compressed image) &size (<return> size of returned data) pix box (<optional>) res (can use 0 for default of 300 ppi) scale (to prevent scaling, use either 1.0 or 0.0) Return: 0 if OK, 1 on error
Notes: (1) See pixWriteStringPS() for usage. (2) This is just a wrapper for pixWriteStringPS(), which writes uncompressed image data to memory.
LEPT_DLL l_int32 pixWriteMemSpix | ( | l_uint8 ** | pdata, |
size_t * | psize, | ||
PIX * | pix | ||
) |
Input: &data (<return> data of serialized, uncompressed pix) &size (<return> size of returned data) pix (all depths; colormap OK) Return: 0 if OK, 1 on error
Input: &data (<return> data of tiff compressed image) &size (<return> size of returned data) pix comptype (IFF_TIFF, IFF_TIFF_RLE, IFF_TIFF_PACKBITS, IFF_TIFF_G3, IFF_TIFF_G4, IFF_TIFF_LZW, IFF_TIFF_ZIP) Return: 0 if OK, 1 on error
Usage: (1) See pixWriteTiff(). This version writes to memory instead of to a file.
LEPT_DLL l_int32 pixWriteMemTiffCustom | ( | l_uint8 ** | pdata, |
size_t * | psize, | ||
PIX * | pix, | ||
l_int32 | comptype, | ||
NUMA * | natags, | ||
SARRAY * | savals, | ||
SARRAY * | satypes, | ||
NUMA * | nasizes | ||
) |
Input: &data (<return> data of tiff compressed image) &size (<return> size of returned data) pix comptype (IFF_TIFF, IFF_TIFF_RLE, IFF_TIFF_PACKBITS, IFF_TIFF_G3, IFF_TIFF_G4, IFF_TIFF_LZW, IFF_TIFF_ZIP) natags (<optional> NUMA of custom tiff tags) savals (<optional> SARRAY of values) satypes (<optional> SARRAY of types) nasizes (<optional> NUMA of sizes) Return: 0 if OK, 1 on error
Usage: (1) See pixWriteTiffCustom(). This version writes to memory instead of to a file. (2) Use TIFFClose(); TIFFCleanup() doesn't free internal memstream.
LEPT_DLL l_int32 pixWriteMixedToPS | ( | PIX * | pixb, |
PIX * | pixc, | ||
l_float32 | scale, | ||
l_int32 | pageno, | ||
const char * | fileout | ||
) |
LEPT_DLL l_int32 pixWritePng | ( | const char * | filename, |
PIX * | pix, | ||
l_float32 | gamma | ||
) |
Input: filename pix gamma Return: 0 if OK; 1 on error
Notes: (1) Special version for writing png with a specified gamma. When using pixWrite(), no field is given for gamma.
LEPT_DLL l_int32 pixWritePSEmbed | ( | const char * | filein, |
const char * | fileout | ||
) |
Input: filein (input file, all depths, colormap OK) fileout (output ps file) Return: 0 if OK, 1 on error
Notes: (1) This is a simple wrapper function that generates an uncompressed PS file, with a bounding box. (2) The bounding box is required when a program such as TeX (through epsf) places and rescales the image. (3) The bounding box is sized for fitting the image to an 8.5 x 11.0 inch page.
LEPT_DLL l_int32 pixWriteRGBAPng | ( | const char * | filename, |
PIX * | pix | ||
) |
Input: filename pix (rgba) Return: 0 if OK, 1 on error
Notes: (1) Wrapper to write the alpha sample of a 32 bpp pix to a png file in rgba format. (2) The default behavior of pix write to png is to ignore the alpha sample. (3) This always leaves alpha writing in the same mode as when this function begins. So if alpha writing is in default mode, this enables it, writes out a rgba png file that includes the alpha channel, and resets to default. Otherwise, it leaves alpha writing enabled.
LEPT_DLL l_int32 pixWriteSegmentedPageToPS | ( | PIX * | pixs, |
PIX * | pixm, | ||
l_float32 | textscale, | ||
l_float32 | imagescale, | ||
l_int32 | threshold, | ||
l_int32 | pageno, | ||
const char * | fileout | ||
) |
LEPT_DLL l_int32 pixWriteStream | ( | FILE * | fp, |
PIX * | pix, | ||
l_int32 | format | ||
) |
Input: stream pix format Return: 0 if OK; 1 on error.
LEPT_DLL l_int32 pixWriteStreamAsciiPnm | ( | FILE * | fp, |
PIX * | pix | ||
) |
Input: stream opened for write pix Return: 0 if OK; 1 on error
Writes "ascii" format only: 1 bpp --> pbm (P1) 2, 4, 8, 16 bpp, no colormap or grayscale colormap --> pgm (P2) 2, 4, 8 bpp with color-valued colormap, or rgb --> rgb ppm (P3)
LEPT_DLL l_int32 pixWriteStreamBmp | ( | FILE * | fp, |
PIX * | pix | ||
) |
Input: stream opened for write pix (1, 4, 8, 32 bpp) Return: 0 if OK, 1 on error
Notes: (1) We position fp at the beginning of the stream, so it truncates any existing data (2) 2 bpp Bmp files are apparently not valid!. We can write and read them, but nobody else can read ours.
LEPT_DLL l_int32 pixWriteStreamGif | ( | FILE * | fp, |
PIX * | pix | ||
) |
Input: stream pix (8 or 32 bpp) quality (1 - 100; 75 is default value; 0 is also default) progressive (0 for baseline sequential; 1 for progressive) Return: 0 if OK, 1 on error
Notes: (1) Under the covers, the library transforms rgb to a luminence-chromaticity triple, each component of which is also 8 bits, and compresses that. It uses 2 Huffman tables, a higher resolution one (with more quantization levels) for luminosity and a lower resolution one for the chromas. (2) Progressive encoding gives better compression, at the expense of slower encoding and decoding. (3) Standard chroma subsampling is 2x2 on both the U and V channels. For highest quality, use no subsampling. This option is set by l_jpegSetNoChromaSampling(1). (4) There are three possibilities: * Grayscale image, no colormap: compress as 8 bpp image. * rgb full color image: copy each line into the color line buffer, and compress as three 8 bpp images. * 8 bpp colormapped image: convert each line to three 8 bpp line images in the color line buffer, and compress as three 8 bpp images. (5) The only valid pixel depths in leptonica are 1, 2, 4, 8, 16 and 32 bpp. However, it is possible, and in some cases desirable, to write out a jpeg file using an rgb pix that has 24 bpp. This can be created by appending the raster data for a 24 bpp image (with proper scanline padding) directly to a 24 bpp pix that was created without a data array. See note in pixWriteStreamPng() for an example.
LEPT_DLL l_int32 pixWriteStreamPdf | ( | FILE * | fp, |
PIX * | pix, | ||
l_int32 | res, | ||
const char * | title | ||
) |
Input: fp (stream opened for writing) pix (all depths, cmap OK) res (override the resolution of the input image, in ppi; use 0 to respect the resolution embedded in the input) title (<optional> pdf title; taken from the first image placed on a page; e.g., an input image filename) Return: 0 if OK, 1 on error
Notes: (1) This is the simplest interface for writing a single image with pdf encoding. It uses G4 encoding for 1 bpp, JPEG encoding for 8 bpp (no cmap) and 32 bpp, and FLATE encoding for everything else.
LEPT_DLL l_int32 pixWriteStreamPng | ( | FILE * | fp, |
PIX * | pix, | ||
l_float32 | gamma | ||
) |
Input: stream pix gamma (use 0.0 if gamma is not defined) Return: 0 if OK; 1 on error
Notes: (1) If called from pixWriteStream(), the stream is positioned at the beginning of the file. (2) To do sequential writes of png format images to a stream, use pixWriteStreamPng() directly. (3) gamma is an optional png chunk. If no gamma value is to be placed into the file, use gamma = 0.0. Otherwise, if gamma > 0.0, its value is written into the header. (4) The use of gamma in png is highly problematic. For an illuminating discussion, see: http://hsivonen.iki.fi/png-gamma/ (5) What is the effect/meaning of gamma in the png file? This gamma, which we can call the 'source' gamma, is the inverse of the gamma that was used in enhance.c to brighten or darken images. The 'source' gamma is supposed to indicate the intensity mapping that was done at the time the image was captured. Display programs typically apply a 'display' gamma of 2.2 to the output, which is intended to linearize the intensity based on the response of thermionic tubes (CRTs). Flat panel LCDs have typically been designed to give a similar response as CRTs (call it "backward compatibility"). The 'display' gamma is in some sense the inverse of the 'source' gamma. jpeg encoders attached to scanners and cameras will lighten the pixels, applying a gamma corresponding to approximately a square-root relation of output vs input: output = input^(gamma) where gamma is often set near 0.4545 (1/gamma is 2.2). This is stored in the image file. Then if the display program reads the gamma, it will apply a display gamma, typically about 2.2; the product is 1.0, and the display program produces a linear output. This works because the dark colors were appropriately boosted by the scanner, as described by the 'source' gamma, so they should not be further boosted by the display program. (6) As an example, with xv and display, if no gamma is stored, the program acts as if gamma were 0.4545, multiplies this by 2.2, and does a linear rendering. Taking this as a baseline brightness, if the stored gamma is: > 0.4545, the image is rendered lighter than baseline < 0.4545, the image is rendered darker than baseline In contrast, gqview seems to ignore the gamma chunk in png. (7) The only valid pixel depths in leptonica are 1, 2, 4, 8, 16 and 32. However, it is possible, and in some cases desirable, to write out a png file using an rgb pix that has 24 bpp. For example, the open source xpdf SplashBitmap class generates 24 bpp rgb images. Consequently, we anble writing 24 bpp pix. To generate such a pix, you can make a 24 bpp pix without data and assign the data array to the pix; e.g., pix = pixCreateHeader(w, h, 24); pixSetData(pix, rgbdata); See pixConvert32To24() for an example, where we get rgbdata from the 32 bpp pix. Caution: do not call pixSetPadBits(), because the alignment is wrong and you may erase part of the last pixel on each line.
LEPT_DLL l_int32 pixWriteStreamPnm | ( | FILE * | fp, |
PIX * | pix | ||
) |
Input: stream opened for write pix Return: 0 if OK; 1 on error
Notes: (1) This writes "raw" packed format only: 1 bpp --> pbm (P4) 2, 4, 8, 16 bpp, no colormap or grayscale colormap --> pgm (P5) 2, 4, 8 bpp with color-valued colormap, or rgb --> rgb ppm (P6) (2) 24 bpp rgb are not supported in leptonica, but this will write them out as a packed array of bytes (3 to a pixel).
Input: stream pix box (<optional>) res (can use 0 for default of 300 ppi) scale (to prevent scaling, use either 1.0 or 0.0) Return: 0 if OK; 1 on error
Notes: (1) This writes image in PS format, optionally scaled, adjusted for the printer resolution, and with a bounding box. (2) For details on use of parameters, see pixWriteStringPS().
LEPT_DLL l_int32 pixWriteStreamSpix | ( | FILE * | fp, |
PIX * | pix | ||
) |
Input: stream pix Return: 0 if OK; 1 on error
LEPT_DLL l_int32 pixWriteStreamTiff | ( | FILE * | fp, |
PIX * | pix, | ||
l_int32 | comptype | ||
) |
Input: stream (opened for append or write) pix comptype (IFF_TIFF, IFF_TIFF_RLE, IFF_TIFF_PACKBITS, IFF_TIFF_G3, IFF_TIFF_G4, IFF_TIFF_LZW, IFF_TIFF_ZIP) Return: 0 if OK, 1 on error
Notes: (1) For images with bpp > 1, this resets the comptype, if necessary, to write uncompressed data. (2) G3 and G4 are only defined for 1 bpp. (3) We only allow PACKBITS for bpp = 1, because for bpp > 1 it typically expands images that are not synthetically generated. (4) G4 compression is typically about twice as good as G3. G4 is excellent for binary compression of text/line-art, but terrible for halftones and dithered patterns. (In fact, G4 on halftones can give a file that is larger than uncompressed!) If a binary image has dithered regions, it is usually better to compress with png.
LEPT_DLL l_int32 pixWriteStreamWebP | ( | FILE * | fp, |
PIX * | pixs, | ||
l_int32 | quality | ||
) |
Input: pixs: all depths, colormap OK box: (a) If box == null, image is placed, optionally scaled, in a standard b.b. at the center of the page. This is to be used when another program like TeX (through epsf) places the image. (b) If box != null, image is placed without a b.b. at the specified page location and with (optional) scaling. This is to be used when you want to specify exactly where (and optionally how big) you want the image to be. Note that all coordinates are in PS convention, with (0,0) at LL corner of the page: (x,y) location of LL corner of image, in mils. (w,h) scaled size, in mils. Use 0 to scale with "scale" and "res" input. res: resolution, in printer ppi. Use 0 for default (300 ppi). scale: scale factor. If no scaling is desired, use either 1.0 or 0.0. Scaling just resets the resolution parameter; the actual scaling is done in the interpreter at rendering time. This is important: it allows you to scale the image up without increasing the file size. Return: ps string if OK, or null on error
Notes: (1) OK, this seems a bit complicated, because there are various ways to scale and not to scale. Here's a summary: (2) If you don't want any scaling at all: * if you are using a box: set w = 0, h = 0, and use scale = 1.0; it will print each pixel unscaled at printer resolution * if you are not using a box: set scale = 1.0; it will print at printer resolution (3) If you want the image to be a certain size in inches: * you must use a box and set the box (w,h) in mils (4) If you want the image to be scaled by a scale factor != 1.0: * if you are using a box: set w = 0, h = 0, and use the desired scale factor; the higher the printer resolution, the smaller the image will actually appear. * if you are not using a box: set the desired scale factor; the higher the printer resolution, the smaller the image will actually appear. (5) Another complication is the proliferation of distance units: * The interface distances are in milli-inches. * Three different units are used internally:
LEPT_DLL l_int32 pixWriteTempfile | ( | const char * | dir, |
const char * | tail, | ||
PIX * | pix, | ||
l_int32 | format, | ||
char ** | pfilename | ||
) |
Input: dir (directory name; use '.' for local dir; no trailing '/') tail (<optional> tailname, including extension if any) pix format &filename (<optional> return actual filename used; use null to skip) Return: 0 if OK; 1 on error
Notes: (1) This generates a temp filename, writes the pix to it, and optionally returns the temp filename. (2) If the filename is returned to a windows program from a DLL, use lept_free() to free it. (3) See genTempFilename() for details. We omit the time and pid here.
LEPT_DLL l_int32 pixWriteTiff | ( | const char * | filename, |
PIX * | pix, | ||
l_int32 | comptype, | ||
const char * | modestring | ||
) |
Input: filename (to write to) pix comptype (IFF_TIFF, IFF_TIFF_RLE, IFF_TIFF_PACKBITS, IFF_TIFF_G3, IFF_TIFF_G4, IFF_TIFF_LZW, IFF_TIFF_ZIP) modestring ("a" or "w") Return: 0 if OK, 1 on error
Notes: (1) For multi-page tiff, write the first pix with mode "w" and all subsequent pix with mode "a".
LEPT_DLL l_int32 pixWriteTiffCustom | ( | const char * | filename, |
PIX * | pix, | ||
l_int32 | comptype, | ||
const char * | modestring, | ||
NUMA * | natags, | ||
SARRAY * | savals, | ||
SARRAY * | satypes, | ||
NUMA * | nasizes | ||
) |
Input: filename (to write to) pix comptype (IFF_TIFF, IFF_TIFF_RLE, IFF_TIFF_PACKBITS, IFF_TIFF_G3, IFF_TIFF_G4) IFF_TIFF_LZW, IFF_TIFF_ZIP) modestring ("a" or "w") natags (<optional> NUMA of custom tiff tags) savals (<optional> SARRAY of values) satypes (<optional> SARRAY of types) nasizes (<optional> NUMA of sizes) Return: 0 if OK, 1 on error
Usage: (1) This writes a page image to a tiff file, with optional extra tags defined in tiff.h (2) For multi-page tiff, write the first pix with mode "w" and all subsequent pix with mode "a". (3) For the custom tiff tags: (a) The three arrays {natags, savals, satypes} must all be either NULL or defined and of equal size. (b) If they are defined, the tags are an array of integers, the vals are an array of values in string format, and the types are an array of types in string format. (c) All valid tags are definined in tiff.h. (d) The types allowed are the set of strings: "char*" "l_uint8*" "l_uint16" "l_uint32" "l_int32" "l_float64" "l_uint16-l_uint16" (note the dash; use it between the two l_uint16 vals in the val string) Of these, "char*" and "l_uint16" are the most commonly used. (e) The last array, nasizes, is also optional. It is for tags that take an array of bytes for a value, a number of elements in the array, and a type that is either "char*" or "l_uint8*" (probably either will work). Use NULL if there are no such tags. (f) VERY IMPORTANT: if there are any tags that require the extra size value, stored in nasizes, they must be written first!
LEPT_DLL l_int32 pixWriteWebP | ( | const char * | filename, |
PIX * | pixs, | ||
l_int32 | quality | ||
) |
Input: pixd (<optional>; this can be null, equal to pixs1, different from pixs1) pixs1 (can be == pixd) pixs2 (must be != pixd) Return: pixd always
Notes: (1) This gives the XOR of two images with equal depth, aligning them to the the UL corner. pixs1 and pixs2 need not have the same width and height. (2) There are 3 cases: (a) pixd == null, (src1 ^ src2) --> new pixd (b) pixd == pixs1, (src1 ^ src2) --> src1 (in-place) (c) pixd != pixs1, (src1 ^ src2) --> input pixd (3) For clarity, if the case is known, use these patterns: (a) pixd = pixXor(NULL, pixs1, pixs2); (b) pixXor(pixs1, pixs1, pixs2); (c) pixXor(pixd, pixs1, pixs2); (4) The size of the result is determined by pixs1. (5) The depths of pixs1 and pixs2 must be equal. (6) Note carefully that the order of pixs1 and pixs2 only matters for the in-place case. For in-place, you must have pixd == pixs1. Setting pixd == pixs2 gives an incorrect result: the copy puts pixs1 image data in pixs2, and the rasterop is then between pixs2 and pixs2 (a no-op).
Input: pix (all depths; not colormapped) &empty (<return> 1 if all bits in image are 0; 0 otherwise) Return: 0 if OK; 1 on error
Notes: (1) For a binary image, if there are no fg (black) pixels, empty = 1. (2) For a grayscale image, if all pixels are black (0), empty = 1. (3) For an RGB image, if all 4 components in every pixel is 0, empty = 1.
LEPT_DLL l_int32 pmsCreate | ( | size_t | minsize, |
size_t | smallest, | ||
NUMA * | numalloc, | ||
const char * | logfile | ||
) |
Input: minsize (of data chunk that can be supplied by pms) smallest (bytes of the smallest pre-allocated data chunk. numalloc (array with the number of data chunks for each size that are in the memory store) logfile (use for debugging; null otherwise) Return: 0 if OK, 1 on error
Notes: (1) This computes the size of the block of memory required and allocates it. Each chunk starts on a 32-bit word boundary. The chunk sizes are in powers of 2, starting at , and the number of levels and chunks at each level is specified by . (2) This is intended to manage the image data for a small number of relatively large pix. The system malloc is expected to handle very large numbers of small chunks efficiently. (3) Important: set the allocators and call this function before any pix have been allocated. Destroy all the pix in the normal way before calling pmsDestroy(). (4) The pms struct is stored in a static global, so this function is not thread-safe. When used, there must be only one thread per process.
LEPT_DLL void* pmsCustomAlloc | ( | size_t | nbytes | ) |
Input: nbytes (min number of bytes in the chunk to be retrieved) Return: data (ptr to chunk)
Notes: (1) This attempts to find a suitable pre-allocated chunk. If not found, it dynamically allocates the chunk. (2) If logging is turned on, the allocations that are not taken from the memory store, and are at least as large as the minimum size the store can handle, are logged to file.
LEPT_DLL void pmsCustomDealloc | ( | void * | data | ) |
Input: data (to be freed or returned to the storage) Return: void
LEPT_DLL void pmsDestroy | ( | ) |
Input: (none) Return: void
Notes: (1) Important: call this function at the end of the program, after the last pix has been destroyed.
LEPT_DLL void* pmsGetAlloc | ( | size_t | nbytes | ) |
Input: nbytes Return: data
Notes: (1) This is called when a request for pix data cannot be obtained from the preallocated memory store. After use it is freed like normal memory. (2) If logging is on, only write out allocs that are as large as the minimum size handled by the memory store.
LEPT_DLL l_int32 pmsGetLevelForAlloc | ( | size_t | nbytes, |
l_int32 * | plevel | ||
) |
Input: nbytes (min number of bytes in the chunk to be retrieved) &level (<return>; -1 if either too small or too large) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 pmsGetLevelForDealloc | ( | void * | data, |
l_int32 * | plevel | ||
) |
Input: data (ptr to memory chunk) &level (<return> level in memory store; -1 if allocated outside the store) Return: 0 if OK, 1 on error
LEPT_DLL void pmsLogInfo | ( | ) |
Input: (none) Return: void
LEPT_DLL l_int32 projectiveXformPt | ( | l_float32 * | vc, |
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 * | pxp, | ||
l_float32 * | pyp | ||
) |
Input: vc (vector of 8 coefficients) (x, y) (initial point) (&xp, &yp) (<return> transformed point) Return: 0 if OK; 1 on error
Notes: (1) This computes the floating point location of the transformed point. (2) It does not check ptrs for returned data!
LEPT_DLL l_int32 projectiveXformSampledPt | ( | l_float32 * | vc, |
l_int32 | x, | ||
l_int32 | y, | ||
l_int32 * | pxp, | ||
l_int32 * | pyp | ||
) |
Input: vc (vector of 8 coefficients) (x, y) (initial point) (&xp, &yp) (<return> transformed point) Return: 0 if OK; 1 on error
Notes: (1) This finds the nearest pixel coordinates of the transformed point. (2) It does not check ptrs for returned data!
Input: ptaa pta (to be added) copyflag (L_INSERT, L_COPY, L_CLONE) Return: 0 if OK, 1 on error
LEPT_DLL PTAA* ptaaCreate | ( | l_int32 | n | ) |
Input: n (initial number of ptrs) Return: ptaa, or null on error
Input: pta x, y Return: 0 if OK, 1 on error
LEPT_DLL void ptaaDestroy | ( | PTAA ** | pptaa | ) |
Input: &ptaa <to be="" nulled>=""> Return: void
LEPT_DLL l_int32 ptaaExtendArray | ( | PTAA * | ptaa | ) |
Input: ptaa Return: 0 if OK, 1 on error
LEPT_DLL PTA* ptaAffineTransform | ( | PTA * | ptas, |
l_float32 * | mat | ||
) |
Input: ptas (for initial points) mat (3x3 transform matrix; canonical form) Return: ptad (transformed points), or null on error
LEPT_DLL PTAA* ptaaGetBoundaryPixels | ( | PIX * | pixs, |
l_int32 | type, | ||
l_int32 | connectivity, | ||
BOXA ** | pboxa, | ||
PIXA ** | ppixa | ||
) |
Input: pixs (1 bpp) type (L_BOUNDARY_FG, L_BOUNDARY_BG) connectivity (4 or 8) &boxa (<optional return>=""> bounding boxes of the c.c.) &pixa (<optional return>=""> pixa of the c.c.) Return: ptaa, or null on error
Notes: (1) This generates a ptaa of either fg or bg boundary pixels, where each pta has the boundary pixels for a connected component. (2) We can't simply find all the boundary pixels and then select those within the bounding box of each component, because bounding boxes can overlap. It is necessary to extract and dilate or erode each component separately. Note also that special handling is required for bg pixels when the component touches the pix boundary.
LEPT_DLL l_int32 ptaaGetCount | ( | PTAA * | ptaa | ) |
Input: ptaa Return: count, or 0 if no ptaa
LEPT_DLL l_int32 ptaaGetPt | ( | PTAA * | ptaa, |
l_int32 | ipta, | ||
l_int32 | jpt, | ||
l_float32 * | px, | ||
l_float32 * | py | ||
) |
Input: ptaa ipta (to the i-th pta) jpt (index to the j-th pt in the pta) &x (<optional return>=""> float x value) &y (<optional return>=""> float y value) Return: 0 if OK; 1 on error
Input: ptaa index (to the i-th pta) accessflag (L_COPY or L_CLONE) Return: pta, or null on error
Input: filename Return: ptaa, or null on error
LEPT_DLL PTAA* ptaaReadStream | ( | FILE * | fp | ) |
Input: stream Return: ptaa, or null on error
LEPT_DLL PTAA* ptaaSortByIndex | ( | PTAA * | ptaas, |
NUMA * | naindex | ||
) |
Input: ptaas naindex (na that maps from the new ptaa to the input ptaa) Return: ptaad (sorted), or null on error
Input: filename ptaa type (0 for float values; 1 for integer values) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 ptaaWriteStream | ( | FILE * | fp, |
PTAA * | ptaa, | ||
l_int32 | type | ||
) |
Input: stream ptaa type (0 for float values; 1 for integer values) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 ptaChangeRefcount | ( | PTA * | pta, |
l_int32 | delta | ||
) |
Input: pta Return: ptr to same pta, or null on error
Input: pta x, y (point) Return: 1 if contained, 0 otherwise or on error
LEPT_DLL BOXA* ptaConvertToBoxa | ( | PTA * | pta, |
l_int32 | ncorners | ||
) |
Input: pta ncorners (2 or 4 for the representation of each box) Return: 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 szie containing all corners.
Input: ptas istart (starting index in ptas) iend (ending index in ptas; use 0 to copy to end) Return: 0 if OK, 1 on error
Input: n (initial array sizes) Return: pta, or null on error.
LEPT_DLL PTA* ptaCreateFromNuma | ( | NUMA * | nax, |
NUMA * | nay | ||
) |
Input: nax (<optional> can be null) nay Return: pta, or null on error.
Input: ptas xs, ys (start point; must be in ptas) Return: ptad (cyclic permutation, starting and ending at (xs, ys), or null on error
Notes: (1) Check to insure that (a) ptas is a closed path where the first and last points are identical, and (b) the resulting pta also starts and ends on the same point (which in this case is (xs, ys).
LEPT_DLL void ptaDestroy | ( | PTA ** | ppta | ) |
Input: &pta (<to be="" nulled>="">) Return: void
Note:
LEPT_DLL l_int32 ptaExtendArrays | ( | PTA * | pta | ) |
Input: pta Return: 0 if OK; 1 on error
Input: pta &nax (<optional return>=""> numa of x array) &nay (<optional return>=""> numa of y array) Return: 0 if OK; 1 on error or if pta is empty
Notes: (1) This copies the internal arrays into new Numas.
LEPT_DLL PTA* ptaGetBoundaryPixels | ( | PIX * | pixs, |
l_int32 | type | ||
) |
Input: pixs (1 bpp) type (L_BOUNDARY_FG, L_BOUNDARY_BG) Return: pta, or null on error
Notes: (1) This generates a pta of either fg or bg boundary pixels.
LEPT_DLL BOX* ptaGetBoundingRegion | ( | PTA * | pta | ) |
Input: pta Return: box, or null on error
Notes: (1) This is used when the pta represents a set of points in a two-dimensional image. It returns the box of minimum size containing the pts in the pta.
LEPT_DLL l_int32 ptaGetCount | ( | PTA * | pta | ) |
Input: pta Return: count, or 0 if no pta
LEPT_DLL l_int32 ptaGetCubicLSF | ( | PTA * | pta, |
l_float32 * | pa, | ||
l_float32 * | pb, | ||
l_float32 * | pc, | ||
l_float32 * | pd, | ||
NUMA ** | pnafit | ||
) |
Input: pta &a (<optional return>=""> coeff a of LSF: y = ax^3 + bx^2 + cx + d) &b (<optional return>=""> coeff b of LSF) &c (<optional return>=""> coeff c of LSF) &d (<optional return>=""> coeff d of LSF) &nafit (<optional return>=""> numa of least square fit) Return: 0 if OK, 1 on error
Notes: (1) This does a cubic least square fit to the set of points in . That is, it finds coefficients a, b, c and d that minimize:
sum (yi - a*xi*xi*xi -b*xi*xi -c*xi - d)^2 i
Differentiate this expression w/rt a, b, c and d, and solve the resulting four equations for these coefficients in terms of various sums over the input data (xi, yi). The four equations are in the form: f[0][0]a + f[0][1]b + f[0][2]c + f[0][3] = g[0] f[1][0]a + f[1][1]b + f[1][2]c + f[1][3] = g[1] f[2][0]a + f[2][1]b + f[2][2]c + f[2][3] = g[2] f[3][0]a + f[3][1]b + f[3][2]c + f[3][3] = g[3] (2) If is defined, this returns an array of fitted values, corresponding to the two implicit Numa arrays (nax and nay) in pta. Thus, just as you can plot the data in pta as nay vs. nax, you can plot the linear least square fit as nafit vs. nax.
LEPT_DLL PTA* ptaGetInsideBox | ( | PTA * | ptas, |
BOX * | box | ||
) |
Input: ptas (input pts) box Return: ptad (of pts in ptas that are inside the box), or null on error
Input: pta index (into arrays) &x (<optional return>=""> integer x value) &y (<optional return>=""> integer y value) Return: 0 if OK; 1 on error
Input: pta &a (<optional return>=""> slope a of least square fit: y = ax + b) &b (<optional return>=""> intercept b of least square fit) &nafit (<optional return>=""> numa of least square fit) Return: 0 if OK, 1 on error
Notes: (1) Either or both &a and &b must be input. They determine the type of line that is fit. (2) If both &a and &b are defined, this returns a and b that minimize:
sum (yi - axi -b)^2 i
The method is simple: differentiate this expression w/rt a and b, and solve the resulting two equations for a and b in terms of various sums over the input data (xi, yi). (3) We also allow two special cases, where either a = 0 or b = 0: (a) If &a is given and &b = null, find the linear LSF that goes through the origin (b = 0). (b) If &b is given and &a = null, find the linear LSF with zero slope (a = 0). (4) If is defined, this returns an array of fitted values, corresponding to the two implicit Numa arrays (nax and nay) in pta. Thus, just as you can plot the data in pta as nay vs. nax, you can plot the linear least square fit as nafit vs. nax.
LEPT_DLL PTA* ptaGetPixelsFromPix | ( | PIX * | pixs, |
BOX * | box | ||
) |
Input: pixs (1 bpp) box (<optional> can be null) Return: pta, or null on error
Notes: (1) Generates a pta of fg pixels in the pix, within the box. If box == NULL, it uses the entire pix.
Input: pta index (into arrays) &x (<optional return>=""> float x value) &y (<optional return>=""> float y value) Return: 0 if OK; 1 on error
LEPT_DLL l_int32 ptaGetQuadraticLSF | ( | PTA * | pta, |
l_float32 * | pa, | ||
l_float32 * | pb, | ||
l_float32 * | pc, | ||
NUMA ** | pnafit | ||
) |
Input: pta &a (<optional return>=""> coeff a of LSF: y = ax^2 + bx + c) &b (<optional return>=""> coeff b of LSF: y = ax^2 + bx + c) &c (<optional return>=""> coeff c of LSF: y = ax^2 + bx + c) &nafit (<optional return>=""> numa of least square fit) Return: 0 if OK, 1 on error
Notes: (1) This does a quadratic least square fit to the set of points in . That is, it finds coefficients a, b and c that minimize:
sum (yi - a*xi*xi -b*xi -c)^2 i
The method is simple: differentiate this expression w/rt a, b and c, and solve the resulting three equations for these coefficients in terms of various sums over the input data (xi, yi). The three equations are in the form: f[0][0]a + f[0][1]b + f[0][2]c = g[0] f[1][0]a + f[1][1]b + f[1][2]c = g[1] f[2][0]a + f[2][1]b + f[2][2]c = g[2] (2) If is defined, this returns an array of fitted values, corresponding to the two implicit Numa arrays (nax and nay) in pta. Thus, just as you can plot the data in pta as nay vs. nax, you can plot the linear least square fit as nafit vs. nax.
LEPT_DLL l_int32 ptaGetQuarticLSF | ( | PTA * | pta, |
l_float32 * | pa, | ||
l_float32 * | pb, | ||
l_float32 * | pc, | ||
l_float32 * | pd, | ||
l_float32 * | pe, | ||
NUMA ** | pnafit | ||
) |
Input: pta &a (<optional return>=""> coeff a of LSF: y = ax^4 + bx^3 + cx^2 + dx + e) &b (<optional return>=""> coeff b of LSF) &c (<optional return>=""> coeff c of LSF) &d (<optional return>=""> coeff d of LSF) &e (<optional return>=""> coeff e of LSF) &nafit (<optional return>=""> numa of least square fit) Return: 0 if OK, 1 on error
Notes: (1) This does a quartic least square fit to the set of points in . That is, it finds coefficients a, b, c, d and 3 that minimize:
sum (yi - a*xi*xi*xi*xi -b*xi*xi*xi -c*xi*xi - d*xi - e)^2 i
Differentiate this expression w/rt a, b, c, d and e, and solve the resulting five equations for these coefficients in terms of various sums over the input data (xi, yi). The five equations are in the form: f[0][0]a + f[0][1]b + f[0][2]c + f[0][3] + f[0][4] = g[0] f[1][0]a + f[1][1]b + f[1][2]c + f[1][3] + f[1][4] = g[1] f[2][0]a + f[2][1]b + f[2][2]c + f[2][3] + f[2][4] = g[2] f[3][0]a + f[3][1]b + f[3][2]c + f[3][3] + f[3][4] = g[3] f[4][0]a + f[4][1]b + f[4][2]c + f[4][3] + f[4][4] = g[4] (2) If is defined, this returns an array of fitted values, corresponding to the two implicit Numa arrays (nax and nay) in pta. Thus, just as you can plot the data in pta as nay vs. nax, you can plot the linear least square fit as nafit vs. nax.
LEPT_DLL l_int32 ptaGetRange | ( | PTA * | pta, |
l_float32 * | pminx, | ||
l_float32 * | pmaxx, | ||
l_float32 * | pminy, | ||
l_float32 * | pmaxy | ||
) |
Input: pta &minx (<optional return>=""> min value of x) &maxx (<optional return>=""> max value of x) &miny (<optional return>=""> min value of y) &maxy (<optional return>=""> max value of y) Return: 0 if OK, 1 on error
Notes: (1) We can use pts to represent pairs of floating values, that are not necessarily tied to a two-dimension region. For example, the pts can represent a general function y(x).
LEPT_DLL l_int32 ptaGetRefcount | ( | PTA * | pta | ) |
LEPT_DLL l_int32 ptaGetSortIndex | ( | PTA * | ptas, |
l_int32 | sorttype, | ||
l_int32 | sortorder, | ||
NUMA ** | pnaindex | ||
) |
Input: ptas sorttype (L_SORT_BY_X, L_SORT_BY_Y) sortorder (L_SORT_INCREASING, L_SORT_DECREASING) &naindex (<return> index of sorted order into original array) Return: 0 if OK, 1 on error
Input: ptad (dest pta; add to this one) ptas (source pta; add from this one) istart (starting index in ptas) iend (ending index in ptas; use 0 to cat all) Return: 0 if OK, 1 on error
Notes: (1) istart < 0 is taken to mean 'read from the start' (istart = 0) (2) iend <= 0 means 'read to the end'
LEPT_DLL l_int32 ptaNoisyLinearLSF | ( | PTA * | pta, |
l_float32 | factor, | ||
PTA ** | pptad, | ||
l_float32 * | pa, | ||
l_float32 * | pb, | ||
l_float32 * | pmederr, | ||
NUMA ** | pnafit | ||
) |
Input: pta factor (reject outliers with error greater than this number of medians; typically ~ 3) &ptad (<optional return>=""> with outliers removed) &a (<optional return>=""> slope a of least square fit: y = ax + b) &b (<optional return>=""> intercept b of least square fit) &mederr (<optional return>=""> median error) &nafit (<optional return>=""> numa of least square fit to ptad) Return: 0 if OK, 1 on error
Notes: (1) This does a linear least square fit to the set of points in . It then evaluates the errors and removes points whose error is >= factor * median_error. It then re-runs the linear LSF on the resulting points. (2) Either or both &a and &b must be input. They determine the type of line that is fit. (3) The median error can give an indication of how good the fit is likely to be.
LEPT_DLL l_int32 ptaNoisyQuadraticLSF | ( | PTA * | pta, |
l_float32 | factor, | ||
PTA ** | pptad, | ||
l_float32 * | pa, | ||
l_float32 * | pb, | ||
l_float32 * | pc, | ||
l_float32 * | pmederr, | ||
NUMA ** | pnafit | ||
) |
Input: pta factor (reject outliers with error greater than this number of medians; typically ~ 3) &ptad (<optional return>=""> with outliers removed) &a (<optional return>=""> coeff a of LSF: y = ax^2 + bx + c) &b (<optional return>=""> coeff b of LSF: y = ax^2 + bx + c) &c (<optional return>=""> coeff c of LSF: y = ax^2 + bx + c) &mederr (<optional return>=""> median error) &nafit (<optional return>=""> numa of least square fit to ptad) Return: 0 if OK, 1 on error
Notes: (1) This does a quadratic least square fit to the set of points in . It then evaluates the errors and removes points whose error is >= factor * median_error. It then re-runs a quadratic LSF on the resulting points.
Input: filename Return: pta, or null on error
LEPT_DLL PTA* ptaReadStream | ( | FILE * | fp | ) |
Input: stream Return: pta, or null on error
LEPT_DLL PTA* ptaRemoveDuplicates | ( | PTA * | ptas, |
l_uint32 | factor | ||
) |
Input: ptas (assumed to be integer values) factor (should be larger than the largest point value; use 0 for default) Return: ptad (with duplicates removed), or null on error
LEPT_DLL PTA* ptaReplicatePattern | ( | PTA * | ptas, |
PIX * | pixp, | ||
l_int32 | cx, | ||
l_int32 | cy, | ||
l_int32 | w, | ||
l_int32 | h | ||
) |
Input: ptas ("sparse" input pta) pixp (1 bpp pattern, to be replicated in output pta) cx, cy (reference point in pattern) w, h (clipping sizes for output pta) Return: ptad (with all points of replicated pattern), or null on error
Notes: (1) The pattern is placed with its reference point at each point in ptas, and all the fg pixels are colleced into ptad. This is equivalent to blitting pix at each point in ptas, and then converting the resulting pix to a pta.
LEPT_DLL PTA* ptaReverse | ( | PTA * | ptas, |
l_int32 | type | ||
) |
Input: ptas type (0 for float values; 1 for integer values) Return: ptad (reversed pta), or null on error
Input: ptas (for initial points) (xc, yc) (location of center of rotation) angle (rotation in radians; clockwise is positive) (&ptad) (<return> new locations) Return: 0 if OK; 1 on error
Notes; (1) See createMatrix2dScale() for details of transform.
Input: ptas (for initial points) scalex (horizontal scale factor) scaley (vertical scale factor) Return: 0 if OK; 1 on error
Notes; (1) See createMatrix2dScale() for details of transform.
Input: pta index (into arrays) x, y Return: 0 if OK; 1 on error
Input: ptas sorttype (L_SORT_BY_X, L_SORT_BY_Y) sortorder (L_SORT_INCREASING, L_SORT_DECREASING) &naindex (<optional return>=""> index of sorted order into original array) Return: ptad (sorted version of ptas), or null on error
LEPT_DLL PTA* ptaSortByIndex | ( | PTA * | ptas, |
NUMA * | naindex | ||
) |
Input: ptas naindex (na that maps from the new pta to the input pta) Return: ptad (sorted), or null on error
LEPT_DLL PTA* ptaSubsample | ( | PTA * | ptas, |
l_int32 | subfactor | ||
) |
Input: ptas subfactor (subsample factor, >= 1) Return: ptad (evenly sampled pt values from ptas, or null on error
LEPT_DLL l_int32 ptaTestIntersection | ( | PTA * | pta1, |
PTA * | pta2 | ||
) |
Input: pta1, pta2 Return: bval which is 1 if they have any elements in common; 0 otherwise or on error.
LEPT_DLL PTA* ptaTransform | ( | PTA * | ptas, |
l_int32 | shiftx, | ||
l_int32 | shifty, | ||
l_float32 | scalex, | ||
l_float32 | scaley | ||
) |
Input: pta shiftx, shifty scalex, scaley Return: pta, or null on error
Notes: (1) Shift first, then scale.
Input: ptas (for initial points) transx (x component of translation wrt. the origin) transy (y component of translation wrt. the origin) Return: ptad (translated points), or null on error
Notes; (1) See createMatrix2dTranslate() for details of transform.
LEPT_DLL PTA* ptaTranspose | ( | PTA * | ptas | ) |
Input: ptas Return: ptad (with x and y values swapped), or null on error
Input: filename pta type (0 for float values; 1 for integer values) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 ptaWriteStream | ( | FILE * | fp, |
PTA * | pta, | ||
l_int32 | type | ||
) |
Input: stream pta type (0 for float values; 1 for integer values) Return: 0 if OK; 1 on error
LEPT_DLL L_PTRAA* ptraaCreate | ( | l_int32 | n | ) |
Input: size of ptr array to be alloc'd Return: paa, or null on error
Notes: (1) The ptraa is generated with a fixed size, that can not change. The ptra can be generated and inserted randomly into this array.
Input: ptra item (generic ptr to a struct) Return: 0 if OK, 1 on error
Notes: (1) This adds the element to the next location beyond imax, which is the largest occupied ptr in the array. This is what you expect from a stack, where all ptrs up to and including imax are occupied, but here the occuption of items in the array is entirely arbitrary.
LEPT_DLL void ptraaDestroy | ( | L_PTRAA ** | ppaa, |
l_int32 | freeflag, | ||
l_int32 | warnflag | ||
) |
Input: &paa (<to be="" nulled>="">) freeflag (TRUE to free each remaining item in each ptra) warnflag (TRUE to warn if any remaining items are not destroyed) Return: void
Notes: (1) See ptraDestroy() for use of and . (2) To destroy the ptraa, we destroy each ptra, then the ptr array, then the ptraa, and then null the contents of the input ptr.
LEPT_DLL L_PTRA* ptraaFlattenToPtra | ( | L_PTRAA * | paa | ) |
Input: ptraa Return: ptra, or null on error
Notes: (1) This 'flattens' the ptraa to a ptra, taking the items in each ptra, in order, starting with the first ptra, etc. (2) As a side-effect, the ptra are all removed from the ptraa and destroyed, leaving an empty ptraa.
Input: ptraa index (location in array) accessflag (L_HANDLE_ONLY, L_REMOVE) Return: ptra (at index location), or NULL on error or if there is no ptra there.
Notes: (1) This returns the ptra ptr. If == L_HANDLE_ONLY, the ptra is left on the ptraa. If == L_REMOVE, the ptr in the ptraa is set to NULL, and the caller is responsible for disposing of the ptra (either putting it back on the ptraa, or destroying it). (2) This returns NULL if there is no Ptra at the index location.
LEPT_DLL l_int32 ptraaGetSize | ( | L_PTRAA * | paa, |
l_int32 * | psize | ||
) |
Input: ptraa &size (<return> size of ptr array) Return: 0 if OK; 1 on error
Input: ptraa index (location in array for insertion) ptra (to be inserted) Return: 0 if OK; 1 on error
Notes: (1) Caller should check return value. On success, the Ptra is inserted in the Ptraa and is owned by it. However, on error, the Ptra remains owned by the caller.
LEPT_DLL l_int32 ptraCompactArray | ( | L_PTRA * | pa | ) |
Input: ptra Return: 0 if OK, 1 on error
Notes: (1) This compacts the items on the array, filling any empty ptrs. (2) This does not change the size of the array of ptrs.
LEPT_DLL l_int32 ptraConcatenatePdf | ( | L_PTRA * | pa, |
const char * | fileout | ||
) |
Input: ptra (array of pdf strings, each for a single-page pdf file) fileout (concatenated pdf file) Return: 0 if OK, 1 on error
Notes: (1) This only works with leptonica-formatted single-page pdf files.
LEPT_DLL l_int32 ptraConcatenatePdfToData | ( | L_PTRA * | pa_data, |
SARRAY * | sa, | ||
l_uint8 ** | pdata, | ||
size_t * | pnbytes | ||
) |
Input: ptra (array of pdf strings, each for a single-page pdf file) sarray (<optional> of pathnames for input pdf files) &data (<return> concatenated pdf data in memory) &nbytes (<return> number of bytes in pdf data) Return: 0 if OK, 1 on error
Notes: (1) This only works with leptonica-formatted single-page pdf files. pdf files generated by other programs will have unpredictable (and usually bad) results. The requirements for each pdf file: (a) The Catalog and Info objects are the first two. (b) Object 3 is Pages (c) Object 4 is Page (d) The remaining objects are Contents, XObjects, and ColorSpace (2) We remove trailers from each page, and append the full trailer for all pages at the end. (3) For all but the first file, remove the ID and the first 3 objects (catalog, info, pages), so that each subsequent file has only objects of these classes: Page, Contents, XObject, ColorSpace (Indexed RGB). For those objects, we substitute these refs to objects in the local file: Page: Parent(object 3), Contents, XObject(typically multiple) XObject: [ColorSpace if indexed] The Pages object on the first page (object 3) has a Kids array of references to all the Page objects, with a Count equal to the number of pages. Each Page object refers back to this parent.
LEPT_DLL L_PTRA* ptraCreate | ( | l_int32 | n | ) |
Input: size of ptr array to be alloc'd (0 for default) Return: pa, or null on error
LEPT_DLL void ptraDestroy | ( | L_PTRA ** | ppa, |
l_int32 | freeflag, | ||
l_int32 | warnflag | ||
) |
Input: &ptra (<to be="" nulled>="">) freeflag (TRUE to free each remaining item in the array) warnflag (TRUE to warn if any remaining items are not destroyed) Return: void
Notes: (1) If == TRUE, frees each item in the array. (2) If == FALSE and warnflag == TRUE, and there are items on the array, this gives a warning and destroys the array. If these items are not owned elsewhere, this will cause a memory leak of all the items that were on the array. So if the items are not owned elsewhere and require their own destroy function, they must be destroyed before the ptra. (3) If warnflag == FALSE, no warnings will be issued. This is useful if the items are owned elsewhere, such as a PixMemoryStore(). (4) To destroy the ptra, we destroy the ptr array, then the ptra, and then null the contents of the input ptr.
LEPT_DLL l_int32 ptraExtendArray | ( | L_PTRA * | pa | ) |
Input: ptra Return: 0 if OK, 1 on error
LEPT_DLL l_int32 ptraGetActualCount | ( | L_PTRA * | pa, |
l_int32 * | pcount | ||
) |
Input: ptra &count (<return> actual number of items on the ptr array) Return: 0 if OK; 1 on error
Notes: (1) The actual number of items on the ptr array, pa->nactual, will be smaller than pa->n if the array is not compacted.
LEPT_DLL void* ptraGetHandle | ( | L_PTRA * | pa, |
l_int32 | index | ||
) |
Input: ptra index (element to be retrieved) Return: item, or null on error
Notes: (1) This returns a ptr to the item. You must cast it to the type of item. Do not destroy it; the item belongs to the Ptra. (2) This can access all possible items on the ptr array. If an item doesn't exist, it returns null.
LEPT_DLL l_int32 ptraGetMaxIndex | ( | L_PTRA * | pa, |
l_int32 * | pmaxindex | ||
) |
Input: ptra &maxindex (<return> index of last item in the array); Return: 0 if OK; 1 on error
Notes: (1) The largest index to an item in the array is . is one less than the number of items that would be in the array if there were no null pointers between 0 and - 1. However, because the internal ptr array need not be compacted, there may be null pointers at indices below ; for example, if items have been removed. (2) When an item is added to the end of the array, it goes into pa->array[maxindex + 1], and maxindex is then incremented by 1. (3) If there are no items in the array, this returns = -1.
LEPT_DLL void* ptraGetPtrToItem | ( | L_PTRA * | pa, |
l_int32 | index | ||
) |
Input: ptra index (element to fetch pointer to) Return: item (just a pointer to it)
Notes: (1) The item remains on the Ptra and is 'owned' by it, so the item must not be destroyed.
Input: ptra index (location in ptra to insert new value) item (generic ptr to a struct; can be null) shiftflag (L_AUTO_DOWNSHIFT, L_MIN_DOWNSHIFT, L_FULL_DOWNSHIFT) Return: 0 if OK, 1 on error
Notes: (1) This checks first to see if the location is valid, and then if there is presently an item there. If there is not, it is simply inserted into that location. (2) If there is an item at the insert location, items must be moved down to make room for the insert. In the downward shift there are three options, given by .
Input: ptra1 (add to this one) ptra2 (appended to ptra1, and emptied of items; can be null) Return: 0 if OK, 1 on error
LEPT_DLL void* ptraRemove | ( | L_PTRA * | pa, |
l_int32 | index, | ||
l_int32 | flag | ||
) |
Input: ptra index (element to be removed) flag (L_NO_COMPACTION, L_COMPACTION) Return: item, or null on error
Notes: (1) If flag == L_NO_COMPACTION, this removes the item and nulls the ptr on the array. If it takes the last item in the array, pa->n is reduced to the next item. (2) If flag == L_COMPACTION, this compacts the array for for all i >= index. It should not be used repeatedly on large arrays, because compaction is O(n). (3) The ability to remove without automatic compaction allows removal with cost O(1).
LEPT_DLL void* ptraRemoveLast | ( | L_PTRA * | pa | ) |
Input: ptra Return: item, or null on error or if the array is empty
LEPT_DLL void* ptraReplace | ( | L_PTRA * | pa, |
l_int32 | index, | ||
void * | item, | ||
l_int32 | freeflag | ||
) |
Input: ptra index (element to be replaced) item (new generic ptr to a struct; can be null) freeflag (TRUE to free old item; FALSE to return it) Return: item (old item, if it exists and is not freed), or null on error
LEPT_DLL l_int32 ptraReverse | ( | L_PTRA * | pa | ) |
Input: ptra Return: 0 if OK, 1 on error
Input: ptra index1 index2 Return: 0 if OK, 1 on error
LEPT_DLL l_int32 quadtreeGetChildren | ( | FPIXA * | fpixa, |
l_int32 | level, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 * | pval00, | ||
l_float32 * | pval10, | ||
l_float32 * | pval01, | ||
l_float32 * | pval11 | ||
) |
Input: fpixa (mean, variance or root variance) level, x, y (of current pixel) &val00, val01, val10, val11 (<return> child pixel values) Return: 0 if OK, 1 on error
Notes: (1) Check return value for error. On error, all return vals are 0.0. (2) The returned child pixels are located at: level + 1 (2x, 2y), (2x+1, 2y), (2x, 2y+1), (2x+1, 2y+1)
LEPT_DLL l_int32 quadtreeGetParent | ( | FPIXA * | fpixa, |
l_int32 | level, | ||
l_int32 | x, | ||
l_int32 | y, | ||
l_float32 * | pval | ||
) |
Input: fpixa (mean, variance or root variance) level, x, y (of current pixel) &val (<return> parent pixel value), or 0.0 on error. Return: 0 if OK, 1 on error
Notes: (1) Check return value for error. On error, val is returned as 0.0. (2) The parent is located at: level - 1 (x/2, y/2)
LEPT_DLL l_int32 quadtreeMaxLevels | ( | l_int32 | w, |
l_int32 | h | ||
) |
Input: w, h (of image) Return: maxlevels (maximum number of levels allowed), or -1 on error
Notes: (1) The criterion for maxlevels is that the subdivision not go down below the single pixel level. The 1.5 factor is intended to keep any rectangle from accidentally having zero dimension due to integer truncation.
LEPT_DLL void rasteropHipLow | ( | l_uint32 * | data, |
l_int32 | pixh, | ||
l_int32 | depth, | ||
l_int32 | wpl, | ||
l_int32 | y, | ||
l_int32 | h, | ||
l_int32 | shift | ||
) |
Input: data (ptr to image data) pixh (height) depth (depth) wpl (wpl) y (y val of UL corner of rectangle) h (height of rectangle) shift (+ shifts data to the left in a horizontal column) Return: 0 if OK; 1 on error.
Notes: (1) This clears the pixels that are left exposed after the rasterop. Therefore, for Pix with depth > 1, these pixels become black, and must be subsequently SET if they are to be white. For example, see pixRasteropHip(). (2) This function performs clipping and calls shiftDataHorizontalLine() to do the in-place rasterop on each line.
LEPT_DLL void rasteropLow | ( | l_uint32 * | datad, |
l_int32 | dpixw, | ||
l_int32 | dpixh, | ||
l_int32 | depth, | ||
l_int32 | dwpl, | ||
l_int32 | dx, | ||
l_int32 | dy, | ||
l_int32 | dw, | ||
l_int32 | dh, | ||
l_int32 | op, | ||
l_uint32 * | datas, | ||
l_int32 | spixw, | ||
l_int32 | spixh, | ||
l_int32 | swpl, | ||
l_int32 | sx, | ||
l_int32 | sy | ||
) |
Input: datad (ptr to dest image data) dpixw (width of dest) dpixh (height of dest) depth (depth of src and dest) dwpl (wpl of dest) dx (x val of UL corner of dest rectangle) dy (y val of UL corner of dest rectangle) dw (width of dest rectangle) dh (height of dest rectangle) op (op code) datas (ptr to src image data) spixw (width of src) spixh (height of src) swpl (wpl of src) sx (x val of UL corner of src rectangle) sy (y val of UL corner of src rectangle) Return: void
Action: Scales width, performs clipping, checks alignment, and dispatches for the rasterop.
Warning: the two images must have equal depth. This is not checked.
LEPT_DLL void rasteropUniLow | ( | l_uint32 * | datad, |
l_int32 | dpixw, | ||
l_int32 | dpixh, | ||
l_int32 | depth, | ||
l_int32 | dwpl, | ||
l_int32 | dx, | ||
l_int32 | dy, | ||
l_int32 | dw, | ||
l_int32 | dh, | ||
l_int32 | op | ||
) |
Input: datad (ptr to dest image data) dpixw (width of dest) dpixh (height of dest) depth (depth of src and dest) dwpl (wpl of dest) dx (x val of UL corner of dest rectangle) dy (y val of UL corner of dest rectangle) dw (width of dest rectangle) dh (height of dest rectangle) op (op code) Return: void
Action: scales width, performs clipping, checks alignment, and dispatches for the rasterop.
LEPT_DLL void rasteropVipLow | ( | l_uint32 * | data, |
l_int32 | pixw, | ||
l_int32 | pixh, | ||
l_int32 | depth, | ||
l_int32 | wpl, | ||
l_int32 | x, | ||
l_int32 | w, | ||
l_int32 | shift | ||
) |
Input: data (ptr to image data) pixw (width) pixh (height) depth (depth) wpl (wpl) x (x val of UL corner of rectangle) w (width of rectangle) shift (+ shifts data downward in vertical column) Return: 0 if OK; 1 on error.
Notes: (1) This clears the pixels that are left exposed after the translation. You can consider them as pixels that are shifted in from outside the image. This can be later overridden by the incolor parameter in higher-level functions that call this. For example, for images with depth > 1, these pixels are cleared to black; to be white they must later be SET to white. See, e.g., pixRasteropVip(). (2) This function scales the width to accommodate any depth, performs clipping, and then does the in-place rasterop.
LEPT_DLL l_int32 readHeaderJpeg | ( | const char * | filename, |
l_int32 * | pw, | ||
l_int32 * | ph, | ||
l_int32 * | pspp, | ||
l_int32 * | pycck, | ||
l_int32 * | pcmyk | ||
) |
Input: filename &w (<optional return>="">) &h (<optional return>="">) &spp (<optional return>="">, samples/pixel) &ycck (<optional return>="">, 1 if ycck color space; 0 otherwise) &cmyk (<optional return>="">, 1 if cmyk color space; 0 otherwise) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 readHeaderMemJpeg | ( | const l_uint8 * | cdata, |
size_t | size, | ||
l_int32 * | pw, | ||
l_int32 * | ph, | ||
l_int32 * | pspp, | ||
l_int32 * | pycck, | ||
l_int32 * | pcmyk | ||
) |
Input: cdata (const; jpeg-encoded) size (of data) &w (<optional return>="">) &h (<optional return>="">) &spp (<optional return>="">, samples/pixel) &ycck (<optional return>="">, 1 if ycck color space; 0 otherwise) &cmyk (<optional return>="">, 1 if cmyk color space; 0 otherwise) Return: 0 if OK, 1 on error
Notes: (1) Parse the jpeg string without without jpeg library calls.
LEPT_DLL l_int32 readHeaderMemTiff | ( | const l_uint8 * | cdata, |
size_t | size, | ||
l_int32 | n, | ||
l_int32 * | pwidth, | ||
l_int32 * | pheight, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp, | ||
l_int32 * | pres, | ||
l_int32 * | pcmap, | ||
l_int32 * | pformat | ||
) |
Input: cdata (const; tiff-encoded) size (size of data) n (page image number: 0-based) &width (<return>) &height (<return>) &bps (<return> bits per sample -- 1, 2, 4 or 8) &spp (<return>; samples per pixel -- 1 or 3) &res (<optional return>="">; resolution in x dir; NULL to ignore) &cmap (<optional return>="">; colormap exists; input NULL to ignore) &format (<optional return>="">; tiff format; input NULL to ignore) Return: 0 if OK, 1 on error
Notes: (1) Use TIFFClose(); TIFFCleanup() doesn't free internal memstream.
LEPT_DLL l_int32 readHeaderPng | ( | const char * | filename, |
l_int32 * | pwidth, | ||
l_int32 * | pheight, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp, | ||
l_int32 * | piscmap | ||
) |
Input: filename &width (<return>) &height (<return>) &bps (<return>, bits/sample) &spp (<return>, samples/pixel) &iscmap (<optional return>="">; input NULL to ignore) Return: 0 if OK, 1 on error
Notes: (1) If there is a colormap, iscmap is returned as 1; else 0.
LEPT_DLL l_int32 readHeaderPnm | ( | const char * | filename, |
PIX ** | ppix, | ||
l_int32 * | pwidth, | ||
l_int32 * | pheight, | ||
l_int32 * | pdepth, | ||
l_int32 * | ptype, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp | ||
) |
Input: filename &pix (<optional return>=""> use null to return only header data) &width (<return>) &height (<return>) &depth (<return>) &type (<return> pnm type) &bps (<optional return>="">, bits/sample) &spp (<optional return>="">, samples/pixel) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 readHeaderSpix | ( | const char * | filename, |
l_int32 * | pwidth, | ||
l_int32 * | pheight, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp, | ||
l_int32 * | piscmap | ||
) |
Input: filename &width (<return>) &height (<return>) &bps (<return>, bits/sample) &spp (<return>, samples/pixel) &iscmap (<optional return>="">; input NULL to ignore) Return: 0 if OK, 1 on error
Notes: (1) If there is a colormap, iscmap is returned as 1; else 0.
LEPT_DLL l_int32 readHeaderTiff | ( | const char * | filename, |
l_int32 | n, | ||
l_int32 * | pwidth, | ||
l_int32 * | pheight, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp, | ||
l_int32 * | pres, | ||
l_int32 * | pcmap, | ||
l_int32 * | pformat | ||
) |
Input: filename n (page image number: 0-based) &width (<return>) &height (<return>) &bps (<return> bits per sample -- 1, 2, 4 or 8) &spp (<return>; samples per pixel -- 1 or 3) &res (<optional return>="">; resolution in x dir; NULL to ignore) &cmap (<optional return>="">; colormap exists; input NULL to ignore) &format (<optional return>="">; tiff format; input NULL to ignore) Return: 0 if OK, 1 on error
Notes: (1) If there is a colormap, cmap is returned as 1; else 0. (2) If
is equal to or greater than the number of images, returns 1.
LEPT_DLL l_int32 readHeaderWebP | ( | const char * | filename, |
l_int32 * | pwidth, | ||
l_int32 * | pheight | ||
) |
LEPT_DLL void* reallocNew | ( | void ** | pindata, |
l_int32 | oldsize, | ||
l_int32 | newsize | ||
) |
Input: &indata (<optional>; nulls indata) size of input data to be copied (bytes) size of data to be reallocated (bytes) Return: ptr to new data, or null on error
Action: !N.B. (3) and (4)! (1) Allocates memory, initialized to 0 (2) Copies as much of the input data as possible to the new block, truncating the copy if necessary (3) Frees the input data (4) Zeroes the input data ptr
Notes: (1) If newsize <=0, just frees input data and nulls ptr (2) If input ptr is null, just callocs new memory (3) This differs from realloc in that it always allocates new memory (if newsize > 0) and initializes it to 0, it requires the amount of old data to be copied, and it takes the address of the input ptr and nulls the handle.
LEPT_DLL void reduceBinary2Low | ( | l_uint32 * | datad, |
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | hs, | ||
l_int32 | wpls, | ||
l_uint8 * | tab | ||
) |
After folding, the data is in bytes 0 and 2 of the word, and the bits in each byte are in the following order (with 0 being the leftmost originating pair and 7 being the rightmost originating pair):
0 4 1 5 2 6 3 7
These need to be permuted to
0 1 2 3 4 5 6 7
which is done with an 8-bit table generated by makeSubsampleTab2x().
LEPT_DLL void reduceRankBinary2Low | ( | l_uint32 * | datad, |
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | hs, | ||
l_int32 | wpls, | ||
l_uint8 * | tab, | ||
l_int32 | level | ||
) |
Rank filtering is done to the UL corner of each 2x2 pixel block, using only logical operations.
Then these pixels are chosen in the 2x subsampling process, subsampled, as described above in reduceBinary2Low().
LEPT_DLL l_int32 regTestCheckFile | ( | L_REGPARAMS * | rp, |
const char * | localname | ||
) |
Input: rp (regtest parameters) localname (name of output file from reg test) Return: 0 if OK, 1 on error (a failure in comparison is not an error)
Notes: (1) This function does one of three things, depending on the mode: * "generate": makes a "golden" file as a copy . * "compare": compares contents with the golden file * "display": makes the file but does no comparison (2) The canonical format of the golden filenames is: /tmp/golden/<root of="" main="" name>="">_golden.<index>.<ext of="" localname>=""> e.g., /tmp/golden/maze_golden.0.png It is important to add an extension to the local name, because the extension is added to the name of the golden file.
LEPT_DLL l_int32 regTestCleanup | ( | L_REGPARAMS * | rp | ) |
Input: rp (regression test parameters) Return: 0 if OK, 1 on error
Notes: (1) This copies anything written to the temporary file to the output file /tmp/reg_results.txt.
LEPT_DLL l_int32 regTestCompareFiles | ( | L_REGPARAMS * | rp, |
l_int32 | index1, | ||
l_int32 | index2 | ||
) |
Input: rp (regtest parameters) index1 (of one output file from reg test) index2 (of another output file from reg test) Return: 0 if OK, 1 on error (a failure in comparison is not an error)
Notes: (1) This only does something in "compare" mode. (2) The canonical format of the golden filenames is: /tmp/golden/<root of="" main="" name>="">_golden.<index>.<ext of="" localname>=""> e.g., /tmp/golden/maze_golden.0.png
LEPT_DLL l_int32 regTestComparePix | ( | L_REGPARAMS * | rp, |
PIX * | pix1, | ||
PIX * | pix2 | ||
) |
Input: rp (regtest parameters) pix1, pix2 (to be tested for equality) Return: 0 if OK, 1 on error (a failure in comparison is not an error)
Notes: (1) This function compares two pix for equality. If not in compare mode, on failure it writes to stderr.
LEPT_DLL l_int32 regTestCompareSimilarPix | ( | L_REGPARAMS * | rp, |
PIX * | pix1, | ||
PIX * | pix2, | ||
l_int32 | mindiff, | ||
l_float32 | maxfract, | ||
l_int32 | printstats | ||
) |
Input: rp (regtest parameters) pix1, pix2 (to be tested for equality) mindiff (minimum pixel difference to be counted; > 0) maxfract (maximum fraction of pixels allowed to have diff greater than or equal to mindiff) printstats (use 1 to print normalized histogram to stderr) Return: 0 if OK, 1 on error (a failure in similarity comparison is not an error)
Notes: (1) This function compares two pix for equality. If not in compare mode, on failure it writes to stderr. (2) To identify two images as 'similar', select to be the upper bound for what you expect. Typical values might be = 15 and = 0.01. (3) Normally, use = 0. In debugging mode, to see the relation between and the minimum value of for success, set this to 1.
LEPT_DLL l_int32 regTestCompareValues | ( | L_REGPARAMS * | rp, |
l_float32 | val1, | ||
l_float32 | val2, | ||
l_float32 | delta | ||
) |
Input: rp (regtest parameters) val1 (typ. the golden value) val2 (typ. the value computed) delta (allowed max absolute difference) Return: 0 if OK, 1 on error (a failure in comparison is not an error)
LEPT_DLL l_int32 regTestSetup | ( | l_int32 | argc, |
char ** | argv, | ||
L_REGPARAMS ** | prp | ||
) |
Input: argc (from invocation; can be either 1 or 2) argv (to regtest: [1] is one of these: "generate", "compare", "display") &rp (<return> all regression params) Return: 0 if OK, 1 on error
Notes: (1) Call this function with the args to the reg test. There are three cases: Case 1: The second arg is "generate". This will cause generation of new golden files for the reg test. The results of the reg test are not recorded, and the display field is set to FALSE, preventing image display. Case 2: The second arg is "compare". This is the mode in which you run a regression test (or a set of them), looking for failures and logging the results to a file. The output, which includes logging of all reg test failures plus a SUCCESS or FAILURE summary for each test, is appended to the file "/tmp/reg_results.txt. For this case, as in Case 1, the display field in rp is set to FALSE. Case 3: There is either only arg, or the second arg is "display". The test will run and files will be written. Comparisons with golden files will not be carried out, so the only notion of success or failure is with tests that do not involve golden files. The display field in rp is TRUE, and this is used by pixDisplayWithTitle(). (2) See regutils.h for examples of usage.
LEPT_DLL l_int32 regTestWritePixAndCheck | ( | L_REGPARAMS * | rp, |
PIX * | pix, | ||
l_int32 | format | ||
) |
Input: rp (regtest parameters) pix (to be written) format (of output pix) Return: 0 if OK, 1 on error (a failure in comparison is not an error)
Notes: (1) This function makes it easy to write the pix in a numbered sequence of files, and either to: (a) write the golden file ("generate" arg to regression test) (b) make a local file and "compare" with the golden file (c) make a local file and "display" the results (3) The canonical format of the local filename is: /tmp/<root of="" main="" name>="">.<count>.<format extension="" string>=""> e.g., for scale_reg, /tmp/scale.0.png
LEPT_DLL void resetMorphBoundaryCondition | ( | l_int32 | bc | ) |
Input: bc (SYMMETRIC_MORPH_BC, ASYMMETRIC_MORPH_BC) Return: void
LEPT_DLL l_float32 returnErrorFloat | ( | const char * | msg, |
const char * | procname, | ||
l_float32 | fval | ||
) |
Input: msg (error message) procname fval (return val) Return: fval
LEPT_DLL l_int32 returnErrorInt | ( | const char * | msg, |
const char * | procname, | ||
l_int32 | ival | ||
) |
Input: msg (error message) procname ival (return val) Return: ival (typically 1)
LEPT_DLL void* returnErrorPtr | ( | const char * | msg, |
const char * | procname, | ||
void * | pval | ||
) |
Input: msg (error message) procname pval (return val) Return: pval (typically null)
LEPT_DLL void rotate90Low | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | d, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_int32 | direction | ||
) |
direction: 1 for cw rotation -1 for ccw rotation
Notes: (1) The dest must be cleared in advance because not all source pixels are written to the destination.
LEPT_DLL void rotateAMColorCornerLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_float32 | angle, | ||
l_uint32 | colorval | ||
) |
LEPT_DLL void rotateAMColorFastLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_float32 | angle, | ||
l_uint32 | colorval | ||
) |
This is a special simplification of area mapping with division of each pixel into 16 sub-pixels. The exact coefficients that should be used are the same as for the 4x linear interpolation scaling case, and are given there. I tried to approximate these as weighted coefficients with a maximum sum of 4, which allows us to do the arithmetic in parallel for the R, G and B components in a 32 bit pixel. However, there are three reasons for not doing that: (1) the loss of accuracy in the parallel implementation is visually significant (2) the parallel implementation (described below) is slower (3) the parallel implementation requires allocation of a temporary color image
There are 16 cases for the choice of the subpixel, and for each, the mapping to the relevant source pixels is as follows:
subpixel src pixel weights -------- ----------------- 0 sp1 1 (3 * sp1 + sp2) / 4 2 (sp1 + sp2) / 2 3 (sp1 + 3 * sp2) / 4 4 (3 * sp1 + sp3) / 4 5 (9 * sp1 + 3 * sp2 + 3 * sp3 + sp4) / 16 6 (3 * sp1 + 3 * sp2 + sp3 + sp4) / 8 7 (3 * sp1 + 9 * sp2 + sp3 + 3 * sp4) / 16 8 (sp1 + sp3) / 2 9 (3 * sp1 + sp2 + 3 * sp3 + sp4) / 8 10 (sp1 + sp2 + sp3 + sp4) / 4 11 (sp1 + 3 * sp2 + sp3 + 3 * sp4) / 8 12 (sp1 + 3 * sp3) / 4 13 (3 * sp1 + sp2 + 9 * sp3 + 3 * sp4) / 16 14 (sp1 + sp2 + 3 * sp3 + 3 * sp4) / 8 15 (sp1 + 3 * sp2 + 3 * sp3 + 9 * sp4) / 16
Another way to visualize this is to consider the area mapping (or linear interpolation) coefficients for the pixel sp1. Expressed in fourths, they can be written as asymmetric matrix:
4 3 2 1 3 2.25 1.5 0.75 2 1.5 1 0.5 1 0.75 0.5 0.25
The coefficients for the three neighboring pixels can be similarly written.
This is implemented here, where, for each color component, we inline its extraction from each participating word, construct the linear combination, and combine the results into the destination 32 bit RGB pixel, using the appropriate shifts.
It is interesting to note that an alternative method, where we do the arithmetic on the 32 bit pixels directly (after shifting the components so they won't overflow into each other) is significantly inferior. Because we have only 8 bits for internal overflows, which can be distributed as 2, 3, 3, it is impossible to add these with the correct linear interpolation coefficients, which require a sum of up to 16. Rounding off to a sum of 4 causes appreciable visual artifacts in the rotated image. The code for the inferior method can be found in prog/rotatefastalt.c, for reference.
*** Warning: explicit assumption about RGB component ordering ***
LEPT_DLL void rotateAMColorLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_float32 | angle, | ||
l_uint32 | colorval | ||
) |
LEPT_DLL void rotateAMGrayCornerLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_float32 | angle, | ||
l_uint8 | grayval | ||
) |
LEPT_DLL void rotateAMGrayLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_float32 | angle, | ||
l_uint8 | grayval | ||
) |
LEPT_DLL l_int32 runlengthMembershipOnLine | ( | l_int32 * | buffer, |
l_int32 | size, | ||
l_int32 | depth, | ||
l_int32 * | start, | ||
l_int32 * | end, | ||
l_int32 | n | ||
) |
Input: buffer (into which full line of data is placed) size (full size of line; w or h) depth (8 or 16 bpp) start (array of start positions for fg runs) end (array of end positions for fg runs) n (the number of runs) Return: 0 if OK; 1 on error
Notes: (1) Converts a set of runlengths into a buffer of runlength membership values. (2) Initialization of the array gives pixels that are not within a run the value 0.
LEPT_DLL l_int32 saConcatenatePdf | ( | SARRAY * | sa, |
const char * | fileout | ||
) |
Input: sarray (of pathnames for single-page pdf files) fileout (concatenated pdf file) Return: 0 if OK, 1 on error
Notes: (1) This only works with leptonica-formatted single-page pdf files.
LEPT_DLL l_int32 saConcatenatePdfToData | ( | SARRAY * | sa, |
l_uint8 ** | pdata, | ||
size_t * | pnbytes | ||
) |
Input: sarray (of pathnames for single-page pdf files) &data (<return> concatenated pdf data in memory) &nbytes (<return> number of bytes in pdf data) Return: 0 if OK, 1 on error
Notes: (1) This only works with leptonica-formatted single-page pdf files.
LEPT_DLL l_int32 saConvertFilesToPdf | ( | SARRAY * | sa, |
l_int32 | res, | ||
l_float32 | scalefactor, | ||
l_int32 | type, | ||
l_int32 | quality, | ||
const char * | title, | ||
const char * | fileout | ||
) |
Input: sarray (of pathnames for images) res (input resolution of all images) scalefactor (scaling factor applied to each image; > 0.0) type (encoding type (L_JPEG_ENCODE, L_G4_ENCODE, L_FLATE_ENCODE, or 0 for default) quality (used for JPEG only; 0 for default (75)) title (<optional> pdf title; if null, taken from the first image filename) fileout (pdf file of all images) Return: 0 if OK, 1 on error
Notes: (1) See convertFilesToPdf().
LEPT_DLL l_int32 saConvertFilesToPdfData | ( | SARRAY * | sa, |
l_int32 | res, | ||
l_float32 | scalefactor, | ||
l_int32 | type, | ||
l_int32 | quality, | ||
const char * | title, | ||
l_uint8 ** | pdata, | ||
size_t * | pnbytes | ||
) |
Input: sarray (of pathnames for images) res (input resolution of all images) scalefactor (scaling factor applied to each image; > 0.0) type (encoding type (L_JPEG_ENCODE, L_G4_ENCODE, L_FLATE_ENCODE, or 0 for default) quality (used for JPEG only; 0 for default (75)) title (<optional> pdf title; if null, taken from the first image filename) &data (<return> output pdf data (of all images) &nbytes (<return> size of output pdf data) Return: 0 if OK, 1 on error
Notes: (1) See convertFilesToPdf().
LEPT_DLL l_int32 sarrayAddString | ( | SARRAY * | sa, |
char * | string, | ||
l_int32 | copyflag | ||
) |
Input: sarray string (string to be added) copyflag (L_INSERT, L_COPY) Return: 0 if OK, 1 on error
Notes: (1) Legacy usage decrees that we always use 0 to insert a string directly and 1 to insert a copy of the string. The enums for L_INSERT and L_COPY agree with this convention, and will not change in the future. (2) See usage comments at the top of this file.
LEPT_DLL l_int32 sarrayAppend | ( | const char * | filename, |
SARRAY * | sa | ||
) |
Input: filename sarray Return: 0 if OK; 1 on error
Input: sa1 (to be added to) sa2 (append specified range of strings in sa2 to sa1) start (index of first string of sa2 to append) end (index of last string of sa2 to append; -1 to end of array) Return: 0 if OK, 1 on error
Notes: (1) Copies of the strings in sarray2 are added to sarray1. (2) The [start ... end] range is truncated if necessary. (3) Use end == -1 to append to the end of sa2.
LEPT_DLL l_int32 sarrayChangeRefcount | ( | SARRAY * | sa, |
l_int32 | delta | ||
) |
sarrayChangeRefCount()
Input: sarray delta (change to be applied) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 sarrayClear | ( | SARRAY * | sa | ) |
Input: sarray Return: 0 if OK; 1 on error
LEPT_DLL SARRAY* sarrayClone | ( | SARRAY * | sa | ) |
Input: sarray Return: ptr to same sarray, or null on error
LEPT_DLL l_int32 sarrayConcatenate | ( | SARRAY * | sa1, |
SARRAY * | sa2 | ||
) |
Input: sa1 (to be added to) sa2 (append to sa1) Return: 0 if OK, 1 on error
Notes: (1) Copies of the strings in sarray2 are added to sarray1.
LEPT_DLL l_int32 sarrayConvertFilesFittedToPS | ( | SARRAY * | sa, |
l_float32 | xpts, | ||
l_float32 | ypts, | ||
const char * | fileout | ||
) |
LEPT_DLL l_int32 sarrayConvertFilesToPS | ( | SARRAY * | sa, |
l_int32 | res, | ||
const char * | fileout | ||
) |
LEPT_DLL SARRAY* sarrayConvertWordsToLines | ( | SARRAY * | sa, |
l_int32 | linesize | ||
) |
Input: sa (sa of individual words) linesize (max num of chars in each line) Return: saout (sa of formatted lines), or null on error
This is useful for re-typesetting text to a specific maximum line length. The individual words in the input sarray are concatenated into textlines. An input word string of zero length is taken to be a paragraph separator. Each time such a string is found, the current line is ended and a new line is also produced that contains just the string of zero length (""). When the output sarray of lines is eventually converted to a string with newlines (typically) appended to each line string, the empty strings are just converted to newlines, producing the visible paragraph separation.
What happens when a word is larger than linesize? We write it out as a single line anyway! Words preceding or following this long word are placed on lines preceding or following the line with the long word. Why this choice? Long "words" found in text documents are typically URLs, and it's often desirable not to put newlines in the middle of a URL. The text display program (e.g., text editor) will typically wrap the long "word" to fit in the window.
LEPT_DLL SARRAY* sarrayCopy | ( | SARRAY * | sa | ) |
Input: sarray Return: copy of sarray, or null on error
LEPT_DLL SARRAY* sarrayCreate | ( | l_int32 | n | ) |
Input: size of string ptr array to be alloc'd (use 0 for default) Return: sarray, or null on error
LEPT_DLL SARRAY* sarrayCreateInitialized | ( | l_int32 | n, |
char * | initstr | ||
) |
Input: n (size of string ptr array to be alloc'd) initstr (string to be initialized on the full array) Return: sarray, or null on error
LEPT_DLL SARRAY* sarrayCreateLinesFromString | ( | char * | string, |
l_int32 | blankflag | ||
) |
Input: string blankflag (0 to exclude blank lines; 1 to include) Return: sarray, or null on error
Notes: (1) This finds the number of line substrings, each of which ends with a newline, and puts a copy of each substring in a new sarray. (2) The newline characters are removed from each substring.
LEPT_DLL SARRAY* sarrayCreateWordsFromString | ( | const char * | string | ) |
Input: string Return: sarray, or null on error
Notes: (1) This finds the number of word substrings, creates an sarray of this size, and puts copies of each substring into the sarray.
LEPT_DLL void sarrayDestroy | ( | SARRAY ** | psa | ) |
Input: &sarray <to be="" nulled>=""> Return: void
Notes: (1) Decrements the ref count and, if 0, destroys the sarray. (2) Always nulls the input ptr.
LEPT_DLL l_int32 sarrayExtendArray | ( | SARRAY * | sa | ) |
Input: sarray Return: 0 if OK, 1 on error
LEPT_DLL char** sarrayGetArray | ( | SARRAY * | sa, |
l_int32 * | pnalloc, | ||
l_int32 * | pn | ||
) |
Input: sarray &nalloc (<optional return>=""> number allocated string ptrs) &n (<optional return>=""> number allocated strings) Return: ptr to string array, or null on error
Notes: (1) Caution: the returned array is not a copy, so caller must not destroy it!
LEPT_DLL l_int32 sarrayGetCount | ( | SARRAY * | sa | ) |
Input: sarray Return: count, or 0 if no strings or on error
LEPT_DLL l_int32 sarrayGetRefcount | ( | SARRAY * | sa | ) |
sarrayGetRefCount()
Input: sarray Return: refcount, or UNDEF on error
LEPT_DLL char* sarrayGetString | ( | SARRAY * | sa, |
l_int32 | index, | ||
l_int32 | copyflag | ||
) |
Input: sarray index (to the index-th string) copyflag (L_NOCOPY or L_COPY) Return: string, or null on error
Notes: (1) Legacy usage decrees that we always use 0 to get the pointer to the string itself, and 1 to get a copy of the string. (2) See usage comments at the top of this file. (3) To get a pointer to the string itself, use for copyflag: L_NOCOPY or 0 or FALSE To get a copy of the string, use for copyflag: L_COPY or 1 or TRUE The const values of L_NOCOPY and L_COPY are guaranteed not to change.
LEPT_DLL l_int32 sarrayPadToSameSize | ( | SARRAY * | sa1, |
SARRAY * | sa2, | ||
char * | padstring | ||
) |
Input: sa1, sa2 padstring Return: 0 if OK, 1 on error
Notes: (1) If two sarrays have different size, this adds enough instances of to the smaller so that they are the same size. It is useful when two or more sarrays are being sequenced in parallel, and it is necessary to find a valid string at each index.
LEPT_DLL l_int32 sarrayParseRange | ( | SARRAY * | sa, |
l_int32 | start, | ||
l_int32 * | pactualstart, | ||
l_int32 * | pend, | ||
l_int32 * | pnewstart, | ||
const char * | substr, | ||
l_int32 | loc | ||
) |
Input: sa (input sarray) start (index to start range search) &actualstart (<return> index of actual start; may be > 'start') &end (<return> index of end) &newstart (<return> index of start of next range) substr (substring for matching at beginning of string) loc (byte offset within the string for the pattern; use -1 if the location does not matter); Return: 0 if valid range found; 1 otherwise
Notes: (1) This finds the range of the next set of strings in SA, beginning the search at 'start', that does NOT have the substring 'substr' either at the indicated location in the string or anywhere in the string. The input variable 'loc' is the specified offset within the string; use -1 to indicate 'anywhere in the string'. (2) Always check the return value to verify that a valid range was found. (3) If a valid range is not found, the values of actstart, end and newstart are all set to the size of sa. (4) If this is the last valid range, newstart returns the value n. In use, this should be tested before calling the function. (5) Usage example. To find all the valid ranges in a file where the invalid lines begin with two dashes, copy each line in the file to a string in an sarray, and do: start = 0; while (!sarrayParseRange(sa, start, &actstart, &end, &start, "--", 0)) fprintf(stderr, "start = %d, end = %d\n", actstart, end);
LEPT_DLL SARRAY* sarrayRead | ( | const char * | filename | ) |
Input: filename Return: sarray, or null on error
LEPT_DLL SARRAY* sarrayReadStream | ( | FILE * | fp | ) |
Input: stream Return: sarray, or null on error
Notes: (1) We store the size of each string along with the string. (2) This allows a string to have embedded newlines. By reading the entire string, as determined by its size, we are not affected by any number of embedded newlines.
LEPT_DLL char* sarrayRemoveString | ( | SARRAY * | sa, |
l_int32 | index | ||
) |
Input: sarray index (of string within sarray) Return: removed string, or null on error
LEPT_DLL l_int32 sarrayReplaceString | ( | SARRAY * | sa, |
l_int32 | index, | ||
char * | newstr, | ||
l_int32 | copyflag | ||
) |
Input: sarray index (of string within sarray to be replaced) newstr (string to replace existing one) copyflag (L_INSERT, L_COPY) Return: 0 if OK, 1 on error
Notes: (1) This destroys an existing string and replaces it with the new string or a copy of it. (2) By design, an sarray is always compacted, so there are never any holes (null ptrs) in the ptr array up to the current count.
Input: sain (input sarray) first (index of first string to be selected) last (index of last string to be selected; use 0 to go to the end of the sarray) Return: saout (output sarray), or null on error
Notes: (1) This makes consisting of copies of all strings in in the index set [first ... last]. Use == 0 to get all strings from to the last string in the sarray.
LEPT_DLL SARRAY* sarraySelectBySubstring | ( | SARRAY * | sain, |
const char * | substr | ||
) |
Input: sain (input sarray) substr (<optional> substring for matching; can be NULL) Return: saout (output sarray, filtered with substring) or null on error
Notes: (1) This selects all strings in sain that have substr as a substring. Note that we can't use strncmp() because we're looking for a match to the substring anywhere within each filename. (2) If substr == NULL, returns a copy of the sarray.
Input: saout (output sarray; can be NULL or equal to sain) sain (input sarray) sortorder (L_SORT_INCREASING or L_SORT_DECREASING) Return: saout (output sarray, sorted by ascii value), or null on error
Notes: (1) Set saout = sain for in-place; otherwise, set naout = NULL. (2) Shell sort, modified from K&R, 2nd edition, p.62. Slow but simple O(n logn) sort.
LEPT_DLL l_int32 sarraySplitString | ( | SARRAY * | sa, |
const char * | str, | ||
const char * | separators | ||
) |
LEPT_DLL char* sarrayToString | ( | SARRAY * | sa, |
l_int32 | addnlflag | ||
) |
Input: sarray addnlflag (flag: 0 adds nothing to each substring 1 adds '
' to each substring 2 adds ' ' to each substring) Return: dest string, or null on error
Notes: (1) Concatenates all the strings in the sarray, preserving all white space. (2) If addnlflag != 0, adds either a '
' or a ' ' after each substring. (3) This function was NOT implemented as: for (i = 0; i < n; i++) strcat(dest, sarrayGetString(sa, i, L_NOCOPY)); Do you see why?
LEPT_DLL char* sarrayToStringRange | ( | SARRAY * | sa, |
l_int32 | first, | ||
l_int32 | nstrings, | ||
l_int32 | addnlflag | ||
) |
Input: sarray first (index of first string to use; starts with 0) nstrings (number of strings to append into the result; use 0 to append to the end of the sarray) addnlflag (flag: 0 adds nothing to each substring 1 adds '
' to each substring 2 adds ' ' to each substring) Return: dest string, or null on error
Notes: (1) Concatenates the specified strings inthe sarray, preserving all white space. (2) If addnlflag != 0, adds either a '
' or a ' ' after each substring. (3) If the sarray is empty, this returns a string with just the character corresponding to .
LEPT_DLL l_int32 sarrayWrite | ( | const char * | filename, |
SARRAY * | sa | ||
) |
Input: filename sarray Return: 0 if OK; 1 on error
LEPT_DLL l_int32 sarrayWriteStream | ( | FILE * | fp, |
SARRAY * | sa | ||
) |
Input: stream sarray Returns 0 if OK; 1 on error
Notes: (1) This appends a '
' to each string, which is stripped off by sarrayReadStream().
LEPT_DLL void scaleAreaMapLow2 | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | d, | ||
l_int32 | wpls | ||
) |
Note: This function is called with either 8 bpp gray or 32 bpp RGB. The result is a 2x reduced dest.
LEPT_DLL l_int32 scaleBinaryLow | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | ws, | ||
l_int32 | hs, | ||
l_int32 | wpls | ||
) |
LEPT_DLL l_int32 scaleBySamplingLow | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | ws, | ||
l_int32 | hs, | ||
l_int32 | d, | ||
l_int32 | wpls | ||
) |
Notes: (1) The dest must be cleared prior to this operation, and we clear it here in the low-level code. (2) We reuse dest pixels and dest pixel rows whenever possible. This speeds the upscaling; downscaling is done by strict subsampling and is unaffected. (3) Because we are sampling and not interpolating, this routine works directly, without conversion to full RGB color, for 2, 4 or 8 bpp palette color images.
LEPT_DLL void scaleColor2xLILineLow | ( | l_uint32 * | lined, |
l_int32 | wpld, | ||
l_uint32 * | lines, | ||
l_int32 | ws, | ||
l_int32 | wpls, | ||
l_int32 | lastlineflag | ||
) |
Input: lined (ptr to top destline, to be made from current src line) wpld lines (ptr to current src line) ws wpls lastlineflag (1 if last src line; 0 otherwise) Return: void
*** Warning: implicit assumption about RGB component ordering ***
LEPT_DLL void scaleColor2xLILow | ( | l_uint32 * | datad, |
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | ws, | ||
l_int32 | hs, | ||
l_int32 | wpls | ||
) |
This is a special case of 2x expansion by linear interpolation. Each src pixel contains 4 dest pixels. The 4 dest pixels in src pixel 1 are numbered at their UL corners. The 4 dest pixels in src pixel 1 are related to that src pixel and its 3 neighboring src pixels as follows:
1-----2-----|-----|-----| | | | | | | | | | | src 1 --> 3-----4-----| | | <-- src 2 | | | | | | | | | | |-----|-----|-----|-----| | | | | | | | | | | src 3 --> | | | | | <-- src 4 | | | | | | | | | | |-----|-----|-----|-----|
dest src ---- --- dp1 = sp1 dp2 = (sp1 + sp2) / 2 dp3 = (sp1 + sp3) / 2 dp4 = (sp1 + sp2 + sp3 + sp4) / 4
We iterate over the src pixels, and unroll the calculation for each set of 4 dest pixels corresponding to that src pixel, caching pixels for the next src pixel whenever possible. The method is exactly analogous to the one we use for scaleGray2xLILow() and its line version.
P3 speed is about 5 x 10^7 dst pixels/sec/GHz
LEPT_DLL void scaleColorAreaMapLow | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | ws, | ||
l_int32 | hs, | ||
l_int32 | wpls | ||
) |
This should only be used for downscaling. We choose to divide each pixel into 16 x 16 sub-pixels. This is much slower than scaleSmoothLow(), but it gives a better representation, esp. for downscaling factors between 1.5 and 5. All src pixels are subdivided into 256 sub-pixels, and are weighted by the number of sub-pixels covered by the dest pixel. This is about 2x slower than scaleSmoothLow(), but the results are significantly better on small text.
LEPT_DLL void scaleColorLILow | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | ws, | ||
l_int32 | hs, | ||
l_int32 | wpls | ||
) |
We choose to divide each pixel into 16 x 16 sub-pixels. Linear interpolation is equivalent to finding the fractional area (i.e., number of sub-pixels divided by 256) associated with each of the four nearest src pixels, and weighting each pixel value by this fractional area.
P3 speed is about 7 x 10^6 dst pixels/sec/GHz
LEPT_DLL void scaleGray2xLILineLow | ( | l_uint32 * | lined, |
l_int32 | wpld, | ||
l_uint32 * | lines, | ||
l_int32 | ws, | ||
l_int32 | wpls, | ||
l_int32 | lastlineflag | ||
) |
Input: lined (ptr to top destline, to be made from current src line) wpld lines (ptr to current src line) ws wpls lastlineflag (1 if last src line; 0 otherwise) Return: void
LEPT_DLL void scaleGray2xLILow | ( | l_uint32 * | datad, |
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | ws, | ||
l_int32 | hs, | ||
l_int32 | wpls | ||
) |
This is a special case of 2x expansion by linear interpolation. Each src pixel contains 4 dest pixels. The 4 dest pixels in src pixel 1 are numbered at their UL corners. The 4 dest pixels in src pixel 1 are related to that src pixel and its 3 neighboring src pixels as follows:
1-----2-----|-----|-----| | | | | | | | | | | src 1 --> 3-----4-----| | | <-- src 2 | | | | | | | | | | |-----|-----|-----|-----| | | | | | | | | | | src 3 --> | | | | | <-- src 4 | | | | | | | | | | |-----|-----|-----|-----|
dest src ---- --- dp1 = sp1 dp2 = (sp1 + sp2) / 2 dp3 = (sp1 + sp3) / 2 dp4 = (sp1 + sp2 + sp3 + sp4) / 4
We iterate over the src pixels, and unroll the calculation for each set of 4 dest pixels corresponding to that src pixel, caching pixels for the next src pixel whenever possible.
LEPT_DLL void scaleGray4xLILineLow | ( | l_uint32 * | lined, |
l_int32 | wpld, | ||
l_uint32 * | lines, | ||
l_int32 | ws, | ||
l_int32 | wpls, | ||
l_int32 | lastlineflag | ||
) |
Input: lined (ptr to top destline, to be made from current src line) wpld lines (ptr to current src line) ws wpls lastlineflag (1 if last src line; 0 otherwise) Return: void
LEPT_DLL void scaleGray4xLILow | ( | l_uint32 * | datad, |
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | ws, | ||
l_int32 | hs, | ||
l_int32 | wpls | ||
) |
This is a special case of 4x expansion by linear interpolation. Each src pixel contains 16 dest pixels. The 16 dest pixels in src pixel 1 are numbered at their UL corners. The 16 dest pixels in src pixel 1 are related to that src pixel and its 3 neighboring src pixels as follows:
1---2---3---4---|---|---|---|---| | | | | | | | | | 5---6---7---8---|---|---|---|---| | | | | | | | | | src 1 --> 9---a---b---c---|---|---|---|---| <-- src 2 | | | | | | | | | d---e---f---g---|---|---|---|---| | | | | | | | | | |===|===|===|===|===|===|===|===| | | | | | | | | | |---|---|---|---|---|---|---|---| | | | | | | | | | src 3 --> |---|---|---|---|---|---|---|---| <-- src 4 | | | | | | | | | |---|---|---|---|---|---|---|---| | | | | | | | | | |---|---|---|---|---|---|---|---|
dest src ---- --- dp1 = sp1 dp2 = (3 * sp1 + sp2) / 4 dp3 = (sp1 + sp2) / 2 dp4 = (sp1 + 3 * sp2) / 4 dp5 = (3 * sp1 + sp3) / 4 dp6 = (9 * sp1 + 3 * sp2 + 3 * sp3 + sp4) / 16 dp7 = (3 * sp1 + 3 * sp2 + sp3 + sp4) / 8 dp8 = (3 * sp1 + 9 * sp2 + 1 * sp3 + 3 * sp4) / 16 dp9 = (sp1 + sp3) / 2 dp10 = (3 * sp1 + sp2 + 3 * sp3 + sp4) / 8 dp11 = (sp1 + sp2 + sp3 + sp4) / 4 dp12 = (sp1 + 3 * sp2 + sp3 + 3 * sp4) / 8 dp13 = (sp1 + 3 * sp3) / 4 dp14 = (3 * sp1 + sp2 + 9 * sp3 + 3 * sp4) / 16 dp15 = (sp1 + sp2 + 3 * sp3 + 3 * sp4) / 8 dp16 = (sp1 + 3 * sp2 + 3 * sp3 + 9 * sp4) / 16
We iterate over the src pixels, and unroll the calculation for each set of 16 dest pixels corresponding to that src pixel, caching pixels for the next src pixel whenever possible.
LEPT_DLL void scaleGrayAreaMapLow | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | ws, | ||
l_int32 | hs, | ||
l_int32 | wpls | ||
) |
This should only be used for downscaling. We choose to divide each pixel into 16 x 16 sub-pixels. This is about 2x slower than scaleSmoothLow(), but the results are significantly better on small text, esp. for downscaling factors between 1.5 and 5. All src pixels are subdivided into 256 sub-pixels, and are weighted by the number of sub-pixels covered by the dest pixel.
LEPT_DLL void scaleGrayLILow | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | ws, | ||
l_int32 | hs, | ||
l_int32 | wpls | ||
) |
We choose to divide each pixel into 16 x 16 sub-pixels. Linear interpolation is equivalent to finding the fractional area (i.e., number of sub-pixels divided by 256) associated with each of the four nearest src pixels, and weighting each pixel value by this fractional area.
LEPT_DLL l_int32 scaleMipmapLow | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas1, | ||
l_int32 | wpls1, | ||
l_uint32 * | datas2, | ||
l_int32 | wpls2, | ||
l_float32 | red | ||
) |
See notes in scale.c for pixScaleToGrayMipmap(). This function is here for pedagogical reasons. It gives poor results on document images because of aliasing.
LEPT_DLL void scaleRGBToGray2Low | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_float32 | rwt, | ||
l_float32 | gwt, | ||
l_float32 | bwt | ||
) |
Note: This function is called with 32 bpp RGB src and 8 bpp, half-resolution dest. The weights should add to 1.0.
LEPT_DLL l_int32 scaleSmoothLow | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | ws, | ||
l_int32 | hs, | ||
l_int32 | d, | ||
l_int32 | wpls, | ||
l_int32 | size | ||
) |
Notes: (1) This function is called on 8 or 32 bpp src and dest images. (2) size is the full width of the lowpass smoothing filter. It is correlated with the reduction ratio, being the nearest integer such that size is approximately equal to hs / hd.
LEPT_DLL void scaleToGray16Low | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_int32 * | tab8 | ||
) |
Input: usual image variables tab8 (made from makePixelSumTab8()) Return: 0 if OK; 1 on error.
The output is processed one dest byte at a time, corresponding to 16 rows consisting each of 2 src bytes in the input image. This uses one lookup table, tab8, which gives the sum of ON pixels in a byte. After summing for all ON pixels in the 32 src bytes, which is between 0 and 256, this is converted to an 8 bpp grayscale value between 0 (for 255 or 256 bits ON) and 255 (for 0 bits ON).
LEPT_DLL void scaleToGray2Low | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_uint32 * | sumtab, | ||
l_uint8 * | valtab | ||
) |
Input: usual image variables sumtab (made from makeSumTabSG2()) valtab (made from makeValTabSG2()) Return: 0 if OK; 1 on error.
The output is processed in sets of 4 output bytes on a row, corresponding to 4 2x2 bit-blocks in the input image. Two lookup tables are used. The first, sumtab, gets the sum of ON pixels in 4 sets of two adjacent bits, storing the result in 4 adjacent bytes. After sums from two rows have been added, the second table, valtab, converts from the sum of ON pixels in the 2x2 block to an 8 bpp grayscale value between 0 (for 4 bits ON) and 255 (for 0 bits ON).
LEPT_DLL void scaleToGray3Low | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_uint32 * | sumtab, | ||
l_uint8 * | valtab | ||
) |
Input: usual image variables sumtab (made from makeSumTabSG3()) valtab (made from makeValTabSG3()) Return: 0 if OK; 1 on error
Each set of 8 3x3 bit-blocks in the source image, which consist of 72 pixels arranged 24 pixels wide by 3 scanlines, is converted to a row of 8 8-bit pixels in the dest image. These 72 pixels of the input image are runs of 24 pixels in three adjacent scanlines. Each run of 24 pixels is stored in the 24 LSbits of a 32-bit word. We use 2 LUTs. The first, sumtab, takes 6 of these bits and stores sum, taken 3 bits at a time, in two bytes. (See makeSumTabSG3). This is done for each of the 3 scanlines, and the results are added. We now have the sum of ON pixels in the first two 3x3 blocks in two bytes. The valtab LUT then converts these values (which go from 0 to 9) to grayscale values between between 255 and 0. (See makeValTabSG3). This process is repeated for each of the other 3 sets of 6x3 input pixels, giving 8 output pixels in total.
Note: because the input image is processed in groups of 24 x 3 pixels, the process clips the input height to (h - h % 3) and the input width to (w - w % 24).
LEPT_DLL void scaleToGray4Low | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_uint32 * | sumtab, | ||
l_uint8 * | valtab | ||
) |
Input: usual image variables sumtab (made from makeSumTabSG4()) valtab (made from makeValTabSG4()) Return: 0 if OK; 1 on error.
The output is processed in sets of 2 output bytes on a row, corresponding to 2 4x4 bit-blocks in the input image. Two lookup tables are used. The first, sumtab, gets the sum of ON pixels in two sets of four adjacent bits, storing the result in 2 adjacent bytes. After sums from four rows have been added, the second table, valtab, converts from the sum of ON pixels in the 4x4 block to an 8 bpp grayscale value between 0 (for 16 bits ON) and 255 (for 0 bits ON).
LEPT_DLL void scaleToGray6Low | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_int32 * | tab8, | ||
l_uint8 * | valtab | ||
) |
Input: usual image variables tab8 (made from makePixelSumTab8()) valtab (made from makeValTabSG6()) Return: 0 if OK; 1 on error
Each set of 4 6x6 bit-blocks in the source image, which consist of 144 pixels arranged 24 pixels wide by 6 scanlines, is converted to a row of 4 8-bit pixels in the dest image. These 144 pixels of the input image are runs of 24 pixels in six adjacent scanlines. Each run of 24 pixels is stored in the 24 LSbits of a 32-bit word. We use 2 LUTs. The first, tab8, takes 6 of these bits and stores sum in one byte. This is done for each of the 6 scanlines, and the results are added. We now have the sum of ON pixels in the first 6x6 block. The valtab LUT then converts these values (which go from 0 to 36) to grayscale values between between 255 and 0. (See makeValTabSG6). This process is repeated for each of the other 3 sets of 6x6 input pixels, giving 4 output pixels in total.
Note: because the input image is processed in groups of 24 x 6 pixels, the process clips the input height to (h - h % 6) and the input width to (w - w % 24).
LEPT_DLL void scaleToGray8Low | ( | l_uint32 * | datad, |
l_int32 | wd, | ||
l_int32 | hd, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_int32 * | tab8, | ||
l_uint8 * | valtab | ||
) |
Input: usual image variables tab8 (made from makePixelSumTab8()) valtab (made from makeValTabSG8()) Return: 0 if OK; 1 on error.
The output is processed one dest byte at a time, corresponding to 8 rows of src bytes in the input image. Two lookup tables are used. The first, tab8, gets the sum of ON pixels in a byte. After sums from 8 rows have been added, the second table, valtab, converts from this value (which is between 0 and 64) to an 8 bpp grayscale value between 0 (for all 64 bits ON) and 255 (for 0 bits ON).
LEPT_DLL void seedfillBinaryLow | ( | l_uint32 * | datas, |
l_int32 | hs, | ||
l_int32 | wpls, | ||
l_uint32 * | datam, | ||
l_int32 | hm, | ||
l_int32 | wplm, | ||
l_int32 | connectivity | ||
) |
Notes: (1) This is an in-place fill, where the seed image is filled, clipping to the filling mask, in one full cycle of UL -> LR and LR -> UL raster scans. (2) Assume the mask is a filling mask, not a blocking mask. (3) Assume that the RHS pad bits of the mask are properly set to 0. (4) Clip to the smallest dimensions to avoid invalid reads.
LEPT_DLL void seedfillGrayInvLow | ( | l_uint32 * | datas, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpls, | ||
l_uint32 * | datam, | ||
l_int32 | wplm, | ||
l_int32 | connectivity | ||
) |
Notes: (1) The pixels are numbered as follows: 1 2 3 4 x 5 6 7 8 This low-level filling operation consists of two scans, raster and anti-raster, covering the entire seed image. During the anti-raster scan, every pixel p such that its current value could still be propogated during the next raster scanning is put into the FIFO-queue. Next step is the propagation step where where we update and propagate the values using FIFO structure created in anti-raster scan. (2) The "Inv" signifies the fact that in this case, filling of the seed only takes place when the seed value is greater than the mask value. The mask will act to stop the fill when it is higher than the seed level. (This is in contrast to conventional grayscale filling where the seed always fills below the mask.) (3) An example of use is a basin, described by the mask (pixm), where within the basin, the seed pix (pixs) gets filled to the height of the highest seed pixel that is above its corresponding max pixel. Filling occurs while the propagating seed pixels in pixs are larger than the corresponding mask values in pixm. (4) Reference paper : L. Vincent, Morphological grayscale reconstruction in image analysis: applications and efficient algorithms, IEEE Transactions on Image Processing, vol. 2, no. 2, pp. 176-201, 1993.
LEPT_DLL void seedfillGrayInvLowSimple | ( | l_uint32 * | datas, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpls, | ||
l_uint32 * | datam, | ||
l_int32 | wplm, | ||
l_int32 | connectivity | ||
) |
Notes: (1) The pixels are numbered as follows: 1 2 3 4 x 5 6 7 8 This low-level filling operation consists of two scans, raster and anti-raster, covering the entire seed image. The caller typically iterates until the filling is complete. (2) The "Inv" signifies the fact that in this case, filling of the seed only takes place when the seed value is greater than the mask value. The mask will act to stop the fill when it is higher than the seed level. (This is in contrast to conventional grayscale filling where the seed always fills below the mask.) (3) An example of use is a basin, described by the mask (pixm), where within the basin, the seed pix (pixs) gets filled to the height of the highest seed pixel that is above its corresponding max pixel. Filling occurs while the propagating seed pixels in pixs are larger than the corresponding mask values in pixm.
LEPT_DLL void seedfillGrayLow | ( | l_uint32 * | datas, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpls, | ||
l_uint32 * | datam, | ||
l_int32 | wplm, | ||
l_int32 | connectivity | ||
) |
Notes: (1) The pixels are numbered as follows: 1 2 3 4 x 5 6 7 8 This low-level filling operation consists of two scans, raster and anti-raster, covering the entire seed image. This is followed by a breadth-first propagation operation to complete the fill. During the anti-raster scan, every pixel p whose current value could still be propagated after the anti-raster scan is put into the FIFO queue. The propagation step is a breadth-first fill to completion. Unlike the simple grayscale seedfill pixSeedfillGraySimple(), where at least two full raster/anti-raster iterations are required for completion and verification, the hybrid method uses only a single raster/anti-raster set of scans. (2) The filling action can be visualized from the following example. Suppose the mask, which clips the fill, is a sombrero-shaped surface, where the highest point is 200 and the low pixels around the rim are 30. Beyond the rim, the mask goes up a bit. Suppose the seed, which is filled, consists of a single point of height 150, located below the max of the mask, with the rest 0. Then in the raster scan, nothing happens until the high seed point is encountered, and then this value is propagated right and down, until it hits the side of the sombrero. The seed can never exceed the mask, so it fills to the rim, going lower along the mask surface. When it passes the rim, the seed continues to fill at the rim height to the edge of the seed image. Then on the anti-raster scan, the seed fills flat inside the sombrero to the upper and left, and then out from the rim as before. The final result has a seed that is flat outside the rim, and inside it fills the sombrero but only up to 150. If the rim height varies, the filled seed outside the rim will be at the highest point on the rim, which is a saddle point on the rim. (3) Reference paper : L. Vincent, Morphological grayscale reconstruction in image analysis: applications and efficient algorithms, IEEE Transactions on Image Processing, vol. 2, no. 2, pp. 176-201, 1993.
LEPT_DLL void seedfillGrayLowSimple | ( | l_uint32 * | datas, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpls, | ||
l_uint32 * | datam, | ||
l_int32 | wplm, | ||
l_int32 | connectivity | ||
) |
Notes: (1) The pixels are numbered as follows: 1 2 3 4 x 5 6 7 8 This low-level filling operation consists of two scans, raster and anti-raster, covering the entire seed image. The caller typically iterates until the filling is complete. (2) The filling action can be visualized from the following example. Suppose the mask, which clips the fill, is a sombrero-shaped surface, where the highest point is 200 and the low pixels around the rim are 30. Beyond the rim, the mask goes up a bit. Suppose the seed, which is filled, consists of a single point of height 150, located below the max of the mask, with the rest 0. Then in the raster scan, nothing happens until the high seed point is encountered, and then this value is propagated right and down, until it hits the side of the sombrero. The seed can never exceed the mask, so it fills to the rim, going lower along the mask surface. When it passes the rim, the seed continues to fill at the rim height to the edge of the seed image. Then on the anti-raster scan, the seed fills flat inside the sombrero to the upper and left, and then out from the rim as before. The final result has a seed that is flat outside the rim, and inside it fills the sombrero but only up to 150. If the rim height varies, the filled seed outside the rim will be at the highest point on the rim, which is a saddle point on the rim.
LEPT_DLL void seedspreadLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datat, | ||
l_int32 | wplt, | ||
l_int32 | connectivity | ||
) |
See pixSeedspread() for a brief description of the algorithm here.
LEPT_DLL SELA* selaAddBasic | ( | SELA * | sela | ) |
Input: sela (<optional>) Return: sela with additional sels, or null on error
Notes: (1) Adds the following sels:
LEPT_DLL SELA* selaAddCrossJunctions | ( | SELA * | sela, |
l_float32 | hlsize, | ||
l_float32 | mdist, | ||
l_int32 | norient, | ||
l_int32 | debugflag | ||
) |
Input: sela (<optional>) hlsize (length of each line of hits from origin) mdist (distance of misses from the origin) norient (number of orientations; max of 8) debugflag (1 for debug output) Return: sela with additional sels, or null on error
Notes: (1) Adds hitmiss Sels for the intersection of two lines. If the lines are very thin, they must be nearly orthogonal to register. (2) The number of Sels generated is equal to . (3) If == 2, this generates 2 Sels of crosses, each with two perpendicular lines of hits. One Sel has horizontal and vertical hits; the other has hits along lines at +-45 degrees. Likewise, if == 3, this generates 3 Sels of crosses oriented at 30 degrees with each other. (4) It is suggested that be chosen at least 1 greater than . Try values of (, ) such as (6,5), (7,6), (8,7), (9,7), etc.
LEPT_DLL SELA* selaAddDwaCombs | ( | SELA * | sela | ) |
Input: sela (<optional>) Return: sela with additional sels, or null on error
Notes: (1) Adds all comb (horizontal, vertical) Sels that are used in composite linear morphological operations up to 63 pixels in length, which are the sizes over which dwa code can be generated.
LEPT_DLL SELA* selaAddDwaLinear | ( | SELA * | sela | ) |
Input: sela (<optional>) Return: sela with additional sels, or null on error
Notes: (1) Adds all linear (horizontal, vertical) sels from 2 to 63 pixels in length, which are the sizes over which dwa code can be generated.
LEPT_DLL SELA* selaAddHitMiss | ( | SELA * | sela | ) |
Input: sela (<optional>) Return: sela with additional sels, or null on error
Input: sela sel to be added selname (ignored if already defined in sel; req'd in sel when added to a sela) copyflag (for sel: 0 inserts, 1 copies) Return: 0 if OK; 1 on error
Notes: (1) This adds a sel, either inserting or making a copy. (2) Because every sel in a sela must have a name, it copies the input name if necessary. You can input NULL for selname if the sel already has a name.
LEPT_DLL SELA* selaAddTJunctions | ( | SELA * | sela, |
l_float32 | hlsize, | ||
l_float32 | mdist, | ||
l_int32 | norient, | ||
l_int32 | debugflag | ||
) |
Input: sela (<optional>) hlsize (length of each line of hits from origin) mdist (distance of misses from the origin) norient (number of orientations; max of 8) debugflag (1 for debug output) Return: sela with additional sels, or null on error
Notes: (1) Adds hitmiss Sels for the T-junction of two lines. If the lines are very thin, they must be nearly orthogonal to register. (2) The number of Sels generated is 4 * . (3) It is suggested that be chosen at least 1 greater than . Try values of (, ) such as (6,5), (7,6), (8,7), (9,7), etc.
LEPT_DLL SELA* selaCreate | ( | l_int32 | n | ) |
Input: n (initial number of sel ptrs; use 0 for default) Return: sela, or null on error
LEPT_DLL SELA* selaCreateFromFile | ( | const char * | filename | ) |
Input: filename Return: sela, or null on error
Notes: (1) The file contains a sequence of Sel descriptions. (2) Each Sel is formatted as follows:
LEPT_DLL void selaDestroy | ( | SELA ** | psela | ) |
Input: &sela (<to be="" nulled>="">) Return: void
LEPT_DLL PIX* selaDisplayInPix | ( | SELA * | sela, |
l_int32 | size, | ||
l_int32 | gthick, | ||
l_int32 | spacing, | ||
l_int32 | ncols | ||
) |
Input: sela size (of grid interiors; odd; minimum size of 13 is enforced) gthick (grid thickness; minimum size of 2 is enforced) spacing (between sels, both horizontally and vertically) ncols (number of sels per "line") Return: pix (display of all sels in sela), or null on error
Notes: (1) This gives a visual representation of all the sels in a sela. (2) See notes in selDisplayInPix() for display params of each sel. (3) This gives the nicest results when all sels in the sela are the same size.
LEPT_DLL l_int32 selaExtendArray | ( | SELA * | sela | ) |
Input: sela Return: 0 if OK; 1 on error
LEPT_DLL l_int32 selaFindSelByName | ( | SELA * | sela, |
const char * | name, | ||
l_int32 * | pindex, | ||
SEL ** | psel | ||
) |
Input: sela sel name &index (<optional, return>) &sel (<optional, return> sel (not a copy)) Return: 0 if OK; 1 on error
LEPT_DLL char* selaGetBrickName | ( | SELA * | sela, |
l_int32 | hsize, | ||
l_int32 | vsize | ||
) |
Input: sela hsize, vsize (of brick sel) Return: sel name (new string), or null if no name or on error
LEPT_DLL char* selaGetCombName | ( | SELA * | sela, |
l_int32 | size, | ||
l_int32 | direction | ||
) |
Input: sela size (the product of sizes of the brick and comb parts) direction (L_HORIZ, L_VERT) Return: sel name (new string), or null if name not found or on error
Notes: (1) Combs are by definition 1-dimensional, either horiz or vert. (2) Use this with comb Sels; e.g., from selaAddDwaCombs().
LEPT_DLL l_int32 selaGetCount | ( | SELA * | sela | ) |
Input: sela Return: count, or 0 on error
LEPT_DLL SEL* selaGetSel | ( | SELA * | sela, |
l_int32 | i | ||
) |
Input: sela index of sel to be retrieved (not copied) Return: sel, or null on error
Notes: (1) This returns a ptr to the sel, not a copy, so the caller must not destroy it!
LEPT_DLL SARRAY* selaGetSelnames | ( | SELA * | sela | ) |
Input: sela Return: sa (of all sel names), or null on error
Input: filename Return: sela, or null on error
LEPT_DLL SELA* selaReadStream | ( | FILE * | fp | ) |
Input: stream Return: sela, or null on error
Input: filename sela Return: 0 if OK, 1 on error
LEPT_DLL l_int32 selaWriteStream | ( | FILE * | fp, |
SELA * | sela | ||
) |
Input: stream sela Return: 0 if OK, 1 on error
Input: height, width name (<optional> sel name; can be null) Return: sel, or null on error
Notes: (1) selCreate() initializes all values to 0. (2) After this call, (cy,cx) and nonzero data values must be assigned. If a text name is not assigned here, it will be needed later when the sel is put into a sela.
Input: height, width cy, cx (origin, relative to UL corner at 0,0) type (SEL_HIT, SEL_MISS, or SEL_DONT_CARE) Return: sel, or null on error
Notes: (1) This is a rectangular sel of all hits, misses or don't cares.
Input: factor1 (contiguous space between comb tines) factor2 (number of comb tines) direction (L_HORIZ, L_VERT) Return: sel, or null on error
Notes: (1) This generates a comb Sel of hits with the origin as near the center as possible.
LEPT_DLL SEL* selCreateFromColorPix | ( | PIX * | pixs, |
char * | selname | ||
) |
Input: pixs (cmapped or rgb) selname (<optional> sel name; can be null) Return: sel if OK, null on error
Notes: (1) The sel size is given by the size of pixs. (2) In pixs, hits are represented by green pixels, misses by red pixels, and don't-cares by white pixels. (3) In pixs, there may be no misses, but there must be at least 1 hit. (4) At most there can be only one origin pixel, which is optionally specified by using a lower-intensity pixel: if a hit: dark green if a miss: dark red if a don't care: gray If there is no such pixel, the origin defaults to the approximate center of the sel.
Input: pix cy, cx (origin of sel) name (<optional> sel name; can be null) Return: sel, or null on error
Notes: (1) The origin must be positive.
Input: pta cy, cx (origin of sel) name (<optional> sel name; can be null) Return: sel (of minimum required size), or null on error
Notes: (1) The origin and all points in the pta must be positive.
LEPT_DLL SEL* selCreateFromString | ( | const char * | text, |
l_int32 | h, | ||
l_int32 | w, | ||
const char * | name | ||
) |
Input: text height, width name (<optional> sel name; can be null) Return: sel of the given size, or null on error
Notes: (1) The text is an array of chars (in row-major order) where each char can be one of the following: 'x': hit 'o': miss ' ': don't-care (2) Use an upper case char to indicate the origin of the Sel. When the origin falls on a don't-care, use 'C' as the uppecase for ' '. (3) The text can be input in a format that shows the 2D layout; e.g., static const char *seltext = "x " "x Oo " "x " "xxxxx";
LEPT_DLL void selDestroy | ( | SEL ** | psel | ) |
Input: &sel (<to be="" nulled>="">) Return: void
Input: sel size (of grid interiors; odd; minimum size of 13 is enforced) gthick (grid thickness; minimum size of 2 is enforced) Return: pix (display of sel), or null on error
Notes: (1) This gives a visual representation of a general (hit-miss) sel. (2) The empty sel is represented by a grid of intersecting lines. (3) Three different patterns are generated for the sel elements:
LEPT_DLL l_int32 selectComposableSels | ( | l_int32 | size, |
l_int32 | direction, | ||
SEL ** | psel1, | ||
SEL ** | psel2 | ||
) |
Input: size (of sel to be decomposed) &factor1 (<return> larger factor) &factor2 (<return> smaller factor) Return: 0 if OK, 1 on error
Notes: (1) This works for Sel sizes up to 62500, which seems sufficient. (2) The composable sel size is typically within +- 1 of the requested size. Up to size = 300, the maximum difference is +- 2. (3) We choose an overall cost function where the penalty for the size difference between input and actual is 4 times the penalty for additional rasterops. (4) Returned values: factor1 >= factor2 If size > 1, then factor1 > 1.
LEPT_DLL l_int32 selectDefaultPdfEncoding | ( | PIX * | pix, |
l_int32 * | ptype | ||
) |
Input: pix &type (<return> L_G4_ENCODE, L_JPEG_ENCODE, L_FLATE_ENCODE)
Notes: (1) This attempts to choose an encoding for the pix that results in the smallest file, assuming that if jpeg encoded, it will use quality = 75. The decision is approximate, in that (a) all colormapped images will be losslessly encoded with gzip (flate), and (b) an image with less than about 20 colors is likely to be smaller if flate encoded than if encoded as a jpeg (dct). For example, an image made by pixScaleToGray3() will have 10 colors, and flate encoding will give about twice the compression as jpeg with quality = 75.
LEPT_DLL l_int32 selFindMaxTranslations | ( | SEL * | sel, |
l_int32 * | pxp, | ||
l_int32 * | pyp, | ||
l_int32 * | pxn, | ||
l_int32 * | pyn | ||
) |
Input: sel &xp, &yp, &xn, &yn (<return> max shifts) Return: 0 if OK; 1 on error
Note: these are the maximum shifts for the erosion operation. For example, when j < cx, the shift of the image is +x to the cx. This is a positive xp shift.
Input: sel row col &type (<return> SEL_HIT, SEL_MISS, SEL_DONT_CARE) Return: 0 if OK; 1 on error
LEPT_DLL char* selGetName | ( | SEL * | sel | ) |
Input: sel Return: sel name (not copied), or null if no name or on error
LEPT_DLL l_int32 selGetParameters | ( | SEL * | sel, |
l_int32 * | psy, | ||
l_int32 * | psx, | ||
l_int32 * | pcy, | ||
l_int32 * | pcx | ||
) |
Input: sel &sy, &sx, &cy, &cx (<optional return>="">; each can be null) Return: 0 if OK, 1 on error
LEPT_DLL l_int32 selGetTypeAtOrigin | ( | SEL * | sel, |
l_int32 * | ptype | ||
) |
Input: sel &type (<return> SEL_HIT, SEL_MISS, SEL_DONT_CARE) Return: 0 if OK; 1 on error or if origin is not found
LEPT_DLL char* selPrintToString | ( | SEL * | sel | ) |
Input: sel Return: str (string; caller must free)
Notes: (1) This is an inverse function of selCreateFromString. It prints a textual representation of the SEL to a malloc'd string. The format is the same as selCreateFromString except that newlines are inserted into the output between rows. (2) This is useful for debugging. However, if you want to save some Sels in a file, put them in a Sela and write them out with selaWrite(). They can then be read in with selaRead().
LEPT_DLL SEL* selReadFromColorImage | ( | const char * | pathname | ) |
Input: pathname Return: sel if OK; null on error
Notes: (1) Loads an image from a file and creates a (hit-miss) sel. (2) The sel name is taken from the pathname without the directory and extension.
LEPT_DLL SEL* selReadStream | ( | FILE * | fp | ) |
Input: stream Return: sel, or null on error
LEPT_DLL SEL* selRotateOrth | ( | SEL * | sel, |
l_int32 | quads | ||
) |
Input: sel quads (0 - 4; number of 90 degree cw rotations) Return: seld, or null on error
Input: sel row col type (SEL_HIT, SEL_MISS, SEL_DONT_CARE) Return: 0 if OK; 1 on error
Notes: (1) Because we use row and column to index into an array, they are always non-negative. The location of the origin (and the type of operation) determine the actual direction of the rasterop.
LEPT_DLL l_int32 selSetName | ( | SEL * | sel, |
const char * | name | ||
) |
Input: sel name (<optional>; can be null) Return: 0 if OK, 1 on error
Notes: (1) Always frees the existing sel name, if defined. (2) If name is not defined, just clears any existing sel name.
Input: sel cy, cx Return: 0 if OK; 1 on error
Input: filename sel Return: 0 if OK, 1 on error
LEPT_DLL l_int32 selWriteStream | ( | FILE * | fp, |
SEL * | sel | ||
) |
Input: stream sel Return: 0 if OK, 1 on error
Input: line (ptr to beginning of line), x (pixel location in line) depth (bpp) val (to be inserted) Return: void
Notes: (1) Caution: input variables are not checked!
LEPT_DLL void setPixMemoryManager | ( | void * | allocator(size_t), |
void(deallocator(void *)) | |||
) |
Input: allocator (<optional>; use null to skip) deallocator (<optional>; use null to skip) Return: void
Notes: (1) Use this to change the alloc and/or dealloc functions; e.g., setPixMemoryManager(my_malloc, my_free).
LEPT_DLL void shiftDataHorizontalLow | ( | l_uint32 * | datad, |
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_int32 | shift | ||
) |
Input: datad (ptr to beginning of dest line) wpld (wpl of dest) datas (ptr to beginning of src line) wpls (wpl of src) shift (horizontal shift of block; >0 is to right) Return: void
Notes: (1) This can also be used for in-place operation; see, e.g., rasteropHipLow(). (2) We are clearing the pixels that are shifted in from outside the image. This can be overridden by the incolor parameter in higher-level functions that call this.
LEPT_DLL l_int32 splitPathAtDirectory | ( | const char * | pathname, |
char ** | pdir, | ||
char ** | ptail | ||
) |
Input: pathname (full path; can be a directory) &dir (<optional return>=""> root directory name of input path, including trailing '/') &tail (<optional return>=""> path tail, which is either the file name within the root directory or the last sub-directory in the path) Return: 0 if OK, 1 on error
Notes: (1) If you only want the tail, input null for the root directory ptr. (2) If you only want the root directory name, input null for the tail ptr. (3) This function makes decisions based only on the lexical structure of the input. Examples: /usr/tmp/abc --> dir: /usr/tmp/ tail: abc /usr/tmp/ --> dir: /usr/tmp/ tail: [empty string] /usr/tmp --> dir: /usr/ tail: tmp (4) N.B. The input pathname must have unix directory separators for unix and windows directory separators for windows.
LEPT_DLL l_int32 splitPathAtExtension | ( | const char * | pathname, |
char ** | pbasename, | ||
char ** | pextension | ||
) |
Input: pathname (full path; can be a directory) &basename (<optional return>=""> pathname not including the last dot and characters after that) &extension (<optional return>=""> path extension, which is the last dot and the characters after it. If there is no extension, it returns the empty string) Return: 0 if OK, 1 on error
Notes: (1) If you only want the extension, input null for the basename ptr. (2) If you only want the basename without extension, input null for the extension ptr. (3) This function makes decisions based only on the lexical structure of the input. Examples: /usr/tmp/abc.jpg --> basename: /usr/tmp/abc ext: .jpg /usr/tmp/.jpg --> basename: /usr/tmp/ tail: .jpg /usr/tmp.jpg/ --> basename: /usr/tmp.jpg/ tail: [empty str] ./.jpg --> basename: ./ tail: .jpg (4) N.B. The input pathname must have unix directory separators for unix and windows directory separators for windows.
LEPT_DLL SARRAY* splitStringToParagraphs | ( | char * | textstr, |
l_int32 | splitflag | ||
) |
Input: textstring splitting flag (see enum in bmf.h; valid values in {1,2,3}) Return: sarray (where each string is a paragraph of the input), or null on error.
LEPT_DLL l_int32 sreadHeaderPng | ( | const l_uint8 * | data, |
l_int32 * | pwidth, | ||
l_int32 * | pheight, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp, | ||
l_int32 * | piscmap | ||
) |
Input: data &width (<return>) &height (<return>) &bps (<return>, bits/sample) &spp (<return>, samples/pixel) &iscmap (<optional return>="">; input NULL to ignore) Return: 0 if OK, 1 on error
Notes: (1) If there is a colormap, iscmap is returned as 1; else 0.
LEPT_DLL l_int32 sreadHeaderPnm | ( | const l_uint8 * | cdata, |
size_t | size, | ||
l_int32 * | pwidth, | ||
l_int32 * | pheight, | ||
l_int32 * | pdepth, | ||
l_int32 * | ptype, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp | ||
) |
LEPT_DLL l_int32 sreadHeaderSpix | ( | const l_uint32 * | data, |
l_int32 * | pwidth, | ||
l_int32 * | pheight, | ||
l_int32 * | pbps, | ||
l_int32 * | pspp, | ||
l_int32 * | piscmap | ||
) |
Input: data &width (<return>) &height (<return>) &bps (<return>, bits/sample) &spp (<return>, samples/pixel) &iscmap (<optional return>="">; input NULL to ignore) Return: 0 if OK, 1 on error
Notes: (1) If there is a colormap, iscmap is returned as 1; else 0.
LEPT_DLL void startTimer | ( | void | ) |
Example of usage:
startTimer(); .... fprintf(stderr, "Elapsed time = %7.3f sec\n", stopTimer());
LEPT_DLL L_TIMER startTimerNested | ( | void | ) |
startTimerNested(), stopTimerNested()
Example of usage:
L_TIMER t1 = startTimerNested(); .... L_TIMER t2 = startTimerNested(); .... fprintf(stderr, "Elapsed time 2 = %7.3f sec\n", stopTimerNested(t2)); .... fprintf(stderr, "Elapsed time 1 = %7.3f sec\n", stopTimerNested(t1));
LEPT_DLL l_float32 stopTimerNested | ( | L_TIMER | rusage_start | ) |
Input: dest (null-terminated byte buffer) size (size of dest) src string (can be null or null-terminated string) Return: number of bytes added to dest; -1 on error
Notes: (1) Alternative implementation of strncat, that checks the input, is easier to use (since the size of the dest buffer is specified rather than the number of bytes to copy), and does not complain if is null. (2) Never writes past end of dest. (3) If it can't append src (an error), it does nothing. (4) N.B. The order of 2nd and 3rd args is reversed from that in strncat, as in the Windows function strcat_s().
LEPT_DLL l_int32 stringCompareLexical | ( | const char * | str1, |
const char * | str2 | ||
) |
Input: str1 str2 Return: 1 if str1 > str2 (lexically); 0 otherwise
Notes: (1) If the lexical values are identical, return a 0, to indicate that no swapping is required to sort the strings.
LEPT_DLL l_int32 stringCopy | ( | char * | dest, |
const char * | src, | ||
l_int32 | n | ||
) |
Input: dest (existing byte buffer) src string (can be null) n (max number of characters to copy) Return: 0 if OK, 1 on error
Notes: (1) Relatively safe wrapper for strncpy, that checks the input, and does not complain if is null or
< 1. If
< 1, this is a no-op. (2) needs to be at least
bytes in size. (3) We don't call strncpy() because valgrind complains about use of uninitialized values.
LEPT_DLL l_int32 stringFindSubstr | ( | const char * | src, |
const char * | sub, | ||
l_int32 * | ploc | ||
) |
Input: src (input string; can be of zero length) sub (substring to be searched for) &loc (<return optional>=""> location of substring in src) Return: 1 if found; 0 if not found or on error
Notes: (1) This is a wrapper around strstr(). (2) Both and must be defined, and must have length of at least 1. (3) If the substring is not found and loc is returned, it has the value -1.
LEPT_DLL char* stringJoin | ( | const char * | src1, |
const char * | src2 | ||
) |
Input: src1 string (<optional> can be null) src2 string (<optional> can be null) Return: concatenated string, or null on error
Notes: (1) This is a safe version of strcat; it makes a new string. (2) It is not an error if either or both of the strings are empty, or if either or both of the pointers are null.
LEPT_DLL l_int32 stringLength | ( | const char * | src, |
size_t | size | ||
) |
Input: src string (can be null or null-terminated string) size (size of src buffer) Return: length of src in bytes.
Notes: (1) Safe implementation of strlen that only checks size bytes for trailing NUL. (2) Valid returned string lengths are between 0 and size - 1. If size bytes are checked without finding a NUL byte, then an error is indicated by returning size.
Input: src string Return: dest copy of src string, or null on error
LEPT_DLL char* stringRemoveChars | ( | const char * | src, |
const char * | remchars | ||
) |
Input: src (input string; can be of zero length) remchars (string of chars to be removed from src) Return: dest (string with specified chars removed), or null on error
LEPT_DLL l_int32 stringReplace | ( | char ** | pdest, |
const char * | src | ||
) |
Input: &dest string (<return> copy) src string Return: 0 if OK; 1 on error
Notes: (1) Frees any existing dest string (2) Puts a copy of src string in the dest (3) If either or both strings are null, does something reasonable.
LEPT_DLL char* stringReplaceEachSubstr | ( | const char * | src, |
const char * | sub1, | ||
const char * | sub2, | ||
l_int32 * | pcount | ||
) |
Input: src (input string; can be of zero length) sub1 (substring to be replaced) sub2 (substring to put in; can be "") &count (<optional return=""> the number of times that sub1 is found in src; 0 if not found) Return: dest (string with substring replaced), or null if the substring not found or on error.
Notes: (1) Replaces every instance. (2) To only remove each instance of sub1, use "" for sub2 (3) Returns NULL if sub1 and sub2 are the same.
LEPT_DLL char* stringReplaceSubstr | ( | const char * | src, |
const char * | sub1, | ||
const char * | sub2, | ||
l_int32 * | pfound, | ||
l_int32 * | ploc | ||
) |
Input: src (input string; can be of zero length) sub1 (substring to be replaced) sub2 (substring to put in; can be "") &found (<return optional>=""> 1 if sub1 is found; 0 otherwise) &loc (<return optional>=""> location of ptr after replacement) Return: dest (string with substring replaced), or null if the substring not found or on error.
Notes: (1) Replaces the first instance. (2) To only remove sub1, use "" for sub2 (3) Returns a new string if sub1 and sub2 are the same. (4) The optional loc is input as the byte offset within the src from which the search starts, and after the search it is the char position in the string of the next character after the substituted string. (5) N.B. If ploc is not null, loc must always be initialized. To search the string from the beginning, set loc = 0.
LEPT_DLL char* stringReverse | ( | const char * | src | ) |
Input: src (string) Return: dest (newly-allocated reversed string)
LEPT_DLL l_int32 stringSplitOnToken | ( | char * | cstr, |
const char * | seps, | ||
char ** | phead, | ||
char ** | ptail | ||
) |
Input: cstr (input string to be split; not altered) seps (a string of character separators) &head (<return> ptr to copy of the input string, up to the first separator token encountered) &tail (<return> ptr to copy of the part of the input string starting with the first non-separator character that occurs after the first separator is found) Return: 0 if OK, 1 on error
Notes: (1) The input string is not altered; all split parts are new strings. (2) The split occurs around the first consecutive sequence of tokens encountered. (3) The head goes from the beginning of the string up to but not including the first token found. (4) The tail contains the second part of the string, starting with the first char in that part that is NOT a token. (5) If no separator token is found, 'head' contains a copy of the input string and 'tail' is null.
LEPT_DLL char* strtokSafe | ( | char * | cstr, |
const char * | seps, | ||
char ** | psaveptr | ||
) |
Input: cstr (input string to be sequentially parsed; use NULL after the first call) seps (a string of character separators) &saveptr (<return> ptr to the next char after the last encountered separator) Return: substr (a new string that is copied from the previous saveptr up to but not including the next separator character), or NULL if end of cstr.
Notes: (1) This is a thread-safe implementation of strtok. (2) It has the same interface as strtok_r. (3) It differs from strtok_r in usage in two respects: (a) the input string is not altered (b) each returned substring is newly allocated and must be freed after use. (4) Let me repeat that. This is "safe" because the input string is not altered and because each returned string is newly allocated on the heap. (5) It is here because, surprisingly, some C libraries don't include strtok_r. (6) Important usage points:
LEPT_DLL L_SUDOKU* sudokuCreate | ( | l_int32 * | array | ) |
Input: array (of 81 numbers, 9 rows of 9 numbers each) Return: l_sudoku, or null on error
Notes: (1) The input array has 0 for the unknown values, and 1-9 for the known initial values. It is generated from a file using sudokuReadInput(), which checks that the file data has 81 numbers in 9 rows.
LEPT_DLL void sudokuDestroy | ( | L_SUDOKU ** | psud | ) |
Input: &l_sudoku (<to be="" nulled>="">) Return: void
LEPT_DLL L_SUDOKU* sudokuGenerate | ( | l_int32 * | array, |
l_int32 | seed, | ||
l_int32 | minelems, | ||
l_int32 | maxtries | ||
) |
Input: array (of 81 numbers, 9 rows of 9 numbers each) seed (random number) minelems (min non-zero elements allowed; <= 80) maxtries (max tries to remove a number and get a valid sudoku) Return: l_sudoku, or null on error
Notes: (1) This is a brute force generator. It starts with a completed sudoku solution and, by removing elements (setting them to 0), generates a valid (unique) sudoku initial condition. (2) The process stops when either , the minimum number of non-zero elements, is reached, or when the number of attempts to remove the next element exceeds . (3) No sudoku is known with less than 17 nonzero elements.
LEPT_DLL l_int32 sudokuOutput | ( | L_SUDOKU * | sud, |
l_int32 | arraytype | ||
) |
Input: l_sudoku (at any stage) arraytype (L_SUDOKU_INIT, L_SUDOKU_STATE) Return: void
Notes: (1) Prints either the initial array or the current state of the solution.
LEPT_DLL l_int32* sudokuReadFile | ( | const char * | filename | ) |
Input: filename (of formatted sudoku file) Return: array (of 81 numbers), or null on error
Notes: (1) The file format has: * any number of comment lines beginning with '#' * a set of 9 lines, each having 9 digits (0-9) separated by a space
LEPT_DLL l_int32* sudokuReadString | ( | const char * | str | ) |
Input: str (of input data) Return: array (of 81 numbers), or null on error
Notes: (1) The string is formatted as 81 single digits, each separated by 81 spaces.
LEPT_DLL l_int32 sudokuSolve | ( | L_SUDOKU * | sud | ) |
Input: l_sudoku (starting in initial state) Return: 1 on success, 0 on failure to solve (note reversal of typical unix returns)
LEPT_DLL l_int32 sudokuTestUniqueness | ( | l_int32 * | array, |
l_int32 * | punique | ||
) |
Input: array (of 81 numbers, 9 lines of 9 numbers each) &punique (<return> 1 if unique, 0 if not) Return: 0 if OK, 1 on error
Notes: (1) This applies the brute force method to all four 90 degree rotations. If there is more than one solution, it is highly unlikely that all four results will be the same; consequently, if they are the same, the solution is most likely to be unique.
LEPT_DLL void thresholdTo2bppLow | ( | l_uint32 * | datad, |
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_int32 * | tab | ||
) |
LEPT_DLL void thresholdTo4bppLow | ( | l_uint32 * | datad, |
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | wpls, | ||
l_int32 * | tab | ||
) |
LEPT_DLL void thresholdToBinaryLineLow | ( | l_uint32 * | lined, |
l_int32 | w, | ||
l_uint32 * | lines, | ||
l_int32 | d, | ||
l_int32 | thresh | ||
) |
LEPT_DLL void thresholdToBinaryLow | ( | l_uint32 * | datad, |
l_int32 | w, | ||
l_int32 | h, | ||
l_int32 | wpld, | ||
l_uint32 * | datas, | ||
l_int32 | d, | ||
l_int32 | wpls, | ||
l_int32 | thresh | ||
) |
LEPT_DLL l_int32 tiffGetCount | ( | FILE * | fp, |
l_int32 * | pn | ||
) |
LEPT_DLL l_int32 writeImageCompressedToPSFile | ( | const char * | filein, |
const char * | fileout, | ||
l_int32 | res, | ||
l_int32 * | pfirstfile, | ||
l_int32 * | pindex | ||
) |
LEPT_DLL l_int32 writeMultipageTiff | ( | const char * | dirin, |
const char * | substr, | ||
const char * | fileout | ||
) |
LEPT_DLL l_int32 writeMultipageTiffSA | ( | SARRAY * | sa, |
const char * | fileout | ||
) |
LEPT_DLL l_int32 wshedApply | ( | L_WSHED * | wshed | ) |
Input: wshed (generated from wshedCreate()) Return: 0 if OK, 1 on error
Iportant note: (1) This is buggy. It seems to locate watersheds that are duplicates. The watershed extraction after complete fill grabs some regions belonging to existing watersheds. See prog/watershedtest.c for testing.
Input: wshed &pixa (<optional return>=""> mask of watershed basins) &nalevels (<optional return>=""> watershed levels) Return: 0 if OK, 1 on error
Input: pixs (8 bpp source) pixm (1 bpp 'marker' seed) mindepth (minimum depth; anything less is not saved) debugflag (1 for debug output) Return: WShed, or null on error
Notes: (1) It is not necessary for the fg pixels in the seed image be at minima, or that they be isolated. We extract a single pixel from each connected component, and a seed anywhere in a watershed will eventually label the watershed when the filling level reaches it. (2) Set mindepth to some value to ignore noise in pixs that can create small local minima. Any watershed shallower than mindepth, even if it has a seed, will not be saved; It will either be incorporated in another watershed or eliminated.
LEPT_DLL void wshedDestroy | ( | L_WSHED ** | pwshed | ) |
Input: &wshed (<will be="" set="" to="" null="" before="" returning>="">) Return: void
LEPT_DLL PIX* wshedRenderColors | ( | L_WSHED * | wshed | ) |
Input: wshed Return: pixd (initial image with all basins filled), or null on error
LEPT_DLL PIX* wshedRenderFill | ( | L_WSHED * | wshed | ) |
Input: wshed Return: pixd (initial image with all basins filled), or null on error
LEPT_DLL l_uint8* zlibCompress | ( | l_uint8 * | datain, |
size_t | nin, | ||
size_t * | pnout | ||
) |
Input: datain (byte buffer with input data) nin (number of bytes of input data) &nout (<return> number of bytes of output data) Return: dataout (compressed data), or null on error
Notes: (1) We repeatedly read in and fill up an input buffer, compress the data, and read it back out. zlib uses two byte buffers internally in the z_stream data structure. We use the bbuffers to feed data into the fixed bufferin, and feed it out of bufferout, in the same way that a pair of streams would normally be used if the data were being read from one file and written to another. This is done iteratively, compressing L_BUF_SIZE bytes of input data at a time.
LEPT_DLL l_uint8* zlibUncompress | ( | l_uint8 * | datain, |
size_t | nin, | ||
size_t * | pnout | ||
) |
Input: datain (byte buffer with compressed input data) nin (number of bytes of input data) &nout (<return> number of bytes of output data) Return: dataout (uncompressed data), or null on error
Notes: (1) See zlibCompress().