path: root/unix/gdev/sgidev/README.gif

Announcement for adass.iraf.system:

	An SGI translator which converts IRAF graphics directly to GIF
images is now available from our anonymous ftp archive as

	ftp://iraf.noao.edu/pub/sgi2gif.c
	ftp://iraf.noao.edu/pub/sgi2gif.readme

The associated readme file describes how to install the translator and
configure a variety of graphcap entries for it.  
	SGI translators are used to convert IRAF graphics to some other
format, usually Postscript, for disposal to a printer or some other
hardcopy device.  The SGI2GIF translator now allows users to generate
GIF images (suitable for web page presentation) directly from IRAF using
the familiar ":.snap" command or non-interactively.  See the readme file
for a full discussion of the capabilities and configuration options, or
contact site support (iraf@noao.edu) with questions or problems. 

--------------------------------------------------------------------------------

README:

1. Introduction
---------------

	IRAF hardcopy graphics are generated by converting the graphics
metacode through the SGI (Simple Graphics Interface) kernel which
translates the numerous graphics commands to a minimal set of move/draw
instructions or a bitmap raster of the plot.  In the case of
hardcopy/output graphics (i.e. the SGI kernel), the dev$graphcap file
defines parameters for this conversion which include the plot size, SGI
kernel options, and most especially a "device dispose" (DD) string which
specifies the SGI translator to be used and what to do with the resulting
translator output.  The SGI kernel is not a full graphics kernel so
information such as line color and fill areas are lost, below we will
discuss how to retain this when producing a GIF images using other
translators and graphcap file trickery.

	For most printer devices the "sgi2uapl" Postscript translator is
used to convert the SGI kernel metacode from a series of move/draw
instructions to equivalent postscript commands, other translators are
available to convert to other printer languages.  The SGI kernel can also
be used, with the proper graphcap entries, to generate a bitmap raster of
the plot which can be easily converted to various image formats.  The SGI2GIF
translator takes advantage of this latter feature to produce GIF images
directly from the IRAF graphics metacode.

	The translator has options for specifying the image size,
foreground and background colors, GIF transparency, and can be used to
convert multiple input bitmap files or a single file containing multiple
graphics frames.  It allows users to easily generate images suitable for
presentation on the web, either manually or automatically.


2. Installation
---------------

	The SGI translator is distributed in source form and to be used
must be compiled and installed in the system hbin$ directory.  To install
the new SGI translator follow these steps while logged in through the iraf
user account:

     [1]  Download the translator from the IRAF anonymous FTP archive or
	  one of it's mirror sites using:

	       % ftp iraf.noao.edu (140.252.1.1)
	        login: anonymous
	        password: [your email address]
	        ftp> cd /pub
	        ftp> mget sgi2gif.c
	        ftp> quit

     [2]  Compile the source using

	     % cc -o sgi2gif.e sgi2gif.c	# compile the source
	     % mv sgi2gif.e $hbin		# move to the $hbin

	  "$hbin" is defined in the iraf environment to be something like
	  $iraf/unix/bin.<arch>, where <arch> would be 'ssol' for Solaris,
	  'sparc' for SunOS and so on.

     [3]  Optionally place the source in the directory $iraf/unix/gdev/sgidev.

     [4]  Edit the dev$graphcap file and add the following default entries
	  for the device near the top of the file:

	    g-gif|UNIX generic interface to multi-frame GIF file generator:\
	        :DD=ugif,tmp$sgk,!{ sgidispatch sgi2gif -w $(PX) -h $(PY) \
	        -bg 0 0 0 -fg 255 255 255 -root sgigif $F.[1-8] ; \
		rm $F.[1-8]; }&:MF#8:NF:tc=sgi_image_format:

	    sgi_image_format|Generic raster file format specification:\
	        :kf=bin$x_sgikern.e:tn=sgikern:ar#.75:\
	        :xr#640:yr#480 :PX#640:PY#480 :XW#640:YW#480:\
	        :BI:MF#1:YF:NB#8:LO#1:LS#0:XO#0:YO#0:

	The 'g-gif' entry takes one or more graphics file input and converts
	each input frame to a redirected file on output called 'sgigifXXX.gif'
	where the 'XXX' is frame number.  See below for details one
	configuring other graphcap entries.


