The vutils library

Ian Horswill 2/10/00
Most of this code was written by Mark DePristo. The windows port of iview was written by Rob Zubek and Chris Beckmann. Some of the vision operators were written by Dac Le. The GRL interfaces and the ancient C code on which the Polly and tracker systems were once based were written by Ian.

GRL data types

Images are represented in the GRL type signal as one of the following types:

grayscale-image

rgb-image

yuv-image

binary-image

Note that these are not parameterized by width or height, so width and height can't be tracked by the type system (sorry). However, you can generally get away with looking width and height up at run-time, particularly if you do it in this initialization of your transducer.

Depth maps are, not surprisingly, type depth-map and are indexed by column number. Regions of the depth map are represented as column-region groups.

(column-region start-column length): Constructor
(column-region-start column-region) (column-region-start column-region): Accessors

GRL Operators

Vision and image processing

(grab-grayscale-frames image-width image-height)
(grab-rgb-frames image-width image-height)
(grab-yuv-frames image-width image-height): Opens frame buffer and allocates storage for a grayscale (or rgb, or yuv) image of the specified width and height. On each cycle of the GRL code, a new image will be grabbed.
(smooth-grayscale-image image smooth-count): Approximates a Gaussian blurring using repeated convolution with triangle functions. This is actually a signal procedure that's smart enough to optimize the code if smooth-count is known at compile time. So there's no added cost of smoothing an image with a smooth-count of zero.
(dangerous-pixels-grayscale image edge-threshold): Runs the cheapo Polly edge detector and returns the result (a binary image).
(dangerous->depth-map dangerous-image distance-floor): Computes the Polly "depth map" from the binary image. The result is of type depth-map and is actually a C-array. It is indexed by image column and gives the image-plane height, in pixels, of the lowest dangerous pixel in that image column. The distance-floor parameter specifies how many rows to ignore from the bottom of the image. This is used, e.g. to keep the robot from seeing its own body as an obstacle if part of itself is in view.
(region-depth depth-map column-region ceiling): Returns the minimum reading from the selected region of column regions, or ceiling, whichever is smaller.

Information display

(display-image image &optional window-title): Returns the minimum reading from the selected region of column regions, or ceiling
(show-image image): Macro. Like show-values, but for images - displays the image in a window whose title is formed from the actually expression passed in for image.
(draw-vectors xy-vectors &optional scale window-size window-title colors): Draws a set of vectors in a window. xy-vectors should be a vector of xy-vectors (note that this would techncally be an xv-vector whose components were two vectors); scale, window-size, and window-title are self-explanatory; colors is an optional vector of colors in which to render the respective lines. For example:

(define-signal foo-display
(draw-vectors foo 1 100 "Foo"
                (if (< (magnitude foo) 50)
                    (enum color-type red)
                    (enum color-type green))))

would draw the vectors in foo, rendering the short ones in red and the long ones in green.
(show-pings &optional scale window-size window-title colors): Draws egocentric-ping-positions.

Polly implementation

The vision pipeline for Polly-style collision avoidance is implemented by the polly package. The pipeline is returned as a group from which all the relevant information can be accessed. In order to make the interface to the pipeline resolution-independent, region widths are specified in percent of the screen width and distances are represented in (integer) percentages of the total height.

(polly-pipeline &key width height input edge-threshold smoothing-factor top-margin bottom-margin side-margin)
(color-polly-pipeline &key width height input edge-threshold intensity-weight chroma-weight smoothing-factor top-margin bottom-margin side-margin): Returns a group containing all the signals of the standard Polly collision avoidance algorithm. Since there are a lot of arguments, they are specified with pseudo-Common Lisp keyword arguments. Note that since Scheme doesn't support keywords, they are just normal symbols, and so need to be quoted when passed in.

input

The grayscale image signal to use as input. If unspecified, the pipeline will open the framegrabber itself.

width
height

Desired resolution. The default is currently 80x60.

smoothing-factor

Half-width of the smoothing kernel to use for edge detection. Default is 2.

edge-threshold

Edge detector threshold. The current default is 15.

top-margin
bottom-margin
side-margin

How much of the image to ignore in computing the left-, right-, and center distances.

side-width-percent
center-width-percent

Desired width of the left-, right-, and center-regions, expressed as a percentage of the width of the image after the side margins are removed.

(polly-input polly-pipeline) (polly-smoothed-image polly-pipeline) (polly-dangerous-pixels polly-pipeline): The image signals used by the pipeline.
(polly-width polly-pipeline)
(polly-height polly-pipeline): Image resolution used by the pipeline.
(polly-depth-map polly-pipeline): The depth map computed by the pipeline it is indexed by image column. Values indicate the image-plane height of the lowest edge pixel in each column. Under normal conditions, this is a monotone function of distance.
(polly-max-distance polly-pipeline): The maximum possible "distance" in the depth map, i.e. the height of the screen less the top- and bottom- margins.
(polly-left-region polly-pipeline) (polly-center-region polly-pipeline) (polly-right-region polly-pipeline): The column-regions corresponding to the left-, right-, and center regions of the screen.
(polly-left-distance polly-pipeline) (polly-center-distance polly-pipeline) (polly-right-distance polly-pipeline): The distances to the closest objects in the left-, right-, and center regions of the screen, expressed as integer percentages of polly-max-distance.
(polly-left-line polly-pipeline) (polly-center-line polly-pipeline) (polly-right-line polly-pipeline): Cheapo lines fit to the left-, right-, and center regions. The lines are fit to the two endpoints of their respective regions.
(polly-left-line-fit-error polly-pipeline) (polly-center-line-fit-error polly-pipeline) (polly-right-line-fit-error polly-pipeline): Cheapo measures of fit for the cleapo lines fit to the left-, right-, and center regions. The fit is measured by taking the average distance from the line to the depth map at four equally space points.

