Initial commit

1 files changed, 438 insertions, 0 deletions

diff --git a/unix/gdev/sgidev/README.gif b/unix/gdev/sgidev/README.gif
new file mode 100644
index 00000000..85833d3f
--- /dev/null
+++ b/unix/gdev/sgidev/README.gif
@@ -0,0 +1,438 @@
+
+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
+