Snakuscule

An ImageJ plugin to nurture a lonely snakuscule.

Philippe Thévenaz, Biomedical Imaging Group, École polytechnique fédérale de Lausanne (EPFL)

Figure 1. Snakuscule ready to pounce on a bright blob.

Figure 2. Snakuscule happily feeding off the bright blob.

General Description

Are you afraid of snakes? or, as Emily Dickinson put it:

    But never met this fellow,
    Attended or alone,
    Without a tighter breathing,
    And zero at the bone.

Fear no more! The snake of this plugin is of the image-processing variety, also known as active contour. Its purpose is to detect circular blobs in images and to quantify them. It also illustrates the behavior of a textbook snakuscule and allows the curious mind to get a glimpse of the fascinating animals described here.

Since ancient times, snakes have been recognized for their cunningness [Liber Genesis 3.1, Vetus Testamentum, Nova Vulgata]:

    Et serpens erat callidior cunctis animantibus agri

This verse could be loosely translated as "wise as a snake". Snakuscules are but minuscule snakes; they follow the same antics as their larger brethren wile remaining harmless to their keepers. Their sole interest lies in hunting circular bright blobs in images. Once found, they ensnare it [William Shakespeare, A Midsummer night's dream, Act II, Scene 1]:

  Oberon
    And there the snake throws her enamelled skin,
    Weed wide enough to wrap a fairy in.

The plugin allows one to keep record of the location and size of all preys.

I. Download

This distribution is dated September 30, 2024. It includes the main source file, along with a jar file that contains the precompiled classes and a Java package for which an API is also made available.

• ZIP distribution
• Source files
• API

II. Related Work

This set of Java classes is based on the following paper:
P. Thévenaz, M. Unser, "Snakuscules," IEEE Transactions on Image Processing, vol. 17, no. 4, pp. 585-593, April 2008. Other relevant on-line publications are available at http://bigwww.epfl.ch/publications/.

Snakuscule has been written as a plugin for ImageJ. Please read the ImageJ documentation to learn how to install plugins.

III. Technical Explanations

The snakuscule is an active contour (or snake) that we stripped down to its bare essentials. The contour is parameterized by no more than two xy-coordinates (four numbers) that define a circle (three numbers). The energy functional combines regularization and data term; regularization is used to restore the balance between the number of parameters of the curve description (four) and the number of parameters of a circle (three), while the data term favors bright blobs surrounded by dark background. Altogether, the snakuscule behaves like a detector of circular bright blobs.

We distribute the source code that handles the mathematical wizardry of our snakuscule. The part of the code that handles more mundane tasks such as the front-end is encapsulated in a Java package for which we distribute the archive and the documentation.

IV. User Manual

Launch

Figure 3. Empty table of results.

The plugin requests at least one open image at launch. All image types are accepted, but the processing will be performed on the luminance channel in the case of RGB Color images. In the case of a RGB Stack or a HSB Stack, the processing will be performed on the current channel instead. In the case of 8-bit Color images, the underlying color indices will be treated as intensity value.

At launch, a results window will appear (see Figure 3). This window is initially empty and previous results are overwritten—they may have resulted from operating the Analyze menu, or from previous Snakuscule sessions. The snakuscule can then be operated upon thanks to a revised set of tools from ImageJ's toolbar, which we discuss below. ImageJ's toolbar is restored as soon as the snakuscule dies.

Image magnification/minification

Figure 4. Zooming tool.

To magnify an image, select the magnification tool and click in the image. To minify an image, use the same tool with the <CNTL> or <ALT> keyboard modifier.

Moving a point

Figure 5. Tool to move points.

To select a point, click anywhere in the image. The point closest to where you clicked will be highlighted. To move points, drag within the image. The point closest to where you clicked will be moved to the position where you release the mouse. Alternatively, you can use the keyboard arrow keys to get a finer control over the position of the points; for this to work, the image window must be frontmost. Note: it is not possible to interactively move a point outside of the image frame; the optimizer, however, is allowed to.

To translate the snake all at once, you can also depress the <SHIFT> key before dragging the mouse. Still, a combination of shift and arrow keys will move just one point.

Optimizing the snake

Figure 6. Tool to launch the optimization.

The 'play' button (a right-pointing black triangle) is used to start optimizing the snake. The <ENTER> and <RETURN> keys provide convenient shortcuts for this operation; for this to work, the image window must be frontmost. In this mode and during the optimization, the set of tools is modified as follows:

Figure 7. Available tools during snake optimization.

The 'stop' button (a black square) is used to manually abort the optimization. If hit, the resulting snake will be returned in the state where it achieved the most favorable configuration so far during the course of optimization. If left to its own devices, the snake will converge to some (possibly local) optimum.

Recording the snake

Figure 8. Tool to deal with the table of results.

The 'record' button (a check mark) is used to give access to a panel of buttons that perform various operations on the table of results. The most important operation is that of appending the current state of the snakuscule and is also available through the shortcut of the <SPACE> key; for this to work, the image window must be frontmost. Similarly, it is possible to remove the last entry from the table, either with the appropriate button, or with the <BACKSPACE> key. Emptying the table is achieved thanks to the 'Clear Table' button. Finally, the button 'Graph Table Entries' gives access to the visualization of the work achieved so far. The panel of buttons is shown in Figure 9.

Figure 9. Operations that deal with the table of results.

The 'Graph Table Entries' leads to the panel of buttons shown in Figure 10. These operations become available as soon as at least one snakuscule has been recorded. Only recorded snakuscules play a role; the current one is ignored entirely. When the box 'Include Labels' is checked, recorded snakuscules are displayed with the number that identifies them in the table of results. The operation 'Stamp' modifies the image values, by impressing the snakuscules outlines—possibly with their label. Beware: subsequent snakuscules will be driven by the stamped data, not by the original data anymore.

Figure 10. Operations and settings to display and document the snakuscules recorded so far.

Understanding the table of results

Figure 11. Table showing the parameters of snakuscules from Figures 1 and 2.

The location and size of a snakuscule is described by the two points p = (p₁, p₂) and q = (q₁, q₁). As described here, this leads to a measure of energy E of the snakuscule. Those are the five numbers recorded in the table of results, along with a numeric ID to label each snakuscule. The concordance of the table headings with the symbols of the paper is as follows: X0 = p₁, Y0 = p₂, X1 = q₁, Y1 = q₂, and J = E. For example, we see in Figure 11 that the initial configuration of Figure 1 leads to a snakuscule with external diameter (2 R) = √((194 - 124)² + (113 - 53)²) and energy E = 32.191, while the optimal configuration of Figure 2 sees a much lower energy E = -33.986.

Returning to ImageJ

Figure 12. Tool to leave the snakuscule.

This tool is used to gracefully return to ImageJ. The leave tool is available during interaction and optimization as well. The <ESCAPE> key provides a convenient shortcut for this operation; for this to work, the image window must be frontmost.

V. Conditions of Use

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

You undertake to include a citation or acknowledgment whenever you present or publish results that are based on this program. EPFL makes no warranties of any kind on this software and shall in no event be liable for damages of any kind in connection with the use and exploitation of this technology.