Derek A. Lamb
If you have decided you want to track features in images, then you have come to the right place. SWAMIS (the Southwest Automatic Magnetic Interpretation Suite) is a freely available and documented feature tracking code. SWAMIS was designed to tracking moving magnetic features on the Sun, but there's no reason it can't be used for other applications. But because it was designed to track magnetic features, it can handle positive-valued and negative-valued features in your image sequence. Of course, if you only have positive values, then SWAMIS will only have to do half the work.
SWAMIS is not a stand-alone program into which you can feed in your image sequence and pop out results. Instead, it is a suite of Perl Data Language (PDL) programs run in sequence. So you will need to have PDL running on your computer. You might already have it-it now comes in the SolarSoft distribution tree, and some Linux distributions are coming with it installed. Indeed, the Mandrake 10.1 I just installed has this available to install just like any other package, though I found this out after I had already installed. If you already have PDL, then you can skip 1.3. If you already have PGPLOT installed, which is likely if you have done any scientific computing or plotting, you can also skip 1.2 and go straight to 1.4. This Guide only assumes that you have a working Linux distribution of some kind (access to the installation media may be necessary) and a working internet connection. If you want to install onto Windows using Cygwin, go ahead, but I don't know anything about it. Your experience with installation may be different-this is just an edited account of my experience installing PDL onto a new system, and hopefully it will be helpful to you.
When I performed this installation, I did Section 1.3 before Section 1.2, but the PDL installation might have gone smoother had PGPLOT been up and running, so I recommend doing it in the order presented here. PGPLOT is a standalone library, so the order will not affect it adversely.
Currently, SWAMIS diagnostics and visual monitoring is accomplished through the powerful PGPLOT graphics package. It would be extremely useful to have this installed. Future versions of SWAMIS might support the newer PLPLOT, but this is not a priority at the moment. Before you try to download this, make sure that you don't already have PGPLOT installed
./PGPLOT_install -system=linux -with-png -with-gif
First, make sure you have Perl. If you have any recent distribution worth it's salt, you will have this. To make sure, at the command line type:
Second, make sure you have a recent version of perl. Say:
At this point I assume you have perl installed. Now, go to pdl.perl.org and download PDL. I recommend getting the latest Stable Release, because then if by chance something goes wrong you'll know it's you, not some unstable code you got. You'll probably end up with a file called PDL-2.4.2.tar.gz in your home or /tmp directory. At this point I make myself root and move the thing to /usr/local/build (make the directory if you need to). Unzip and unpack it with
tar -xvf PDL-2.4.2.tar;
cpan> install PDL
When I did this, CPAN gave me an error, something to the effect of ``Installation seems impossible.'' Don't worry, it's not really impossible, the script just didn't get a lot of positive reinforcement growing up. You're probably just missing some libraries. I scrolled up and found about the most useful information I could:
make: *** No rule to make target `/usr/lib/perl5/5.8.5/i386-linux-thread-multi/CORE/EXTERN.h', needed by `_01syntax_t_6b3a.o'. Stop.
make: Leaving directory `/root/.cpan/build/Inline-0.44/C/_Inline_test/build/_01syntax_t_6b3a'
A problem was encountered while attempting to compile and install your Inline C code. The command that failed was:
make > out.make 2>&1
The build directory was: /root/.cpan/build/Inline-0.44/C/_Inline_test/build/_01syntax_t_6b3a
So I went to the directory it told me to go to, and basically found the same information in the output files as was printed above. Having determined that the ``No rule to make target EXTERN.h'' seemed to be the first error message, and that I did not have a file by that name anywhere on my system, I decided to see what Google said. I found that Mandrake 10.1 was missing the perl-devel RPM, so I downloaded it (and its dependencies) and installed it. Went back to the CPAN prompt and reran ``install PDL'', then it crunched for awhile and said it couldn't find the file glu.h. So I went to Mandrake's rpm finder and found the packages with glu.h and installed them, then reran ``install PDL''. Lather, rinse, and repeat untill your system has all the packages it needs for a complete build. It might be a good ideal to get GSL, the Gnu Scientific Library, if you don't already have it. Get the GSL-devel package too, while you're there.To debug the problem, cd to the build directory, and inspect the output files.
Now PDL is installed, and it will work. You can type ``perldl'' at the command line and get into the shell. But you are going to need some more things to get it to work nicely. Go back to your CPAN and type:
Now you need to get SWAMIS itself. This is the last step, and then you're up and running. Go back to the SWAMIS website and download the SWAMIS archive. It might be useful to make a ``pdl'' directory in your home directory for holding your programs. Unzip and unpack the archive there, and you're ready to go. Now wasn't that easy?
This is slightly modified copy from a forthcoming ApJ article by DeForest et al.
SWAMIS uses a two-threshold signed discriminator with hysteresis in space and time. Pixels are subjected to the high threshold unless they are adjacent to any already- detected pixel, in which case they are subjected to the low threshold. The discrimination is iterated, dilating detected regions by comparison of their boundaries to the lower threshold, until no more points are added to the detected locus.
The high threshold is typically set to about 6 σ of the measured noise, and the low threshold is typically 2-3 σ. The discriminator keeps track of sign, yielding masks that are either 0, 1, or -1 depending on whether each feature is positive or negative. The threshold is specified to the code in absolute data value units: noise characteristics are determined in advance.
The neighborhood of a particular pixel in a dataset comprises up to 26 pixels in a 3×3 x,y,t cube, and SWAMIS can be switched to include different sorts of neighbors. Typically one does not consider the eight pixels that comprise the corners of the cube and that only share a single corner with the central pixel. The low threshold applies only to neighbors with the same sign as the adjacent region. The code can be made to allow neighbors only within the same frame as the test pixel.
SWAMIS uses recursion to extend features as far as possible into an output detection mask. First, all pixels above the high threshold are marked in the output mask, then multiple passes are made through each image. At each iteration, all pixels adjacent to newly-detected pixels are tested against the low threshold. Because neighbors are allowed on the time axis as well as the spatial axes, a recursive algorithm is used to step back and forth through the data as new points are detected (requiring points in the previous frame to be checked against the lower threshold). There is a user-settable limit on how far back this "look-behind" can traverse.
SWAMIS contains two identification methods: "clump" and "downhill". The clump method groups any adjacent same-sign pixels into one feature with one identification number. The downhill method finds local maxima in the absolute data and assigns each maximum a unique label number. Label value then flows from each maximum toward zero until it either reaches the end of the feature or reaches a valley. In the event that two or more identification numbers meet in a "valley", any pixel that could go to either is arbitrarily assigned to the first number to reach that pixel.
The clump identifier also begins by seeding each local maximum with a unique label, but allows label value to flow "uphill", so that contiguous blocks of detected pixels all end up carrying the lowest numerical label assigned to any of the local maxima within each block. This step produces a list of images, each of which contains features marked by integer labels that are unique with the frame. Positive features get positive labels; negative features get negative labels.
SWAMIS scans through the identification frames and identifies intersections of same-sign features between each frame n and the successive frame n+1 For each feature f in n , a "forward intersection list" of intersecting features in n+1 is assembled. For the largest of those intersecting features, f'max, a "reverse intersection list" of features in n is assembled. f' is assigned the same label as f if and only if the largest reverse intersector of f'max is f. After all such features have been found and associated, the remaining unassociated features are presumed to be new and are assigned new globally unique labels. The output of this step is a set of images marked with globally unique labels that are persistent across frames.
SWAMIS separates the acts of associating features and tabulating feature histories into two separate passes. In the tabulation pass, SWAMIS calculates the flux, size, and x & y center-of-flux of each feature for each frame. Features with lifetimes less than 4 frames, maximum sizes less than 4 pixels, or x,y,t volumes less than 8 pixels are discarded (though the user is able to set these options). To avoid the swiss cheese problem, such discarded features are re-associated: if a discarded feature is touching another non-discarded feature of the same sign then all of its pixels are reassigned to the non-discarded feature. The output of this step is a table with feature ID running across the top and time step running vertically, containing, the location and size information for the feature for each frame. The associated-label images can be touched-up in place to save disk space.
SWAMIS' final pass through the data is an attempt to extract histories for all features. We determine how each feature is born and dies. The possible birth methods are: emergence, appearance, and fragmentation. An emergence occurs if there is nearby opposing flux that also emerged within a settable window of time, or a nearby feature of opposite sign that increases in flux. An appearance is an origin with no nearby flux of either sign, or if nearby concentrations change in a way that does not conserve flux. If an origin coincides with a nearby (or reverse-intersecting) feature of the same sign, and the nearby feature loses flux, then it is classified as a fragmentation.
Conservation of flux is enforced only approximately, to allow for noise and the difficulty of calibrating total flux. The "slop" on delta-flux is settable by the user for each of these types of event.
The death events of submergence (or cancellation), disappearance, and merging, respectively, are the birth events run backwards in time. An additional event type, complex, is present for multiple-feature interactions, and an error type is present for those events that do not conserve flux.
Get the sample tracking pipeline. This is how we use it, but you're free to experiment. ``00-data'' is the directory that contains all your images. ``01-mask'', ``02-id'', ``03-assoc'', and ``04-tab'' are directories that contain images of the intermediate steps. My advice is to copy and paste the code directly into the command line so you know what is happening with each command. If you want to see the documentation for a particular program, you can type at the command line
Please pass on questions or suggestions for this document to . Questions about SWAMIS operation can be directed either to Derek or to the main SWAMIS author, .
This document was generated using the LaTeX2HTML translator Version 2002 (1.62)
Copyright © 1993, 1994, 1995, 1996,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir519799Q6wZ/lyx_tmpbuf0/SwamisGuide.tex
The translation was initiated by Derek Lamb on 2005-06-02