2. Translator Options
---------------------
    The SGI2GIF translator allows the following options:

        -w N         Set the width of input bitmap and output image.  The
		     argument must be derived from the graphcap value since
		     that is what the SGI kernel will use when generating the
		     bitmap, e.g.  "-w $(PX)" instead of "-w 640".

        -h N         Set the height of input bitmap and output image. The
		     argument must be derived from the graphcap value since
		     that is what the SGI kernel will use when generating the
		     bitmap, e.g.  "-h $(PY)" instead of "-h 640".

        -i           Invert the bitmap before conversion.  By default the
		     graphics are drawn using the foreground color, this
		     option inverts the bitmap before conversion meaning the
		     graphics are drawn using the background color.

        -t           Set background color as transparent.  If enabled the
		     translator will produce a GIF89 format image with the
		     background color set as "transparent".  When this image
		     is used with an HTML document the background color is
		     the HTML page color.

        -root        Set the root rame for output file.  If defined this
		     root name will be combined with the frame number and
		     a ".gif" extension to form the output name.  If not 
		     defined and only one input image is present the default
		     action is to send the output to STDOUT.

        -fg R G B    Specify foreground color (default 'black').  Set the
		     foreground color as a triplet of RGB values in the
		     range 0-255.  The -fg flag must have three arguments.

        -bg R G B    Specify background color (default 'white').  Set the
		     foreground color as a triplet of RGB values in the
		     range 0-255.  The -bg flag must have three arguments.


3. Configuring Alternate Graphcap Entries
-----------------------------------------

	Most of the work in a graphcap entry is done by the 'device
dispose' (i.e. "DD") string.  This string is composed of three comma
delimited parts:  a node/device name (which is normally ignored), a
temporary filename, and a host dispose command.  To configure a new entry
it is only this last field that normally needs to be modified, perhaps in
conjunction with another graphcap parameter.  As an example let's look at
the DD string used in the example graphcap above:

   :DD=ugif,tmp$sgk,!{ sgidispatch sgi2gif -w $(PX) -h $(PY) \
   -bg 0 0 0 -fg 255 255 255 -root sgigif $F.[1-8] ; rm $F.[1-8]; }&:

where 'ugif' is the unused node/device name, 'tmp$sgk' is the temporary
filename, and the remainder is a host dispose command.  The 'sgidispatch'
command is an iraf binary that launches the specified translator
('sgi2gif' here) with any required arguments.  Note that everything within
the "!{...}&" curly braces is executed (as a background Bourne shell
command) so any string of valid unix command separate by a semicolon will
be executed.  In this case the sgidispatch command launches the sgi2gif
translator with all of it's arguments, it then deletes the input metacode
file symbolized by the "$F".
	You may notice that some arguments are specified as e.g. "-w
$(PX)".  When the DD string is executed any macro values beginning with a
'$' such as '$(PX)' are replaced with values from the rest of the graphcap
entry.  In this case '$(PX)' is replaced by the value contained in the
graphcap :PX (physical X size) field, the "$F.[1-8]" is expanded to
include the unique root filename along with any extension 1 thru 8 which may
be generated because of multiple plots in the input.   In
most cases all you may need to change in the DD string itself is the
output file, or e.g. whether it gets piped to some other command.


3.1 Changing Image Size
-----------------------

	Changing the image size is simply a matter of changing the graphcap
parameters

	    :xr#640:yr#480:		sets X,Y device resolution
	    :PX#640:PY#480:		sets X,Y physical size of bitmap
	    :XW#640:YW#480: 		sets X,Y width of plotting window

These are defined in the 'sgi_image_format' entry given above.  Graphics
are drawn using Normalized Device Coordinates ('NDC', values in the range
0.0 to 1.0) and will be scaled appropriately for any specified output
dimensions allowing users to configure graphcap entries for images which are
larger/smaller than the default, or have square or elongated aspect ratios.

3.2 Preserving Color Information
--------------------------------

	Colors such as those used for the axis labels and frame, and colors
used in the plot itself for different line/marker types cannot be preserved
by the SGI kernel directly.  To do this you must use a full graphics kernel
such as the PSIKERN postscript kernel found in STSDAS.  The V2.11
distribution contains graphcap entries suitable for this kernel but assumes
you have STSDAS available.  See the online help for more information about
this kernel.
	Using the '-fg' and '-bg' flags will allow you to specify foreground
and background colors to be used for the plot as a whole.  Note that these
flags require three arguments to specify the RGB color components.  The '-t'
flag may be used to mark the background color as 'transparent' so only the
foreground color is shown when the image is used in an HTML document.

3.3 Generating Other Image Formats
----------------------------------

	GIF may be used as an intermediate format which can be converted to
something else as part of the graphcap DD string.  For example, to use the
ImageMagick CONVERT task to produce a JPEG image the graphcap DD string
could be written as

	g-jpeg|UNIX generic interface to JPEG file generator:\
	    :DD=ugif,tmp$sgk,!{ sgidispatch sgi2gif -w $(PX) -h $(PY) \
	    -bg 0 0 0 -fg 255 255 255 -root sgi $F | \
	    convert sgi$$.gif sgi$$.jpg ; rm $F; }&: \
	    :MF#1:NF:tc=sgi_image_format:

