| igi | stsdas.graphics.stplot | igi |
igi -- Interactive Graphics Interpreter
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 STSDAS tables, new commands such as [XY]FLIP, [XYEPLS]EVALUATE, [XYEPLS]SECTION, VPAGE, and EDITCMD, and enhancements to MONGO commands such as CURSES.
st> igi <mycmd
When the graphics device is the user's terminal, command interaction (user input and single-line information and error messages) takes place in the status line (normally, a single scrolling line at the bottom of the screen). Output consisting of more than one line, e.g., paging the command buffer, is directed to the text window. The "igi> " prompt in the status line indicates that igi is ready to interpret a command.
Commands names are minimum-matched, that is, they may be abbreviated to the extent that the command name is unique. Commands are case-insensitive, i.e., they may be typed in upper or lower case; however, note that cl syntax, e.g., filenames and escaped cl commands, is case-sensitive. Also, single-character cursor mode keystrokes and IRAF native cursor mode (e.g., ":.") commands are case-sensitive.
Commands may be followed by positional arguments, separated from the command name and each other by white space (spaces or tabs) or a comma. Extra white space at the beginning of a command line or between arguments is ignored. Blank lines and commands beginning with the IRAF comment character "#" are ignored. More than one command may be entered on a single line; if you intend to do this, then a command and its arguments should be separated from the next command by a ";".
In this text, igi commands are always written in upper case. Macro names are represented in lower case. Command arguments are written in lower case and optional arguments are enclosed in square brackets.
Many commands belong to a family of commands. That is they are the same in syntax and semantics but operate on a specific instance of some category. For example, the DRAW command is really three commands: DRAW, DDRAW, VDRAW. They all draw a line, but operate in different coordinate systems. Another example is the COLUMN command that reads data into a plot buffer. This comprises six commands: XCOLUMN, YCOLUMN, ECOLUMN, PCOLUMN, LCOLUMN, and SCOLUMN, each filling a different plot vector buffer. These families of commands are usually. represented in this text by the prefix characters shown together in square brackets followed by the family name, [XYEPLS]COLUMN, for example.
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.
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
Images of any data type may be read. INDEF values will be ignored except when projecting a multi-dimensional image section.
Data present in the plot buffers may be modified using the [XYEPLS]EVALUATE or [XY]LOGARITHM commands. Note that INDEF values operated on in this way may cause igi to crash since they are not recognized as INDEF by the expression evaluator but treated as normal data values.
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
The plot scale is determined by the user coordinates associated with the viewport and the size of the viewport on the page. The LIMITS command. This command associates WC (user coordinate) values with each edge of the viewport and thus defines the transformation between the user and device coordinates. The LIMITS command may be used to explicitly specify the coordinate scale, or to autoscale based on the current X and Y plot vector data values. In the latter case, the edges of the world coordinates will be at the minimum and maximum data value of the X and Y arrays and therefore one or more plotted data points will fall on an axis.
To add a border between the plotted curve or points and the axes, either explicitly specify the edges of the user coordinates with the LIMITS command, or use the MARGIN command to automatically include an equal border between the edges of the data and the axes. The default margin is 2.5% the width of the viewport (axis). However, the MARGIN command has an optional argument to specify the border as a fraction of the size of the viewport.
It is possible to use world coordinates from an input image as the X values that correspond to Y values input from the image. This can be done with the YSECTION command if the appropriate parameters exist in the image header. By default, these coordinates will not be used and you must supply the appropriate independent variable as the X values. However, if you use the IMGWCS command and the image contains the appropriate transformation parameters, then YSECTION will automatically fill in the X plot buffer with the coordinate values.
Note that in general this works only for inherently one-dimensional data, e.g., spectra. For 2-D data such as images, coordinates are rather meaningless for an arbitrary 1-D section of the image. You will get an "identity" vector if the coordinate parameters are not present in the image. That is, the X values will be the element number of the extracted pixels. This is not exactly the same result as not using the WCS, since the coordinate transformation is applied to the image section. That is, the returned coordinates are the coordinates with respect to the original full image, not the extracted piece. For example, if you use:
igi> imgwcs igi> ysection dev$pix[10,50,1]
the range of the X values will be 10 to 50 rather than 1 to 41 if you do not use IMGWCS and do not otherwise fill in the X vector. Even if the image does not contain a WCS transformation, YSECTION will provide an X vector that corresponds to the pixel numbers in the full input image.
The commands requiring a plot position (move and draw) have versions for each of the coordinate systems:
WC VPC PC NDC
Move RELOCATE VRELOCATE PRELOCATE DRELOCATE
MOVE VMOVE PMOVE DMOVE
Draw DRAW VDRAW PDRAW DDRAW
The current X and Y (logical pen) position is maintained in user (world) coordinates. Several commands change this position and others depend on its value.
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.
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
The size of a macro is limited by the size of the "pushback" buffer used to expand macros before execution. The IRAF system default for the pushback buffer allows only for 512 characters. For igi, the size can be modified using the cl environmental variable "igi_buflen". One can use the command
set igi_buflen = XXXXX
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:
ERROR: Pushback buffer overflow (recursive macro?) (STDIN)
occurs.
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.
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.
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.
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.
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.
Installed a modified version of SECTION provided by Frank Valdes (NOAO) to implement recognition of multispec format images (spectra) with IMGWCS enabled.
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.
Modified FILLPAT to print the current pattern style if there's no argument.
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).
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.
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.
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.
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.
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.
! Escape a command to the cl !cl Spawn a cl process (bye ==> return to igi) !! Escape a command to the host !!! Spawn a host (VMS) process (logout ==> return to igi) ? Page the help summary ^ Re-execute a previous command ANGLE Set the marker and text rotation angle APROPOS List commands associated with a keyword AXIS Draw and label an arbitrary axis BARGRAPH Draw a bar graph (histogram-style plot) BOX Draw and label the axes BYE Terminate igi (alias for END) COLOR Set (hardware-dependent) color index CONNECT Draw a (polyline) curve connecting the data coordinates CURSES Read back cursor position (IRAF cursor mode) DATA Specify the input text data file DDRAW Pen down move (draw) in NDC DLIST Print the data values DMOVE Pen up move in NDC (alias for DRELOCATE) DOT Draw a single marker DRAW Pen down move (draw) in WC DRELOCATE Pen up move in NDC ECOLUMN Read errors from a column of the text data file EDITCMD Edit the command buffer or macro text EEVALUATE Operate on error values ELLIPSE Draw an ellipse END Exit igi or terminate macro define (end the current mode) ERASE Erase the screen ERRORBAR Draw error bars ETYPE Change the error bar style EXPAND Set the marker and text size FILLPAT Specify the fill pattern for hollow symbols and bar graphs FITPIX Specify a viewport to match shape of image raster FMTICK Specify the axis tick label format FONTSET Select igi or gio font set GRID Draw lines between major axis ticks HELP Print help HISTOGRAM Draw a histogram-style plot (bar graph) ID Write identification label IMGWCS Toggle using image WCS for X values INPUT Execute commands from a file JUSTIFY Set text justification LABEL Draw text at current position LIMITS Set the plot scale LINES Specify the range of input rows to read LIST List the command buffer or macro text LOCATION Set the viewport on the virtual page LTYPE Set the line style (hardware dependent) LWEIGHT Set the line width (hardware dependent) MACROS List defined macros MARGIN Rescale to include a border between curve and axes MENU Page the help summary MINMAX Print the data range MOVE Pen up move in WC (alias for RELOCATE) NOTATION Set the format for axis labels NUMBER Write the element number at each data coordinate PAGECMD Page the command buffer or macro text PCOLUMN Read point specifications from the input data file PDRAW Pen down move (draw) in viewport coordinates (PC) PEVALUATE Operate on point code values PHYSICAL Set the virtual page in physical device coordinates PIXMAP Render (display) a pixmap raster image PLAYBACK Execute the commands in the command buffer PMOVE Pen up move in PC (alias for PRELOCATE) POINTS Draw a polymarker at input data coordinates POLYGON Draw a closed polygon using the data coordinates PRELOCATE Pen up move in PC (alias for PMOVE) PSCMD Insert a user-specified PostScript command into the PostScript file PSFONT Specify a user-defined PostScript font PTYPE Specify the point marker type PUTLABEL Draw a label with a specified justification READ Read commands into the command buffer without execution RELOCATE Pen up move in WC RESET Return settable plot and data parameters to defaults SAOCMAP Apply a colormap in SAOimage format to a rendered image SECTION Read an image section for a plot buffer SHOW Page the plot limits and attributes STEP Draw a stepped curve (histogram without vertical lines) TICKSIZE Set the axis tick spacing TITLE Specify the plot title ULLIM Draw upper or lower limit symbols UNDO Selectively erase the last plot command VDRAW Pen down move (draw) in VPC VERSION Show igi version and date VMOVE Pen up move in VPC (alias for VRELOCATE) VPAGE Set the virtual page in normalized coordinates VRELOCATE Pen up move in VPC WCSLAB Label the viewport in WCS coordinates WINDOW Divide screen into panes WRITE Write the command buffer to a file XCOLUMN Read X coordinates from a column of the data file XEVALUATE Operate on X data values XFLIP Flip X axis XLABEL Specify the X axis label XLOGARITHM Take common log of X data XSECTION Read X coordinates from an image section YCOLUMN Read Y coordinates from a column of the data file YEVALUATE Operate on Y data values YFLIP Flip Y axis YLABEL Specify the Y axis label YLOGARITHM Take common log of Y data YSECTION Read Y coordinates from an image section ZEVALUATE Operate on Z data values ZRANGE Specify range of pixel values to map to display range ZSECTION Read image section as a pixmap raster
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 PAGECMD
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.
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
See ? for the command summary and HELP for the full help text.
Arguments: AXIS w1 w2 minor major x y len label clock
w1 -- 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
Draw an arbitrary axis scaled from w1 to w2 in data coordinates (WCS) starting at (x,y) and length len in virtual page coordinates (VPC). If major > 0, use that for the spacing of major ticks. If minor < 0, draw a logarithmic axis; if minor > 0, try to use that for the spacing of minor ticks; if minor = 0, let igi decide where to put minor ticks. If label = 0, don't draw labels; if label = 1, draw labels parallel to the axis; if label = 2, draw labels perpendicular to the axis. If clock = 1 draw ticks clockwise with respect to the axis, counterclockwise if clock = 0.
The current angle specifies the position angle of the axis with respect to horizontal (see ANGLE). 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).
See BOX for drawing default axes at the current plot scale.
This command is saved in the command buffer. The results of this command may be erased with UNDO.
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.
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.
no arguments
Terminate igi. This is an alias for END, except in macro define mode (see DEFINE).
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.)
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 STSDAS 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.
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.
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.
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 STSDAS 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.
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.
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.
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.
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.
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.
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.
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 STSDAS 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.
Arguments: EDITCMD [macro]
Edit the command buffer or macro text. The edited text may be invoked as before.
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.
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.
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.
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.
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)
ERRORBAR must be used twice to draw a full error bar spanning the data coordinate. For symmetrical errors, use the same data column and change the direction argument. For asymmetrical errors, read new data into the errors buffer and respecify the direction arguement.
The current text and point size determines the size of the ticks at the end of each error bar; use EXPAND to change the size. Change the default error bar style with ETYPE.
See DATA and ECOLUMN to read error data and EEVALUATE to operate on them.
This command is saved in the command buffer. The results of this command may be erased with UNDO.
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)
See the ERRORBAR command for drawing the error bars. See the ULLIM command for another way to draw upper or lower limit symbols.
This command is saved in the command buffer.
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.
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.
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.
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 # Displayon a "landscape" format device would result in a viewport that was narrower than the one specified.
The arguments specify the edges of the viewport as a fraction of the virtual page. If FITPIX is used with no arguments, the edges of the current viewport are listed. If FITPIX is not used, the default is to fill the viewport, which in general matches the virtual page, except for margins outside the axes for tick labels. This is useful to smear (widen) a narrow image section, such as a spectrum, to cover the viewport. LOCATION or PHYSICAL may be used to specify a viewport in this case. If the first (only) argument is INDEF, then FITPIX will use the currently specified viewport but adjust the top right corner to match the aspect ratio of the input image.
Note that the virtual page itself may be a subset of the display area. See PHYSICAL, VPAGE, and WINDOW to specify the virtual page.
This command is saved in the command buffer.
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.
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.
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 \f\fB\fRR Roman plain font
\g \fG Greek (Symbol) font
\s Script font
\t Small sans-serif font
\i Toggle italics
\f\fB\fRI Italic roman font
\f\fB\fRB Bold roman font
\f Toggle proportional spacing
\u Superscript
\d Subscript
\b Backspace
\e End string
\fP User-defined PostScript font
Italics (\\i) and proportional spacing (\ behave as toggles for igi fonts, enclosing a (sub)string in matching escapes sets the attribute for that string only. Superscript and subscript each ondoes the action of the other, to write a substring as a super(sub)script, enclose it in matching pairs of \\u...\\d or \\d...\\u.
The User-defined PostScript font is set using the PSFONT command prior to using this escape sequence. This font will then be active for remainder of the string or until another font is selected, like the Roman font with the escape sequence.
This command is saved in the command buffer.
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.
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.
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.
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
This command is saved in the command buffer. The results of this command may be erased with UNDO.
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.
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.
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
This command is saved in the command buffer.
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 \f -- toggle proportional spacing \u -- superscript \d -- subscript \b -- backspace \e -- end string
Italics (\\i) and proportional spacing (\ behave as toggles, enclosing a (sub)string in matching escapes sets the attribute for that string only. Superscript and subscript each ondoes the action of the other, to write a substring as a super(sub)script, enclose it in matching pairs of \\u...\\d or \\d...\\u. Note that these are the igi text escapes. When using gio fonts (see FONTSET) a different set of escapes applies.
This command is saved in the command buffer. The results of this command may be erased with UNDO.
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 STSDAS 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.
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.
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 20will cause lines 10 through 20 to be read using the next COLUMN command.
If no parameters are specified, then the current range will be listed. Specifying first = 0 is the same as first = 1; last = 0 will read to the last row in the input file. Specifying one argument will read only that one line. Therefore, to return the range of lines to the default (read all lines in the file) use "LINES 0".
This command does not have any effect on reading image sections (See SECTION).
This command is saved in the command buffer.
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.
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.
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
If no parameter is given, the current setting is listed. The default is solid.
This command is saved in the command buffer.
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.
no arguments
Print the names of defined macros and the number of their arguments. See DEFINE to define a new macro.
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.
no arguments
Print the range of data values in both the X and Y arrays.
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.
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.
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.
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 STSDAS 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
Any value larger than 4 is read as 4 (half-filled symbols).
The tens and up digits specify the number of vertices in the marker, and the decimal portion represents a multiplier for the global text and marker size. The global text and marker angle determines the angle of all point markers. For example, if the value in the points column were 52.5 the marker would be a five pointed star half the size of the current marker and text size. If no decimal value is present, the marker size is the global text and marker size.
This command is saved in the command buffer.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
Any value larger than 4 is read as 4 (half-filled symbol type). Alternately, the style may be specified as a string with the
If the number of vertices is -1, 0, or 1, then DOT or POINTS draws the smallest plottable point. If the number of vertices is less than -1, PTYPE ignores the style DOT or POINTS draws markers defined by the IRAF marker drawing routine as described in the GIO reference manual.
To draw a circle, use a large number of vertices, 25, e.g. To draw small points, use a small size, EXPAND .1, e.g. See the POINTS command to draw markers at the data coordinates, the DOT command to draw a single marker at the current pen position.
This command is saved in the command buffer.
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
The size of the text may be specified with the EXPAND command and the angle may be set using the ANGLE command.
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 -- tiny font \i -- toggle italics \f -- toggle proportional spacing \u -- superscript \d -- subscript \b -- backspace \e -- end string
Also see the LABEL command.
This command is saved in the command buffer. The results of this command may be erased with UNDO.
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.
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.
no arguments
Return settable plot and data parameters to defaults.
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 STSDAS 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.
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)Note that the colors displaying correctly depends on the graphics kernel and the output device. Only the PostScript kernel (psikern) supports this feature.
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:
will read 100 pixels from the lower left corner of myimage into the X buffer. The command:
will read read all of the pixels but will store the average of all of the image lines in the X buffer.
will add the columns of myimage and store the result in the Y plot buffer.
[XY]SECTION saves the input file name string with the section specification in the X or Y axis label buffer. This may be used with the [XY]LABEL command with no arguments to label the X or Y axis with the section.
It is possible to use world coordinates from the input image as the X values corresponding to Y values read using YSECTION if the appropriate parameters exist in the image header. By default, these coordinates will not be used and you must supply the appropriate independent variable as the X values. However, if you use the IMGWCS command and the image contains the appropriate transformation parameters, then YSECTION will automatically fill in the X plot buffer with the coordinate values.
Note that in general this works only for inherently one-dimensional data, e.g., spectra. For 2-D data such as images, coordinates are rather meaningless for an arbitrary 1-D section of the image. You will get an "identity" vector if the coordinate parameters are not present in the image. That is, the X values will be the element number of the extracted pixels. This is not exactly the same result as not using the WCS, since the coordinate transformation is applied to the image section. That is, the returned coordinates are the coordinates with respect to the original full image, not the extracted piece. For example, if you use:
igi> imgwcs igi> ysection dev$pix[10,50,1]
the range of the X values will be 10 to 50 rather than 1 to 41 if you do not use IMGWCS and do not otherwise fill in the X vector. Even if the image does not contain a WCS transformation, YSECTION will provide an X vector that corresponds to the pixel numbers in the full input image.
WARNING: This command, if used with IMGWCS, will modify the contents of the X plot buffer (see above).
This command is saved in the command buffer.
no arguments
Print the plot limits and attributes using the IRAF page facility.
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.
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.
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.
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.
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.
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"
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.
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.
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.
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.
Arguments: WCSLAB [edit]
Label the currently specified viewport with WCS, including equatorial (celestial) coordinates as with the STSDAS 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.
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.
Arguments: WRITE filename
Write the command buffer to the file specified by the filename parameter.
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 STSDAS 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.
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.
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.
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 STSDAS 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.
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.
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:
will read 100 pixels from the lower left corner of myimage into the X buffer. The command:
will read read all of the pixels but will store the average of all of the image lines in the X buffer.
will read read all of the pixels but will store the sum of all of the image columns in the X buffer.
XSECTION saves the input file name string with the section specification in the X axis label buffer. This may be used with the XLABEL command with no arguments to label the X axis with the section.
This command is saved in the command buffer.
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 STSDAS 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.
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.
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.
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 STSDAS table, then the YCOLUMN command appends the column name to the string.
This command is saved in the command buffer.
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.
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:
will read 100 pixels from the lower left corner of myimage into the Y buffer. The command:
will read read all of the pixels but will store the average of all of the image lines in the Y buffer.
will read read all of the pixels but will store the sum of all of the image columns in the Y buffer.
YSECTION saves the input file name string with the section specification in the Y axis label buffer. This may be used with the YLABEL command with no arguments to label the Y axis with the section.
It is possible to use world coordinates from the input image as the X values corresponding to Y values read using YSECTION if the appropriate parameters exist in the image header. By default, these coordinates will not be used and you must supply the appropriate independent variable as the X values. However, if you use the IMGWCS command and the image contains the appropriate transformation parameters, then YSECTION will automatically fill in the X plot buffer with the coordinate values.
Note that in general this works only for inherently one-dimensional data, e.g., spectra. For 2-D data such as images, coordinates are rather meaningless for an arbitrary 1-D section of the image. You will get an "identity" vector if the coordinate parameters are not present in the image. That is, the X values will be the element number of the extracted pixels. This is not exactly the same result as not using the WCS, since the coordinate transformation is applied to the image section. That is, the returned coordinates are the coordinates with respect to the original full image, not the extracted piece. For example, if you use:
igi> imgwcs igi> ysection dev$pix[10,50,1]
WARNING: This command, if used with IMGWCS, will modify the contents of the X plot buffer (see above).
This command is saved in the command buffer.
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.
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.
Arguments: ZSECTION section
Read an image section (one- or two-dimensional) into the Z buffer.
[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.
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/STSDAS 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."
1. Start the interpreter, reading commands from STDIN and displaying graphics output on the standard graphics device:
2. Interpret the commands in the file cmd.igi and direct the output to a hardcopy device:
In this case, there will be no user interaction. The task will terminate on encountering the end of the file cmd.igi.
4. Interpret commands interactively and write the plot instructions to the metacode file igi.vdm but use the device characteristics of a Pericom terminal:
In this case, command interaction will occur in the text screen and no graphics will be drawn. To display the graphics, you might use the stdgraph task in the plot package.
5. Combine igi graphics with other IRAF graphics tasks. In the first example, run igi first and then append the additional grpahics. In the second example, run the stplot.newcont task and then append additional graphics using igi. This will work for both terminal/window display as well as hardcopy plots. Note that to properly append graphics, do not use gflush between the tasks. Afterwards, you may use gflush to dispose of the plot to a printer.
pl> igi < cmd.igi pl> newcont image append+ pl> newcont image pl> igi < cmd.igi append+
In the particular case of PostScript output to a file, if you wish to create a single file but plot on separate frames (pages), you must use "append=yes" for the second and subsequent plots. To create a new frame, use the igi ERASE command.
1. Read data from a text file, scale the plot, draw the axes, and draw the curve:
igi> data igi.dat igi> xcolumn 1; ycolumn 2 igi> limits igi> box; connect
Note the multiple commands on a line, separated by ";".
2. Change the above to plot on an log-log scale:
igi> data igi.dat igi> xcolumn 1; ycolumn 2 igi> xlogarithm; ylogarithm igi> limits igi> ticksize -1 0 -1 0 igi> box; connect
3. Read data from a table, scale the plot, draw the axes, and draw the curve as the Y elements versus row number:
igi> data table; ycolumn ycol igi> limits; box; connect
4. Read data from the third row of FITS table which has an array for each cell of a column, scale the plot, draw the axes, and draw the curve:
igi> data table.fits[1] igi> xcolumn wavelength 3; ycolumn flux igi> limits; box; connect
5. Using a row selector, choose a range of rows to be plotted from a FITS table which has an array for each cell of a column. The column command will then be used to read the data from each row in succession, since the row number given will be relative to the rows specified in the row selector. Next, scale the plot to the range of the first row's data, draw the axes, plot each curve with a different line style, then reset the line style to default:
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
6. Define a macro named "simple" to scale and draw a plot and invoke the macro:
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
7. Print a vertical label (in italics with a special character) centered at the current pen position twice the default character size. Note the FONTSET command to ensure that igi recognizes the text escapes and special characters.
igi> expand 2; angle 90; justify 5 igi> fontset igi igi> label \\iWavelength (\gVngstroms)
8. Draw a curve and superimpose symmetrical error bars in the Y data. Note that the error values are read with the ECOLUMN command and you need to call ERRORBAR twice to get both halves of the symbols.
igi> data tdat igi> ycolumn 2 igi> ecolumn 3 igi> limits igi> etype 1 igi> errorbar 2 igi> errorbar -2
9. Plot two curves in separate windows (different axis grids), the data as read in one, and the log of the data in another:
igi> window 2 1 1 igi> limits; box; connect igi> window 2 igi> yevaluate log10(y) igi> limits; box; connect
10. Assuming the image named specim contains two lines, one having wavelength values and the other intensities, the following would plot the spectrum as intensities versus wavelength:
igi> xsection specim[*,1] igi> ysection specim[*,2] igi> limits igi> box igi> connect
a. Label the above plot with the input file names:
igi> xlabel igi> ylabel
11. Use coordinate information in an input image to fill in the X values:
igi> imgwcs igi> ysection spect
# 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"
Data input to the above example may be constructed by using the urand task in the IRAF utilities package. The following command would create the file rand.dat used in the example:
urand 20 5 > rand.dat
13. Display images. The following draws four windows with 2-D image sections in two and a 1-D image section in the others.
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
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
Developed as an IRAF application by Zolt Levay, STScI. The printed "IGI Reference Manual" is available. It is an expanded version of this on-line help and includes figures and additional examples. The modifications to work with row selectors, cell arrays, and PostScript fonts were performed by Warren Hack.
cursor, plot