chickadee » leptonica

Leptonica

In progress.

An interface to the leptonica library of routines for image analysis and processing.

Memory Management

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.

Implemented Procedures

Creating and managing images

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.

Image attributes

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.

Manipulating images

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.

Finding Components in Images

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

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.

Pix arrays

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.

Constants

choose-type
L-CHOOSE-MAX, L-CHOOSE-MIN
copy-type
L-COPY L-CLONE
image-type
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.
in-colour
L-BRING-IN-WHITE, L-BRING-IN-BLACK.
rotation-type
L-ROTATE-AREA-MAP, L-ROTATE-SHEAR, L-ROTATE-SAMPLING.
scale-type
L-LINEAR-SCALE, L-LOG-SCALE

Examples

See the examples folder in the repository.

The more useful examples include:

Author

Peter Lane

License

GPL version 3.0.

Requirements

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.

Version History

Contents »