Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

Leptonica

In progress.

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.

Implemented Procedures

Creating and managing images

[procedure] (pix-clone pix)

Return a reference to given pix.

[procedure] (pix-copy pix-d pix-s)

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.

[procedure] (pix-create width height depth)

Returns a pointer to a new pix, an image of given width and height in pixels, and colour depth.

[procedure] (pix-destroy pix)

Reduces reference count to pix, and destroys picture if count is 0.

[procedure] (pix-read filename)

Returns a pointer to a new pix created by reading image from filename. Returns #f if there is an error.

[procedure] (pix-write filename pix image-type)

Writes pix to an image file called filename. The image-type is taken from the list of constants, below.

Image attributes

[procedure] (pix-get-width pix)

Returns the width in pixels of given pix.

[procedure] (pix-set-width pix integer)

Sets the width in pixels of given pix. Returns 0 if ok, or 1 if error.

[procedure] (pix-get-height pix)

Returns the height in pixels of given pix.

[procedure] (pix-set-height pix integer)

Sets the height in pixels of given pix. Returns 0 if ok, or 1 if error.

[procedure] (pix-get-depth pix)

Returns the colour depth of given pix.

[procedure] (pix-set-depth pix integer)

Sets colour depth of given pix. Returns 0 if ok, or 1 if error.

[procedure] (pix-set-dimensions pix width height depth)

Sets all three properties of given pix. Returns 0 if ok, or 1 if error.

[procedure] (pix-get-x-res pix)

Returns the x resolution of given pix.

[procedure] (pix-set-x-res pix integer)

Sets the x resolution of given pix. Returns 0 if ok, or 1 if error.

[procedure] (pix-get-y-res pix)

Returns the y resolution of given pix.

[procedure] (pix-set-y-res pix integer)

Sets the y resolution of given pix. Returns 0 if ok, or 1 if error.

[procedure] (pix-set-resolution pix x-res y-res)

Sets the x and y resolution of given pix. Returns 0 if ok, or 1 if error.

[procedure] (pix-scale-resolution pix x-scale y-scale)

Rescales the image in the x and y directions. Returns 0 if ok, or 1 if error.

[procedure] (pix-get-input-format pix)

Returns the input format of pix.

[procedure] (pix-set-input-format pix integer)

Sets the input format of pix.

Manipulating images

[procedure] (pix-abs-difference pix-1 pix-2)

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.

[procedure] (pix-add-gray pix-d pix-1 pix-2)

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.

[procedure] (pix-add-constant-gray pix-s value)

In-place modification of pix-s by adding value to each pixel. Returns 0 if OK or 1 if error.

[procedure] (pix-close-gray pix h-size v-size)

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.

[procedure] (pix-combine-masked pix-d pix-s pix-m)

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.

[procedure] (pix-dilate-gray pix h-size v-size)

h-size and v-size must be odd values. Returns a pointer to a new pix, based on the given pix.

[procedure] (pix-dither-to-binary pix)

Uses Floyd-Steinberg error diffusion dithering algorithm to convert given pix to a new pix. Returns #f on error.

[procedure] (pix-dither-to-binary-spec pix lowerclip upperclip)

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.

[procedure] (pix-erode-gray pix h-size v-size)

h-size and v-size must be odd values. Returns a pointer to a new pix, based on the given pix.

[procedure] (pix-find-skew pix)

Returns two values: the angle (in radians) and confidence level of skew in the given pix.

[procedure] (pix-invert pix-d pix-s)

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.

[procedure] (pix-max-dynamic-range pix scale-type)

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.

[procedure] (pix-min-or-max pix-d pix-1 pix-2 choose-type)

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.

[procedure] (pix-mult-constant-gray pix-s value)

In-place modification of pix-s by multiplying each pixel value by value. Returns 0 if OK, or 1 if error.

[procedure] (pix-open-gray pix h-size v-size)

h-size and v-size must be odd values. Returns a pointer to a new pix, based on the given pix

[procedure] (pix-rotate-am-gray pix angle filler)

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.

[procedure] (pix-subtract-gray pix-d pix-1 pix-2)

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.

[procedure] (pix-threshold-to-binary pix threshold)

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.

[procedure] (pix-threshold-to-value pix-d pix-s threshold set-value)

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.

[procedure] (pix-var-threshold-to-binary pix-s pix-g)

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.

[procedure] (rotate pix angle rotation-type in-colour width height)

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

[procedure] (scale pix scale-x scale-y)

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.

[procedure] (pix-conn-comp-bb pix connectivity)

Returns an array of bounding boxes corresponding to the components within pix. pix must be a 1 bpp image.

[procedure] (pix-conn-comp-pixa pix connectivity)

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.

[procedure] (pix-count-conn-comp pix connectivity)

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.

[procedure] (box-get-geometry box)

Returns four values: the x, y, width, height of the box in pixel coordinates. Returns #f on error.

[procedure] (box-set-geometry box x y w h)

Sets the values of x, y, width and height of the given box in pixels. Returns 0 if OK, or 1 if error.

[procedure] (boxa-get-box boxa index copy-type)

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.

[procedure] (boxa-get-count boxa)

Returns a count of the number of boxes within the box array.

Pix arrays

The PIXA structure can be explored using the following procedures:

[procedure] (pixa-get-count pixa)

Returns the number of pix images in the pix array.

[procedure] (pixa-get-pix pixa index copy-type)

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:

component extraction (identifies all the letter-like components of a scanned image)
lineremoval (after the version provided with leptonica)

Note: this egg has only been tested under Linux.

Version History

0.3: try to figure out the location of leptonica's headers
0.2: includes component analysis
0.1: initial release