The DD string first uses the SGI2GIF translator to produce a 'sgi.gif'
image, then calls the convert task (which is assumed to be in the user's
path) to convert this to JPEG as a separate step.   The :MF field is
set to one meaning each frame will generate a new file.  The '$$' used in
the filenames (e.g. 'sgi$$.gif') is the process id created for the shell
running the DD command meaning multiple filenames of the form 'sgi12345.gif'
will be created, each with a unique id number so the images aren't over-
written.  In the past this form of DD string could be used with the standard
sgi2uapl postscript translator and a host task such as 'gs' to convert 
postscript to some other format.

4. Interfacing to Web CGI Scripts
----------------------------------

	It would be impossible to give complete details about interfacing
IRAF programs to CGI scripts due to the variety of languages and tasks
that may be used.   To begin lets look at how to execute a task from the
host level, which is essentially what we'll be doing from within a CGI 
script.
	In principle this can be done in one of two ways:  Either invoke
the executable directly with the correct command line arguments, or run
the CL with the input redirected to execute the task.  In the first case
you must know in which executable the task resides, core IRAF system tasks
(e.g.  things in the PLOT and IMAGES packages) have their executables in
the main $iraf/bin.<arch> directory, NOAO package tasks have the
executables in the $iraf/noao/bin.<arch> directory.  There is usually a
separate executable for each package and you can probably figure out which
one goes for each package otherwise just look at the package cl file to
find out, for example the PLOT package defines the task in the
$iraf/pkg/plot/plot.cl file, if you look in their you'll see that is
defines the tasks as (part of the file reads)

task    contour,
	surface, hafton, velvect         = "plot$x_ncar.e"

which means that the CONTOUR, SURFACE, etc tasks are in the "x_ncar.e"
executable.
	Once you find the correct binary, you need to create a file with
the task parameters:  usually it's easiest to set the parameters and then
dump the parameter file with 'dpar', e.g.

	cl> dpar listpix > listpix.par

It's likely that CGI scripts will need to set certain parameters itself so
thought must be given to how to edit this list of default parameters with
values given in the CGI script.

To run the task you would then do something like:

	% $iraf/bin.sparc/x_images.e listpix @listpix.par

In this case you must be careful that ALL of the task parameters are
defined, this is done by 'dpar' but empty string parameters will always
be prompted for.  On a host command line simply respond to the parameter
prompts by hitting the return key, from with a CGI script these must
be supplied automatically in some way (e.g. via redirection).
	In the second case you create a command file and input it to the
cl, for example

	% cl < cl.input >& some_logfile

where cl.input contains CL commands such as

	wfits.scale=no               # set a parameter wfits image*.imh
	mta            		     # call a task 
	logout                       # logout of the CL

You must be careful about making sure you are in the right directory and
that parameters are given explicitly if they're like to change, but with
this approach you can call any iraf task.

4.1  Graphics Tasks
-------------------

	Regardless of the method chosen, you need to be careful about
redirecting any required input or text/graphics output.  Graphics output
can be redirected either by setting the "device" parameter to e.g. 'vdm'
to create a file called 'vdm' in the uparm directory, or using the '>G' CL
syntax as in

	cl> surface dev$pix >G surf.plot     # redirect metacode to a file
	cl> surface dev$pix dev="vdm"        # save metacode to uparm dir
	cl> surface dev$pix dev="stdplot"    # to print it out 
	cl> gflush			     # flush graphics buffer

Which of these approaches works best for depends depends on the tasks you
need and the method of execution chosen above.  Note that the ">G" syntax
will only work for tasks executed within the CL, setting a device
parameter to something that creates a file will work with either method.
	For non-interactive tasks like SURFACE or CONTOUR this file is
created automatically, interactive tasks however may need to create
metacode files explicitly or else the CGI script must take care to extract
only those plots of interest from the metacode file (e.g. with a separate
call to GKIEXTRACT).
	Interactive tasks must also satisfy requests for cursor commands,
including the usual 'q' keystroke needed to exit the task.  Since cursor
commands are in reality queries to the CL any binary run as a host task
will generate a cursor prompt on the standard output the same as for any
other parameter query.  The response to a cursor query however is usually
of the form
		x y wcs key strval

where 'x' and 'y' are the cursor position, 'wcs' is the WCS of those coords
(usually not important), 'key' is the keystroke you would normally enter,
and if 'key' is a color the 'strval' is the remainder of that color command.
See section 3.7 of the "help cursors" help page for more details on alternate
graphics input.  Note however, that your CGI script must know in advance the
order in which the prompts will occur to be able to satisfy them correctly,
e.g. any parameter prompts generated by empty string values should be met
with a newline, and cursor prompts with something as above.  Since the tasks
will be very narrowly defined as to how they are run this usually isn't
difficult to set up.

