Microbeam Analysis Journal Article

This article is a good introduction to MacLispix. Although the specific directions are written for the 1995 version, which uses menus and runs native on 68k Macs only, it show many of the things MacLispix can do. This article had a companion article about NIH Image.

This is a version of the paper published in MICROBEAM ANALYSIS, the Journal of the Microbeam Analysis Society, 4 (1995): 151-163. Additions have been made since the article went to press to bring it up to date.


A Special Purpose Public Domain Image Analysis Program

for the Macintosh*

David S. Bright
Surface and Microanalysis Science Division
National Institute of Standards and Technology
Gaithersburg, MD.


This paper is a guide to, or a hands-on introduction to MacLispix, a Macintosh based, public domain image processing program written by David Bright, NIST, Gaithersburg, Md. It and the sample images are available via anonymous FTP from NIST as described. The reader is introduced to some capabilities of MacLispix and some elementary image processing steps, including various kinds of scaling, measuring image statistics, averaged line profiles, color overlays, three dimensional scatter diagrams, thermal scales and the direction of gradient operator.

I. Introduction Top

This is a demonstration guide to MacLispix, a public domain image processing and analysis program for the Macintosh. MacLispix is a special purpose image processing program with some unique tools and features developed to meet research needs of the Microanalysis Group in the Surface and Microanalysis Science Division at NIST. MacLispix is introduced by comparing it to NIH Image , a much more widely known image processing program for the Macintosh, described in an accompanying article in this issue. In general, if NIH Image will do the job, then use it rather than MacLispix, because MacLispix is harder to use.

II. Features Top

Features of MacLispix include red -> green -> blue color overlays, real, complex, integer, byte or bit image arithmetic, two and three dimensional histograms, line profiles of any thickness, scaling (including clipping outliers) and cropping tools for operating on many images at once. There are also tools to read corresponding single pixel values in a number of images, to give intensity profiles for similar situations, to give statistics of pixel values within a moveable rectangle, to draw one image and duplicate the drawing on a number of others regardless of how they are zoomed, and to add color to an image with reference to both the original and the scaled pixel values.

More special purpose tools are included to load, display and process a group of images at a time in order to provide two and three-dimensional histograms, red -> green -> blue overlays, principal components and phase analysis.

MacLispix can be used to 'publish' algorithms in a form others can use and test. With the Common LISP environment available, new algorithms can be written and this LISP source code can be sent to a colleague along with MacLispix. The colleague can load the new LISP source and test the algorithms. LISP is a computer language that was developed for LISt Processing by the Artificial Intelligence community, and that now enjoys varied applications.

The source code for the image processing tools is supplied with MacLispix, and is available on- line -- a mouse click will display the code that implements a particular menu item. The documentation is available in a similar fashion. The Macintosh Common Lisp environment also includes help features for LISP functions, if desired.

I by no means claim that these features cannot be found in other image processing programs, but most of these features are not yet found in those that are public domain and Macintosh- based.

B. Non-Macintosh like features
This is to anticipate the reaction of first time users, who are often frustrated by the program behaving differently from what they might expect after using NIH Image, for example. MacLispix is primarily a research and development environment rather than a fully tested and debugged Mac application. The user interface differs in some respects from the traditional Mac interface, both to make the software more simple and to more naturally fit some of the research requirements for which it is used. MacLispix is being distributed because it has unique tools that others have requested and found valuable. MacLispix consists of the Macintosh Common Lisp programming environment (less the compiler so that it can be distributed freely) with added commands to load, process and display images. Since the original programming environment is not hidden from the user, MacLispix appears to be more complex than it is.

Two major differences between MacLispix and many other Mac Image processing software are the named image arrays for calculations and the Listener window for status messages and results.

Images are read from files into arrays which are given a name (as with most programming languages, but not as in most Macintosh applications). The arrays can be displayed, but do not need to be. Arithmetic and processing operations are specified with reference to the arrays themselves and not the windows that may display them because of this reason: Displayed images are always of byte precision -> values ranging from 0-255, because that is the display capacity of most computers and image processing systems. The data that the images represent, however, may exceed the 8-bit range (such as often the case for maps of x-ray counts), ratios of other images, micrographs from a scanning electron microscope with a 12- bit analog-to-digital converter, etc. (This is not the case for many image sources -- these often give single byte images, or images with higher precision but where no useful information is lost by scaling the image to one byte or by other processing steps. For these situations, NIH Image may be more than adequate.) Scaling for display can be tricky -- MacLispix retains both the original and the scaled data, referring to the original for statistics, profile plots, etc. The parameter lists take the place of preferences dialogs, and control the operation of MacLispix in many respects. MacLispix requires more active use of the parameter lists than other programs may of their preferences dialogs. Use of the parameter lists is described below.

