diff options
Diffstat (limited to 'unix/gdev/sgidev/README.gif')
| -rw-r--r-- | unix/gdev/sgidev/README.gif | 438 |
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 + |