Spamalize Programming Hints
These hints are for folks who are interested in fooling around with the source code for Spamalize and/or optimizing its performance.
A. Source Code:
The full download includes all of the Spamalize source code. You can read this code, and have permission to use entire programs and/or code snippets in your own programming efforts. Simple courtesy should apply here- you need to find a way to give credit to the Spamalize author. If you are unsure about how to do this, read the Conditions for Use and/or email Terry Oakes. Also, if you have specific questions about how to incorporate or use any of the Spamalize modules, send Terry an email.
B. Calling Sequence (Full Installation):
1. Introduction:
There are several ways to call SPAMALIZE:
- The easiest way is to add the SPAMALIZE directory to your IDL file path via the Preferences menu in the IDLDE (GUI) environment. After you add the directory "/.../spam_dir/", click the box to the left of the directory name, to include the subdirectories.
- If you want to call SPAMALIZE as the IDL startup file, select
"/.../spam_dir/src/spamalize_startup.pro"
from the Preferences menu. This is only a good idea if the only IDL application you will use is SPAMALIZE. Do NOT do this at the LfAN.
- If you want to compile and run SPAMALIZE from within the IDLDE environment, open, compile, and run the file "/.../spam_dir/src/spamalize.pro'.
- If you are currently in the SPAMALIZE main directory, you can enter IDL and type "SPAMALIZE".
The primary SPAMALIZE code is contained in /.../spam_dir/ (unix), which is the same as W:\local\progs\spamalize\ (Windows/PC). All Unix machines and Windows95/PCs machines should reference this. Every attempt is made to ensure that the code used by the Unix machines is identical to and compatible with the PC version, primarily by having then run the IDENTICAL CODE.
2. Unix:
Call from the shell script "spam__unix", containing the command:
idl /local/progs/spamalize/src/spamalize_startup
The file "spamalize_startup.pro" is technically not a procedure, but rather a "main" program, which is analogous to a batch-file. This construct is the only way to call idl from the command line and start up a series of programs. It is a short program, which does the following:
the last line calls the actual program (SPAMALIZE.PRO). This command can be an alias in your .cshrc file:
alias spam '/local/progs/spamalize/src/spam__unix'
It is tricky to set SPAMALIZE as the default when starting IDL; calling SPAMALIZE as the IDL startup is not usually a good idea, since sometimes you will want to call IDL without SPAMALIZE.
3. Windows95/98/2000 (also Windows NT, Linux emulator):
Run IDLDE (the interactive version with the fancy menu). This is usually located in
C:\RSI\IDL52\IDLDE
Go to File->Preferences->Path. Add the directory:
W:\local\progs\spamalize\
Click the box to indicate you want to search all subdirectories. If you want to have SPAMALIZE start automatically when you start up IDL:
Go to File->Preferences->Startup. Add the following:
IDL Main Directory: C:\RSI\IDL52
Startup file: W:\local\progs\spamalize\src\spamalize.pro
4. Macintosh:
Follow the general scheme for unix for the settings in “spamalize_defaults.txt”, but follow the Windows guidelines for starting IDL and Spamalize.
C. Make a shortcut to call SPAMALIZE easily.
For a Full license:
alias spam 'idl /apps/spamalize/install/spamalize_startup'
(Change the directory name above to reflect your installation.) Edit the following shell script and Spamalize program so that the directories reflect your directory structure.
/spam_dir/install/spamalize_startup.pro
Then, all you ned to do is type "spam" at the command line to start IDL with Spamalize. I recommend this approach, as opposed to making Spamalize be the default startup file, because if (heaven forebid!) you need to start IDL without Spamalize, you can then easily do so.
Run-Time IDL:
If you have a RunTime or VM license and the SPAMALIZE .sav file:
alias spam 'idl -rt=spam_dir/src/spamalize.sav'
D. Customizing Spamalize for your site:
Modify the following file, which contains directory shortcuts andgraphics-related parameters:
/spam_dir/install/spamalize_defaults.txt
The "defaults" text file is used so that users can modify the defaults at their own site. This is especially useful for users with a Virtual Machine or RunTime license, because without a text-file containing the defaults, the defaults have to be "cast in stone" when the RunTime application is created.
Using the preferences file "/spam_dir/install/spamalize_defaults.txt" means that you can build up a set of preferred settings over time and not have to figure out what they were every time you upgrade your version of SPAMALIZE. It is helpful to save the preferences file elsewhere when you upgrade to a newer version of Spamalize, then copy the old settings into the new preferences file. (Do not copy over the old preferences file, in case new categories were added.)
For the full colorized glory of certain SPAMALIZE buttons and menus, you will need to add some IDL menu-related items to your ".Xdefaults" file for unix/linux OS (usually in your home directory).
Change the location of the temporary-file directory.
You need to make sure that the designated temporary directory for Spamalize is large enough that many large files can be written to it, and that all users have read- and write-permission for it. There is a somewhat complex Spamalize program that tries to make sure that output files can be successfully written. It tries several locations if the first does not work. If writing to any directory fails, Spamalize will eventually attempt to write the data to /spam_dir/temp/ so make sure this directory can also be written to by all users.
E. Installation patches, etc.
1) There is a bug in the IDL routine STR_MID prior to IDLv5.3, which you will have to fix in your IDL distribution code. Change line 93:
arr[count] = strmid(str, spos, strlen(str)) ;Last element
to:
slen = strlen(str) & slen=slen[0]
arr[count] = strmid(str, spos, slen) ;Last element
Note that this frequently looks like a bug in STR_SEP.
F. Desktop Icons.
There are several icon-suitable image files in the directory /.../spamalize/data/. They are all various formats and sizes of the Spamalize icon:
For Windows98/2000/NT, use
C:\...\spamalize\data\canned_spam_32.gif
For linux/GNOME, use
/.../spamalize/data/canned_spam128.jpg
In linux/GNOME, you can launch IDLDE (the IDL development environment) by adding a new launcher to your panel. The command should be "idlde" if it is in your path, or "/fullpath/idlde" otherwise. Click on the icon-box and browse for the appropriate canned_spam icon. After applying your changes, you can launch idlde by clicking on the icon, and then simply type "spamalize" to start Spamalize. (The Spamalize directory must by included in your IDL path.)
G. Source code file naming conventions:
Programs which are primarily for displaying images in windows, or which are primarily composed of widgets for a user interface, tend to be named "spw_***.pro", while programs whose primary purpose is to perform a task with little user input tend to be named "spam_***.pro". Frequently there are pairs of similarly named programs: the "spw_" program gets input and parameters from the user, and the "spam_" program performs the desired task. This makes it easy to incorporate a worker program (spam_***) into a larger program without needing to use the GUI interface.
See the file, "Catalogue_of_spam", for a brief description of (older) ndividual programs and functions, as well as a more detailed explanation of how SPAMALIZE functions. Most individual programs have fairly detailed documentation within the source code. In particular, there is usually a one-line "Purpose", a longer "Abstract", a "Calling Sequence", and an explanation of parameters and keywords within each program.
At the Waisman lab, IDL/SPAMALIZE files are kept in the directory:
/apps/spamalize/
which is generally called "/.../spam_dir/" in this document.
There are several subdirectories needed by SPAMALZIE:
H. Data I/O.
In some older Spamalize programs (e.g. “Display”, “Write”, “Sum”), the data are read into a central location and are accessible to all older programs. Image data are stored in an array, "img_arr". Associated image subheader info is stored in the array "sub_header", and main_header info is stored in the array "main_header". These arrays are all COMMON arrays, declared from the main program (SPAMALIZE) so they are available to all subroutines that declare the appropriate COMMON variables. Any type of image array can be stored in img_arr. All quantitation should be performed by the I/O routines, so "img_arr" contains fully quantified values. SPAMALIZE sub-headers and main-header contain enough empty space so they may be modified if necessary to accommodate most types of images. This system got a bit unwieldy, so most newer programs (BrainMaker, BrainSqueezer, Patlak plots, etc.) are each reposnible for their own data I/O. Most programs use the same core of programs from the EZ_WRITER suite for file I/O.
Back to Spamalize