Encyclopedia of Graphics File Formats Companion/GFF_CD.ISO/software/unix/saoimage/sao1_07.tar/readme_iraf.txt

Text File | 1991-10-28 | 19KB | 450 lines

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 "[e-mail]".  Bugs that appear to be
IRAF-related should be reported to IRAF site support, [e-mail] (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, "<path>" 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 <path>saoimage.tar.Z | tar -xpf -

    Otherwise (saoimage.tar) just use tar:

    % tar -xpf <path>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.<machine>).  You will want to select
    a <machine> 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.<whatever>

    You could also simply specify MFLAGS and DFLAGS on the "make" command
    line, rather than editing the file; for instance,

    % make -f makefile.<whatever> 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.<machine> install

    There are several machine-dependent makefiles; <machine> 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.<machine>), 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 <architecture>

    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, "<path>" 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 <nbyt> 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 <path>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 <destination path>

    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 <destination path>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 :== @<destination path>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.