An interface to the leptonica library of routines for image analysis and processing.
Most of the library's operations are based around manipulating images, which are stored in a structure known as a pix. You should manually manage the references to the images. If you want a copy of an existing pix, use pix-clone; this updates the reference count for an image. Use pix-destroy when you are finished with a reference to a pix; this decrements the reference count, and finally deletes the image when the count is 0.
- pix-clone pixprocedure
Return a reference to given pix.
- pix-copy pix-d pix-sprocedure
Makes a copy of pix-s: if pix-d is #f then returns a pointer to a copy of pix-s, else makes pix-d a copy of pix-s.
- pix-create width height depthprocedure
Returns a pointer to a new pix, an image of given width and height in pixels, and colour depth.
- pix-destroy pixprocedure
Reduces reference count to pix, and destroys picture if count is 0.
- pix-read filenameprocedure
Returns a pointer to a new pix created by reading image from filename. Returns #f if there is an error.
- pix-write filename pix image-typeprocedure
Writes pix to an image file called filename. The image-type is taken from the list of constants, below.
- pix-get-width pixprocedure
Returns the width in pixels of given pix.
- pix-set-width pix integerprocedure
Sets the width in pixels of given pix. Returns 0 if ok, or 1 if error.
- pix-get-height pixprocedure
Returns the height in pixels of given pix.
- pix-set-height pix integerprocedure
Sets the height in pixels of given pix. Returns 0 if ok, or 1 if error.
- pix-get-depth pixprocedure
Returns the colour depth of given pix.
- pix-set-depth pix integerprocedure
Sets colour depth of given pix. Returns 0 if ok, or 1 if error.
- pix-set-dimensions pix width height depthprocedure
Sets all three properties of given pix. Returns 0 if ok, or 1 if error.
- pix-get-x-res pixprocedure
Returns the x resolution of given pix.
- pix-set-x-res pix integerprocedure
Sets the x resolution of given pix. Returns 0 if ok, or 1 if error.
- pix-get-y-res pixprocedure
Returns the y resolution of given pix.
- pix-set-y-res pix integerprocedure
Sets the y resolution of given pix. Returns 0 if ok, or 1 if error.
- pix-set-resolution pix x-res y-resprocedure
Sets the x and y resolution of given pix. Returns 0 if ok, or 1 if error.
- pix-scale-resolution pix x-scale y-scaleprocedure
Rescales the image in the x and y directions. Returns 0 if ok, or 1 if error.
- pix-get-input-format pixprocedure
Returns the input format of pix.
- pix-set-input-format pix integerprocedure
Sets the input format of pix.
- pix-abs-difference pix-1 pix-2procedure
Returns pointer to new image which is formed by taking the pixel-wise absolute difference between pix-1 and pix-2. The two source images must have identical dimensions and colour depth. #f is returned on an error.
- pix-add-gray pix-d pix-1 pix-2procedure
Returns pointer to image which is pixel sum of pix-1 and pix-2. Unless #f, pix-d may specify the destination image, and pix-d may be equal to pix-1 for an in-place change.
- pix-add-constant-gray pix-s valueprocedure
In-place modification of pix-s by adding value to each pixel. Returns 0 if OK or 1 if error.
- pix-close-gray pix h-size v-sizeprocedure
h-size and v-size must be odd values: they denote the size of gray block to find. Returns a pointer to a new pix, based on the given pix, removing parts that do not fit a h-size x v-size block.
- pix-combine-masked pix-d pix-s pix-mprocedure
Modifies pix-d in place. Each pixel in pix-d corresponding to a set pixel in the mask pix-m is set to that pixel's value from pix-s. pix-d and pix-s must be equivalent in pixel depth. The three images are aligned to the top-left corner, stopping when outside the intersection of three images. Returns 0 if OK or 1 if error.
- pix-dilate-gray pix h-size v-sizeprocedure
h-size and v-size must be odd values. Returns a pointer to a new pix, based on the given pix.
- pix-dither-to-binary pixprocedure
Uses Floyd-Steinberg error diffusion dithering algorithm to convert given pix to a new pix. Returns #f on error.
- pix-dither-to-binary-spec pix lowerclip upperclipprocedure
Similar to pix-dither-to-binary, but the integers lowerclip and upperclip specific the distance to 0 or 255 respectively beyond which the routine stops propagating excess.
- pix-erode-gray pix h-size v-sizeprocedure
h-size and v-size must be odd values. Returns a pointer to a new pix, based on the given pix.
- pix-find-skew pixprocedure
Returns two values: the angle (in radians) and confidence level of skew in the given pix.
- pix-invert pix-d pix-sprocedure
Inverts the image pix-s. If pix-d is #f, then a pointer to a new pix is returned; otherwise, pix-d holds the inverted image.
- pix-max-dynamic-range pix scale-typeprocedure
Returns a new pointer to an image which stretches the colour values in pix to the full available range. Returns #f if error. scale-type is constant given below.
- pix-min-or-max pix-d pix-1 pix-2 choose-typeprocedure
Returns a pointer to an image which is formed either from the pixel-wise min or max of the two source images (the type determined by choose-type, defined below). If pix-d is #f then a new image is created and returned. If pix-d is an image, then that image is updated. If pix-d is the same as pix-1 then an in-place change is made.
- pix-mult-constant-gray pix-s valueprocedure
In-place modification of pix-s by multiplying each pixel value by value. Returns 0 if OK, or 1 if error.
- pix-open-gray pix h-size v-sizeprocedure
h-size and v-size must be odd values. Returns a pointer to a new pix, based on the given pix
- pix-rotate-am-gray pix angle fillerprocedure
Returns a pointer to a new 8bpp pix created by rotating the given 8 bpp pix through the given angle; filler specifies the gray value to be brought in to fill blanks, 0 for black, 255 for white.
- pix-subtract-gray pix-d pix-1 pix-2procedure
Returns pointer to image which is pixel difference of pix-1 and pix-2. Unless #f, pix-d may specify the destination image, and pix-d may be equal to pix-1 for an in-place change.
- pix-threshold-to-binary pix thresholdprocedure
Returns a pointer to a new pix created from the given pix. The given pix should be a 4 or 8 bpp colour image; the given threshold value is used to convert the image to binary.
- pix-threshold-to-value pix-d pix-s threshold set-valueprocedure
If pix-d is #f, returns a pointer to a new pix. Else, pix-d must be equal to pix-s and thresholding is done in place. If set-value > threshold, then all pixels with a value >= threshold are set to set-value; else, if set-value < threshold, then all pixels with value <= threshold are set to set-value.
- pix-var-threshold-to-binary pix-s pix-gprocedure
Returns a pointer to a new pix created from the given 8 bpp pix-s by thresholding each corresponding pixel according to the value in pix-g.
- rotate pix angle rotation-type in-colour width heightprocedure
Returns a pointer to a new pix created by rotating given pix.
- angle: in radians, with positive value indicating clockwise.
- rotation-type: from list of constants below.
- in-colour: from list of constants below, determines if white or black pixels complete missing spaces.
- width: of final image
- height: of final image
- scale pix scale-x scale-yprocedure
Returns a pointer to a new pix created by rescaling given pix along x and y dimensions.
In each of the following, the connectivity must be 4 or 8 depending on whether pixels are connected to their 4 neighbours in the up/down/left/right directions or with all 8 of their neighbours.
- pix-conn-comp-bb pix connectivityprocedure
Returns an array of bounding boxes corresponding to the components within pix. pix must be a 1 bpp image.
- pix-conn-comp-pixa pix connectivityprocedure
Returns two values: an array of bounding boxes (type BOXA) and an array of pix images (type PIXA). The bounding boxes and images are the components within the given pix. pix must be a 1 bpp image.
- pix-count-conn-comp pix connectivityprocedure
Returns the number of connected components, or #f if there was an error. pix must be a 1 bpp image.
Boxes are used within Leptonica to hold information about regions of an image. These boxes can be stored as arrays. The following procedures let you work with boxes and box arrays, extracting information from them and subobjects.
box stands for an instance of the BOX structure within the C-code.
boxa stands for an instance of the BOXA structure, an array of boxes.
- box-get-geometry boxprocedure
Returns four values: the x, y, width, height of the box in pixel coordinates. Returns #f on error.
- box-set-geometry box x y w hprocedure
Sets the values of x, y, width and height of the given box in pixels. Returns 0 if OK, or 1 if error.
- boxa-get-box boxa index copy-typeprocedure
Return a pointer to the indexed box in the box array: copy-type is a constant, as defined below, and determines if the box is returned as a copy or a clone. Returns #f on error.
- boxa-get-count boxaprocedure
Returns a count of the number of boxes within the box array.
The PIXA structure can be explored using the following procedures:
- pixa-get-count pixaprocedure
Returns the number of pix images in the pix array.
- pixa-get-pix pixa index copy-typeprocedure
Returns a pointer to the indexed pix in the pix array: copy-type is a constant, as defined below, and determines if the pix is returned as a copy or a clone. Returns #f on error.
- L-CHOOSE-MAX, L-CHOOSE-MIN
- L-COPY L-CLONE
- IFF-UNKNOWN, IFF-BMP, IFF-JFIF-JPEG, IFF-PNG, IFF-TIFF, IFF-TIFF-PACKBITS, IFF-TIFF-RLE, IFF-TIFF-G3, IFF-TIFF-G4, IFF-TIFF-LZW, IFF-TIFF-ZIP, IFF-PNM, IFF-PS, IFF-GIF, IFF-JP2, IFF-DEFAULT, IFF-SPIX.
- L-BRING-IN-WHITE, L-BRING-IN-BLACK.
- L-ROTATE-AREA-MAP, L-ROTATE-SHEAR, L-ROTATE-SAMPLING.
- L-LINEAR-SCALE, L-LOG-SCALE
See the examples folder in the repository.
The more useful examples include:
- component extraction (identifies all the letter-like components of a scanned image)
- lineremoval (after the version provided with leptonica)
GPL version 3.0.
You will need libraries for handling images: libjpeg, libpng, libtiff are currently assumed in the setup file.
Also, you must download and compile the source code for the leptonica library.
Note: this egg has only been tested under Linux.
- 0.3: try to figure out the location of leptonica's headers
- 0.2: includes component analysis
- 0.1: initial release