Instructions for Enhanced SAOimage for Unix This file explains how to install and use Enhanced SAOimage and the SAOimage communications interface software on Unix operating systems. The enhanced version of SAOimage (v. 1.22E) allows loading multiple independent images, cursor and vector drawing, cursor readback, and lookup table control from a user program. Video is also possible. The Unix version of SAOimage will compile on several platforms, e.g., Alpha, DEC, Linux, Mac OS, SGI, and Sun. The companion interface software and demonstration programs have been tested on DECstations, Linux, and Mac OS systems, but should work on other platforms as well. On DECstations the built-in compiler can be used to compile the interface modules, on Linux the Portland Group f77 compiler can be used, and on Mac OS the Absoft f77 compiler can be used. 1. The first part of the installation process involves compiling and installing a new version SAOimnage and imtoolrc, and installing the named pipes. For all flavors of Unix and for each installation, recompiling is required so that SAOimage can recognize the location of imtoolrc. Only under OpenVMS can the execute image simply be copied, so that recompiling is not necessary. To obtain the source code of the enhanced version of SAOimage download the file saoimage.tar-gz from the link at http://www.astro.gsu.edu/~gudehus/enhanced_saoimage.html and then extract the files. If you have access to the MIIPS package and are on an OpenVMS system you can alternately extract the files from MIIPS$DISK:[MIIPS.X_WINDOW]SAOIMAGE.TAR-GZ. On some systems a few preparatory steps should be taken. E.g., on a Silicon Graphics enter "setenv SGI_CC - cckr" before running the make file. Also, if the directories indicated in the make file do not exist, they must be created, or the make file edited to agree with your machine. Some Unix systems may yield code which apparently restricts the number of displayed colors when those colors are downloaded with subroutine sao_load_vlt. This will affect, for example, the behavior of saodemo7. The OpenVMS version does not have this problem. To build SAOimage, log on as root or superuser and enter make -f makefile.xxx install where xxx is one of the extensions of the makefiles, such as dec, linux, macos, etc., corresponding to your system of choice. The effect of this will be to create a new saoimage execute image and place a copy of it in /usr/local/bin and place a copy of imtoolrc into /usr/local/lib. It will also install the named pipes imt1i and imt1o into the directory /dev and install the help files. Ignore the warning messages. Note that because on Mac OS, the /dev directory will not function with the named pipes, the /usr/dev directory is used instead. The name of the resulting execute image is "saoimage", the same as the name of the unenhanced version, so if you want to also use the unenhanced version, you will need to change its name before installing. You should also change the name of any preexisting /usr/local/lib/imtoolrc since a new and different one is created. The enhanced version will still work with IRAF, but you may need to include the -half switch instead of the -one switch, as the meanings of these switches have been changed to make them more intuitive . If you wish to place SAOimage in a different location, a different procedure is required. One approach would be to edit the makefiles and procede as described above. Alternately, first log on as root or superuser and install the pipes. For systems other than Mac OS go to /dev and enter mknod imt1i p mknod imt1o p ln -s imt1o imt1 chmod 777 imt1* For Mac OS go to /usr/dev (you will need to create the dev directory) and enter mkfifo imt1i mkfifo imt1o ln -s imt1o imt1 chmod 777 imt1* Fall all systems, next be sure that there is no irafenv.o file in the source code directory. Then enter make -f makefile.xxx install_saobin IMTRCDIR="/machine_name/desired_directory/" SAOBINDIR="/machine_name/desired_directory/" Note that the carriage return key is pressed only once for the above command. Next enter make -f makefile.xxx install_imtoolrc IMTRCDIR="/machine_name/desired_directory/" SAOBINDIR="/machine_name/desired_directory/" This will work as long as the desired directory is not the same as the source code directory. There is a known bug in the makefiles which creates a problem when trying to install SAOimage in the same directory as the source code. In this case rename the source code directory to a different name. Then create a new directory with the old source code directory name. Run the installation and then delete saoimage from the new directory. This is OK because a new copy gets placed in the temporarily renamed source code directory. Now rename imtoolrc from the new directory to the same name in the temporary directory. Delete the now empty new directory and rename the temporary directory back to its old and desired name. If you wish to put the named pipes into a different location, you will need to edit defs/control.def and substitute their new location. Alternately, when you launch saoimage you can speicify the new locations on the command line with the switches "-idev pipename" and "-odev pipename". The help files (which are not up to date) are not installed by the above procedure, but can be installed by following the directions in the makefile. If you wish others to use saoimage, be sure the protection is set to world read and execute for saoimage, and world read for imtoolrc. The protection on the directories will have to be changed also. 2. The second part of the installation involves downloading the source code for the interface software and several demonstration programs. It is also possible to download compiled versions of the demonstration programs. Compiled versions are available for DECstations, Linux on Intel, and Mac OS X. To use the compiled demonstration programs on a DECstation, on a Linux system, or on Mac OS X, download sao_dec_executables.tar-gz, sao_linux_executables.tar-gz, or sao_macos_executables.tar-gz, respectively, from the link at http://www.astro.gsu.edu/~gudehus/enhanced_saoimage.html. If you have access to the MIIPS package, you can alternately extract saodemo.exe, saodemo2.exe, saodemo3.exe, saodemo4.exe, saodemo5.exe, saodemo6.exe, saodemo7.exe, saodemo8.exe, saodemo9.exe, and saosample.exe, from [MIIPS.UNIX.DISPLAY]SAO_DEC_EXECUTABLES.TAR-GZ, [MIIPS.UNIX.DISPLAY]SAO_LINUX_EXECUTABLES.TAR-GZ, or [MIIPS.UNIX.DISPLAY]SAO_MACOS_EXECUTABLES.TAR-GZ. The compiled demonstration programs can be put in a directory such as /usr/local/bin. Before starting SAOimage, create an alias as folows: alias saoimageE '~your_account/desired_directory/saoimage -g 886x886-2+134 -q -one +coord +magnifier &' The above geometry assumes a 19-inch monitor with 95 dots/inch, or a 1240 by 1024 available pixel area. With a 75 dots/inch display a geometry of say 600x775-2+84 may give better results. On a 17-in, 1280 by 1024 pixel, display, assuming that saoimage is in the path for executables, the alias alias saoimageE 'saoimage -g 820x1000-5+0 -q -one +coord +magnifier &' will put saoimage at the right side of the dispaly. As mentioned above, the effect of the "one" switch is different than in previous versions of SAOimage. The switches zero, half, and one, assign the starting pixel corner to (0.0, 0.0), (0.5, 0.5), and (1.0, 1.0), respectively. The effect of the former "one" switch is now accomplished by use of the "half" switch. This relationship is more intuitive. Also, +magnifier now enables the magnifier window. Before running the demos, you may also need to reset the path for your executables. Finally, enter saoimageE, and then enter the name of one of the demonstration executables. Because SAOimage is an eight-bit pseudocolor display your currect display must be set at eight bits. On most Unix systems, e.g. Linux, the setup program Xconfigurator allows you to create displays of various numbers of bits. You can switch between displays with the Control-Alt-F# key combination (# is 7, 8, etc.), after you have separately logged into each individual display. On Mac OS, the number of displayed bits is more easily adjusted. Assuming that the X Window software has been installed and that X11 is running, go to the X11/Preferences... menu and select "Output" and then "256 Colors". Colors on the Mac Finder will remain where they were before, e.g. "Millions". On the Mac, running xgterm and SAOimage at the same time may change some colors on xgterm from their expected values. If you want to compile the demos, create a new demo or display images from a custom application on Enhanced SAOimage you will need to download the source code file, sao_demos_unix_source.tar-gz, from the link at http://www.astro.gsu.edu/~gudehus/enhanced_saoimage.html. This file is also availablein the MIIPS package. Once you have the source code file, just enter gzip -d sao_demos_unix_source.tar-gz and tar -xf sao_demos_unix_source.tar from a desired directory location, usually /usr/local/src. Set default to the sao_demos directory and enter make linux for Linux systems, make macos for Mac OS X systems, make ultrix for Ultrix systems, and make unix for other Unix systems. It is also possible to use the command make -f makefile-saodemos.xxx, where xxx is the extension corresponding to the desired system. Ignore any warning messages. The makefile will also create the object library, sao_u.olb, which can be used to link with any user written programs. Put the executables or copies of them in /usr/local/bin. The programs will compile and link on a DECstation with the default compiler. For Linux on Intel processors, you will need to have installed the Portland Group f77 compiler (http://www.pgroup.com). A free 15-day trial version of their compiler is available from their website. Their compiler also works for Solaris on Intel processors, but I have not tested this. Presumably, the linux makefile should work for their compiler on Solaris as well. For Mac OS X, you will need to have installed the Absoft Pro Fortran compiler (http://www.absoft.com). A free 30-day trial version of their compiler is available from their website. The Absoft f77 compiler doesn't support variable FORMAT expressions which necessitated creating a special set of files just for that compiler. Also, the Absoft compiler has a bug with handling %REF with character data. A special usrinp.for, i.e., usrinp_char.for, was created to handle this problem. New subroutines for this and other limitations are located in the subdirectories mac_os. The compiled PPC version will also run on Macintoshes which use the Intel processors. It is possible that the Portland Group's compiler for Mac OS X with Intel will work with the Linux make file but this has not been tried. For other Unix flavors the default f77 compiler may or may not work. A compatible compiler should support BYTE data type, ENCODE, DECODE, %REF, %VAL, variable FORMAT expressions, CARRIAGECONTROL keyword, and PARAMETER statement with or without parentheses. For the C code files, the built-in compiler will work. A brief description of the communications interface and demo source code files follows. In the directory sao_demos, one should have the files: Name Description alpha.for Text handling routine chfitsmhv.for Returns a comment from a FITS keyword closefits.for Closes a FITS file dcd.for Lower level routine for usrinp.for delay.for Routine to delay exection do.for Required lower level routine for usrinp.for dynamic.for Routine to obtain dynamic memory dynamic_c.c Lower level routine for dynamic memory error.for Routine to handle errors get_endian.for Routine to determine the system endian and write the results to a common block get_fits_info.for Routine to read a FITS file and put essential information into the FITSFACTS* COMMON blocks ibm2.for Required lower level routine ibm4.for Required lower level routine ieeeflt.c Required lower level routine imtoolchecksum.for Required lower level routine inel.for Required lower level routine kepler.for Solves Kepler's equation. makefile General makefile makefile-saodemos.linux Makefile for Linux makefile-saodemos.macos Makefile for Mac OS makefile-saodemos.ultrix Makefile for Ultrix makefile-saodemos.unix Makefile for other Unix message.for Routine to print messages on terminal and in log file nel.for Required lower level routine neld.for Required lower level routine ngc1316o.fits Sample INTEGER*2 FITS file release_memory_c.c Routine to release dynamic memory sao_curn.for Routine to read back cursor positions (desktop, frame, and file) sao_demos_linux_executables.com Command file to create tar file of executables sao_demos_macos_executables.com Command file to create tar file of executables sao_demos_ultrix_executables.com Command file to create tar file of executables sao_demos_unix_executables.com Command file to create tar file of executables sao_display_vect.for Routine to display a set of vectors already written into frame sao_draw.for Routine to display cursors sao_erase_cursor.for Routine to erase cursors sao_load_vlt.for Routine to download a custom video video look-up table sao_vect.for Routine to draw vectors (2 modes) saocaption.for Routine to display a message on SAOimage. It also reinitializes the world coordinate system in SAOimage. saoconvlt.for Routine to control the lookup table saodemo.for Demo #1, shows all features saodemo2.for Demo #2, simulated focusing operation saodemo3.for Demo #3, contact binary video saodemo4.for Demo #4, cursor position readback saodemo5.for Demo #5, vector drawing saodemo6.for Demo #6, polygon drawing saodemo7.for Demo #7, mondrian-like images saodemo8.for Demo #8, three gravitating masses saodemo9.for Demo #9, video of binary in elliptical orbit saodemo10.for Demo #10, FITS file display saodot.for Routine to display a single dot saoeras.for Routine to erase the image buffer saofirst.for Routine to set up the coordinate system and erase the screen of all items. saoload.for Routine to load an image or images saosample.for Simple sample saostart.for Routine to prompt the user for the frame buffer size if not already selected si_subs.c Lower level routine for named pipes si_subs.h Include file for si_subs.c save.for Lower level routine for usrinp.for strkey.for Lower level routine tst0001.fits Sample BYTE FITS file tst0004.fits Sample INTEGER*4 FITS file tst0005.fits Sample REAL*4 FITS file usrinp.for Routine for generalized character, logical, and numerical input include/saofacts.for Include file mac_os_ppc/dcd.for Mac OS/Absoft version mac_os_ppc/intoolchecksum.for Mac OS/Absoft version mac_os_ppc/nel.for Mac OS/Absoft version mac_os_ppc/neld.for Mac OS/Absoft version mac_os_ppc/saodemo5.for Mac OS/Absoft version mac_os_ppc/saodemo10.for Mac OS/Absoft version mac_os_ppc/save.for Mac OS/Absoft version mac_os_ppc/si_subs.c Mac OS/Absoft version mac_os_ppc/si_subs.h Mac OS/Absoft version mac_os_ppc/usrinp.for Mac OS/Absoft version The demos are run by first starting SAOimage as described above and then entering saodemo.exe or saodemo2.exe etc. If you are not signed in as root and try to run from the /usr/local/bin or /usr/local/src/sao_demos directories you will encounter a permission error because the programs write to the current directory. Therefore, after the path has been established, run them from your home directory. One workaround to this problem is to first run one of the programs as root in one of the above two directories. This will create the files fort.7 and fort.49. Change the ownership of these files to your account. This will allow you to run from the normally protected directory. For the cursor readback function (Demo #4), and polygon drawing (Demo #6), be sure that SAOimage has focus by clicking on the title bar if necessary, and press the carriage return at each postion. Any questions should be directed to Donald Gudehus at gudehus@astro.gsu.edu.