igi: Interactive Graphics Interpreter.
Package: stplot
Description
'Igi' is an interactive graphics command interpreter that allows a user to enter commands to read data, draw plots, and manipulate those plots. The syntax (form of the commands) and semantics of 'igi' are based on the MONGO interpreter, but 'igi' runs as an IRAF task and uses the IRAF graphics I/O (GIO) and file I/O (FIO) protocols.
'Igi' has several significant extensions that are not included in MONGO, such as the ability to read ST4GEM tables, new commands such as [XY]FLIP, [XYEPLS]EVALUATE, [XYEPLS]SECTION, VPAGE, and EDITCMD, and enhancements to MONGO commands such as CURSES.
- Command Syntax
- 'Igi' commands are read from the standard IRAF input stream (STDIN).
Therefore, they may be typed interactively, piped or redirected from a
file on the command line when 'igi' is started. For example, with igi
commands in the file mycmd, the following would execute those commands
just as if they had been typed interactively:
st> igi <mycmd
- Standard Input and Standard Output
- Igi uses Standard Input (STDIN) and Standard Output (STDOUT) quite explicitly. Commands to be executed are read from STDIN. Therefore, a command file may be redirected (using the "< filename" syntax) or piped (using the "task | " syntax) to STDIN on the igi task command line and executed just as commands typed interactively. Thus, a script or compiled task may be written to build and execute igi commands for drawing plots. STDOUT is used to display text containing data values, a status summary, or a list of executed commands, among other things. STDOUT may also be redirected (using the "> filename" syntax) on the task command line to save this displayed output.
- Data
- Six vector buffers are predefined for the X and Y plot coordinates, errors,
point style codes, upper or lower limit flags, and a scratch buffer.
These buffers may be filled from any of several data formats: an ASCII
text (list) file with values arranged in columns, an ST4GEM binary
table, a FITS table, or an IRAF image on any dimensionality. The
latter may be an OIF ("old" IRAF), STF (STScI or GEIS), or QPF (PROS)
format image.
The DATA command specifies the name of the table file to read. Columns
from either format are read into the buffers using the separate
explicit commands [XYEPLS]COLUMN. The text data to be read are
specified by the column number and table data are specified by column
name. Note that table column names are case-sensitive. The same
commands are used to read text and table files; the file format itself
determines the command syntax and semantics.
Data may be any single-precision floating point value. Points with
either coordinate having the value 'INDEF' will be excluded from
autoscaling, and will not be plotted.
Text files used as input consist of columns of values separated by
white space (spaces or tabs). Rows of the input are restricted to a
single line of the input file. Column values need not line up row to
row. Any blank line or one whose first non-blank character is # is
ignored and may be used as a comment.
Image data are handled slightly differently. The [XYEPLS]SECTION
command opens an image file and reads data into one of the igi
vectors. Neither the DATA nor COLUMN commands are used. An "image
section" may specify some portion of the image to read. In addition,
an optional qualifier argument after the image name specifies how to
treat multi-dimensional images. The qualifier must be an interger. If
zero the image section is read as a single one-dimensional vector
regardless of the dimensionality of the data. If the argument is
non-zero, its value specifies the axis on which to project the data to
form a single vector. If positive, igi will average the data
perpendicular to the specified axis. If negative, igi will sum instead
of average. For example:
igi> YSECTION myimage 2
- Image Display
- Some graphics devices are able to display gray-scale images and igi has basic image rendering (display) capabilities. Note that these capabilities overlap only partially with those dealing with line (vector) plots.
- Coordinates and Scaling
- Coordinates in most commands (pen position, cursor readback, etc.) are
specified in World Coordinates or WC, also known as user coordinates.
The area on which to plot is specified in `Normalized Device
Coordinates' or NDC, in the range 0:1 in both the X and Y direction. A
`virtual page' may be specified as a subset of the physical device
drawing area by setting the edges in NDC using the VPAGE command, or in
physical units (inches) using the PHYSICAL command. The `viewport',
i.e., the axes of a plot, may fall anywhere within this page and is
specified as a fraction of the virtual page in the range 0:1 using the
LOCATION command.
One additional comand, FITPIX, fixes the virtual page on the device to
match a 2-D image input with the ZSECTION command. The edges of the
viewport are as specified in NDC as with VPAGE, but the actual viewport
set may be smaller.
Coordinates Command Sets WC -- PC LIMITS WC on viewport PC -- VPC LOCATION Viewport on virtual page VPC -- NDC VPAGE Virtual page on device NDC -- Inches PHYSICAL Virtual page on device NDC -- Pixels FITPIX Virtual page on device
igi> imgwcs igi> ysection dev$pix[10,50,1]
WC VPC PC NDC Move RELOCATE VRELOCATE PRELOCATE DRELOCATE MOVE VMOVE PMOVE DMOVE Draw DRAW VDRAW PDRAW DDRAW
- Axes
- There are two commands that draw axes, AXIS and BOX. AXIS is lower level and quite general while BOX is more convenient to use but has fewer options. BOX automatically draws four axes at the current viewport boundaries with the current world coordinates. Optional arguments to the BOX command specify how to draw the axis labels. There are two additional commands that alter the way in which the axes are drawn. TICKSIZE specifies the spacing between major and minor ticks and optionally specifies logarithmic axes. NOTATION specifies the range of data values within which tick labels will be written in exponential notation. To fill in a grid of lines between major tick marks use the GRID command. It uses the current line type (see LTYPE) and width (see LWEIGHT). You must use BOX before GRID to compute the tick spacing. BOX does not label any axis. The XLABEL and YLABEL commands allow an arbitrary string to be drawn below the bottom horizontal (X) axis and to the left of the left vertical (Y) axis, respectively. To draw any other style of axis label, use the LABEL command to draw an arbitrary string. There are two string buffers maintained for the X and Y labels. These are filled by the [XY]COLUMN and [XY]SECTION commands with the filenames used as input data. If the argument to [XY]LABEL is a null string, then igi will use the label strings. Otherwise, it will use the string argument. AXIS is a lower level command that draws an arbitrary axis. It does not take into account the current viewport and world coordinates. Arguments to AXIS specify the position of the axis, it's range of data values, the format of the labels and spacing of ticks. The current angle set by the ANGLE command determines the orientation of the axis.
- Macros
- Macro text may be defined and expanded as commands and/or arguments.
Macros are defined with the DEFINE command whose argument is the macro
name. The prompt changes to "macro> ", indicating that subsequent text
is not interpreted, but saved as macro text. Macro define mode is
terminated by typing END at the prompt.
Arguments to macros are defined by the "&" character followed by an
integer appearing in the macro text. The argument number specifies the
position of the replacement argument value when the macro is invoked.
The maximum argument value specifies the number of arguments to the
macro.
A macro is invoked using its name, followed by the values to replace its
positional arguments, if any. A macro may invoke any 'igi' command or
other defined macros, but may not invoke itself (i.e., no recursion).
BYE is not equivalent to END for terminating a macro. Therefore, BYE
does not terminate macro define mode, will be stored as part of the
macro text, and will be expanded into the command stream when the macro
is invoked.
The following example defines and invokes a macro named "simple" to
scale and draw a plot:
igi> define simple macro> data &1 macro> xcolumn &2; ycolumn &3 macro> limits; box; connect macro> end igi> simple igi.dat 1 2 igi> erase igi> simple igi.dat 3 4
where XXXXX is the number of characters to allow in the pushback buffer. This comman can be executed either at the cl prompt, or within the login.cl or loginuser.cl file. An indication that the buffer size may need to be increased is when the error:set igi_buflen = XXXXX
occurs.ERROR: Pushback buffer overflow (recursive macro?) (STDIN)
- Command Buffer
- Many commands are saved in the `command buffer'. The commands in the buffer may be listed and edited. The commands may be replayed. Commands may be read into the command buffer from a file, commands may be executed directly from a file, or the contents of the buffer may be written to a file. The command buffer may be edited during an 'igi' session and the edited buffer played back. Commands are stored in their full, unabbreviated extent, capitalized, one command per line, regardless of how they were typed or read from a command file. String arguments (to LABEL, for example) are delimited by double quotes. The command memory mechanism operates differently for separate classes of commands. In general, commands dealing with data I/O, data manipulation, plot parameters, and drawing commands are saved while those dealing with commands themselves are not. [XYEPLS]COLUMN, DATA, [XYEPLS]EVALUATE, LINES, and [XY]LOGARITHM are stored in the command buffer. All of the graphics output commands: AXIS, BOX, CONNECT, DOT, [DPV]DRAW, ELLIPSE, ERRORBAR, HISTOGRAM, ID, LABEL, POINTS, POLYGON, PUTLABEL, STEP, and ULLIM are saved in the command buffer. Parameter (plot attribute) manipulation commands: ANGLE, EXPAND, [XY]FLIP, ID, JUSTIFY, [XY]LABEL, LIMITS, LOCATION, LWEIGHT, NOTATION, [DPV]RELOCATE, RESET, [XY]SIXTY TICKSIZE, TITLE, [ELP]TYPE, and VPAGE are saved in the plot command buffer. Command buffer manipulation commands: EDITCMD, LIST, PAGECMD, PLAYBACK, READ, and WRITE are not saved, except INPUT. The remaining miscellaneous commands: !, ?, ^, APROPOS, CURSES, DLIST, END, ERASE, HELP, MACROS, MINMAX, SHOW, and UNDO are not saved in the command buffer. In cursor mode, a RELOCATE (MOVE) command is stored for each cursor position read, and commands are saved in the command buffer when entered in ":" mode. Macro invokations rather than the expanded text are stored in the command buffer. The last command resulting in plotted vectors remains in a single line command buffer. The UNDO command uses this buffer to erase the result of this instruction on devices supporting vector erase.
- Cursor Interaction
- All of the existing capabilities of the IRAF/GIO graphics cursor for manipulating the `graphics buffer' are available within 'igi'. IRAF/GIO cursor interaction may be initiated with the 'igi' command CURSES. It recognizes a number of keystrokes and commands with a broad range of capabilities to manipulate the existing plot, including zoom, roam, reading and writing binary plot metacode files, generating hard copies, etc. After a plot has been produced, the graphics metacode commands remain in the IRAF graphics buffer after igi terminates until it is explicitily erased with gflush or graphics are opened again. Cursor interaction is still available from the cl to interact with the plot using "=gcur", in order to obtain hard copies using the ":.snap" cursor command, for example. In addition to the IRAF/GIO cursor capability, all 'igi' commands are available in cursor mode using the colon command capability. Upon typing ":" when the graphics cursor is displayed, the terminal returns to text mode with the ":" displayed as a prompt. At this prompt, any valid 'igi' command may be typed. All of the logical pen movement commands (RELOCATE, DRAW, etc.) will use the current cursor position regardless of the coordinate system or any arguments input on the command, therefore, these coordinate arguments should be ommitted.
New features
- Version Dec 1999
- A new command was created for use by IGI. The new command, PSCMD, allows a user to insert complete Postscript command strings directly into the PostScript output. The PSCMD command can support any PostScript command, but the PDFMARK commands provide a way to insert Acrobat PDF functions into a PostScript document. The PDFMARK functions are completely transparent to the PostScript (due to an enhanced PostScript prolog in 'psikern') but are activated upon conversion from PostScript to PDF format. This allows the user to insert bookmarks, links, and other PDF functions into a document during initial generation by IGI. The user, however, must take all responsibility for syntax and usage rules for the commands inserted into the PostScript. In addition, the PSFNT and PSCMD commands were revised to only create output when the output device uses the 'psikern' kernel. This avoids problems with these commands outputting the strings to a device which won't understand them, such as 'stdgraph'. Thus, the effects of these commands are isolated to PostScript devices, and only those PostScript devices supported in the graphcap by the 'psikern' kernel.
- Version May 1997
- A couple of new capabilities were added to IGI in this version, one for working with which have arrays as elements of its columns, the other providing greater freedom in the use of PostScript fonts. The DATA and COLUMN commands were modified to accept arguments for working with tables that have arrays contained in table cells. Row selectors can now be added to a filename in the DATA command to specifiy which row of the column the array should be pulled from for plotting. Alternatively, a row number can be given as the second argument of the COLUMN command to specify which row of the named column should be used for plotting. The two features can also be used in conjunction, with a range of rows being specified in the DATA commands row selector and the row number in the COLUMN command selecting the row from that range to be used. This allows one range of rows to be read in using the DATA command while the COLUMN command is used to step through that range of rows. Labels in IGI plots can now use more than the usual Times-Roman or Symbol font when using the GIO (or HARD) fonts. A new command, PSFONT, has been created to allow a user to specify a new PostScript font to use in a label. This font is then used when a new GIO escape sequence, "", is seen in in the label text. Each time the PSFONT command is called, it resets what font will be used with the "" command in the text, but the PSFONT command can be called as many times in an IGI script as desired. The only limitations of this command is that it only affects labels printed out after setting FONTSET to "hard", only one new font can be used at a time, and only those fonts supported by the printer can be used.
- Version May 1994
- The command POLYGON has been added to draw arbitrary closed, filled polygons.
- Version 3.6 July 1993
- Added the WCSLAB command to provide WCS coordinate labeling identical to the stplot.wcslab task. Optionally, the command may permit editing the extensive wlpars parameter set for specifying attributes via eparam. If the ZSECTION command was used to read an image section into the Z buffer, then the WCS attributes of that image are used in labeling the plot. Otherwise, the WCS is taken from parameters in the wcspars pset. Note that the psets may be edited before entering igi by explicitly assigning parameter values or by using eparam at the cl prompt. In addition, parameter values may be assigned or the psets edited from igi using the "!" escape before using the WCSLAB command. Added the VERSION command to show the current version and the date of its installation. This is intended to help in determining the state of implementation of features and bug-fixes. Modified the initial prompt, the listing from the SHOW command, and the result of the ID command also to show the current version and installation date. Modified SAOCMAP to correct a bug which certain colormaps cause igi to fail with memory corrupted (crashing the cl as well). This is an old problem that was corrected in playpen.scmapc but not igi. The code for inttab(), the guts of the colormap code, now matches between the tasks, except that in scmapc it uses floating point output colormap and igi uses shorts.
- Version 3.5.3 April 1993
- Modified STEP to correct a bug preventing drawing the curve when one or both axes are reversed using the [XY]FLIP command. Installed a modified version of SECTION provided by Frank Valdes (NOAO) to implement recognition of multispec format images (spectra) with IMGWCS enabled.
- Version 3.5.2, March 1993
- Modified DLIST to permit writing the plot buffer values to a file instead of STDOUT. An optional argument now specifies the output text file. Modified LINES to permit resetting the range to the default, using all of the input table rows. An optional argument value of zero returns one or both limits to the default. Fixed a bug in BARGRAPH (HISTOGRAM) resulting in incorrect plots with both X and Y data. Changed all explicit INDEF test to use IS_INDEF macros. Chanced dummy array declarations to use ARB.
- Version 3.5.1, October 1992
- Removed dependence on ST4GEM so the Tables version links and executes independently. Modified FILLPAT to print the current pattern style if there's no argument.
- Version 3.5, September 1992
- Implemented the FILLPAT command to specify a fill pattern style. The argument is an index corresponding to the gio pattern index. The plotted pattern is kernel- and device-dependent and implemented only in psikern. Added the BARGRAPH command as an alias (preferred) for HISTOGRAM, whose name is confusing since it doesn't compute a histogram from data. Modified BARGRAPH, HISTOGRAM, DOT, and POINTS to implement filled areas. The current fill pattern as specified by the FILLPAT command will be used if the symbol style (set with PTYPE) is "open" or "starred". The former result is achieved as long as the fill pattern is 1 (outline, the default). Implemented the SAOCMAP command to read a colormap as written by SAOimage and apply this to the image rendered by PIXMAP. By default, it will scale the entire SAOimage color map to the full output map. There is an option force the appropriate elements of the color map to match the "graphics" colors as defined in the servers. This permits rendering an image as dumped directly from a server's display raster buffer (using playpen.dstoim, for example).
- Version 3.4.1, August 1992
- Fixed a problem with the text justification for gio (hardware) fonts. There is a fundamental discrepency in the definition of justification between igi and gio. The gio convention is to specify the justification relative to the horizontally aligned bounding box surrounding the text, not the string itself. The fix involves a matrix which maps the justification index to one which will render the text with the closest applicable justification by gio. The modified scheme should work properly for "cardinal" angles but not as well for many combinations of angle and justification.
- Version 3.4, July 1992
- Implemented the ZSECTION and PIXMAP to read and plot 2-D image sections. This currently really works only with the PostScript kernel, psikern (of course). Added FITPIX to specify a viewport that matches on the device the aspect ratio of the pixmap raseter. Added ZRANGE to specify the minimum and maximum pixel value to map to the display range. The default behavior is an attempt at an analogy with the 1-D case. That is, ZSECTION fills the Z buffer with the image section. LIMITS should be used to set the WCS. Margin may be used to reset the WCS to create a margin between the viewport (axes) and the edge of the image. FITPIX may be used to specify a viewport that fits the raster. Otherwise, the pixmap will fill the viewport. ZRANGE should be used to specify the range of pixel values to map to the range of display values. With no argument, ZRANGE permits autoscaling on the input data. Added the "viewport" commands PDRAW, PMOVE, and PRELOCATE, identical to DRAW, MOVE, and RELOCATE except the coordinates are expected to be in "viewport coordinates" (PC). These are in the range 0:1, relative to the edges of the axes. That is, the same as WC, except always in the range 0:1. The same results may be obtained by explicitly using "LIMITS 0 1 0 1" except of course, these commands avoid that. Implemented ZEVALUATE to permit arithmetic operations on the Z buffer. Note that there is some ambiguity in dealing with inherently 2-D Z data. Implement the FILLPAT command to specify the fill pattern for hollow symbols and bar charts (HISTOGRAM). This is kernel-dependent. Only psikern supports it currently, of course. Modified HISTOGRAM to accept an argument specifying the relative width of the bars. Simplified the code in the equally-spaced case. Added the BARGRAPH command as an alias for HISTOGRAM. Modified LOCATION to permit specifying a square (unity aspect) viewport, regardless of the shape of the device or virtual page. This is analagous to the action of FITPIX, signalled with a first argument of INDEF. Modified ig_scale() and ii_location() in ig_scale.x.
- Version 3.3, June 1992
- Add the FONTSET command to select igi or gio font sets. The latter permits using real PostScript fonts with the PostScript graphics kernel, psikern. Note that the text "escapes" for doing things like changing fonts, super/sub-scripts, etc. are different between the font sets. Add the `initcmd' task parameter to permit startup with igi commands. Among other things, this permits a user to use a constant command file but with some variation with each execution, specifying a new data file, for example. Modified code that pages listings on STDOUT, such as DLIST and SHOW to display text without paging if STDOUT is redirected. This permits running igi in "batch" but using these commands without annoying page prompts.
- Version 3.2, May 1992
- Fixed a bug causing some tick labels to include an extra zero between the ones place and decimal point. Fixed the NOTATION command, which did not have any effect. It is now possible to change the data range outside which tick labels are plotted as exponential. Added the NUMBER command to draw the element number at each data point. Fixed extra line drawn by GRID. Added the COLOR command to specify the color index for all subseqeuent drawing. The color index is an integer specifying the device-dependent (kernel) color that is rendered. Currently, only the PostScript graphics kernel (psikern) supports color.
- Version 3.1, November 1991
- Changed the font file to be machine independent binary using mii to read it. There is no longer need for the ASCII font file or anything to be done at installation. The single font file is now stplot$miifont.dat. Modified the STEP command to draw the vertical connecting lines between points even if adjacent points fall outside the viewport. Fixed a bug preventing macros invoked in upper case from being recognized. Fixed axis tick labels that were incorrectly placed when perpendicular to the axis. Cosmetic changes to SHOW output. Fixed a bug in the command parser that showed up in the DEC/Ultrix Fortran compiler (and apparently nowhere else) causing no commands to be recognized. Changed the way help text is paged. Instead of using the spawned cl command directly, we now redirect the help text from the cl command to a temporary text file, page the file, then delete it.
Parameters
- (initcmd = "") [string]
- An igi command string executed upon startup. This may be any valid igi command including command separators (";") to execute multiple commands. This may be useful to specify a different input data file for multiple executions but use a constant input file otherwise, for example.
- (wlpars = "") [pset]
- Parameter set (pset) for modifying the plot and labels produced by the WCSLAB command. These parameters are described in the help file for 'wlpars' (i.e., type "help wlpars").
- (usewcs = no) [bool]
- Use the information in the 'wcspars' pset for the world coordinate information. If 'no', the information will come from the image read in by the 'zsection' command.
- (wcspars = "") [pset]
- Parameter set (pset) for specifying a WCS for the WCSLAB command. This is used to specify a different WCS from an image read by ZSECTION. Type "help wcspars" for more information.
- (device = "stdgraph") [device name]
- The output graphics device. If device = "file", the graphics output is stored in the file specified by the parameter `metacode'.
- (metacode = "") [file name]
- The name of an output binary GKI metacode file. This is required if device = "file".
- (append = no) [boolean]
- Append to existing graphics? This may be used to run igi several times but plot to the same frame (page) or combine igi graphics with plots from other IRAF/ST4GEM tasks. Use the ERASE task to create a new frame, even with append=yes. If appending graphics to a metacode file you must also use ">>G file" rather than "device=file". Using "append=yes" also permits creating a single file if you are creating a PostScript output file. If you also wish to create a new page but use a single file, use the ERASE command. This will not actually erase existing graphics from any non-interactive (hard copy) graphics output.
- (debug = no) [boolean]
- Echo commands and list additional internal information.
- (cursor = "") [graphics cursor]
- Graphics cursor.
!
Arguments: !text Escape a command to the cl. Input text following the "!" is passed to the cl for interpretation. The cl environment at the time igi was invoked is in effect. For example: !dir executes the IRAF directory command to list the files in the current directory using the IRAF virtual file names. Note that cl commands are case sensitive. The command !cl starts a new cl process complete with the cl prompt and with the same environment as when igi started. To terminate this process and return to igi, type bye at the cl prompt. Any text preceeded by "!!" is executed as a host (e.g., VMS, UNIX, etc.) command. The first "!" escapes the command to the cl, and since the remaining text starts with another "!", this escapes the command to the host. Any valid host command will be interpreted. The environment at the time the cl and igi were invoked is in effect. For example, the command !!dir on VMS (!!ls on UNIX) will list the current default directory using the host file names. The command !!! on VMS or !!csh on Unix starts a new host process. To terminate this process and return to igi, type "logout" on VMS and "exit" on Unix.?
no arguments Page the help summary. Only a list of the commands and their meaning is listed. To get this extended text, use the HELP command.^
Arguments: ^[n] Execute a previous command. If no argument follows the character, execute the last command. The optional argument must be an integer, and if present specifies the sequence number of the command in the command buffer to execute. See LIST, EDITCMD, and PAGECMDAngle
Arguments: ANGLE [ang] The orientation for markers and text is specified by the floating point parameter in degrees counterclockwise from the horizontal (positive X axis). If no parameter is specified, the value of the currently set angle will be listed. This command is saved in the command buffer.Apropos
Arguments: APROPOS keyword List a brief description of the commands associated with the specified keyword. For example, APROPOS move results in:DDRAW Pen down move (draw) in NDC DMOVE Pen up move in NDC (alias for DRELOCATE) DRAW Pen down move (draw) in WC DRELOCATE Pen up move in NDC MOVE Pen up move (alias for RELOCATE) RELOCATE Pen up move in WC VDRAW Pen down move (draw) in VPC VMOVE Pen up move in VPC (alias for VRELOCATE) VRELOCATE Pen up move in VPC
Axis
Arguments: AXIS w1 w2 minor major x y len label clockw1 -- WC at beginning of axis w2 -- WC at end of axis minor -- Spacing of minor ticks; < 0 => logaritmic major -- Spacing of major ticks x, y -- Position of axis (at w1) in VPC len -- Size of axis in VPC label -- 0 => No tick labels 1 => Tick labels parallel to axis 2 => Tick labels perpendicular to axis clock -- 0 => Ticks and labels counterclockwise 1 => Ticks and labels clockwise
Bargraph
Arguments: BARGRAPH width Draw a bar graph (histogram-style plot) using the current X and Y data. If no X data exist, the horizontal axis will be scaled on the pixel numbers. This is an alias for the HISTOGRAM command. The optional argument specifies the relative width of the bars. If no argument is used or the value is INDEF, the bars fill the available space. For equally spaced data (equally-spaced or no X values), all of the bars are as wide as the difference in X between adjacent points. For unequally spaced data, the edges of the bars fall halfway between adjacent points. The "width" argument is a constant factor to apply to this width. For example, "BARGRAPH 0.5" will draw bars half the natural width, leaving an equal space between bars. It is not possible to apply a different factor to each bar separately, except by specifying the X data explicitly. Bars may be drawn with a fill pattern, specified using the FILLPAT command. Note that the nature of the fill patterns depends on the device and kernel used. See LTYPE and LWEIGHT for specifying the style of the curve to draw. See CONNECT, STEP, POLYGON, and POINTS for different curve styles This command is saved in the command buffer. The results of this command may be erased with UNDO.Box
Arguments: BOX [xlabel[ ylabel]] Draw and label the axes using the current page, viewport, and window transformations and any axis label or title specified. The optional label arguments specify the X and Y tick labels: 0 ==> no labels; 1 ==> labels parallel to the axis; 2 ==> labels perpendicular to the axis. The default is xlabel = 1, ylabel = 2. See AXIS for drawing a single arbitrary axis. See [XY]LABEL for annotating the axes with a text label. See LIMITS for setting the plot scale. See MARGIN for adjusting the scale to include a border between curves and axes. The current tick label format specifies how the tick labels will be written (see FMTICK). The current line width specifies how the axis will be drawn (see LWEIGHT). This command is saved in the command buffer. The results of this command may be erased with UNDO.Bye
no arguments Terminate igi. This is an alias for END, except in macro define mode (see DEFINE).Color
Arguments: COLOR index Set the color index for all subsequent drawing. The argument, the color index, is a positive integer. All drawing operations -- lines, text, symbols, curves, axes -- will be rendered in the selected color. The default color index is 1, rendered as black (or the foreground color) on most devices. The rendered color depends on the device used and whether the IRAF kernel supports it. (Currently, only the psikern IRAF kernel supports color for use with color PostScript devices.)Column
Arguments: [XYEPLS]COLUMN column [row number] Read a column of data from the file specified by the DATA command. The command prefix indicates which data buffer to fill: x coordinates, y coordinates, errors, point marker styles, limits, or scratch. If the input data is a text (ASCII list) file, 'column' must be an integer specifying the column number. If it is an ST4GEM or FITS table, 'column' must be a string specifying the column name. Note that table column names are case-sensitive and may not be abbreviated. The second argument, row number, provides the ability to plot from tables where each element of a column is an array itself. The row number specifies which cell of the column you want to plot out. Arrays from these tables can be plotted by specifying a row selector as an extension to the input file (table) name in the DATA command. See DATA to specify the input file (table) name. See [XYEPLS]SECTION to read an IRAF image into a buffer. This command is saved in the command buffer.Connect
no arguments Draw a (polyline) curve in the current line style (see LTYPE) connecting the data coordinates. See POINTS for drawing markers without connection. The current pen position is left on the last point. This command is saved in the command buffer. The results of this command may be erased with UNDO.Curses
Arguments: CURSES [file] Start cursor mode and read back the cursor position. If the argument `file' exists, it is the name of a file to which are written the coordinates of positions selected with the cursor. If no argument exists, the positions are written only to STDOUT (the terminal); the coordinates are not saved in a file. To terminate cursor mode, type "q" or "e" (lower case!). Any other lower case character will list the cursor position and redisplay the cursor. Upper case and special characters are recognized by IRAF cursor mode. This command invokes the IRAF/GIO cursor facility (see !help cursor). In addition to the IRAF/GIO cursor capability, all igi commands are available in cursor mode using the colon command capability. Upon typing ":" when the graphics cursor is displayed, the terminal returns to text mode with the ":" displayed as a prompt. At this prompt, any valid igi command may be typed. Commands expecting input coordinates ([DPV]RELOCATE and [DPV]DRAW) will use the current cursor position regardless of any arguments input on the command, therefore, these coordinates may be ommitted. The CURSES command is not stored in the command buffer, but a RELOCATE command with the last cursor position is stored on each cursor read or ":" command. Therefore, on PLAYBACK, no cursor interaction takes place but any commands relying on the interactively specified cursor position execute appropriately. Type "!help cursor" from igi ("help cursor" from the cl) for help on the IRAF cursor facility.Data
Arguments: DATA [filename] Specify the input data file. This file may be either an ASCII list (text) file whose contents are numerical values arranged in columns, an ST4GEM table, or a FITS table. If no file name is specified, the current data file and type is listed on the standard output. See [XYEPLS]COLUMN to read an arbitrary column into one of the predefined igi arrays. See [XYEPLS]SECTION to read an IRAF image into a buffer. A row selector can be appended to the file name for a FITS table with arrays as elements of its columns to allow plotting of data from these tables. (For more information on the syntax of row selectors, use "help selectors" in the TABLES package.) This command is saved in the command buffer.Ddraw
Arguments: DDRAW xpos ypos Draw a line in the current line style from the current position to the normalized device coordinates (NDC) specified by the two floaing point parameters. The ending point of the line becomes the new current position. If ":DDRAW" is used in cursor mode, xpos and ypos are ignored and should be omitted. See DRAW to draw in WC and VDRAW to draw in VPC. This command is saved in the command buffer.Define
Arguments: DEFINE macro Enter macro text. The argument is the name of the macro. A defined macro may be invoked as any other command, possibly with arguments. DEFINE causes igi to enter macro define mode, in which commands are not interpreted (except END) but stored as is. The prompt "macro> " indicates macro define mode. To terminate the macro definition, type "END". The macro is invoked by typing its name. The name is not case sensitive. It may not be abbreviated. When the macro is invoked, the text is expanded and interpreted just as typed text. Optional macro arguments are positional and are defined by the character "&" and an integer. Defined arguments are replaced by their values typed on the command line in the order specified by their definition. The order in which the arguments appear in the macro text is unimportant, but the order in which the argument values appear on the invoked macro must match the definitions. The highest numbered argument definition specifies how many argument values must appear in the macro call. If a macro is defined more than once with the the same name, the new text and argument definition will supercede existing text. Macro text may be listed (LIST), edited (EDITCMD), or saved in a text file (WRITE). The MACROS command lists the currently defined macro names and the number of their arguments.Dlist
Arguments: DLIST [file] Print the data values (if any) currently in the X, Y, error, and point code buffers. If there is no argument, print to standard output. If STDOUT is not redirected, uses the IRAF page facility. The optional argument specifies the name of a file in which to save the output. This is not redirection, so it's not possible to append to an existing file but will always write a new file or overwrite an existing file. With no arguments, DLIST is not saved in the command buffer. With an output file argument, DLIST is saved in the command buffer.Dot
no arguments Draw a single marker of the current style, size, and angle at the current location. See PTYPE, EXPAND, and ANGLE to specify the marker style. To draw a single circle or ellipse, see the ELLIPSE command. To draw markers at the data coordinates in the plot buffers, use the POINTS command. This command is saved in the command buffer. The results of this command may be erased with UNDO.Draw
Arguments: DRAW xpos ypos Draw a line in the current line style from the current position to the coordinates specified by the two floating point parameters in world coordinates (WC). The ending point of the line becomes the new current position. If ":DRAW" is used in cursor mode, xpos and ypos are ignored and should be omitted. See [DPV]RELOCATE (or [DPV]MOVE) to specify the initial position and see [DPV]DRAW to specify the position in other coordinates. This command is saved in the command buffer.Drelocate
Arguments: DRELOCATE xpos ypos Pen up move, i.e., change the current position to the normalized device coordinates (NDC) specified by the two floating point parameters. This is an alias for DMOVE. If ":DRELOCATE" is used in cursor mode, xpos and ypos are ignored and may be omitted. In fact, it is unnecessary to use any move command in cursor mode. Issuing any command or request for readback resets the current position to the coordinates of the cursor. This command is saved in the command buffer.Ecolumn
Arguments: ECOLUMN column Read error values from the column in the current data file specified by the column parameter. If the input data is a text (ASCII list) file, column must be an integer specifying the column number. If it is an ST4GEM or FITS table, column must be a string specifying the column name. Note that table column names are case-sensitive and may not be abbreviated. See DATA to specify the input file (table) name. See ETYPE to specify the style of error bars and ERRORBAR for drawing them. This command is saved in the command buffer.Editcmd
Arguments: EDITCMD [macro] Edit the command buffer or macro text. The edited text may be invoked as before.Eevaluate
Arguments: EEVALUATE expression Replace the errors data vector by the result of the expression in the string argument. Typical expression syntax may be used to specify operators: +, -, *, /, **, and common functions: sqrt, sin, cos, log, log10, exp, etc. The current value of any of the four plot data vectors is specified by the single (case-insensitive) character: x, y, e, or p; the element number may be specified by r, and the number of elements in the vector by n. For example, EEVALUATE log10(r**2) will replace each error value by the log of the square of the element number. An array may operate on itself. This command is saved in the command buffer.Ellipse
Arguments: ELLIPSE eccentricity Draw an ellipse with specified eccentricity. The major axis is the current size multiplied by the default point marker size. The center of the ellipse is at the current location, and it is rotated counterclockwize from the horizontal by the current angle. If a negative value is provided for eccentricity, it will be interpreted as an ellipticity defined as 1 - b/a where a is the length of the semi-major axis, and b is the length of the semi-minor axis. The absolute value will then be converted internally to an eccentricity using e = sqrt(2*abs(eccentricity) - eccentricity^2). This command is saved in the command buffer. The results of this command may be erased with UNDO.End
no arguments End the current command mode. In normal interactive command mode, END terminates igi. END also terminates macro define mode to resume interpreting commands.Erase
no arguments Erase the entire screen. For hardcopy (printer) plots, ERASE will start a new frame (page). All of the parameters retain their values. To reset data and plot attribute parameters to defaults, use RESET. Note that it is not possible to erase only part of the screen, except to UNDO a previous command, if the hardware supports the erase line type. In the particular case of PostScript output to a file, ERASE will also create a new page. If you wish to run igi several separate times but create a single file, you must use "append=yes" for the second and subsequent plots. Use the ERASE command to create a new frame. This will not actually erase existing graphics from any non-interactive (hard copy) graphics output.Errorbar
Arguments: ERRORBAR direction Draw error bars at the positions specified by current X and Y coordinate buffers. The integer argument direction specifies the direction of the error bars:-2 -- -Y (down) -1 -- -X (left) 1 -- +X (right) 2 -- +Y (up) 3 -- -X (left) 4 -- -Y (down)
Etype
Arguments: ETYPE style Change the error bar style. The argument specifies which style to select:1 -- Standard error bars with a bar and a tick at the end 2 -- Bar only, no tick at the end 3 -- Tick only, no bar 4 -- Upper or lower limit arrow (pointing away from data coordinate)
Evaluate
Arguments: [XYEP]EVALUATE expression Replace a plot data vector by the result of the expression in the string argument. Typical expression syntax may be used to specify operators: +, -, *, /, **, and common functions: sqrt, sin, cos, log, log10, exp, etc. Note that the trig functions expect arguments in degrees! The current value of any of the four plot vectors is specified by the single character: x, y, e, or p, the element number may be specified by r, and the number of elements in the vector by n. For example, XEVALUATE log10(r**2) will replace each X value by the logarithm of the square of the element number. An array may operate on itself. [XY]EVALUATE may be used in place of [XY]LOGARITHM. This command is saved in the command buffer.Expand
Arguments: EXPAND [size] Set the marker and text size in units of the default size, 0.0125 times the smallest dimension of the device. Note that this base size is constant, regardless of the window, virtual page, or viewport. That is, characters and points will not be scaled to the size of the viewport as a fraction of the full page, but will be drawn the same size on a full page plot as on a plot in a small window. So if you wish to retain the relative size of objects on a pane of a windowed screen, you must manually reset the size using EXPAND. If no argument is specified, the current setting of the size is printed, with the resulting character and point sizes in NDC units. This command is saved in the command buffer.Fillpat
Arguments: pattern Specify the fill pattern for hollow symbols and bar graphs. The integern argument is an index for the device-dependent pattern. A value of zero indicates no fill or hollow pattern with an outline only. If no argument is specified, the current setting of the pattern index is printed. This command is saved in the command buffer.Fitpix
Arguments: FITPIX [left right bottom top] Specify the location of the viewport (plot axes) and force the shape of the viewport to be the same as the pixmap raster image input by ZSECTION. The resulting viewport will, in general, not actually span the edges specified by the command arguments. The bottom right corner is fixed, but the right or top edge will be changed to adjust the aspect ratio of the viewport to match the aspect ratio of the image as rendered on the output device. Note that this is device-dependent in the sense that different devices have different aspect ratios and the image, while having the same aspect ratio, may not occupy exactly the same location on the page. Both device and image pixels are assumed to be square. The computed viewport depends on the shape of the device, the input image, and the edges specified to FITPIX. For example,
igi> zsection myimage[1:100,1:200] # Read a "portrait" image
igi> fitpix .25 .75 .25 .75 # Use a centered, half-size display
igi> limits; zrange # Autoscale
igi> pixmap # Display
Flip
no arguments Flip an axis by reversing the upper and lower limits. The prefix to the command (X or Y) determines which axis is modified. This must be used before the axes are drawn (BOX) for the plot to scale to match the data. This is equivalent to specifying LIMITS with the lower and upper limits reversed, but operates on the currently set limits, whether set manually or automatically. [XFY]LIP should be used _after_ LIMITS. [XY]FLIP only modifies whatever is the currently set scaling. Using LIMITS after [XY]FLIP will nullify the flip by resetting the scale to whatever is specified in the LIMITS command. This command is saved in the command buffer.Fmtick
Arguments: FMTICK [format] Specify the print format for axis tick labels. The optional argument format is a string containing a Fortran or SPP print format specifier. Note that in general, axis labels are floating point values. By default, igi tries to format the labels logically, including superscripts for exponential notation on large numbers. If there is no argument, reset to the default formatting. Note that overriding the default precludes formatting using superscripts. See AXIS and BOX for drawing axes and tick labels. This command is saved in the command buffer.Fontset
Arguments: FONTSET fonts Select the set of fonts to use in drawing text. The argument is a string specifying igi or gio fonts. If no argument is specified, FONTSET shows the current font set in use. The choices for the "fonts" argument are "soft" or "igi", indicating to use the software outline (igi) fonts or "hard" or "gio" indicating to use hardware (gio) fonts. In the former case, the text will appear similar regardless of the device used to display or print the plot. In the latter case, the appearance of the fonts depends on the device. This is primarily intended to permit using PostScript fonts resident in a laser printer or used by a PostScript interpreter, which can be realized by using the PostScript graphics kernel, psikern. In both cases, the EXPAND command is used to specify the size, ANGLE the rotation, COLOR sets the hardware(kernel)-specific color, and JUSTIFY the justification. LWEIGHT may be used to change the line width used to draw igi characters, but does not effect gio characters. Embedded control characters specify further attributes of the plotted text. Note that there are different escapes for the font sets.igi gio --- --- \\ Set mode for rest of string \ Set mode for next character only \r fBR Roman plain font \g Greek (Symbol) font \s Script font \t Small sans-serif font \i Toggle italics fBI Italic roman font fBB Bold roman font Toggle proportional spacing \u Superscript \d Subscript \b Backspace \e End string User-defined PostScript font
Grid
No arguments Draw lines connecting major tick marks on the axes drawn by the BOX command. Note that BOX must have been used first to compute the tick spacing. GRID uses the current value of the line style (solid, dotted, etc.) and the line width in drawing the grid. See LTYPE to set the line type and LWEIGHT to set the line width. This command is saved in the command buffer. The results of this command may be erased with UNDO.Help
Arguments: HELP [command] Page help text. If the optional argument is present, a description of the command is listed. See "!help help" for a description of the IRAF help command. The optional argument may also be used to list any major section of the igi help text. For example, HELP description lists the general description of igi. See APROPOS for listing commands by keyword and ? for a list of the commands.Histogram
Arguments: HISTOGRAM width Draw a histogram style plot (bar graph) through the current X and Y data. If no X data exist, the horizontal axis will be scaled on the pixel numbers. Note that this command does NOT compute and plot an actual histogram of the data, but plots a bar graph style plot of the data in the plot vectors. This is an alias for the BARGRAPH command. The optional argument specifies the relative width of the bars. If no argument is used or the value is INDEF, the bars fill the available space. For equally spaced data (equally-spaced or no X values), all of the bars are as wide as the difference in X between adjacent points. For unequally spaced data, the edges of the bars fall halfway between adjacent points. The "width" argument is a constant factor to apply to this width. For example, "HISTOGRAM 0.5" will draw bars half the natural width, leaving an equal space between bars. It is not possible to apply a different factor to each bar separately, except by specifying the X data explicitly. Bars may be drawn with a fill pattern, specified using the FILLPAT command. Note that the nature of the fill patterns depends on the device and kernel used. See LTYPE and LWEIGHT for specifying the style of the curve to draw. See CONNECT, STEP, and POINTS for different curve styles This command is saved in the command buffer. The results of this command may be erased with UNDO.Id
no arguments Draw a standard identification text string vertically to the right of the right Y (vertical) axis. The label includes the user name, time, date, etc., for example:igi STScI/IRAF V2.5 LEVAY@scivax Fri 10:25:50 15-Apr-88
Imgwcs
no arguments Toggle using world coordinates of an image in the X plot buffer (see the YSECTION command). By default SECTION will not fill in the X buffer when reading the Y buffer. If the IMGWCS command is used, the next use of YSECTION will do so. Using IMGWCS again will toggle this state. Note that this command together with YSECTION will modify the contents of the plot buffer. Note that this toggles an internal parameter. Therefore if this command is used twice consecutively, it will revert to it's previous state. This command is saved in the command buffer.Input
Arguments: INPUT filename Execute commands from a file. The commands are executed as they are read. Only the INPUT command is written to the command buffer, not the individual commands. Use the READ command to input the commands into the buffer without execution. This command is saved in the command buffer.Justify
Arguments: JUSTIFY [justification] Set the justification for text drawn using the LABEL command.left center right above 7 8 9 center 4 5 6 below 1 2 3
Label
Arguments: LABEL string Draw text in the parameter string at the current position. The string is assumed to terminate at the end of the line, or may be enclosed in single or double quotes to enter more than one command on the line. The size of the text may be specified with the EXPAND command, the orientation may be set using the ANGLE command, and the justification may be specified with the JUSTIFY command. Roman, Greek, Script, and small Type fonts may be selected using the \r, \g, \s, or \t escapes. Any font may be italicized by using \i escape, and any font may be printed in fixed rather than proportional spacing by using the escape. A single backslash (\) sets the attribute for a single character only. Two backslashes (\\) sets the attribute for the remainder of the string, or until it's reset by the opposite attribute. Embedded control characters specify further attributes of the plotted text:\\ -- set mode for rest of string \ -- set mode for next character only \r -- roman font \g -- greek font \s -- script font \t -- small sans-serif font \i -- toggle italics -- toggle proportional spacing \u -- superscript \d -- subscript \b -- backspace \e -- end string
Lcolumn
Arguments: LCOLUMN column Read a column of limits data from the file specified by the data command. If the input data is a text (ASCII list) file, column must be an integer specifying the column number. If it is an ST4GEM or FITS table, column must be a string specifying the column name. Note that table column names are case-sensitive and may not be abbreviated. See DATA to specify the input file (table) name. See ULLIM for use of the limits data in drawing upper or lower limit symbols. This command is saved in the command buffer.Limits
Arguments: LIMITS [left right bottom top] Set the plot scale, i.e., the user (world) coordinates assigned to the edges of the plot (viewport). If no arguments are specified, then the limits will be set automatically based on the range of current data values. The data used to autoscale depends on which data buffers are in use. Note that in general, the current viewport is not the entire screen. The scaling set by LIMITS may be adjusted to include a border between the data extremes and the axes using the MARGIN command. See BOX for drawing axes at the current plot scale. This command is saved in the command buffer.Lines
Arguments: LINES [first[ last]] Specify the range of lines to read from the input data file using the DATA and [XYEPLS]COLUMN commands. This applies to both input text and binary tables. For example:
LINES 10 20
List
Arguments: LIST [macro] List the command buffer. The optional argument is used to list the text of a defined macro. See MACROS to list defined macro names.Location
Arguments: LOCATION [left right bottom top] Specify the location of the plot axes (viewport) as a fraction of the virtual page. The default is to fill the virtual page except for margins outside the axes for tick labels. Note that the virtual page itself may be a subset of the display area. If the first argument is INDEF, then the existing viewport will be adjusted to make it square regardless of the device. See PHYSICAL, VPAGE, and WINDOW to specify the virtual page. See FITPIX for specifying a viewport that matches an image input with ZSECTION. This command is saved in the command buffer if arguments are specified.Ltype
Arguments: LTYPE [style] Set the line style. The integer parameter selects a hardware specific line type.-1 -- Clear (erase) 0 -- Solid (default) 1 -- Dotted 2 -- Dashed 3 -- Dashed 4 -- Dot-dash 5 -- Dot-dash 6 -- Dashed
Lweight
Arguments: LWEIGHT [width] Set the line width. A floating point parameter specifies the factor to multiply the default hardware line width. Not all devices support selectable line width. This command is saved in the command buffer.Macros
no arguments Print the names of defined macros and the number of their arguments. See DEFINE to define a new macro.Margin
Arguments: MARGIN [fraction] Adjust the current plot scale to provide a border between the data extremes and the axes. The optional argument specifies the size of the margin as a fraction of the current viewport. If the argument is missing, the default margin is 0.025, or 2.5% of the size of the viewport.Minmax
no arguments Print the range of data values in both the X and Y arrays.Notation
Arguments: NOTATION xlo xhi ylo yhi Set the format for axis labels drawn by BOX. The parameters [xy]lo and [xy]hi specify the range of values within which axis label values will be written as floating point values and outside which they will be written in exponential notation. The default is [xy]lo = 1.0E-4 and [xy]hi = 1.0E+5. If xlo = xhi, all values on the X axis will be written in exponential notation, and similarly for the Y axis. This command is saved in the command buffer.Number
No arguments Draw the element number at the coordinates of each data point. If no X vector is defined, then use the element number as the X coordinate. If both an X and Y vector is defined, use those values as the X and Y coordinate. The current size, line width, rotation angle and text justification are used for the attributes of the string. This command is saved in the command buffer. The results of this command may be erased with UNDO.Pagecmd
Arguments: PAGECMD [macro] Page the command buffer, i.e., invoke the IRAF pager to list the stored commands. The optional argument is used to page the text of a defined macro.Pcolumn
Arguments: PCOLUMN column Read point specifications from the input data file (table). If the file is a text file, the column number must be an integer. If the file is an ST4GEM or FITS table, the column name must be a string. Note that table column names are case-sensitive and may not be abbreviated. See DATA to specify the input file (table) name. The floating point data values are assumed to represent a coded marker style and size for each data value. The units digit specifies the marker style by the same code as PTYPE:0 -- Open, vertices connected 1 -- Skeletal, center connected to vertices 2 -- Starred 3 -- Filled 4 -- Half-filled
Pdraw
Arguments: PDRAW xpos ypos Draw a line in the current line style from the current position to the coordinates specified by the two floating point parameters in viewport coordinates (PC). The ending point of the line becomes the new current position. If ":PDRAW" is used in cursor mode, xpos and ypos are ignored and should be omitted. See [DPV]RELOCATE (or [DPV]MOVE) to specify the initial position and see [DPV]DRAW to specify the position in other coordinates. This command is saved in the command buffer.Pevaluate
Arguments: PEVALUATE expression Replace the point marker code data vector by the result of the expression in the string argument. Typical expression syntax may be used to specify operators: +, -, *, /, **, and common functions: sqrt, sin, cos, log, log10, exp, etc. The current value of any of the four plot data vectors is specified by the single (case-insensitive) character: x, y, e, or p, the element number may be specified by r, and the number of elements in the vector by n. This command is saved in the command buffer.Physical
Arguments: PHYSICAL [left right bottom top] Set the plot location on the device in physical units (inches). This is analagous to the VPAGE command that sets the virtual page on the device. While VPAGE uses normalized device coordinates (NDC), PHYSICAL uses real device coordinates. The LOCATION command may be used to specify the viewport (location of the axes) in normalized coordinates on the virtual page. The LIMITS command defines the transformation between data, world, or user coordinates (WC) and the viewport. This command is saved in the command buffer.Pixmap
no arguments Render (display) an image if data are in the Z buffer, read using ZSECTION. The image is displayed using the current pixel scaling specified by LIMITS, the brighness scale specified by ZRANGE in the current viewport, set by FITPIX LOCATION, or PHYSICAL.Playback
no arguments Execute the commands in the command buffer. Note that any attributes (point style, size, etc.) set by the already executed commands may influence the action of the playback.Points
no arguments Draw a marker at each data coordinate according to the code read from the data file by PCOLUMN. The floating point data values are assumed to represent the marker style and size for each data value. See PTYPE for coding the marker style. The size of the markers is specified by the current size parameter and may be set using the EXPAND command. The marker may be rotated by the current angle parameter, which may be set using the ANGLE command. See the DOT command to draw a single marker at the current pen position. See the ELLIPSE command to draw a single ellipse (or circle) at the current pen position. The current pen position is left at the last point drawn. This command is saved in the command buffer. The results of this command may be erased with UNDO.Polygon
no arguments Draw a closed, fill polygon connecting the data coordinates. The COLOR command affects the color of the filled area and the FILLPAT determines the pattern used to fill the polygon. See CONNECT to draw a curve through the points. See POINTS for drawing markers without connection. The current pen position is left on the last point. This command is saved in the command buffer. The results of this command may be erased with UNDO.Pscmd
Arguments: PSCMD [PostScript command string] Insert a PostScript command string directly into the PostScript output. This command will only pass this string along if the output device will use the 'psikern' kernel for output; meanwhile, this command will not do anything for any other output device. The user has complete control over the string inserted into the PostScript and assumes all responsibility for correct syntax and usage of the PostScript command. For example, this command works well for inserting PDFMARK commands into the output PostScript files to provide Acrobat PDF functionality when converted to PDF format.Psfont
Arguments: PSFONT [font name] Set the name of the Postscript font the user wants to use in the following label(s). This font will be used when GIO fonts are specified by setting FONTSET to 'gio' or 'hard' fonts. A special escape sequence, "", signifies when this font will be used in the string and will be active for that string until reset with another escape sequence. This font can also be redefined as necessary in the IGI script to allow the use of as many fonts as needed, although only one additional font may be active at a time. Furthermore, only those fonts recognized by the printer you are sending the plot to will be output, with each printer handling unrecognizable font names differently.Ptype
Arguments: PTYPE [vertices style] Set the marker type. The integer parameter vertices specifies how many vertices are in the marker, and the parameter style selects one of the marker styles either as an integer code or a string keyword:0 open -- Polygon outline, open vertices connected 1 skeletal -- Skeletal, center connected to vertices 2 starred -- Starred, lines radiating from the center 3 solid -- Filled polygon 4 half -- Half filled polygon
Putlabel
Arguments: PUTLABEL justify string Draw text in the argument string relative to the current coordinates according to the argument justify:left center right above 7 8 9 center 4 5 6 below 1 2 3
\\ -- set mode for rest of string \ -- set mode for next character only \r -- roman font \g -- greek font \s -- script font \t -- tiny font \i -- toggle italics -- toggle proportional spacing \u -- superscript \d -- subscript \b -- backspace \e -- end string
Read
Arguments: READ filename Read commands into the command buffer without execution. Commands come from the command file specified by the filename parameter. See EDITCMD, INPUT, LIST, and PAGECMD.Relocate
Arguments: RELOCATE xpos ypos Pen up move, i.e., change the current position to the world (user) coordinates (WC) specified by the two floating point parameters. This is an alias for MOVE. If ":RELOCATE" is used in cursor mode, xpos and ypos are ignored and should be omitted. In fact, it is unnecessary to use any move command in cursor mode. Issuing any command or request for readback resets the current position to the coordinates of the cursor. See [DPV]RELOCATE to specify the position in NDC, PC and VPC. This command is saved in the command buffer.Reset
no arguments Return settable plot and data parameters to defaults.Scolumn
Arguments: SCOLUMN column Read a column of scratch data from the file specified by the data command. If the input data is a text (ASCII list) file, column must be an integer specifying the column number. If it is an ST4GEM or FITS table, column must be a string specifying the column name. Note that table column names are case-sensitive and may not be abbreviated. See DATA to specify the input file (table) name. See EVALUATE for use of the scratch data in manipulating the data buffers. This command is saved in the command buffer.Saocmap
Arguments: SAOCMAP cmapfile Apply a colormap to an image rendered using PIXMAP. The argument is the name of a plain text file containing a colormap written by SAOimage. This consists of a functional description of a mapping between stored and displayed pixel values for the three display colors: red, green, and blue, as shown in the example below.
# SAOimage color table
# saodump - SAODUMP[1/1]
# Fri Mar 13 15:53:40 1992
PSEUDOCOLOR
RED: gamma 1.504
(0.000,0.000)(0.500,1.000)(1.000,1.000)
GREEN: gamma 1.504
(0.000,0.000)(0.250,0.000)(0.750,1.000)(1.000,1.000)
BLUE: gamma 1.504
(0.000,0.000)(0.500,0.000)(1.000,1.000)
Section
Arguments: [XYEPLS]SECTION image project This family of commands reads a column of data from an IRAF (OIF, or STF) image. The image may be of any dimensionality and data type and may include an image section specification that might be a subraster of the image or may include a group number. By default, all of the image section pixels are read as a one-dimensional array into the specified igi vector. There is no capability to draw any multi-dimensional plots or gray scale images. It is not possible to extract an arbitrarily oriented vector from a multidimensional image. (See the pvector task in the plot package.) [XYEPLS]SECTION overrides the use of the DATA and [XYEPLS]COLUMN commands in filling the data arrays. One array may be filled with an image and another by a table column using DATA and [XYEPLS]COLUMN, yet another from a text file, also using DATA and [XYEPLS]COLUMN. Multi-dimensional images are read pixel by pixel, line by line, plane by plane, and so forth. For example, a 2-D image is read from left to right along each line from the bottom to the top. Optionally, a multi-dimensional section may be reduced to a single dimension by averaging or summing all of the image lines into a single vector the size of the lines in the image section. The optional argument project is an integer. For example, the command:- igi> XSECTION myimage[1:10,1:10]
- igi> XSECTION myimage 1
- igi> YSECTION myimage -2
igi> imgwcs igi> ysection dev$pix[10,50,1]
Show
no arguments Print the plot limits and attributes using the IRAF page facility.Step
no arguments Draw a stepped curve, i.e., a histogram or bar graph without vertical lines, through the current data values. This command is saved in the command buffer. The results of this command may be erased with UNDO.Ticksize
Arguments: TICKSIZE minorx majorx minory majory Set the intervals in WC for tick marks on the X and Y axes drawn by BOX. The arguments minor[xy] specify the spacing for minor (small, unlabeled) ticks; major[xy] specify the spacing for major (large, optionally labeled) ticks. If minor[xy] < 0, the axis will have logarithmic tick spacing with major ticks at each decade and minor ticks at each integer. See BOX for drawing the axes and NOTATION for specifying labels. See AXIS for drawing an arbitrary axis. This command is saved in the command buffer.Title
Arguments: TITLE text Draw text centered above the top X (horizontal) axis. The text escape characters may be used to specify different fonts, superscripts and subscripts (See LABEL). This command is saved in the command buffer. The results of this command may be erased with UNDO.Ullim
no arguments Draw a limit symbol (an arrow) to indicate upper or lower limits. The base of the arrow is drawn at the coordinates in the X and Y columns. If no X data are specified, the X coordinate is the element number. The direction of the arrow depends on the value in the limits column. Values less than zero indicate lower limits and result in an upward arrow. Values greater than zero indicate upper limits and result in an downward arrow. The current size determines the size of the arrow. See the DATA, XCOLUMN, YCOLUMN, LCOLUMN commands. See the ERRORBAR and ETYPE commands for drawing error bars and an alternate way of drawing upper or lower limit symbols. This command is saved in the command buffer. The results of this command may be erased with UNDO.Undo
no arguments Selectively erase the result of the last command that produced plotted output. This command will not restore the same figure if called again. Note that this only works if the device supports erasing vectors.Version
No arguments Show the current igi version and date of its initial installation. This information is also printed in the initial prompt when starting igi in an interactive session, in the first line of the result of the SHOW command and in the text written to the plot using the ID command. For example: "Version 3.6 13 July 1993"Vdraw
Arguments: VDRAW xpos ypos Draw a line in the current line style from the current position to the virtual page coordinates (VPC) specified by the two floaing point parameters. The ending point of the line becomes the new current position. If ":VDRAW" is used in cursor mode, xpos and ypos are ignored and should be omitted. See DRAW to draw in WC and DDRAW to draw in NDC. This command is saved in the command buffer.Vmove
Arguments: VMOVE xpos ypos Pen up move, i.e., change the current position to the virtual page coordinates (VPC) specified by the two floating point parameters. This is an alias for VRELOCATE. If ":VMOVE" is used in cursor mode, xpos and ypos are ignored and should be omitted. In fact, it is unnecessary to use any move command in cursor mode. Issuing any command or request for readback resets the current position to the coordinates of the cursor. See VDRAW to draw in VPC, MOVE to move in WC, and DMOVE to move in NDC. This command is saved in the command buffer.Vpage
Arguments: VPAGE [left right bottom top] Specify the edges of the virtual page on the plotting area of the device as a fraction of the width and height. For example, to use only the upper left corner of the frame, use VPAGE 0.5 1.0 0.5 1.0. The default is the entire plot area. This does not change the relative location of the axes on this page (see LOCATION). See PHYSICAL to specify the page in device coordinates (inches). This command is saved in the command buffer.Vrelocate
Arguments: VRELOCATE xpos ypos Pen up move, i.e., change the current position to the virtual page coordinates (VPC) specified by the two floating point parameters. If ":VRELOCATE" is used in cursor mode, xpos and ypos are ignored and should be omitted. In fact, it is unnecessary to use any move command in cursor mode. Issuing any command or request for readback resets the current position to the coordinates of the cursor. See VDRAW to draw in VPC, RELOCATE to move in WC, and DRELOCATE to move in NDC. This command is saved in the command buffer.Wcslab
Arguments: WCSLAB [edit] Label the currently specified viewport with WCS, including equatorial (celestial) coordinates as with the ST4GEM stplot.wcslab task. The optional command argument is a string that begins with "e" or "E". This allows editing wlpars parameter set for specifying attributes via eparam. If the ZSECTION command was used to read an image section into the Z buffer, then the WCS attributes of that image are used in labeling the plot. Otherwise, the WCS is taken from parameters in the wcspars pset. Note that the psets may be edited before entering igi by explicitly assigning parameter values or by using eparam at the cl prompt. In addition, the parameter values may be assigned or the psets edited from igi using the "!" escape before using the WCSLAB command. WARNING: Some of the attributes specified in the wlpars pset conflict with attributes set using igi commands, such as text size and color. Currently, the wlpars parmaeters take precedence over any igi attributes.Window
Arguments: WINDOW [nx ny] [pane] Divide the device plotting area into nx by ny windows (tiles or panes) and select the pane in which to plot, numbered left to right, bottom to top. For example, WINDOW 3 3 3 will create nine panes and select the bottom right pane for subsequent plotting. If only two arguments are given, the current pane number is selected, but with a different division. If only one argument is given, a different pane is selected in the same tiling. WINDOW is an alternative to PHYSICAL or VPAGE to specify the virtual page on the device. This command is saved in the command buffer.Write
Arguments: WRITE filename Write the command buffer to the file specified by the filename parameter.Xcolumn
Arguments: XCOLUMN column Read X coordinate data from the specified column in the current input data file. If the file is a text file, the column number must be an integer. If no X data are specified, the Y data are plotted against row number. If the file is an ST4GEM or FITS table, the column name must be a string. Note that table column names are case-sensitive and may not be abbreviated. See DATA to specify the input file (table) name. This command is saved in the command buffer.Xevaluate
Arguments: XEVALUATE expression Replace the X plot data vector by the result of the expression in the string argument. Typical expression syntax may be used to specify operators: +, -, *, /, **, and common functions: sqrt, sin, cos, log, log10, exp, etc. The current value of any of the four plot vectors is specified by the single character: x, y, e, or p, the element number may be specified by r, and the number of elements in the vector by n. For example, XEVALUATE log10(r**2) will replace each X value by the logarithm of the square of the element number. The X array may operate on itself. This command is saved in the command buffer.Xflip
no arguments Flip the X axis. That is, plot horizontal data and axis labels increasing right to left instead of the default left to right. This must be used before the axes are drawn (BOX) for the plot to scale to match the data. This is equivalent to specifying LIMITS with the lower and upper X limits reversed, but operates on the currently set limits, whether set manually or automatically. XFLIP should be used _after_ LIMITS. XFLIP only modifies whatever is the currently set scaling. Using LIMITS after XFLIP will nullify the flip by resetting the scale to whatever is specified in the LIMITS command. This command is saved in the command buffer.Xlabel
Arguments: XLABEL [text] Draw text centered below the bottom X (horizontal) axis. The text escape characters may be used to specify different fonts, superscripts and subscripts (See LABEL). If the optional argument is missing, igi uses an internal string. This is filled by the DATA and XCOLUMN commands. If the DATA command specifies a binary ST4GEM table, then the XCOLUMN command appends the column name to the string. Note that the label may not appear if the edge of the viewport (the axes) falls too close to the edge of the (virtual) page. Use LOCATION to change the placement of the viewport. This command is saved in the command buffer. The results of this command may be erased with UNDO.Xlogarithm
no arguments Take the common logarithm of the X data values. If any value is less than or equal to zero, the result is made INDEF, causing that point to be ignored in scaling and plotting. See XEVALUATE for an alternate way of doing this. You must use [XY]LOGARITHM for ERROBAR to work correctly on log data. This command is saved in the command buffer.Xsection
Arguments: XSECTION image project Read an IRAF (OIF, or STF) image as the X column values. The image may be of any dimensionality and data type. The image name may include an image section specification that might be a subraster of the image or may include a group number. By default, all of the image section pixels are read as a one-dimensional array into the specified igi vector. There is no capability to draw any multi-dimensional plots or gray scale images. XSECTION overrides the use of the DATA and XCOLUMN commands in filling the X data array. One array may be filled with an image and another by a table column using DATA and [XYEPLS]COLUMN, yet another from a text file, also using DATA and [XYEPLS]COLUMN. By default, multi-dimensional data are read pixel by pixel, line by line, plane by plane, and so forth. For example, a 2-D image is read from left to right along each line from the bottom to the top. Optionally, a multi-dimensional section may be reduced to a single dimension by averaging or summing all of the image lines into a single vector the size of the lines in the image section. The second, optional argument to the XSECTION command is an integer which indicates that the section should be summed or averaged along an image axis. The absolute value specifies along which axis to collapse the section. Positive integers cause vectors to be averaged, negative integers cause successive vectors to be added. For example, the command:- igi> XSECTION myimage[1:10,1:10]
- igi> XSECTION myimage 1
- igi> XSECTION myimage -2
Ycolumn
Arguments: YCOLUMN column Read Y coordinate data from the specified column in the current input data file. If the file is a text file, the column number must be an integer. If the file is an ST4GEM or FITS table, the column name must be a string. Note that table column names are case-sensitive and may not be abbreviated. If no X data are specified, the Y data are plotted against row number. See DATA to specify the input file (table) name. This command is saved in the command buffer.Yevaluate
Arguments: YEVALUATE expression Replace the Y data vector by the result of the expression in the string argument. Typical expression syntax may be used to specify operators: +, -, *, /, **, and common functions: sqrt, sin, cos, log, log10, exp, etc. The current value of any of the four plot data vectors is specified by the single (case-insensitive) character: x, y, e, or p, the element number may be specified by r, and the number of elements in the vector by n. For example, YEVALUATE log10(r**2) will replace each Y value by the log of the square of the element number. An array may operate on itself. This command is saved in the command buffer.Yflip
no arguments Flip the Y axis. That is, plot vertical data and axis labels increasing top to bottom instead of the default bottom to top. This must be used before the axes are drawn (BOX) for the plot to scale correctly. This is equivalent to specifying LIMITS with the lower and upper Y limits reversed, but operates on the currently set limits, whether set manually or automatically. YFLIP should be used _after_ LIMITS. YFLIP only modifies whatever is the currently set scaling. Using LIMITS after YFLIP will nullify the flip by resetting the scale to whatever is specified in the LIMITS command. This command is saved in the command buffer.Ylabel
Arguments: YLABEL [text] Draw text centered left of the left Y (vertical) axis. The text escape characters may be used to specify different fonts, superscripts and subscripts (See LABEL). If the optional argument is missing, igi uses an internal string. This is filled by the DATA and YCOLUMN commands. If the DATA command specifies a binary ST4GEM table, then the YCOLUMN command appends the column name to the string. This command is saved in the command buffer.Ylogarithm
no arguments Take the common logarithm of the Y data values. If any value is less than or equal to zero, the result is made INDEF, causing that point to be ignored in scaling and plotting. See YEVALUATE for an alternate way of doing this. You must use [XY]LOGARITHM for ERROBAR to work correctly on log data. This command is saved in the command buffer.Ysection
Arguments: YSECTION image project Read an IRAF (OIF, or STF) image as the Y column values. The image may be of any dimensionality and data type. The image name may include an image section specification that might be a subraster of the image or may include a group number. By default, all of the image section pixels are read as a one-dimensional array into the specified igi vector. There is no capability to draw any multi-dimensional plots or gray scale images. YSECTION overrides the use of the DATA and YCOLUMN commands in filling the Y data array. One array may be filled with an image and another by a table column using DATA and [XYEPLS]COLUMN, yet another from a text file, also using DATA and [XYEPLS]COLUMN. By default, multi-dimensional data are read pixel by pixel, line by line, plane by plane, and so forth. For example, a 2-D image is read from left to right along each line from the bottom to the top. Optionally, a multi-dimensional section may be reduced to a single dimension by averaging or summing all of the image lines into a single vector the size of the lines in the image section. The second, optional argument to the YSECTION command is an integer which indicates that the section should be summed or averaged along an image axis. The absolute value specifies along which axis to collapse the section. Positive integers cause vectors to be averaged, negative integers cause successive vectors to be added. For example, the command:- igi> YSECTION myimage[1:10,1:10]
- igi> YSECTION myimage 1
- igi> YSECTION myimage -2
igi> imgwcs igi> ysection dev$pix[10,50,1]
Zevaluate
Arguments: ZEVALUATE expression Replace the Z data (raster) buffer by the result of the expression in the string argument. Typical expression syntax may be used to specify operators: +, -, *, /, **, and common functions: sqrt, sin, cos, log, log10, exp, etc. The current value of any of the four plot data vectors is specified by the single (case-insensitive) character: x, y, z, e, or p, the element number may be specified by r, and the number of elements in the vector by n. For example, ZEVALUATE log10(z) will replace each Z value by the log of the square of the original value. This command is saved in the command buffer.Zrange
Arguments: ZRANGE [min max] Specify the minimum and maximum image pixel values that map to the darkest and brightest display values. Using no arguments indicates to use the range of values in the image data. In fact, min may be greater than max, which will result in the lower-valued pixels rendered brighter than the higher-valued pixel -- a negative image.Zsection
Arguments: ZSECTION section Read an image section (one- or two-dimensional) into the Z buffer.Bugs
[XYEPLS]EVALUATE does not recognize INDEF values and therefore either will crash, or the evaluated column will contain strange values. Not all errors are trapped. For example, using "!" to execute a cl command resulting in an error condition will cause igi to abort. An extra prompt is printed after a macro is defined (DEFINE) in cursor mode (CURSES) and after UNDO. UNDO does not erase lines drawn by [ DV]DRAW. Error bars are not drawn correctly if [XY]EVALUATE is used to take the logarithm of the data. Macros are limited to a relatively small number of commands (something like a dozen or so in practice) because of an inherent internal buffer size limit.Examples
The examples fall in two groups. The first simply shows different ways to run the task, interactively or by using input command files and some device options. This is analagous to the usual IRAF/ST4GEM tasks. The larger section shows some specific examples of using igi commands to build plots and manage the interaction. These are examples of the unique igi "mini-language."- Running the task
- There is potentially an infinite number of possible examples of command
interaction and plotting, of course. The following attempts to offer
some common, simple examples of basic plots and demonstrations of some
of the unique capabilities of igi. These may be used as templates on
which to begin building more complete, useful and complex graphics.
1. Start the interpreter, reading commands from STDIN and displaying
graphics output on the standard graphics device:
- pl> igi
- pl> igi < cmd.igi dev=stdplot
- pl> igi >G igi.vdm device=pericom
pl> igi < cmd.igi pl> newcont image append+ pl> newcont image pl> igi < cmd.igi append+
- Command Interaction
- The following are examples of igi interactions. That is, the commands typed interactively after starting up the igi task. The prompt ("
igi> data igi.dat igi> xcolumn 1; ycolumn 2 igi> limits igi> box; connect
igi> data igi.dat igi> xcolumn 1; ycolumn 2 igi> xlogarithm; ylogarithm igi> limits igi> ticksize -1 0 -1 0 igi> box; connect
igi> data table; ycolumn ycol igi> limits; box; connect
igi> data table.fits[1] igi> xcolumn wavelength 3; ycolumn flux igi> limits; box; connect
igi> data table.fits[1][r:sporder=10:12] igi> xcolumn wavelength 1; ycolumn flux igi> limits; box; connect igi> xcolumn wavelength 2; ycolumn flux; ltype 1; connect igi> xcolumn wavlength 3; ycolumn flux; ltype 2; connect igi> ltype 0
igi> define simple macro> data &1 macro> xcolumn &2; ycolumn &3 macro> limits; box; connect macro> end igi> simple igi.dat 1 2 igi> erase igi> simple igi.dat 3 4
igi> expand 2; angle 90; justify 5 igi> fontset igi igi> label \\iWavelength (\gVngstroms)
igi> data tdat igi> ycolumn 2 igi> ecolumn 3 igi> limits igi> etype 1 igi> errorbar 2 igi> errorbar -2
igi> window 2 1 1 igi> limits; box; connect igi> window 2 igi> yevaluate log10(y) igi> limits; box; connect
igi> xsection specim[*,1] igi> ysection specim[*,2] igi> limits igi> box igi> connect
igi> xlabel igi> ylabel
igi> imgwcs igi> ysection spect
12. The following is an example of an igi command file it includes some comments describing what's going on. Note that the data are totally fabricated random numbers and bear no intentional resemlance to any real observations or theory. After the commands listing is the data file used as input. This text could be saved to two text files and used as input to igi.
# Read data from the first 10 lines of file rand.dat data rand.dat; lines 1 10 # Read column 3 into the Y buffer and operate on it ycol 3; yevaluate y/(r+10) # Scale the plot with a 4% margin limits; margin 0.04 # Draw data points expand 0.5; ptype 4 3; points # Read errors from column 3 ecol 3 eev sqrt(y)/5 etype 1; errorbar 2; errorbar -2 # Read the first 20 lines of column 2 into the Y buffer lines 1 20; ycol 2 yevaluate 1/(r+10) limits; margin 0.04 connect # Rescale and draw the axes limits 1 50 -1 4; margin 0.04 ticksize 1 10 -1 0; notation 1e-4 1e5 2e-3 2e2 expand 1.2; box ltype 1; grid # Draw the labels, note the embedded text formatting escapes xlabel "\\iSample Number" ylabel "\gx [\\i\gms \gV\\u-1\\d\\i]" title "\\iObserved versus Theoretical Bogus Data"
urand 20 5 > rand.dat
WINDOW 2 2 1
ZSECTION "dev$pix[*:5,*:5]"
FITPIX .25 .9 .15 .9
LIMITS; margin; ZRANGE 80 250
PIXMAP
ticksize 5 20 5 20
BOX
title "Aspect Preserved"
WINDOW 2; LOCATION .1 .9 .15 .9
ZRANGE 250 80
PIXMAP
# Line indicating 1-D cut
move 0.5 41; draw 103.5 41
# Draw a border only
limits 0 1 0 1
move 0 0; draw 1 0; draw 1 1; draw 0 1; draw 0 0
move .5 1.075; putlabel 2 "Filled Viewport, Negative Map"
# Widened 1-D section
WINDOW 3; LOCATION .1 .9 .2 .75
ZSECTION "dev$pix[*:5,200]"
LIMITS; ZRANGE; margin
ticksize 2 10 10 10
BOX 1 0
title "1-D Image Section"
PIXMAP
# Line plot of 1-D cut
WINDOW 4; LOCATION .1 .9 .1 .85
YSECTION "dev$pix[*:5,200]"
LIMITS; margin
ticksize 5 20 20 100
BOX
CONNECT
- Buffer Size modification
- The following example shows how to modify the pushback buffer when a
macro is too large for the default buffer size.
cl> show igi_buflen 0 cl> igi < large_macro.igi ERROR: Pushback buffer overflow (recursive macro?) (STDIN) cl> set igi_buflen=10000 cl> flprc cl> igi < large_macro.igi ...igi successfully runs