Previous: , Up: Guile-CV   [Contents][Index]

3.2.9 Utilities

Other Guile-CV procedures and methods utilities.


Procedure: im-compose position alignment [#:color '(0 0 0)] img-1 img-2 …
Procedure: im-compose-channels position alignment channels widths heights [#:value '0.0]

Returns a new image or a new channel.

The valid position and alignment symbols are:

left right

top center bottom

above below

left center right

When used, the optional #:color keyword argument must come after the mandatory alignment argument and precede img-1, otherwise Guile will raise an exception. For RGB images, it is the color used to padd images passed in argument that are inferior, in width or height (depending on the position), to the biggest of them. For GRAY images, the #:color is reduced to its corresponding gray value:

(/ (reduce + 0 color) 3)

For the im-compose-channels procedure, the list of channels, widths and heights must be of equal length and equally ordered, so the nth element of widths and heights are the width and height of the nth element of channels. The optional #:value keyword argument is used to padd channels that are inferior, in width or height (depending on the position), to the biggest of them.

Procedure: im-display image [#:proc #f] [#:port (current-output-port)]
Procedure: im-display-channel channel width height [#:proc #f] [#:port (current-output-port)]

Returns nothing.

Displays the content of image or channel on port.

The optional #:proc keyword argument must either be #f, the default, or a procedure that accepts a single (32 bits float) argument. When #:proc is #f, im-display will use an internally defined procedure which formats its argument ‘à la octave’: nine positions, six decimals, all number aligned on the dot. any value >= 1000 is converted to use the exponential float notation. Here is an ‘hand made’ example:

$2 = (4 3 3 (#f32(0.0 1.0 2.0 3.0 4.0 5.0) ... ...)
scheme@(guile-user)> (im-divide $2 99)
$3 = (4 3 3 (#f32(10.1010103225708 0.010101010091602802 …) …))
scheme@(guile-user)> (im-set! $3 0 0 0 10000)
$4 = (4 3 3 (#f32(10000.0 0.010101010091602802 # # # # …) …))
scheme@(guile-user)> (im-display $4)

Channel 1

     1.0E+4    0.01010    0.02020    0.03030
    0.04040    0.05051    0.06061    0.07071
    0.08081    0.09091    0.10101    0.11111

Channel 2

    0.12121    0.13131    0.14141    0.15152
    0.16162    0.17172    0.18182    0.19192
    0.20202    0.21212    0.22222    0.23232

Channel 3

    0.24242    0.25253    0.26263    0.27273
    0.28283    0.29293    0.30303    0.31313
    0.32323    0.33333    0.34343    0.35354

Caution: unless you specify port, both this and im-display-channel procedures are ment to be used on very small and testing images, otherwise even on a small image, it might be ok in a terminal, but it will definitely will kill your emacs.

Procedure: im-histogram image [#:subtitle “Untitled”]

Returns two values: (1) an image; (2) a list (or a list of list) of significant values for image: one list if image is GRAY, a list of list of values per channel if image is RGB.

The returned image is composed of a header (title, #:subtitle), either the GRAY or the RGB channel histogram(s) for image and a footer, which is a table containg, for each channel, the following values: mean, standard deviation, minimum, maximum, the mode16 followed by its value.

Here below, the call sequence and the histogram for the GRAY image sinter.png given along with Guile-CV documentation and examples:

scheme@(guile-user)> (im-load "sinter.png")
$32 = (212 128 1 (#f32(25.0 39.0 50.0 52.0 51.0 45.0 # …)))
scheme@(guile-user)> (im-histogram $32 #:subtitle "sinter.png")
$34 = (282 271 1 (#f32(255.0 255.0 255.0 255.0 255.0 # …)))
$35 = (27136 163.346 75.081 0 243 215 727)

Note that histogram images returned by im-histogram have no borders, the above histogram has been padded - using (im-padd $34 1 1 1 1 #:color '(96 96 96)) - for better readability, otherwise the title above and the table below would look as if they were not centered.

Method: im-show filename
Method: im-show image [scale #f]
Method: im-show image name [scale #f]

Returns the string "#<Image: …>", where "…" is either filename or a filename constructed by im-show, see below.

The optional scale argument can take the following values:


pixel values are ‘clipped’: values < 0 are saved as 0, values > 255 are saved as 255, and otherwise are saved unchanged


all pixel values are scaled17 to the [0 255] range

These three methods will also effectively dislay the image if you are using Geiser, which analyzes Guile’s procedures and methods returned values (through the use of its pattern matcher), and when appropriate, triggers its image display mechanism.

Geiser has two variables that allow you to choose either to inline images in its Emacs (Guile repl) buffer, or to display them using externel viewer: geiser-image-viewer and geiser-repl-inline-images-p. You may choose to add these variables in your .emacs file, for example:

(setq geiser-image-viewer "eog")
(setq geiser-repl-inline-images-p nil)

Note that (setq geiser-repl-inline-images-p t) will only work if you are using a graphics-aware Emacs, and otherwise, will fall on the external viewer approach, if the variable geiser-image-viewer has been defined. When using Geiser in a non graphics-aware Emac, or when using the external viewer approach, images will appear as buttons: press return on them to invoke (or raise) the external viewer (window containing that image).

Except for the first im-show method, Guile-CV has to save the image first, and does it in the location defined by the %image-cache variable. If you call im-show passing name, the image is saved as %image-cache/name.png, otherwise under a generated name, the result of (symbol->string (gensym "im-show-")).

Note that if you do not specify name, a new external viewer window is opened at each im-show invocation, even for identical image calls: this because in Guile-CV, on purpose, images are just list, with no (unique) identifier, and there is no way for im-show to know ... Further to this point, when you pass name as an argument, you are not ‘identifyingimage, which may actually differ, but rather just ask to reuse the filename and hence the external viewer window associated with it.

Last note: many external viewers, such as Eog (the Gnome Eye Viewer), will try to apply, per default, some sort of smoothing techniques, especially on zoom-in and zoom-out: where this is fine for viewing ‘lazer’ pictures, you probably want to check and disable these options when working with Guile-CV.


Variable: %image-cache

Specifies the location used by im-show to save images.

The default value is /tmp/<username>/guile-cv, but you may set! it. If you’d like to reuse that location for future guile-cv sessions, you may save it in guile-cv’s ‘per user’ config file <userdir>/.config/guile-cv as an assoc pair, here is an example:

cat ~/.config/guile-cv.conf
((image-cache . "~/tmp"))

Note that if used, the ‘~’ is expanded at load time, so in geiser, it becomes:

scheme@(guile-user)> ,use (cv)
scheme@(guile-user)> %image-cache
$2 = "/home/david/tmp"
Variable: %image-cache-format

Specifies the format used by im-show to save images.

The default value is "png", but you may set! it. If you’d like to reuse that format for future guile-cv sessions, you may save it in guile-cv’s ‘per user’ config file <userdir>/.config/guile-cv, as an assoc pair, here is an example:

cat ~/.config/guile-cv.conf
((image-cache-format . "jpg"))



The mode is the integer corresponding to the histogram entry that received the maximum of hits, and the value displayed in parens precisely is the number of hits.


Note that in this particular context, scale does not mean a change in dimension, but rather bringing pixel values from the range they occupy in memory to the [0 255] range

Previous: , Up: Guile-CV   [Contents][Index]