4.2 Example
-----------

	As an example let create a CGI script to execute the PCOL task
from a web interface.  All that we need to do this is the PLOT package
binary to execute the task, a 'graphcap' file, and the SGIKERN binary in
order to convert our graphics metacode to a GIF format using the specified
graphcap entries and the newly installed SGI2GIF translator.  In the
following we detail the steps involved in creating this script on a system
with IRAF installed, your application may vary somewhat.   We use a
C-shell script here but the same principles apply to all scripting
languages, users should contact site support with questions.

-----------------------------------------------------------------------------

#!/bin/csh -f
#
# Sample CGI script demonstrating the using the PCOL graphics task to 
# produce an 'sgigif.gif' file of the resulting plot which can be shown
# as an image of the output web page.  The script does not show how to
# parse arguments or format the resulting HTML page.  All that is required
# for IRAF execution is the binary for the task to be run, the SGIKERN
# binary, and a graphcap file to produce the GIF (given below).  The CGI
# script can define the task parameters itself or use a predefined 'dpar'
# dump to set defaults as we do below.

# The REMOTE_ADDR variable is defined in the environment of the CGI
# script automatically, we specify it here for demonstration purposes.
set REMOTE_ADDR  = 140.252.30.95

# This would be defined as the graphcap file installed for the local web
# server.

# The only graphcap entries needed to output graphics to a GIF file using
# the SGI translator is as follows:
#
#     vdm|stdvdm|Virtual Device Metafile:\
#         :co#80:li#35:xr#1024:yr#1024:zr#256:ar#.77:ch#.0294:cw#.0125:\
#         :X1#0:X2#1023:Y1#0:Y2#1023:
# 
#     g-gif|UNIX generic interface to multi-frame GIF file generator:\
#         :DD=ugif,tmp$sgk,!{ /<path>/sgi2gif.e -w $(PX) -h $(PY) \
#         -bg 0 0 0 -fg 255 255 255 -root sgigif $F.[1-8] ; \
#         rm $F.[1-8]; }&:MF#8:NF:tc=sgi_image_format:
# 
#     sgi_image_format|Generic raster file format specification:\
#         :kf=bin$x_sgikern.e:tn=sgikern:ar#.75:\
#         :xr#640:yr#480:PX#640:PY#480:XW#640:YW#480:\
#         :BI:MF#1:YF:NB#8:LO#1:LS#0:XO#0:YO#0:
#
# Note that the path to the sgigif.e binary is specified explicitly, this
# must be replaced by the path to the actual binary.
#
# On the web server this file would normally be installed in the cgi-bin
# or some other directory, the cgi script itself needs to define this location
# with the following variable:

set graphcap    = /tmp/graphcap

# A uparm directory needs to be defined for saving the VDM file.  This is
# defined based on the REMOTE_ADDR so we can have multiple connections 
# running at the same time without concurrency problems.

set uparm       = /tmp/uparm-$REMOTE_ADDR/

# Create the uparm directory we'll be using...
mkdir $uparm

# Execute the graphics task desired.  In this example we're running the PCOL
# task and assume we've saved the parameters to a 'pcol.dpar' file in the
# current directory.  In practice the parameters can be specified using a
# dpar file in the cgi-bin dir or explicitly on the command line.  To execute
# the task we call the binary directly, direct output to /dev/null and
# redirect input blank lines to respond to params that take no value.  We
# must set the uparm and graphcap values set above to handle the graphics.
# The CGI script can insert values such as 'image' based on arguments, the
# defaults come from a predefined dpar file. 

/iraf/iraf/bin.ssun/x_plot.e >>& /dev/null << EOF
set uparm = $uparm
set graphcap = $graphcap
pcol @pcol.dpar pcol.device="vdm"

EOF

# At this point the GKI metacode is saved in the uparm$vdm file, where
# 'uparm' is set above and is created by the custom graphcap file we're
# using.  To convert GKI metacode to the final GIF file we call the SGIKERN
# directly and specify the device as 'g-gif' which produces an 'sgigif.gif'
# file in the current directory.  Graphcap entries can be created to name
# the file anything desired, that filename is then used as a URL for the
# web page returned.

/iraf/iraf/bin.ssun/x_sgikern.e >>& /dev/null << EOF
set uparm = $uparm
set graphcap = $graphcap
sgikern input=uparm\$vdm device=g-gif generic=yes
EOF

# Finally, clean up the temp files we've created.
/bin/rm -rf $uparm