chickadee » image-processing


This page is maintained in the package's github repository.

This is a Chicken Scheme egg with various image processing utilities.

Note that a few of these functions call ImageMagick.

Color spaces

*max-red* constant
*max-green* constant
*max-blue* constant
*max-grey* constant
*max-hue* constant
*max-saturation* constant
*max-value* constant

These are exposed in case we want to switch to 16-bit grayscale or colors.

(rgb->hsv rgb) procedure
(hsv->rgb hsv) procedure
(rgb->cd rgb) procedure
(rgb->cmyk rgb) procedure
(rgb->uv-hsv c) procedure

Various color space conversions. Colors are vectors of values.

(rgb->xyz c) procedure
(xyz->rgb c) procedure
(xyz->l*ab c) procedure
(l*ab->xyz c) procedure
(rgb->l*ab c) procedure
(l*ab->rgb c) procedure

Convert to l*ab. Colors are vectors of values. This is space in which Euclidean distance is similar to human perceputal distance. These implement a 2 degree observer and the D65 illuminant.

(rgb->html c) procedure

Not really a color space conversion, covert an rgb color to an HTML color #rrggbb.


(define-structure pbm raw? bitmap) record
(define-structure pgm raw? maxval grey) record
(define-structure ppm raw? maxval red green blue) record
(pnm? m) procedure

Three image formats are supported. PBMs are binary images, PGMs are greyscale and PPMs are tri-plane (nominally RGB) images. All planes are stored as scheme matrices. Together all of these formats are called PNM. This is a standard format that many tools (such browser and ImageMagick) can read and write. PNMs can be serialized as either raw packed binaries or ascii text files. Note that we are unable to read or write raw PBMs.

(image-ref i p) procedure

Index into an PNM image or into a matrix. This is like indexing into a matrix except that the arguments are reversed. A matrix-ref takes the row and then the column, image-ref takes a point which is an (x,y) coordinate.

(pbm-ascii pbm) procedure

Ensure that the PBM image is in ascii. We are unable to read or write raw PBMs.

(pnm-copy pnm) procedure

The resulting image will not share any data with the original.

Creating images

(read-pnm pathname) procedure

Read a PNM. We determine the kind of image (PBM, PGM, PPM see above) from the file header.

(write-pnm pnm pathname) procedure

Write a PNM. If don't provide an extension an appropriate one will be appended to your pathname.

(pbm-constant width height bit) procedure
(pgm-constant width height grey) procedure
(ppm-constant width height red green blue) procedure

Create constant images.

(pbm-left-vertical-stripe width height left) procedure

Create a black vertical stripe on a white image.

(crop-image pnm x y width height) procedure

Crop an image and return a new image of the given size.

(pnm->ppm pnm) procedure
(pnm->pgm pnm) procedure

Convert any image format to a color or greyscale image

(pbm->pgm pbm) procedure
(pgm->ppm pgm) procedure
(pbm->ppm pbm) procedure
(ppm->pgm ppm) procedure

Various image conversions.

(pgm->pbm pgm threshold) procedure
(ppm->pbm ppm threshold) procedure

Convert a color or greyscale image to a binary image with the provided threshold.

Basic image information

(pnm-width pnm) procedure
(pnm-height pnm) procedure

Basic image information.

(ppm-hue ppm) procedure
(ppm-saturation ppm) procedure
(ppm-value ppm) procedure

Creates a greyscale image representing one of the HSV channels from a color image.

(ppm-mean image colour-transform) procedure
(ppm-covariance image colour-transform) procedure
(pgm-mean image) procedure
(pgm-variance image) procedure

Compute the mean or covariance of an image. These take an optional colour transform.

Logical and morphological operations

(pbm-and pbm1 pbm2) procedure
(pbm-or pbm1 pbm2) procedure
(pbm-not pbm) procedure
(pbm-xor pbm1 pbm2) procedure

Basic logical operations on binary images.

(pgm-absolute-difference pgm1 pgm2) procedure

Compute the difference between two greyscale images.

(empty-pnm? pnm) procedure

Is this image empty?

(pbm-skeletonize pbm) procedure
(pbm-bloat pbm n) procedure

Bloat or skeletonize a binary image.

(pbm-flood pbm point) procedure

Floor fill a binary image.

PNM movies

(pnm-movie-frame-pathname pathname i) procedure
(pnm-movie-length pathname) procedure
(read-pnm-movie pathname) procedure
(write-pnm-movie pnm-movie pathname) procedure

A PNM movie is a sequence of PNMs on disk.

Image operations

(overlay-pbm-on-pnm pbm pnm) procedure

The white pixels in the pbm become white in the resulting image.

(pnm-black-window pnm upper-left lower-right) procedure
(pnm-white-window pnm upper-left lower-right) procedure

Draw white or black windows on an image.

(pbm-ppm-and pbm ppm) procedure
(pgm-and-pbm pgm pbm) procedure

Black pixels in the PBM become black pixels in the result.

(pnm-shift pnm delta) procedure

Shift an image down and rightward by the give number of pixels.

(pgm-smooth pgm sigma) procedure