(show-polly polly): Displays the raw image with the edge map as an overlay, and the left-, right-, and center-distances as colored horizontal lines
(show-polly-lines polly &key left-enable right-enable center-enable): Displays the raw image extracted left, right, and center lines. The enable controls determine whether they are displayed. By default, the lines display if their fit error is less than 20 pixels.
(polly-freespace-follower polly-pipeline gains stopping-distance): Returns a the standard freespace follower as a behavior. The gains should be an rt-vector, and the stopping-distance should be an integer.

Low-level Scheme procedures

Accessing resources in the C heap

The package vutils exports the following routines for accessing named resources in the C heap. Each procedure takes a name and a set of constructor arguments and returns the named resource. If the resource does not already exist, it is created and a pointer to it is saved for future use. Successive calls will then return the same object without reallocating it.

(get-frame-grabber width height): Returns a frame grabber object configured for the specified dimensions. If this function is called with different arguments, different objects are returned that are configured for different resolutions. These objects can be used simultaneously. Note that this function does not take a resource name, since it would be useless. However, successive calls with the same arguments always return the same object.
pixel-type: An enumeration containing the set of low-level C image pixel types.   It is currently defined as:

(define-enumeration pixel-type (
                    yuv         ;; 24-bit
                    grayscale ;; 8-bit
                    monochrome ;; binary,one byte/pixel
                    cdt         ;; 8-bit bitset
                    rgb         ;; 24-bit
                    nuv         ;; 24-bit
                    ))

values are accessed by using the enum macro: (enum pixel-type type)
(signal-identity): This isn't actually part of the vutils package. It is a pseudofunction that is recognized by the GRL compiler and replaced with the name (as a quoted symbol) of the variable in which the current signal's value is stored. It is therefore useful to pass as the name parameter to get-image, etc. since it tends to stay consistent from compilation to compilation.
(get-image name width height pixel-type): Returns an image of the specified width, height, and pixel type.
(get-image-like name image &optional pixel-type): Returns an image of the same size as image. If no pixel-type is specified, then the type of the image is the same too.
(get-window name width height title): Returns an window of the specified width and height, and with the specified title.
(get-window-like name image title): Returns an window of the same dimensions as image, and with the specified title.
(close-windows): Deallocates all windows managed by the resource manager.
(get-c-array name width): Returns C array of the specified width.
(shutdown): Deallocates everything managed by the resource manager.

The low level resource manager routines are found in package resource-pools, which exports:

(make-resource-pool name constructor destructor lookup-proc): Creates a new resource pool. When resources are created, the constructor will be called with whatever arguments are passed to get-resource. When a resource is freed, destructor will be called on it with no arguments. When looking for resources in its alist, lookup-proc will be used. lookup-proc should generally be assoc or assq.
(get-resource pool name . constructor-args): Returns the specified resource. If it needs to be created, constructor-args will be used.
(deallocate-resource pool name): Frees the specified resource.
(deallocate-all pool): Frees all the resources in the specified pool.
(shutdown): Frees all resources in all pools.

The iview graphics library

The vutils package also exports stubs for iview. Here is a partial list of the iview functions. Note that iview is double-buffered, so that updates do not appear on the screen until iview-show is called.

color-type: An enumeration containing the defined color pens in iview. It's present definition is:

(define-enumeration color-type (white red green blue black))
(iview-background-color! window color): Sets the background color of window.
(iview-circle window x y radius color): Draws the specified circle in the window.
(iview-clear window): Clears the window.
(iview-draw-image window image): Draws the specified image in the window.
(iview-ellipse window x y width height color): Draws the specified (horizontal?) ellipse in the window.
(iview-line window start-x start-y end-x end-y color): Draws the specified line in the window.
(iview-overlay-opaque window image color): Overlays the specified image in the window using foreground color color. This presumably only works for binary images (i.e. image type monochrome). This would appear to effectively just be draw-image with the option of changing the color in which the image is rendered. Thus the term "overlay" is a misnomer.
(iview-overlay-transparent window image color): Transparently overlays the specified image in the window using foreground color color. Window pixels for which the corresponding image pixel is zero (false) are left intact. This presumably only works for binary images (i.e. image type monochrome).
(iview-point window x y color): Draws the specified point in the window.
(iview-rectangle window start-x start-y end-x end-y color): Draws the specified rectangle in the window.
(iview-text window start-x start-y string color): Draws the specified string in the window.
(iview-show window): Repaints the window.
(iview-y-level! window level): Sets the intensity with which to render nuv (intensity-normalized yuv) images in window.

In addition to the drawing functions about, the following routines can be used to create and destroy windows. However, they should generally be avoided in favor of get-window or get-window-like.

(make-iview-driver width height title): Creates an iview "driver" object. (I don't actually know what this does).
(make-iview driver): Creates an iview window.
(destroy-iview-driver driver): Destroys an iview driver object.
(destroy-iview window): Destroys an iview window. (Although they don't seem to disappear from the screen, at least for a while).