Image Processing and Analysis in Guile
a Computer Vision functional programming library
Latest News
February 2023
Guile-CV version
This is a maintenance release, which introduces new interfaces.
Here is a summary of visible changes since
version
Dependencies
New interfaces
- im-fft
- im-fft-channel
- im-fft-inverse
- im-fft-inverse-channel
- im-fcc
- im-fcc-channel
- im-fncc
- im-fncc-channel
Older News
November 2021
Guile-CV version
This is a maintenance release, which fixes a bug in the
Here is a summary of visible changes since
version
Bug fixing
The
Guile 3.0 (>= 3.0.6) does not use libltdl anymore, and although in guile (system foreign-library) module, both the comment and the definition of augment-ltdl-library-path seems to take care of finding .so files either aside .la or in a .libs/ subdir, it does not work.
November 2021
Guile-CV version
This is a maintenance release, which allows Guile-CV to work with Guile 3.0 (>= 3.0.7 to be specific). In addition, im-transpose performance has been improved.
The documentation has been restructured and follows the model we adopted for G-Golf. The "Configuring Guile's raised exception system" section has been updated. Make sure you carefully read and apply the proposed changes.
Here is a summary of visible changes since
version
Dependencies
- Guile >= 2.0.14
- Makeinfo >= 6.6
[allows 2.2, 3.0 (>= 3.0.7)]
Performance improvements
- im-transpose
- im-transpose-channel
The f32vector-delineate core functionality has been moved to libguile-cv. Note that all memory allocation - except for some local variables - still is being performed in scheme.
This move makes im-transpose work 22x faster. Because all memory allocation still is done in scheme, and not in C, I am very confortable with this approach. When Guile has an AOT compiler that compiles fixed size floating points and small integers operations and vector loops for these that runs as fast as in C, and I am prety confident that it will happen, maybe not tomorrow, but it will happen, we will revert these and use Guile Scheme again.
Documentation
- The documentation has been restructured and follows the model we adopted for G-Golf.
- The "Configuring Guile's raised exception system" section has been updated. Make sure you carefully read and apply the proposed changes.
November 2018
Guile-CV version
This is a maintenance release, which introduces new interfaces and some performance improvements.
Here is a summary of visible changes since
version
Dependencies
- Vigra C >= commit 0af647d08 - Oct 28, 2018
The local minima and maxima interfaces have been improved, and now support the full set of options provided by Vigra, to our request (thank you Benjamin!). In addition there has been a few bugs fixed, including one we detected while working on Guile-CV local minima bindings.
New interfaces
- im-crack-edge
- im-crack-edge-channel
- im-local-minima
- im-local-minima-channel
- im-local-maxima
- im-local-maxima-channel
Performance improvements
- im-delineate
- im-delineate-channel
The f32vector-delineate core functionality has been moved to libguile-cv. Note that all memory allocation - except for some local variables - still is being performed in scheme.
This move makes im-delineate work almost twice as fast. Because all memory allocation still is done in scheme, and not in C, I am very confortable with this approach. When Guile has an AOT compiler that compiles fixed size floating points and small integers operations and vector loops for these that runs as fast as in C, and I am prety confident that it will happen, maybe not tomorrow, but it will happen, we will revert these and use Guile Scheme again.
September 2018
Guile-CV version
This is a 'milestone' release, which introduces image texture measures. In addition (a) the default installation locations have changed; (b) there is a new configure option; (c) some new insterfaces; (d) matrix multiplication performances have been greatly improved; (d) a few interface (name) have changed.
Here is a summary of visible changes since
version
Installation location changes
The default and
- $(datadir)/guile-cv
- $(libdir)/guile-cv/guile/$(GUILE_EFFECTIVE_VERSION)/site-ccache
In the above,
This change makes Guile-CV compatible with the
GNU Coding Standards, but it also implies that, unless you use the new
configure option describe below, you will have to augment both Guile's
variables
New configure option
The configure option --with-guile-site has been added, used to explicitly ask Guile-CV's source modules and compiled files to be installed using Guile's global site and site-ccache directories respectively (see Guile-CV's installation 'Notes' for more on this).
It will only be honored if (and only if) it is passed as:
- --with-guile-site=yes
- [ in this case, there is obviously no need to augment Guile's
- [ variables %load-path and %load-compiled-path
Interface changes
The following methods have been renamed, and the matrix
operations
- im-mtimes <- im-multiply (matrix)
- im-mtimes-channel <- im-multiply-channel
- im-times <- im-multiply (scalar)
- im-times-channel <- im-multiply-channel
- im-mdivide <- im-divide (matrix)
- im-mdivide-channel <- im-divide-channel
The former two methods, related to matrix multiplication, are now procedures. The later two are methods: see the manual to see the different ways you may call them.
Likewise, these were methods, they are now procedures.
New interfaces
- im-times (element by element)
- im-times-channel
- im-divide (element by element)
- im-divide-channel
- im-texture
- im-glcp
- im-glcm
Performance improvements
- im-mtimes
- im-mtimes-channel
- im-mdivide
- im-mdivide-channel
- im-invert
- im-invert-channel
These matrix operations (actually, their corresponding f32vector-* core functionality) have been moved to libguile-cv. Note that all memory allocation - except for some per-function local variables - still is being performed in scheme.
This move makes a small black and white 515 x 515 image matrix multiplication by itself (for the sake of timing things) execute in 0.228 sec instead of 29.51 sec - that is 134x faster.
In image processing 'real world', this would be a tiny image, being 134x faster for these linear algebra procedures makes a huge difference. Until Guile offers 32 bits floating point and integer calculus performances equal to or faster of those we get using libguile-cv, and since memory allocation is done in scheme, I am confortable with this approach.
Mai 2018
Guile-CV version
Here is a summary of visible changes since
version
Dependencies
- Vigra C >= commit a2ff675f4 April 15, 2018
new interface vigra_nonlocalmean_c (introduced in Jan 2018), has an argument that has been renamed;
the vigra_medianfilter_c function (updated in Jan 2018 as well) takes an additional 'out-of-bound strategy' argument.
New interfaces
- im-median-filter
- im-median-filter-channel
- im-nl-means
- im-nl-means-channel
Bug fixes
- latex-pdftoppm
in the module (cv support latex) - undocumented but quite usefull procedure, to 'prepare' text to be added to images (see im-compose) - the optional keyword [#:res 72] argument was actually not used in the core of the procedure, fixed.
18 December 2017
Guile-CV version
Here is a summary of the changes since
version
Dependencies
- Vigra C >= commit 691b189b0 Oct 25, 2017
A clipping bug has been fixed in vigra_exportgrayimage_c, vigra_exportrgbimage_c and vigra_exportrgbaimage_c. A new vigra_clipimage_c function is available and Guile-CV uses it.
Configuring Guile for Guile-CV
- I finally got my hands on how to configure Guile's raised exception system (special thanks to Daniel Lloren) so it does not 'blow' the repl upon errors anymore, while using Guile-CV (or manipulating any other big structures for that matters, huge lists, arrays, sfri-4 bytevectors ...).
- As a consequence, the manual has been updated and now covers both Guile's repl-print and raised exception system configuration, either globally, or individually: it is highly recommended for all users, even those who are already using GUile-CV I mean, not just new users, to very carefully read and apply these two recommendations.
Interface changes
- im-fill-holes
im-fill-holes-channel - im-scrap
- im-label
- im-label-channel
- im-label-all
- im-label-all-channel
- im-features
- im-binary?
Previously, these two procedures were respectively named im-fill and im-fill-channel, but that was a bit ambiguous.
New optional keyword,
Return n-label, not n-object. The number of labels correspond to the highest label value + 1: earlier version of Guile-CV, prior to version 1.8.0, did return the number of objects, which correspond to the highest label value. This was less then optimal, since not only 0.0 is a label, but other procedures, im-features for example, do consider and return a feature object for the background as well.
Note that Vigra C functions return the label highest value, but the vigra-label-all function starts to label using 1.0, so in this case, the label highest value is also the number of label used, hence im-label-all-channel has to return 'n-object' and not '(+ n-object 1)', fixed. I don't like this, for me it is inconsistent, and im-label-all should start to label using 0.0 as well, so I mailed the Vigra folks, let's see...
Consistency between im-label, im-label-all and im-features. All these already named their argument 'n-label', but it actually ment 'n-object'. I changed all this - and the segmentation related code as well - so it is consistent everywhere in the code. And now, the n-label argument value also correspond to the length of the list of features returned, so much better.
Vigra C functions, at the contrary, expect 'n-object', or expressed differently, expect the label highest value, which correspond to (- n-label 1). This is also consistent everywhere in the code now.
Now accepts more then one image.
New interfaces
- im-clip
- im-clip-channel
- im-reconstruct
- im-and-channel
- im-or-channel
- im-xor-channel
- im-binary-channel?
- or-l
We had and-l already. There are (well known among schemers) situations where you need a function that works on lists.
- im-composite->rgb
Composite images only differs to others in the sence that they can have more then 3 channels, any number of channels actually, the 4th _not_ being the traditional alpha channel. Each channel holds on specific information, depending on the application domaim. It is sometime necessary to visualize these though, in which case they must be 'converted' to RGB images, hence this new procedure. This is a 'work in progress': as it is, it will only work if the composite image has 4 channels. In this first implementation, the algorithm will super impose the 4th channel to the RGB's, so one says 'white pixels always win' (this because the 4th channel is (generally) associated with the White 'color').
Removed interfaces
- im-list=?
It was a bad idea to make this internal procedure public, and users can call (apply im-=? ...) anyway.
Performance improvements
- im-rgb->gray
im-threshold - im-fill-holes
- im-features
- im-min
- im-min-channel
- im-max
- im-max-channel
- im-range
- im-range-channel
- im-add
- im-add-channel
- im-subtract
- im-subtract-channel
- im-multiply (value)
- im-multiply-channel (value)
- im-divide (value)
- im-divide-channel (value)
- im-and
- im-and-channel
- im-or
- im-or-channel
- im-xor
- im-xor-channel
- im-=?
- im-=-channel?
- im-binary?
- im-binary-channel?
- im-rgb->gray
- im-fill-holes
- im-fill-holes-channel
- im-threshold
- im-reconstruct
Calls im-rgb->gray-1, which was unnecessary calling float-round at each step, and I also noticed that recursive tail call procedures have a tiny penalty compared to loop, so rewrote both. Now, in addition, both procedures will split their work in between as many core as available, except if the parameter %use-par-map has been set to #f. On my laptop - i5-2450M CPU @ 2.50GHz × 4 and 5.7GB of mem - both procedures are now 3 to 4 times faster.
Labels are 'discrete' floats, by definition, so we can use = instead of float=?, which is 3 to 4 times faster.
Area, left, top, right, bottom values are discrete floats, use float->int, not float-round.
Till Guile-3.0 becomes available, I decided to temporarily rewrite the math, linear algebra and logical 'low level' procedures in C. Tests performed on my laptop - i5-2450M CPU @ 2.50GHz × 4 and 5.7GB of mem - using GRAY and RGB test images of 2718 x 1732 show gains in the range of 23x to 100x faster, depending on the operation and wether images involved have 1 or more channels (though in Guile-CV, unless the user sets the %use-par-map parameter to #f, all multi channel operations are multi threaded).
Because all memory allocation still is done in scheme, and not in C, I am very confortable with this approach, as I said, till we have an AOT compiler that compiles fixed size floating point and small integers operations and vector loops for these that runs as fast as in C, and I am prety confident that it will happen, maybe not tomorrow, but it will happen.
23 October 2017
Guile-CV version
Here is a summary of the changes since
version
Dependencies
- Vigra C >= commit a38f361 Sep 18, 2017
That commit introduces - kindly implemented by Benjamin Seppke upon our request - the following new features: centre of mass, perimeter, skewness, kurtosis.
Interface changes
- im-save
im-show
Adding an optional (scale #f) argument. Till now, images pixel values would be always scaled at save time, unless saving the file using tif. This was really less then optimal because (a) tif preserves values, but no image viewer knows how to display these Guile-CV 32 bits float images (they beleive these are RGBA images) and (b) scaling at save time totally destroyed the results of im memory calcuations ... What we really want here, most of the time at least, and hence it becomes the default from now on, is what is called 'clipping': pixel values are ‘clipped’, which means that values < 0 are saved as 0, values > 255 are saved as 255, and otherwise are saved unchanged.
- im-invert
im-channel-invert
f32vector-invert
f32vector-invert
Previously, these procedures were using the name 'inverse', but that was not 'optimal', fixed.
New interfaces
- k-make
- k-make-circular-mask
- k-size
- k-width
- k-height
- k-channel
- kernel?
- k-ref
- k-fast-ref
- k-set!
- k-fast-set!
- k-offset
- k-fast-offset
- k-display
- im-convolve
- im-convolve-channel
- im-gaussian-sharp
- im-gaussian-sharp-channel
- im-sharpen
- im-sharpen-channel
- %pi
- %2pi
- %pi/2
New features
- new GRAY features
major-ev-x, major-ev-y, minor-ev-x, minor-ev-y, major-axis, minor-axis, angle, center-mass-x, center-mass-y, perimeter, skewness, kurtosis, circularity, aspect-ratio, roundness.
- new RGB features
major-ev-x, major-ev-y, minor-ev-x, minor-ev-y, major-axis, minor-axis, angle, center-mass-x, center-mass-y, perimeter, skewness-r, skewness-g, skewness-b, kurtosis-r, kurtosis-g, kurtosis-b, circularity, aspect-ratio, roundness.
Bug fixes
- im-set!
im-images?both procedures have been 'relaxed' and do not check anymore that either the value or pixel values respectively are in the [0 255] range, as doing so was actually incorrect: images need to be normalized and scaled (as in bringing their pixel values in the [0 255] range) only to be displayed, but otherwise, their should be no such limitations.
- im-binary?:
was returning #f for BLACK and WHITE images, so either composed of eiher 0.0 or 255.0, fixed.
14 August 2017
Guile-CV version
Here is a summary of the changes since
version
Interface changes
- im-normalize
im-normalize-channel:Adding an optional #:key (val 255.0), since we need to be able to normalize to specific values in some circumstances, such as, for example, to normalize gray level co-occurrence matrices.
- f32vector-reduce:
The arguments order has been changed for 'vector proc default' not 'proc default vector', because it is the order we use in im-reduce and im-reduce-channel - as [almost] all other im-* procedures or methods take an image as their first argument. As a user, it is also a bit more naturel, imo at least, to 'reduce image using proc, return default if the image is empty'.
- im-add
im-add-channel
im-subtract
im-subtract-channel
im-multiply
im-multiply-channel
im-divide
im-divide-channel:All linear algebra matrix methods now accept any number of images or channels. Note that due to the inherent checks between lines and columns of intermediate results, im-multiply-channel and im-divide-channel methods arguments must be a series of at least one tuple(s) composed of three values - channel width height - represented in the manual as: c1 w1 h1 c2 w2 h2 c3 w3 h3 …
- im-collect:
Updated so its interface is 'identical' to im-map and friends, and a typical call now looks like: im-collect what i1 i2 i3 … (instead of im-collect images what).
New interfaces
- im-range
- im-range-channel
- im-min
- im-min-channel
- im-max
- im-max-channel
- im-map
- im-map-channel
- im-reduce
- im-reduce-channel
- f32vector->s32vector
- f32vector-range
- s32vector-range
- s32vector-min
- s32vector-max
- s32vector-reduce
- s32vector->f32vector
Bug fixes
- im-normalize:
the width and height of the result normalized image were inadvertently inverted, now fixed.
- f32vector-matrix-multiply:
the sub results were inadvertently using 'n' instead of 'p' to compute their destination position in the 'n x p' cells returned result f32vector, now fixed.
24 July 2017
Guile-CV version
Here is a summary of the changes since
version
Interface changes
- dark -> black
light -> white:- both in the source code (optional kw default values)
- and in the documentation
New interfaces
- im-delineate
- im-delineate-channel
- im-distance-map
- im-distance-map-channel
- im-canny
- im-canny-channel
- im-xor
- f32vector-xor-at-offset
Bug fixes
- Import export test-suite
- Error message for im-gaussian-gradient
- Documentation typos
- Histogram gray legends below their histogram
24 May 2017
Guile-CV version
This is the first public release of Guile-CV, earlier releases were made available to GNU evaluators and Savannah hackers only.
Here is a summary of the changes since
version
Dependencies
- Makeinfo >= 6.3
- Latex: any modern latex distribution will do
documentclass: standalone.
packages: inputenc, fontenc, lmodern, xcolor, booktabs, siunitx, iwona
API changes
- im-properties:
- renamed im-features
- im-*grey* procedures and methods:
- renamed im-*gray*
- dito for arguments
- GREY -> GRAY in the documentation
- colour -> color
COLOUR -> COLOR:- both in the source code (arg and kw arg names)
- and in the documentation
- f32vector-* procedures:
- use #:key, not #:optional
- im-padd
im-padd-channel:- accept a #:color optional keyword argument
- f32vector-multiply:
- renamed f32vector-matrix-multiply
New procedures
- f32vector-inverse
- f32vector-reduce
- f32vector-mean
- f32vector-std-dev
- im-add
- im-add-channel
- im-subtract
- im-subtract-channel
- im-multiply
- im-multiply-channel
- im-divide
- im-divide-channel
- im-inverse
- im-inverse-channel
- im-compose
- im-compose-channels
- im-particles
- im-particle-clean
- im-histogram
13 March 2017
Guile-CV is now on Savannah nongnu.
The GNU evaluation of Guile-CV has been completed on March the 11th, 2017, but due to backlog, we've been informed then that its approval step would take another five weeks, so we decided to upload it on Savannah non gnu in the mean time, done!
Releases, Guile-CV git summary and Guile-CV git log all available now... Special thank to the GNU evaluator and of course to the Savannah hackers!
31 January 2017
A couple of months ago, we started to work on Guile-CV, a Computer Vision functional library for the Guile Scheme language, and now is the right time for it to be evaluated to be part of the GNU Project.
Guile-CV is based on Vigra (Vision with Generic Algorithms). It comprises a direct binding to Vigra C (a C wrapper to a subset of the Vigra library), and a higher level API written in Guile Scheme.