Smooth a greyscale image with the given variance.

(pbm-proximity-clusterer pbm threshold) procedure

Cluster white pixels in the binary image with the given distance threshold.

(pnm-rotate pnm) procedure
(pnm-flip pnm) procedure

Rotate (transpose) an image or flip (mirror) an image.

(ppm-burn base mask colour) procedure

Burn the ppm with the given mask and color.

Image pairs

(normal-flow-magnitude pgm1 pgm2 epsilon sigma sensitivity) procedure
(threshold-normal-flow-magnitude pgm1 pgm2 epsilon sigma threshold) procedure

Compute normalized flow between two pairs of greyscale images.


(flatten-ppm ppm colour-transform) procedure

Returns a single matrix from a tri-plane PPM. This maps colour-transform over the image.

(binary-threshold pgm threshold) procedure

Threshold a greyscale image.

(find-threshold-otsu pgm) procedure
(binary-threshold-optimal pgm) procedure

Otsu's Method to find an optional threshold and apply it.

(find-threshold-means pgm) procedure
(binary-threshold-means pgm) procedure

Method of Successive Means to find an optimal threshold and apply it.

Colour Threshold

(sample-image ppm colour-tx window-centre window-size) procedure

Map colour-tx over an region of a color image.

(binary-threshold-colour ppm colour-tx point threshold) procedure

Binary threshold a colour image by sampling a region around the given point and thresholding all values that are within the given distance threshold of the mean color of that region.

(colour-threshold ppm colour-tx mu isigma threshold) procedure

Binary threshold a colour image with the given mean and variance. The mahalanobis-distance between each pixel and the given mean and variance will be computed and compared to the threshold.

Histogram Equalization

(histogram-equalise pgm) procedure

Equalize a greyscale image.

Adaptive Thresholding

(make-integral-matrix matrix) procedure

Given a matrix compute an integral matrix which can provide the mean value of a rectangular region in O(1).

(compute-integral-matrix-mu integral-matrix x y w) procedure
(compute-integral-matrix-sigma squared-integral-matrix mu x y w) procedure

This computes the mean and variance of a square of size w in the given integral matrix.

(compute-adaptive-threshold integral-matrix squared-integral-matrix x y w) procedure

Compute an adaptive threshold on the given integral matrix.

(adaptive-threshold pgm winsize) procedure

Compute an adaptive threshold for a greyscale image with a given window size.

(slide-window m f size) procedure

Map f over a matrix passing it square submatrices of the given size. At the edges f is passed #f.

(count-pixels a) procedure

Count number of true values in a matrix.