The Listener window is a feature more like non-Macintosh environments. It is much like a terminal window, to which messages and results are printed. Commands may also be typed in this window, however this is never required when using the tools found in the menus.
III. Comparison with NIH Image Top
Function NIH Image MacLispix
Mac User Interface complete, well developed partial (eg.: no cutting and pasting)
Multiple Images as a stack or movie (typically 50 or more) as components, usually 2 or 3 or as stack
Support frame grabber cards many none
Data (Pixel) precision byte (0-255) bit, byte, integer, real, complex
Documentation and Source code Separate files. can be accessed and searched from within MacLispix
Background calculations, timer no yes
Number of users thousands, e-mail list 100
Development mature new
Modifications macro programming language add small pieces of LISP code
Memory requirements 4 MB minimum, 8 MB typical 4 MB minimum, 8 MB typical
Disk storage 1 MB -> will fit on one high density floppy disk 5-10 MB -> requires compacting and more than one floppy disk
Speed usually faster usually slower
Color display 8 bit (RGB images converted) 1, 8 or 24 bit, etc.
IV. Installation Top

MacLispix comes as a self extracting archive containing the program, sample images, source code and documentation files. It is available via anonymous FTP from enh.nist.gov, in the Mac sub-directory. MacLispix and the many auxiliary files will be extracted into a folder in which MacLispix should stay if it is to work with the auxiliary files. Double click on the archive and follow the directions. Make an alias of the program and put it in a convenient place such as the desktop or the apple menu items folder.


MacLispix requires more memory per image to run than do most other programs, because the original data is retained for intensity measurements, and a scaled version and a pixel map are retained for display. At least 20 MB is recommended for these demonstrations. Use the File -> Get Info command in the finder to assign the 'Preferred Size'. After starting, the Memory button will show how much memory is available for images.


Double click on the alias to start MLx and wait for it to start up. The Listener window will appear at the bottom of the screen with a message when MLx is ready to use. The Listener window acts like a terminal window and shows status messages. Text can be cut and pasted from this window to other text windows made using the File -> New command. (In the MacLispix help dialogs and in some of the documentation, the command names are surrounded by curly brackets, e.g. {File -> New}. This is because the italics are cumbersome to implement within the dialogs.) Note that these text windows can scroll left to right as well as up and down. There is virtually no limit to the length of a row of text. Text windows can be read from and written to plain text files, which can be read with most any text editor, although the formatting information such as the italics will be lost. The bottom of the Listener window gives the processor status, and should say 'idle' before invoking most menus. The on-line help and source code is accessed by holding the option key down while selecting a colored menu item, that is, a MacLispix command. Most black and white menus come with the Macintosh Common Lisp environment from Apple, and will not access this type of help.

For example, with no images loaded, invoking the Show button will bring up a selection dialog with no items in it. However, holding down the option key while invoking the command will bring up a dialog box that briefly describes the command and the effect of other keys on it.

If one is interested in looking at the source code, the source code button will display the LISP function that begins with "(defun display_globals_linear ()", which is the top level function for displaying image arrays. Other functions that are called by this function may be displayed in turn by putting the selection bar (the text editing tool) on either side of the function name and pressing option-period (option-.).


Pressing the HELP button will display the documentation describing the command in more detail.


The apple -> about MacLispix command displays a dialog similar to that seen when holding down the option key for the colored menus. Clicking on the Help button will display a list of documentation files and instructions for accessing them, which is a second way to browse the documentation. The last, and most obvious way, but probably the least useful, is to look at the files with MacLispix using the File -> Open command or the File -> Open MLx -> Docs command, or with some other text editor.

MacLispix has several parameter lists that control various aspects of its behavior. In the main parameter list, there is a parameter called auto_display that renders it unnecessary to use the MLx -Show Image Arrays command, by displaying images whenever they are loaded or generated as a result of calculations. Since displaying images uses additional overhead both in the LISP heap to store the scaled image array and in the Mac heap to store the pixel map for the window, the default for auto_display is "NO".


To turn auto_display on, invoke the MLx -> Parameters command, then either double click on auto_display or select auto_display by clicking on it (it will become highlighted) and click the "Select" button. A new dialog will appear giving the choices for the auto_display parameter. The title bar for this dialog shows which parameter is being changed, and the current value in parentheses. Either double click on "YES", or click on "Yes" to select it and click the Select button. Another dialog will appear explaining what has been done (most parameters do not have such a dialog). If you click "OK", the parameters dialog will return for selection of another parameter -- click the "Done" button to quit changing parameters. If you click "Cancel", you will also quit changing parameters (but the ones you have changed -> auto_display in this case -> will remain changed.) When auto_display is on, ignore references to the MLx -> Show Image Arrays command that follow.

V. Demonstrations

These examples are meant to be cook-book type lists that can be followed by a new user to get started. Menu commands are shown in bold , for example, File -> Open is the Open command in the File menu.

MacLispix is supplied with some demonstrations and instructions in the documentation. The sample images are in the Demo_images folder. Some of these demonstrations are not included here.

The examples in this paper are different from the {other} demonstrations, and are of specific interest to microscopists, and illustrate a few of the capabilities of MacLispix.