README.SAOIMAGE -- instructions for building SAOimage and installing it for communication with IRAF INTRODUCTION ------------ SAOimage was developed and is maintained by Mike VanHilst at the Smithsonian Astrophysical Observatory. This README file and the makefile have been added or modified at NOAO to facilitate building and installing SAOimage for compatibility with IRAF. The [possibly compressed] tar archive of SAOimage source code constructed at NOAO from the CfA archive plus a couple of other files contains everything needed to build and install SAOimage, including communications with IRAF v2.8 or later. It will not work with versions of IRAF prior to 2.8. Bugs that seem to be purely SAOimage bugs should be reported to the author, Mike VanHilst at email address "mvh@cfa.harvard.edu". Bugs that appear to be IRAF-related should be reported to IRAF site support, iraf@noao.edu (Internet), or 5355::iraf (SPAN). If in doubt as to where to report, try IRAF site support first. Documentation is in the doc subdirectory. The full User Guide is a LaTeX document called manual.tex, and there is a Unix manual page as well. A VMS help file is provided in the vms subdirectory. INSTALLATION ------------ There are two likely locations for the SAOimage directory tree: Either: [a] If you received SAOimage as part of your IRAF distribution, it will probably be in iraf$host/x11/saoimage, where "host" is "unix", "vms", etc. Or: [b] If you are installing SAOimage as add-on software distributed from NOAO, it is best NOT to place it under the IRAF directory tree, because it might not survive a future IRAF update. Instead, it should be placed with other locally-added software, e.g. on a Unix system in "/usr/local/src/saoimage", or in a place for X11 added software, e.g. "/usr/X11/src/saoimage". If case [b] applies, you will need to build the SAOimage executable and install the necessary program files according to the instructions below. There are separate build and installation instructions for Unix hosts and VMS hosts; proceed to the appropriate section at this point. If you received SAOimage with your IRAF distribution, it is probably already compiled and linked, with the executable located with the other bootstrap (not portable IRAF) executables, e.g. on a Unix system in the logical directory $hbin, and on VMS systems in IRAFHLIB. If this is the case, you do not need to build or install SAOimage unless you need to relink it, for example after an X11 upgrade. You may need to do part of the installation described in the parts numbered [4] below, in the event that you have never before set up an image display program (imtool or SAOimage) for use with IRAF. It is easy to check this on Unix systems: there will be files /dev/imt1i and /dev/imt1o if an installation has been performed previously. On VMS, you just need to be sure that users have a way of running SAOSETUP.COM. Note that there are two sections numbered [4]: one in the Unix instructions, one in the VMS instructions. Installation of SAOimage as add-on software on Unix --------------------------------------------------- [1] Login as iraf. It is important that the iraf account be used, and that the iraf system has already been installed on this machine, to set up the account environment properly. % cd /usr/local/src # (or wherever you put these things) Check to see if there is an "saoimage" subdirectory, create one if necessary, and change the working directory to it: % mkdir saoimage % cd saoimage [2] Unpack the archive. In what follows, "" is wherever your saoimage.tar[.Z] archive is located, either on disk or on magtape. If the archive file is listed as ending in ".Z", it is compressed and needs to be uncompressed before unpacking. If the archive is "saoimage.tar.Z", use: % zcat saoimage.tar.Z | tar -xpf - Otherwise (saoimage.tar) just use tar: % tar -xpf saoimage.tar [3] Build the software (compile and link). The SAOimage makefile is set up so that to build the executable for most systems all you have to do is execute it with the appropriate architecture on the command line. The Unix architectures currently supported are: aix # IBM RS/6000 running AIX alliant # Alliant FX series apollo # Any Apollo, software floating point apollo_68882 # Apollo for MC68882 fp apollo_fpa # Apollo for FPA1 apollo_prism # Apollo for PRISM architecture (a88k) hp # HP-UX mips # MIPStation running RISCOS sgi # SGI Personal Iris running Irix sun # Default Sun architecture: SPARC sun_sparc # Sun SPARC sun_ffpa # Sun-3 floating point accelerator sun_f68881 # Sun-3 motorola f68881 floating point sun_fswitch # All Suns, switchable floating point ultrix # DECstation and VAXstation To build SAOimage, execute make for the appropriate architecture, e.g.: (in the saoimage directory) % make ultrix >& spool & When the job finishes, inspect the spool file for errors, and if none were found, proceed to the next section. Otherwise do some troubleshooting: e.g. if it appears to be a compile-time problem, inspect the values of the various *FLAGS macros in makefile; if it is link-time, look for the location of the X11 libraries. They may differ from system to system, and if yours are not accessible with "-lX11", check with your system manager. If your system is not listed above, first examine makefile to see if it has been added to the file but not to these instructions. If your architecture is still not present, it can probably be made to work by editing the values of MFLAGS and ADFLAGS in the one of the machine- dependent makefiles (makefile.). You will want to select a with a Unix architecture like yours: makefile.hp would be a good place to start for System V Unixes, makefile.dec for the more Berkeley-like derivatives. You will need to run make and specify the makefile name on the command line: % make -f makefile. You could also simply specify MFLAGS and DFLAGS on the "make" command line, rather than editing the file; for instance, % make -f makefile. MFLAGS="-DSYSV -DLSB" See the comments in the makefiles concerning the conditional compilation flag values for MFLAGS and ADFLAGS. [4] If the compile and link were successful, install the SAOimage executable and manual page, along with the files needed for communication with IRAF. This installation step must be taken as superuser! On a Unix system, this is fairly straightforward, except that you must specify the correct makefile for your machine type: % su % make -f makefile. install There are several machine-dependent makefiles; can be one of alnt, apo, dec, hp, ibm, mips, sgi, or sun. NOTE for Apollo sites: Although Domain/BSD does not support named pipes at all, a Domain/OS system configured with *both* BSD and System V may be used to install the two named pipes (fifo's). If the SysV software is not installed, this step will fail. Note that by default the executable will be placed in /usr/local/bin, the manual page will go in /usr/man/manl, and the IRAF imtoolrc file will be copied to /usr/local/lib. *These directories must exist prior to invoking the installation procedure*. You can override these location choices either by editing the makefile for your specific machine (makefile.), of by defining the proper macros on the command line; these are: SAOBINDIR # Destination directory for SAOimage program SAOMANDIR # Destination directory for on-line manpage IMTRCDIR # Destination directory for imtoolrc The path to the imtoolrc file is used in the code at one point, so if the IMTRCDIR is changed, it will be necessary to recompile the irafenv.c module: % rm -f irafenv.o % make Obviously, irafenv.c must be recompiled (and SAOimage relinked) prior to installing the program. If the installation is still unsuccessful, call IRAF site support. Unix sites may wish to run "catman" on /usr/man/manl/saoimage.l. [5] After a successful installation, you can strip out the various files that were created during the build procedure (object files, libraries, and so forth). % make clean You may wish to test the installation first. See the sections below that deal with SETTING UP SAOIMAGE and TESTING SAOIMAGE. Note that the `make clean' command will delete any *executable* versions of SAOimage in the directory; it is assumed that the real executable will have been copied into SAOBINDIR during the installation phase (and that you didn't manually set SAOBINDIR to the SAOimage source directory itself). Installation of SAOimage as add-on software on VMS -------------------------------------------------- In addition to the instructions in this section, there are comments and explanations in the SAOSETUP.COM and [.VMS]README.VMS files that might be helpful and/or interesting. [1] Login as IRAF. It is important that the IRAF account be used, and that the IRAF system has already been installed on this machine, to set up the account environment properly. $ set def sys$sysdisk:[local.src] ! or wherever these things go Check to see if there is an "saoimage" subdirectory, create one if necessary, and change the working directory to it: $ create/directory [.saoimage] $ set def [.saoimage] [2] Unpack the archive. In what follows, "" is wherever your saoimage.tar[.Z] archive is located, either on disk or on magtape. If the archive file is listed as ending in ".Z", it is compressed and needs to be uncompressed before unpacking; in this case, you will also need the VMS compress/uncompress program available in the util subdirectory of the FTP archive (get the README file, too). $ uncompress :== $disk:[dir]compress_vms uncompress The preceding statement sets up the DCL symbol that defines the program as a foreign command. The VMS uncompress program needs to know how many data bytes are in the compressed file; this is the number of bytes transferred via FTP. Also, the program expects the filename extension end in "_z", so when you transfer the SAOimage archive, you should specify an output filename to the get command. $ uncompress -s saoimage.tar_z The file will be uncompressed in place, and saoimage.tar will be left. You can unpack the tarfile with the IRAF rtar utility. This can be run from DCL as long as the IRAFUSER.COM file has been run, usually by typing the `iraf' command (symbol); you do not have to be in the IRAF CL to use rtar. $ rtar -xltvf saoimage.tar [3] Build the software (compile and link). There is a set of MAKE.COM files that accomplishes this; you only need to start the one in the [.saoimage] directory. $ @make/output=spool.log When the job finishes, inspect the spool file for errors, and if none were found, proceed to step [4]. Otherwise do some troubleshooting: if it appears to be a compile-time problem, inspect the values of the various flags set in the "/define=(...)" qualifier in MAKE.COM; if a link-time problem occurred, check the location of the X11 libraries. [4] If the compile and link were successful, install the SAOimage executable and the startup .COM file, along with the configuration file needed for communication with IRAF. If you intend to install the files in a system location, you will need to be logged in as SYSTEM. $ @[.vms]install All of the "run-time" files (there are 4) are installed in the same place on VMS systems. You may wish to install the help information in a standard help library on your system: $ lib/help/log sys$help:localtools saoimage.hlp You may wish to set up a symbol that users can use to run the startup command procedure; global symbols such as this are often defined in SYS$MANAGER:SYLOGIN.COM $ saosetup :== @saosetup [5] After a successful installation, you can strip out the various file that were created during the build procedure (object files, libraries, and so forth). $ @make clean You may wish to test the installation first. See the sections below that deal with SETTING UP SAOIMAGE and TESTING SAOIMAGE. SETTING UP SAOIMAGE ------------------- Use of SAOimage requires that the program be known to your login session, and that SAOimage be permitted to open a window on your X display. The means for achieving these things are different for Unix and VMS. Setting up your Unix environment to use SAOimage ------------------------------------------------ The SAOimage executable must be on each user's search path, which is why it is important that SAOimage be installed in a commonly accessible directory such as /usr/local/bin. You can be sure that the program is accessible by using the `which' program: % which saoimage The full path to the program should be echoed. If it is not, check to be sure that the SAOimage executable is on one of the directories reported. If you hvae just completed the installation, you may need to rehash. You can direct SAOimage to use a particular X display with the -d switch on the command line, or by using the DISPLAY environment variable. All X applications query for the DISPLAY variable, so it is conventional for this to be defined when the X Wind System is used. % setenv DISPLAY mynode:0 If you are running SAOimage on the local node, you can use the string "localhost" instead of your workstation name. If the display is a different node, i.e. if you are running SAOimage on a remote host, you must allow network access to the local X display screen. This is most easily done with the xhost program. % xhost nodename xhost must be run on the machine with the X display. SAOimage's hardcopy facility makes a PostScript file and ships it to a printer according to instructions in the user's R_DISPOSE environment variable. Typically, this is set to something like: % setenv R_DISPOSE 'lpr -Plw5 -r -s %s' # OR % setenv R_DISPOSE 'lpr -P$PRINTER -r -s %s' SAOimage is usually run in the background. Many parameters that can be changed with command line switches can be adjusted while SAOimage is running, so it is not necessary to fire it up with lots of arguments. See the user manual (manual.tex) for details. % saoimage & You may need to position the window and click the mouse. If you get a message something like 'cannot handle pseudocolor map', try: % set USE_MIT_VISUALS=1 Setting up your VMS environment to use SAOimage ----------------------------------------------- The SAOimage program must be run as a foreign command from DCL, and the DECwindows display must be properly set. The SAOSETUP.COM procedure is provided to ensure that both of these things are taken care of. There are numerous comments in that file which explain what needs to be set up; please refer to them. SAOimage is usually run in the background. Many parameters that can be changed with command line switches can be adjusted while SAOimage is running, so it is not necessary to fire it up with lots of arguments. See the user manual (manual.tex) for details. $ spawn/nowait/in=nl: saoimage You may need to position the window and click the mouse. TESTING SAOIMAGE ---------------- This section describes a couple of tests that should be run from the IRAF CL to verify that communication between SAOimage and the CL is working. You should run the CL from an IRAF-compatible graphics/text window like xterm, which will also probably be running in the background as a separate X application. % xterm -ls & Once a Unix shell has come up in the xterm window, start the IRAF CL by typing `cl'. After the usual login messages, type cl> stty xtermjh cl> images im> tv tv> reset stdimage = imtool tv> reset stdimcur = stdimage tv> display dev$pix 1 The canonical IRAF test image of the Whirlpool galaxy should be displayed in the SAOimage window. tv> =imcur A new cursor will appear in the image window. If you are using a window manager that requires you to click the mouse in the window to assign the input focus, you will first have to move the mouse pointer into the upper border of the SAOimage window and click the left button. Don't click *in* the SAOimage window; do it on the border. Move the mouse/image cursor somewhere over the image, and press the key "a". You should see in the xterm window something like this, depending of course on where the mouse was: 256.000 256.000 101 a If the image displays correctly, and cursor readback is working, the installation was successful. PRINTING THE DOCUMENTATION -------------------------- The SAOimage manual is provided in LaTeX source form. It is roughly 30 pages long when processed and printed. LaTeX produces "device independent" output in a .dvi file that must be postprocessed through a translator for your specific print device. The DVI file can be produced with the SAOimage makefile: % make manual The file doc/manual.dvi is the result of this command. Access to a TeX installation must be available on the same system on which SAOimage is being installed obviously. If the manual must be copied to a different host, only the manual.tex file is required, although the .aux and .toc files could be copied as well; this would reduce the number of LaTeX iterations. (these files are auxiliary files produced during the first "pass" of LaTeX over the document and contain auxiliary and table of contents information.) Conversion of the .dvi file requires an appropriate DVI->whatever translator for the target laser printer. Many laser printers today use the PostScript language, and a typical name for a DVI->PostScript translator is "dvips". One would produce device-specific output (and sometimes even dispose of it on the printer) with a single command: % dvips manual It would be best to confirm what needs to be done by checking the local documentation about LaTeX and your printers.