(ppm->label-closest ppm mu1 sigma1 mu2 sigma2 #!optional colour-transform) procedure

Create a binary image from a color image where points are either white or black depending on which is closer to the given means and variances.


(find-histogram pixmap maxval) procedure
(histogram-mean histogram i) procedure
(histogram-variance histogram mu i) procedure
(normalised-histogram histogram val) procedure
(weighted-histogram histogram) procedure
(cumulative-histogram histogram) procedure
(find-between-class-variances omegas mus mu-total) procedure

Compute histograms from a matrix.

Rendering Line Segments

(midpoint l) procedure

Compute the midpoint of a line segment.

(orientation v) procedure

Compute the orientation of a vector.

(line-segment-orientation l) procedure

Compute the orientation of a line segment.

(line-segment->points l) procedure
(line-segments->points ls) procedure
(points->line-segments ps) procedure

Convert between points and line semgents.

Points and bounding boxes

(points->pbm-of-size points height width) procedure

Take the list of points and create a binay image of the given size where those points are white.

(points-bounding-box points) procedure

Computing a bounding box for a set of points.

(bounding-box-size bb) procedure

Compute the size of a bounding box

(points->points-bounding-box points bb) procedure

Recompute the coordinates of the given points relative to the top-left corner of the bounding box.

(points->bounding-box-points points) procedure

Convert points to a list of points on the bounding box of those points.

(normalize-to-bounding-box ps) procedure
(normalize-to-other-bounding-box points ps) procedure
(points->target-bounding-box points target-bb) procedure
(points->other-target-bounding-box points ps target-bb) procedure

Normalize the cooredinates of these points to their bounding box. Or to the bounding box of the given points.

(bounding-box-bloat bb p) procedure

Bloat a bounding box.

(bounding-box-crop bb image) procedure

Crop a bounding box out of an image.

(pbm->points pbm) procedure
(points->pbm points height width) procedure

Convert a binary image to a set of points or vice versa.


(quantize-coordinate x) procedure
(quantize-point p) procedure
(quantize-points ps) procedure
(quantize-line-segment l) procedure
(quantize-line-segments ls) procedure

Quantize coordinates, points or line segments.


(define-structure ellipse x0 y0 t0 a b) procedure
(ellipse-center ellipse) procedure
(ellipse-area ellipse) procedure
(ellipse-eccentricity ellipse) procedure

Define and compute basic properties of ellipses.

(radial-distance theta phi) procedure

The radial distance between two angles.

(point-on-ellipse? p ellipse tolerance) procedure

Compute if a point is on an ellipse.

(line-segment->ellipse l) procedure

Place an ellipse around a line segment

(ellipse->points e #!optional (n 360)) procedure

Sample n points on an ellipse.


(resize-image w h i) procedure

Resize an image. This is quite slow as it writes the image out and calls imagemagick to resize it.

(subsample-pbm pbm) procedure

Subsample a pbm by a factor of 2.

(scale-ppm ppm scale) procedure

Scale a pbm by a factor of 2 or 4.

Connected Components

(connected-component-filter pbm delta threshold) procedure

Compute connected components of a binary image with distance thershold delta and size threshold threshold.x

(define-private-structure vertex pixels vertex edges) record
(define-private-structure edge u v) record
(define-private-structure graph vertices edges) record

These are defined private for now as they need to be renamed.

(pbm->graph pbm delta) procedure
(labeling->graph labeling delta) procedure

Convert a binary image to a graph where pixels within delta of each other are connected.

(dereference-vertex u) procedure
(connected-components g) procedure

Compute the connect components of a graph.

(vertices->pbm vertices height width) procedure
(graph->pbm g height width) procedure

Convert a graph or list of vertices to a pbm.


(pbm->chains pbm) procedure

Convert a binary image to a list of chains, pixels that are connected to each other.

(chains->pbm chains height width) procedure

Convert a list of chains to a pbm.

(chain-filter pbm threshold) procedure

Filters chains below a certain length.

(break-chain chain l) procedure
(break-chains chains l) procedure

Break chains below a certain length.


(conjure pbms delta span threshold1 threshold2) procedure

Fill in missing values in pairs of frames.

Distance Transform

(distance-transform pbm) procedure
(closest-transform-ref closest-transform p) procedure

Compute the Manhattan distance transform for a binary image and reference into that distance transform.

(euclidean-1d-dt v) procedure
(euclidean-2d-dt m) procedure
(euclidean-1d-dt-vals v) procedure
(euclidean-2d-dt-vals m) procedure

Compute a generalized squared-euclidean distance transform on the given vector or matrix. The -vals version also returns a map of the closest points.


(define-structure pnm-buffer buffer width height pixfmt storage type) record

A mechanism to store raw image pointers.

(pnm->pixfmt p p4?) procedure
(pixfmt->stride pixfmt) procedure
(image-type->pixfmt t p4?) procedure
(image-type->storage-size t p4?) procedure
(pnm->image-type p) procedure
(pnm->storage p) procedure
(pixfmt->red pixfmt) procedure
(pixfmt->green pixfmt) procedure
(pixfmt->blue pixfmt) procedure
(pnm-buffer-size p p4?) procedure
(pnm->pnm-buffer! p . p4?) procedure
(pnm-fill-buffer! p b pixfmt) procedure
(free-pnm-buffer! p) procedure

Misc raw image buffer operations.

(imlib-image->pnm-buffer! image) procedure
(imlib-image->ppm image) procedure
(ppm->imlib-image ppm) procedure

Convert between PPMs and Imlib images. PGMs and PBMs must first be converted to PPMs because Imlib only handles RGB images.

(pnm-buffer->pnm b) procedure
(pnm-buffer->pbm p) procedure
(pnm-buffer->pgm p) procedure
(pnm-buffer->ppm p) procedure

Convert a raw image buffer to a scheme image.

(image->pnm-buffer! image) procedure

Convert any image to a raw image buffer.


(ppm-absolute-difference ppm1 ppm2) procedure

Compute the absolute difference between two color images.

(set-ppm-pixel! ppm x y value) procedure

Set a pixel in a color image to a given value (a 3-vector).

(pnm-pixel? i x y) procedure

Is this a valid position in the given image?

(map-ppm-values ppm f) procedure

Map f on each component of each pixel in the image.


(pbm-stack-vertical pbm1 pbm2) procedure
(pbm-stack-horizontal pbm1 pbm2) procedure
(ppm-stack-vertical ppm1 ppm2) procedure

Stack pbms.

(ppm-stack-horizontal ppm1 ppm2) procedure

Stack ppms.


(degrees->radians angle) procedure
(radians->degrees angle) procedure
(normalize-rotation rotation) procedure
(rotation+ x y) procedure
(rotation- x y) procedure
(angle-separation x y) procedure
(mean-angle angles) procedure

Misc operation on angles.

(rotation-matrix-2d theta) procedure

Produce the 2D rotation matrix for the given angle.


(show i) procedure

Display an image. This invokes feh.


  Written by the
  [[Center for the Computational Study of Cognition, Control, and Perception|]].
  Maintainer: Andrei Barbu,
  Copyright 1993-1995 University of Toronto. All rights reserved.
  Copyright 1996 Technion. All rights reserved.
  Copyright 1996 and 1997 University of Vermont. All rights reserved.
  Copyright 1997-2001 NEC Research Institute, Inc. All rights reserved.
  Copyright 2002-2013 Purdue University. All rights reserved.
  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.
  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  GNU Lesser General Public License for more details.
  You should have received a copy of the GNU Lesser General Public License
  along with this program.  If not, see

Contents »