cl-imagemagic: A Common Lisp layer for ImageMagick

Table of contents

• Description
• Author
• Author comments
• Documentation
• Platforms
• Dependencies
• Installation
• Configuration
• Licence
• Notes
• Examples
• Open Source

Description

cl-imagemagick is a Common Lisp wrapper for the ImageMagick libraries, MagickWand.

Author

Mikel Bancroft

Author comments

ImageMagick is a suite of tools allowing you to create, edit, and compose bitmap images. It provides powerful command-line tools to this effect, but also provides a number of APIs to make the same features available programmatically. Using SWIG, we have generated the foreign wrappers to the MagickWand API.

Platforms

It is known to work with Allegro Common Lisp 8.1 and ImageMagick 6.5.2-Q16 on Windows and 6.2.2 on Linux.

Dependencies

• ImageMagick
• swig (optional see the notes section below)

Installation

Make sure you have the ImageMagick libraries installed on your system. We currently pre-generate foreign-function definitions on both the linux86 and windows platforms. If you wish to try this demo on another platform, please see the notes section of this README file.

• Download the cl-imagemagick repository from github.
• cd into the directory in which you've downloaded cl-imagemagick.
• start Allegro CL
• Enter the demo directory :cd demo
• Load the demo code. :cl demo-thumb.cl

This will compile and load the demo. To run it you'll be starting a server on the local machine via the function start-server. This function takes an optional argument indicating the port on which the server listens. It defaults to 8080. If that is acceptable, you can start the server by evaluating:

(start-server)

The server should now be up and running.

Configuration

If you'd like to specify a different port, for example port 9000, evaluate:

(start-server 9000)

Documentation

For more documentation please see the cl-imagemagick tech corner.

License

The cl-imagemagick source code is licensed under the terms of the Lisp Lesser GNU Public License, known as the LLGPL. The LLGPL consists of a preamble and the LGPL. Where these conflict, the preamble takes precedence. cl-imagemagick is referenced in the preamble as the LIBRARY.

Notes

The file MagickWand.cl found in the architecture specific subdirectories of windows/ and linux86/ were generated using the Makefile found in this distribution by running an up-to-date SWIG on MagickWand.i. If you wish to generate this interface on additional platforms, you can use this interface and the accompanying Makefile as a reference.

The swig command-line used to generate this interface:

swig -allegrocl -nocwrap -DACL_LINUX -I/usr/include -isolate MagickWand.i

-nocwrap tells SWIG that we do not want to generate any C wrapper code. In many, but not all, cases it is possible to interface to a foreign library directly from Allegro CL, via lisp code only. There are some situations where the C code being wrapped cannot be adequately parsed, and it becomes necessary to interface to the foreign code through a C wrapper as well.

-D's and -I's. As with typical compilers, you can tell swig to "#define" certain constants, and tell it where to search for include (.h) files.

-isolate tells swig to place it's helper code in a unique directory. By default, all helper code is added to the "swig" package. using -isolate makes it possible to load multiple interface generated by swig into the same lisp without running into any conflicts.

Here is a brief discussion of the contents of MagickWand.i

%module MagickWand

This names the Module currently being generated. In more concrete terms, the name chosen here determines the name of the output file, MagickWand.cl, and the common-lisp package into which the symbols defined by this interface are created.

%insert("lisphead")  %{
#+linux (load "/usr/lib/libWand.so")
#+mswindows (load "CORE_RL_wand_.dll")
%}

This form inserts code into the generated lisp wrapper. "lisphead" means that it will be output after any SWIG helper functions, but before any of the types, classes, or functions have been defined. On linux, this form assumes a default installation, while on windows, the assumption is that the path to the core ImageMagick libraries has been added to your PATH environment variable.

#ifdef ACL_WINDOWS
%include "wand/MagickWand.h"

%include "magick/magick-config.h"

%include "magick/magick-type.h"
%include "magick/MagickCore.h"
%include "wand/animate.h"
...

First, SWIG interface files are parsed just as a C/C++ header file would be, with the exception that by default, #include directives are not followed. You can use the same preprocessor syntax as you would in your foreign C/C++ code.

Second, most of the %include's you see here represent the "#include"'s that are found inside of wand/MagickWand.h. In particular, note that while MagickCore.h is included, this is not creating a wrapper for the entire MagickCore API. Rather, a few small types that are useful to the MagickWand API are being included.

If you have any questions about the interface or suggestions, please email us at support@franz.com.

Examples and Information

Please see the cl-imagemagic tech corner.

Open Source

This project's homepage is http://opensource.franz.com. There is an informal community support and development mailing list opensource@franz.com for these open source projects. We encourage you to take advantage by subscribing to the list. Once you're subscribed, email to opensource@franz.com with your questions, comments, suggestions, and patches.