Graphics Commands

The graphics command section is divided into sections on Primitive commands and High Level commands. The primitive commands provide the most flexibility and are suitable for writing sophisticated programs in the GENIE command language (GCL). The high level commands are provided to give a simple to use set of commands which can be used by a less inexperienced user get pictures of their data on the screen quickly and easily.

It is quite possible to mix both sorts of command once experience has been gained with the way in which the Open GENIE graphics system operates.

High Level Commands

The High level graphics commands are listed below, these are based on similar commands used in the original GENIE-V2 program although the command syntax and functionality are enhanced.

A more general overview of the operation of these commands is available in the "User Notes" section of this manual

Primitive Commands

The primitive commands listed here give maximum control over the operation of the Open GENIE graphics sub-system. As a result they are slightly less easy to use for the novice user. For example, before any drawing primitives can be used, the Device() command must be used to open a display device.

Examples of the use of many of these commands may be found in the GCL procedures in the examples directory (usually /usr/local/genie/examples on UNIX or [OPENGENIE.EXAMPLES] on VMS). Where possible, an example or two showing a possible use of the primitive command is given as part of the reference section for that command.

For a basic introduction to the primitive graphics system, please see the advanced graphics user note in the "User notes" section of this manual.

TABLE OF CONTENTS

The primitive graphics commands are listed alphabetically in their functional groups below.

Control of graphics objects

Devices, Pictures and Windows

Graphics input

Simple drawing and plotting

Two-Dimensional plotting

Utility Commands

COMMAND REFERENCE

All commands are listed here alphabetically under the appropriate section. This is the definitive description for all the Open GENIE graphics commands.

Section I - High Level Graphics Commands

Alter()

Sets various defaults for the subsequent Display(), Plot() and Multiplot() commands

Note: See also the Toggle() command for changing plot parameters

Alter/Status

Shows the current values of any settings which may be changed using the Alter() command.

Alter/Binning

This command alters the bin grouping value used by the Display() command when displaying a histogram or bin-mode workspace. Note, the effect is simulated for ease of use when the user is plotting a point-mode workspace.

When the bin grouping value is set to a value greater than one, the display command groups the data by averaging the values of n-bin groups starting from the first bin in the histogram. This averaging can be viewed as a rudimentary form of smoothing the data which is done on the fly, each time the display command is used. It is possible to apply the same operation to a standard workspace permanently, see the Groupbins() command for more information.

Parameters:

P1 (Integer)

Number of bins to group together, no grouping occurs if this value is set to 1.

Alter/Device

This command changes the device to which the output of the display command will be sent.

Parameters:

P1 (String)

This is the name of the supported graphics device to which to set the display. Following the Alter/Device command all high level graphics commands will use the selected device.

Alter/Font

This command changes the default font used by the Display() command. This will change the font for all the text used in the display.

Parameters:

P1 (Font)

This is the name of a supported font to which to set the display. After an Alter/Font command all high level graphics commands will use new font..

Alter/Hardcopy

This command changes the default hardcopy device to which the output of display command is sent when a Hardcopy() command is issued.

Parameters:

P1 (String)

This is the name of the supported graphics device to which to set the hardcopy device will save the plot.

Alter/Linecolour

This command changes the default colour the Display() and command uses for drawing the axes and surrounding boxes.

Parameters:

P1 (Colour)

This is a colour variable returned by one of the colour functions or listed as one of the supported colours.

Alter/Linetype

This command changes the default line type the Display() and Plot() commands use for drawing line plots. Useful for separating plots on monochrome terminals.

Parameters:

P1 (LineStyle)

This is a line style listed as one of the supported linestyles.

Alter/Linewidth

This command changes the default line width used by the Display() and Plot() commands use for drawing line plots.

Parameters:

P1 (Real)

This is a real multiplier for the default line plot width of 1 unit. The width of the line may vary on different graphics devices.

Alter/Markers

This command changes the default marker used on a Marker plot.

Parameters:

P1 (Marker)

This is one of the available markers listed as one of the supported markers.

Alter/Markersize

This command changes the default marker size used by the Display() and Plot() commands use for drawing marker plots.

Parameters:

P1 (Real)

This is a real multiplier for the default marker size of 1 unit. The size of the marker may vary on different graphics devices.

Alter/Plot

This command changes the area of the display device which will be taken up by a Display() or Plot() command. The limits of the box are specified in device co-ordinates in the range 0.0-1.0 where the the values (0.0, 0.0) and (1.0, 1.0) represent the largest square available on the plotting device. It may be possible to draw slightly outside this area for devices with rectangular aspect ratios.

Parameters:

Xmin (Real), Xmax=(Real), Ymin=(Real), Ymax=(Real)

Normalised device co-ordinate values in the range 0.0 to 1.0. Xmin < Xmax, Ymin < Ymax.

Alter/Plotcolour

This command changes the default colour the Display() command uses for drawing the data plot (line, histogram or markers or errors).

Parameters:

P1 (Colour)

This is a colour variable returned by one of the colour functions or listed as one of the supported colours.

Alter/Size

Changes the size of the display device by a scaling factor. 1.0 is the default scaling factor.

Parameters:

P1 (Real)

Multiplier for the display device size.

Alter/Textheight

This command changes the default text height used by the Display() and Plot() commands.

Parameters:

P1 (Real)

This specifies the text height as a multiplier of 100th of the height of the display. The default text height is 3.0 or 3 hundredths of the display height.

Alter/Textcolour

This command changes the default colour the Display() command uses for drawing text.

Parameters:

P1 (Colour)

This is a colour variable returned by one of the colour functions or listed as one of the supported colours.

Cursor()

Displays a cursor on the graphics screen to allow interactive annotation.

example:

Cursor

This command is used mainly for annotating a plot whilst it is on the screen. An obvious use is for tagging peaks with the data value in the X or Y direction at the point selected by the cursor.

The command enters a sub-system where only certain keystrokes are recognized. Annotation operations as listed above can be carried out repeatedly until the E key is pressed to terminate the command.

Parameters:

/Vertical

Sets the default for any annotation text to be drawn vertically (from bottom to top).

/Horizontal

Sets the default for any annotation text to be drawn horizontally, this is the default if no qualifiers are given.

Xval, Yval (Real)

Optional starting values for the cursor position. If a peak is known to be somewhere near the middle of the screen, for example, it can save unnecessary cursor movement. The default position for the cursor to appear is at (0,0) in the current window.

Display()

Display a graphical plot of spectra in a workspace.

Note: Other display parameters may be altered using the Alter() and Toggle() commands.

Display

The display command is the high level command used to plot one or more spectra from a workspace in a single operation. By default, the Display() command will assume that the plot is to be done as a histogram. The plot will be automatically scaled and titled with other relevant information from the workspace. Most features of the Display() command may be customized either by using the command line parameters on Display() itself or by modifying characteristics of the plot using the Alter(), Toggle() or Limits() commands.

Parameters:

/Histogram

This is the default for the Display() command when given bin-mode (histogrammed) data. It will plot a spectrum making the assumption that it is a valid histogram (i.e. binned data with one more X value than Y value). The data values are represented by the height of the corresponding bin. Remember that several commands can actually affect the height of bins unexpectedly by changing the binning method and/or data. Examples of these are Alter/Binning and Units/Channel.

If point-mode data is supplied with the /Histogram qualifier an error will be reported as it is not possible for Open GENIE to guess the assumptions you may want to make about the conversion (an extra X value would have to be generated by interpolation).

/Line

This is the default for the Display() command when given point-mode data. It will plot a spectrum as if it is a numerically calculated function (i.e. with the same number of X-values as Y-values) and join the points with a straight lines. If histogram data is displayed with the /Line qualifier, the data will undergo a transformation to take the bin centre positions as the X-values for the data points (see the Centre_bins() function). There are situations where you may not wish this behaviour to be the default (e.g. for logarithmic binning). Generally, it is safer to transform the data yourself into point-mode and then use Display to plot it.

/Markers

This is identical to the /Line qualifier in operation except that instead of joining the data points with lines, marker symbols are used instead. See Marker Types for a list of available styles.

/Errors

This is identical to the /Line qualifier in operation except that instead of joining the data points with lines, error bars are generated. These are centered on the data points and have a size scaled from the values of the data error values contained within the workspace E array.

Wksp (Workspace)

This gives the workspace to be plotted. As long as the workspace is a valid Open GENIE workspace containing one or more spectra this command will produce a display. In later version of Open GENIE this will also take multi-spectra workspaces to produce multiplots (see Multiplot()).

For convenience, if the Display() command is used without a workspace being specified, the last workspace to be plotted will be used.

Xmin, Xmax, Ymin, Ymax (Real)

These parameters can be used to set fixed limits for the display, for more details see the Limits() command.

Linecolour (Colour)

This parameter changes the colour for drawing the axes and surrounding boxes, see Alter() for details.

Linewidth (Real)

This parameter changes the line width used for drawing line plots, see Alter() for details.

Textcolour (Colourl)

This parameter changes the colour used for drawing text, see Alter() for details.

Textheight (Real)

This parameter changes the text height used for drawing text, see Alter() for details.

Hardcopy()

Makes a copy of picture on a hardcopy device.

The Hardcopy command allows a copy to be made of either the currently displayed window, or an earlier picture.

The supported hardcopy devices on most machines include "PS" Postscript, "CPS" Colour Postscript and "HPGL" HPGL driver for 7475A For full details of supported devices on each machine type see Supported Graphics Devices.

The "filename" and "devtype" parameters also set the default for further calls to the Hardcopy command so normally just typing Hardcopy is sufficient to make a hardcopy of the current screen.

Parameters:

filename (String)

The name of a file into which to put the hardcopy, the default is "GENIE.PS".

devtype (String)

One of the supported hardcopy graphics devices.

picture (Gobject)

The picture to be copied. By default picture 0 is selected which is the last picture to be created.

aspect (Real)

The aspect ratio of the hardcopy output.

width (Real)

The width of the hardcopy output.

height (Real)

The height of the hardcopy output.

Limits()

Sets axis limits for the Display() and Plot() commands.

Note: If no data appears on a Display(), typing "Limits" may help find it!

Limits

The Limits() command is used to gain independent control over the scaling of the axes used in the Display() and Plot() commands. Settings made using the command remain in effect until another Limits() command is issued.

Parameters:

/Default

This qualifier enables automatic limit scaling for the Display() command. If for some reason the data has disappeared off the plot, using Limits/Default will ensure any data is plotted in the viewable area. This is the default qualifier so just typing "Limits" will perform a Limits/Default.

Limits/X

Sets explicit X limits for the Display() and Plot() commands to adhere to. Note that the actual setting of the limits will still be dependent on whether rounding is switched on for the X axis (see Alter())

Parameters:

Xmin, Xmax (Real)

Real values for the lower and upper bounds of the visible data region in data co-ordinates.

Limits/Y

Sets explicit Y limits for the Display() and Plot() commands to adhere to. Note that the actual setting of the limits will still be dependent on whether rounding is switched on for the Y axis (see Alter())

Parameters:

Ymin, Ymax (Real)

Real values for the lower and upper bounds of the visible data region (in data co-ordinates).

Limits/No_auto

Sets explicit X and Y limits for the Display() and Plot() commands to adhere to. Note that the actual setting of the limits will still be dependent on whether rounding is switched on for either or both axes (see Alter())

Parameters:

Xmin, Xmax, Ymin, Ymax (Real)

Real values for the lower and upper bounds of the visible data region in data co-ordinates.

Multiplot()

Plots multiple spectra on one set of axes using a hidden line removal

Note: multiplot from a file is more efficient in terms of memory

Multiplot

The multiplot command provides an easy to interpret display of multiple spectra on the same X-axis. It is useful for comparing groups of spectra which although essentially similar may show a trend across the group (e.g. a phonon effect with temperature). The command works by producing a psuedo Y-axis where subsequent plots are placed at an artificial Y offset value (ygap). Individual spectra are overplotted using hidden line removal. Currently, multiplot only plots as a histogram, the binning is controlled with the Alter() command.

Parameters:

Spectra (Range)

When the Multiplot() command is used with this parameter specified, it is assumed that the data source for the multiplot has already been specified as a default input source, see Set/File, or is given with the "file" parameter to this command.

Open GENIE also supports unique data types called Interval and Range, a Range or Interval can be used to specify multiple indices or a range of indices respectively to access multi-dimensional data. For more information on specifying intervals, please see a description of the Interval syntax. For the most general ability to specify a group of arbitrary spectra an Integer array of spectrum identifiers can be given as the the "Spectra" parameter. The spectra will be plotted in the order specified.

Wa (WorkspaceArray)

If this form of the command is used, the data to be plotted is supplied in the form of multiple spectra stored in a Workspace array. The spectra must all be binned identically on the same X-axis for the multiplot command to be able to work.

Ygap (Real)

This parameter sets the spacing artificially added to separate the multiple spectra on the Y-Axis. It is specified in the same coordinates as the data and is calculated automatically by the Multiplot() command if it is not specified. The real Y height of a point in any spectrum on a multiplot is given by yvalue = measured-height - ygap * spectrum-number where spectrum-number is the nth spectrum in the order of plotting.

file (String)

Specifies a data file other than the default set by Set/File.

Linecolour (Colour)

This parameter changes the colour for drawing the axes and surrounding boxes, see Alter() for details.

Linetype (LineStyle)

This parameter changes the line style for drawing the axes and surrounding boxes, see Alter() for details.

Linewidth (Real)

This parameter changes the line width used for drawing line plots, see Alter() for details.

Textcolour (Colourl)

This parameter changes the colour used for drawing text, see Alter() for details.

Textheight (Real)

This parameter changes the text height used for drawing text, see Alter() for details.

Peak()

Performs interactive peak fitting

Note: See the Peakfit() and Peakgen() commands for more detail.

Peak

The peak command is a high level command built on the powerful Open GENIE peak fitting primitive commands. It operates interactively to allow selection of the bounds of the peak and the form of fit to use. Once fitted the peak parameters of the fit are displayed and made available as a result so that they can be used later. For more control over the fitting process see the Peakgen() and Peakfit() primitive commands.

Parameters:

W (Workspace)

Any valid single spectrum in a workspace.

RESULT = (Workspace)

The result of the Peak() command is a workspace containing the fitting parameters used as well as a description of the type of fit and an algebraic description of the function fitted.

Plot()

Overplots an existing graph produced by Display()

Note: Plot does not allow any change of scaling.

Plot

The Plot() command is really an adjunct to the Display() command. It is used to plot just the data plot of a spectrum such that it can be used to superimpose new data onto existing plots made with with the Display() command. The Plot() command itself has no ability to create axes or scale the data.

Parameters:

/Histogram

This is the default as for the Display() command when given bin-mode (histogrammed) data. It will plot a spectrum making the assumption that it is a valid histogram (i.e. binned data with one more X value than Y value). The data values are represented by the height of the corresponding bin. Remember that several commands can actually affect the height of bins unexpectedly by changing the binning method and/or data. Examples of these are Alter/Binning and Units/Channel.

If point-mode data is supplied with the /Histogram qualifier an error will be reported as it is not possible for Open GENIE to guess the assumptions you may want to make about the conversion (an extra X value would have to be generated by interpolation).

/Line

This is the default for the Plot() command when given point-mode data. It will plot a spectrum as if it is a numerically calculated function (i.e. with the same number of X-values as Y-values) and join the points with a straight lines. If histogram data is displayed with the /Line qualifier, the data will undergo a transformation to take the bin centre positions as the X-values for the data points (see the Centre_bins() function). There are situations where you may not wish this behaviour to be the default (e.g. for logarithmic binning). Generally, it is safer to transform the data yourself into point-mode and then use Display to plot it.

/Markers

This is identical to the /Line qualifier in operation except that instead of joining the data points with lines, marker symbols are used instead. See Marker Types for a list of available styles.

/Errors

This is identical to the /Line qualifier in operation except that instead of joining the data points with lines, error bars are generated. These are centered on the data points and have a size scaled from the values of the data error values contained within the workspace E array.

Wksp (Workspace)

The workspace containing the data to overplot with.

Binning (Integer)

Binning for this plot only. See Alter/Binning for more details on binning. Note that by binning differently with the Plot() command, data may appear quite differently. This is because the implicit micro-averaging in the binning may substantially reduce the height of sharp peaks or noise.

Toggle()

Toggles between common settings, mainly graphics.

Note: See the Alter() command for changing other graphics settings.

Toggle/Status

The Toggle command acts like an on off switch for the settings described below. The Toggle() command used on its own without any parameters reports the settings of all toggleable parameters.

All the toggle commands switch the setting to it's opposite value unless /Off or /On is specified in which case the value of the setting is forced on or off.

Parameters:

/On

Applies to all Toggle() commands and forces the value of the parameter to the On state.

/Off

Applies to all Toggle() commands and forces the value of the parameter to the Off state.

/NoMessage

Applies to all Toggle() commands and suppresses any informational messages that may have been printed.

Toggle/LogX

Set the default mode for plotting with the Display() and Plot() commands to plot logs of the X data against a log X Axis. On startup, the X-Axis mode is linear.

Toggle/LogY

Set the default mode for plotting with the Display() and Plot() commands to plot logs of the Y data against a log Y Axis. On startup, the Y-Axis mode is linear.

Toggle/Clear

Alters the behaviour of the Display() and Multiplot() commands to produce plots without clearing the display device first. This can be used with the Alter/Plot command to put multiple pictures on one display, see also the Graphics primitive window creation commands. On startup, both the commands clear the display device by default.

Toggle/Graticule

Switches a graticule or crosshatch on for subsequent invocations of the Display() command. The frequency of the graticule may be altered by the Alter() command.

Toggle/Header

Switches the default for whether to display the standard Display() command banner or not. The banner can be toggled off to make more room to display the plot on a small screen. On startup the banner is enabled.

Toggle/RoundX

Enables rounding on the X axis. By default this is switched on, but for accuracy it may be desireable to let the absolute values of the axis be fixed to the exact limits of the plot.

Toggle/RoundY

Enables rounding on the Y axis. By default this is switched on, but for accuracy it may be desireable to let the absolute values of the axis be fixed to the exact limits of the plot.

Toggle/Info

Switches the display of informational messages on/off. Normally Open GENIE operations report warning or informational messages as ANSI style blue coloured text using the Printin() command. For example, Genie command language procedures using a lot of data I/O may wish to supress messages about the data being read.

Toggle/Debug

Switches the display of debugging messages on/off. Normally Open GENIE operations report debug messages as ANSI style pink coloured text using the Printdn() command. This display will print alot of information to the screen and therefore is probably only of use for debugging procedures.

Zoom()

Interactively choose an area of a plot to magnify.

Note: A zoom can be undone by a Limits/Default command with no arguments

Zoom

The Zoom() command is an interative command which helps examine a plot already on the screen in more detail. The zoom command works by re-displaying the selected region of data. As a result of this approach, the resolution of a zoom is only limited to the resolution set by the data or the current bin setting (see Alter/Binning).

Parameters:

/Errors

Display the resulting plot in the form of error bars.

/Histogram

Display the resulting plot in the form of a histogram (the default for bin-mode data).

/Line

Display the resulting plot in the form of a line plot (the default for point-mode data).

/Markers

Display the resulting plot in the form of marker symbols

/Multiplot

Perform the zoom on an area of a multiplot and re-display as a multiplot. See the Multiplot() command.

Section II - Primitive Graphics Commands

Delete()

Deletes unwanted graphics objects from memory

Note: Once something is deleted then there is no going back.

Delete

Deletes a DrawableObject from the window it is found in. There is no default object chosen by Delete(), as the operation is permanent, an object must be specified. Delete() will change the numbering order of pictures, windows and objects.

Parameters:

Item (Gobject)

Deletes the specified object. If the object refers to a window or picture, all contained objects are deleted too.

Pic_add()

Copy graphical objects from picture to picture.

Note: item can only ever be a primitive object or a window.

Pic_add()

This command allows graphical objects to be reshown more than once, moved from display to display or duplicated. Open GENIE contains a copy of every graphical object that has been created and is still in use (they can be removed permanently by the Delete() command).

Objects can either be referred to using the Pic(), Win(), Dev() or Obj() functions or obtained directly as an object reference when an object is created (as in the example above).

Note that the default destination for Pic_add() is the current Picture when "item" is a window, and is the Current Window when "item" is a primitive object.

Parameters:

Item (Gobject)

This must be an object reference to either a drawing primitive (e.g. a line) or a window. This parameter cannot be a device or picture reference. This is the item which is to be copied and redrawn at a new destination. Probably the most useful form of the command is to copy windows which already have several things drawn in them.

Dest (Gobject) [ default = current window ]

Specifies a destination picture or window. If a picture is specified and the "item" parameter is a primitive object the window used will be the last one in the picture. When the "item" parameter is a window, the window is simply added at the end of the specified picture.

Device (Gobject) [ default = current device ]

After adding an object to a picture, the object will be re-drawn, by default this will be on the current device. If this is not the device required, the device in which to re-draw the newly copied primitive can be specified explicitly.

RESULT = (Restype)

Returns a reference to the copied item. This allows "/alter" commands to be applied to the object without having to find it again.

Select()

Select a new current device, window or picture

Note: Drawing is always to the current window.

Select

The Open GENIE graphics system always maintains a record of a current device, picture and window. This is done so that drawing commands can all occur without having to specify where to draw. Normally Open GENIE looks after the setting of these defaults in an intuitive way but the Select() command makes it possible to change the currently selected objects.

The most likely use for the Select() command is when programming a complex system involving several windows, pictures and open devices. It is also the only way to go back to draw in a window which was created earlier on and which has been superceded by subsequent window creating commands. To specify which objects to select, see the Dev(), Pic() and Win() commands.

Parameters:

Item (Gobject)

This specifies either a picture, window or device object and the object specified then becomes the current device, picture or window. Generally if you wish to draw into a previous picture or window, the object to select is the window, drawing commands can only be into a window. The only time to select a picture explicitly is when adding a new window to an old picture.

RESULT = (Gobject or Undefined)

Returns the Gobject selected as the new current device, window or picture.

Redraw()

Redisplay current or previous pictures or objects.

Note: The default is to redraw the current picture on the current device

Redraw

This command allows a complete redraw of a picture (either one currently displayed on the device or one which was previously displayed and still remains in the picture list). As pictures are stored independently of the device on which they are displayed, it is possible to close the currently open device, open another, and then redraw one or more pictures to the new device. This is how the high level command Hardcopy() works. Windows and objects may also be redrawn specifically where the underlying graphics driver allows updates to specific parts of the display.

Parameters:

Item (Gobject) [ default = current picture ]

The graphics object to be redrawn, this will default to the current picture and effectively refresh the whole picture on the current device. If a window or even an individual primitive object is specified instead, just the window or object will be redrawn.

Device (Gobject) [ default = current device ]

The device on which to which to redraw the item specified. The default is the currently selected device.

Undraw()

Undraw a primitive graphics operation.

Note: See Obj(), Win() and Pic() commands for specifying objects.

Undraw

Undraw allows a temporary removal of a graphics item; either a primitive object, window or picture. Normally it is used interactively when annotating a plot as a means of undoing some annotation which was inappropriate. An undrawn item remains in the display list and can be redrawn if desired with the Redraw() command. If somthing is undrawn by mistake, it can be redrawn using the Redraw() command.

Parameters:

item (Gobject) [ default = last graphical object drawn ]

This parameter specifies the the primitive to remove. Objects can be refererred to either by an object reference saved when the object was created or by one of the object locating functions Pic(), Win(), Obj().

Device()

Selects and controls graphics devices

Note: For windowing systems, multiple device may be open at once.

Device/Open

The supported interactive devices on most machines include "XWINDOWS" X-Windows and "TEK4010" Tek 4010 compatible. The supported non-interactive devices include "PS" Postscript, "CPS" Colour Postscript and "HPGL" HPGL driver for 7475A For full details of supported devices on each machine see Supported Graphics Devices.

Parameters:

Devtype (String) [ default = "XWINDOW" ]

The device name string, this can be any supported device, interactive or hardcopy. Only one device can be open at any one time.

Width (Real) [ default = 8.0 inches ]

Width of the graphics display in inches.

Height (Real) [ default = 8.0 inches ]

Height of the graphics display in inches.

RESULT = (Device)

Returns the device object for later reference.

Device/Clear

Clears the display surface on the currently open device or advances to a new sheet of paper, a new picture is created automatically and will become the current picture. The older pictures will still be available by using the Redraw() command (Redraw pic(-1) will redraw the picture before the device was cleared).

Device/Close

Deactivates the currently open graphics device. This command flushes output to a file when using a hardcopy device and must be called before the file can be used. Once the device is closed, it is not possible to draw anything without re-opening the device. A different device can be used when the device is re-opened.

Parameters:

Object (Gobject)

Optional device to close, otherwise the default is to close the current device.

Device:Status()

Returns true if there is at least one graphics device open. This can be useful where another procedure may or may not have initialized the graphics system previously and it would be unnecessary or unhelpful to open a second device.

Picture()

Creates a picture

Note: To create a pictures without opening a real device, open a "/NULL" device.

Picture

Create and display a picture on the current device. After a picture command the current picture will be reset to the new picture and the previous picture can be accessed via the Pic() command ( i.e. Redraw pic:rel(-1) ). Whenever a picture is created, a default unscaled window is also created see ( Win_unscaled() ) this window takes up the whole drawable area of the picture so that the device co-ordinates and window co-ordinates match.

Parameters:

RESULT = (Picture)

This returns all of the properties of a Picture as a picture object reference.

Window()

Obsolete command

Window()

This command is now obsolete. The new "Win_" commands provide the same functionality.

Win_autoscaled()

Creates a scaled window automatically from supplied data.

Note: d means the device co-ordinate.

Win_Autoscaled

Creates and displays a scaled window, without the knowledge of the exact co-ordinates needed for the scaling of the window. The scaling is fairly intelligent and can be controlled by the "maxmode" and "minmode" parameters. Obviously for this routine to work, the data must be available already, if not the Win_scaled() command can be used.

Parameters:

Dxmin (Real)

Sets the minimum x device co-ordinate.

Dxmax (Real)

Sets the maximum x device co-ordinate.

Dymin (Real)

Sets the minimum y device co-ordinate.

Dymax (Real)

Sets the maximum y device co-ordinate.

X (RealArray)

Scales the autoscaled window.

Y (RealArray)

Scales the autoscaled window.

E (RealArray)

Scales the autoscaled window.

Minmode (Integer)

Specify how the axes are scaled by setting the minimum mode where, 0=absolute values, 1 or 3 = +10%, 2 or 3 = round down, and 4 = force zero.

Maxmode (Integer)

Specify how the axes are scaled by setting the maximum mode where, 0=absolute values, 1 or 3 = +10%, 2 or 3 = round down, and 4 = force zero.

Colour (Colour)

Sets the colour of the window. By default the colour of the window is the background colour.

RESULT = (WindowScaled)

Returns all of the properties of the newly created window.

Win_multiplot()

Controls and creates multi_plot windows for plotting

Note: d means the device co-ordinate.

Win_MultiPlot

Creates and displays a window which enables multiplots to be drawn. This window can not be created without a completed multi_plot object from which to scale the axes.

Parameters:

Dxmin (Real)

Sets the minimum x device co-ordinate.

Dxmax (Real)

Sets the maximum x device co-ordinate.

Dymin (Real)

Sets the minimum y device co-ordinate.

Dymax (Real)

Sets the maximum y device co-ordinate.

Object (Gobject)

An already created multi_plot object with spectra added so that this window can scale from it.

Minmode (Integer)

Specify how the axes are scaled by setting the minimum mode where, 0=absolubte values, 1 or 3 = +10%, 2 or 3 = round down, and 4 = force zero.

Maxmode (Integer)

Specify how the axes are scaled by setting the maximum mode where, 0=absolubte values, 1 or 3 = +10%, 2 or 3 = round down, and 4 = force zero.

Colour (Colour)

Sets the colour of the window. By default the colour of the window is black.

RESULT = (MultiplotWindow)

Returns all of the properties of the newly created window.

Win_scaled()

Controls and creates pre-scaled windows for plotting data.

Note: d means the device co-ordinate, w means the world co-ordinate.

Win_Scaled

Creates and displays a scaled window. A scaled window is an area in which it is possible to specify any range of data or window co-ordinates to map onto an area of the display device (specfied in device co-ordinates). Normally a scaled window should be created for every data plot. For drawing simple graphics which do not require an extra scaling to match the data you can use the Win_unscaled() command instead.

Parameters:

Dxmin (Real)

Sets the minimum x device co-ordinate.

Dxmax (Real)

Sets the maximum x device co-ordinate.

Dymin (Real)

Sets the minimum y device co-ordinate.

Dymax (Real)

Sets the maximum y device co-ordinate.

Wxmin (Real)

Sets the minimum x world co-ordinate.

Wxmax (Real)

Sets the maximum x world co-ordinate.

Wymin (Real)

Sets the minimum y world co-ordinate.

Wymax (Real)

Sets the maximum y world co-ordinate.

Colour (Colour)

Sets the colour of the window. By default the colour of the window is black.

Minmode (Integer)

Specify how the axes are scaled by setting the minimum mode where, 0=absolubte values, 1 or 3 = +10%, 2 or 3 = round down, and 4 = force zero.

Maxmode (Integer)

Specify how the axes are scaled by setting the maximum mode where, 0=absolubte values, 1 or 3 = +10%, 2 or 3 = round down, and 4 = force zero.

RESULT = (WindowScaled)

Returns all of the properties of the newly created window.

Win_twod()

Controls and creates two dimensional windows for plotting

Note: d means the device co-ordinate. Giving the x/yarray the window is scaled automatically.

Win_Twod

Creates and displays a Two dimensional window ready for plotting a colour cell or contour plot. The area of the sceen to use for the window is specified with the four device co-ordinates and the supplied X and Y arrays are used to auto-scale the axes in the X and Y directions respectively. Currently all transformations are handled by the plotting commands so it is possible to scale the axes explicity by giving X and Y arrays with two elements each to specify the maximum and minimum values instead of the complete grid arrays (which would be needed for a non-linear grid).

Parameters:

Dxmin (Real)

Sets the minimum x device co-ordinate.

Dxmax (Real)

Sets the maximum x device co-ordinate.

Dymin (Real)

Sets the minimum y device co-ordinate.

Dymax (Real)

Sets the maximum y device co-ordinate.

X (RealArray)

Scales the two dimensional window.

Y (RealArray)

Scales the two dimensional window.

Colour (Colour)

Sets the colour of the window. By default the colour of the window is black.

RESULT = (TwoDWindow)

Returns all of the properties of the newly created window.

Win_unscaled()

Controls and creates unscaled windows for plotting.

Note: d means the device co-ordinate.

Win_Unscaled

Creates and displays an unscaled window. The unscaled window is the simplest form of graphics window. By default every new picture has an unscaled window associated with it and they can be created as desired. Normally things such as plot annotation, text and boxes are drawn in the default unscaled window to avoid scaling the simple graphics primitives in the same coordinates as the plot. The co-ordinates within an unscaled window always go from 0 to 1 in the X and Y directions.

Parameters:

Dxmin (Real)

Sets the minimum x device co-ordinate.

Dxmax (Real)

Sets the maximum x device co-ordinate.

Dymin (Real)

Sets the minimum y device co-ordinate.

Dymax (Real)

Sets the maximum y device co-ordinate.

Colour (Colour)

Sets the colour of the window. By default the colour of the window is black.

RESULT = (Window)

Returns all of the properties of the newly created window.

New_zoom()

Zooms in on a graphics device

Note: This is only partially implemented.

New_Zoom

The left mouse button specifies the region to be zoomed.
The Right mouse button will:

- go back to the original picture (clicked once and device is showing zoomed area)
- exits the command (clicked twice - if originally showing
a zoomed area, otherwise click once)

Getcursor()

Cursor input routine for a window or a picture.

Note: If there is more than one window where the pointer clicked, it will return the last window drawn.

Getcursor()

Returns the point where the mouse clicked in device co-ordinates (d_x, d_y), window co-ordinates (w_x, w_y), and a character to represent the mouse button clicked ("A" for left "X" for right).

X, Y (Real) [ default = (0, 0) ]

Specifies an optional starting place to put the cross hairs on the screen. This is specified in device co-ordinates.

= (Workspace)

At the point the mouse clicked, it returns all of the possible co-ordinates and window number in a single workspace

RESULT = (Workspace)

At the point the mouse clicked, it returns all of the possible co-ordinates and window number in a single workspace.

Draw()

Obsolete command

Draw()

This command is now obsolete. The alternatives listed above provide the same functionality.

Axes()

Displays an axes on the graphics device

Note: By default the axes are linear, x is labelled horizontally and y is labelled vertically

Axes/Draw

Draws an axes on a graphics device when a window is displayed previously.

Parameters:

/Xlog

Draws a logarithmic x axis.

/Ylog

Draws a logarithmic y axis.

/Yhoriz

Labels the numbers horizontally on the y axis..

/Noxnum

Does not put numbers on the x axis.

/Noynum

Does not put numbers on the y axis.

/Xlinear

Draws a linear x axis.

/Ylinear

Draws a linear y axis.

/Yvertical

Draws the numbers vertically on the y axis.

/Xnum

Draws numbers on the x axis.

/Ynum

Draws numbers on the y axis.

Colour (Colour)

Defines the colour of the axis.

Size (Real)

Defines the size of the numbers.

Font (Font)

Defines the font, $Normal, $Roman, $Italic, $Script.

Line_thickness (Real)

Defines the thickness of the axis.

Line_type (LineStyle)

Defines the line_type of the axes, $Full, $Dash, $Dot-Dash, $Dot.

RESULT = (OneDAxes)

This returns all of the properties of the newly created axes.

Axes/Alter

Alters a specified axes, the parameter object MUST be specified.

Parameters:

/Xlog

Draws a logarithmic x axis.

/Ylog

Draws a logarithmic y axis.

/Yhoriz

Labels the numbers horizontally on the y axis..

/Noxnum

Does not put numbers on the x axis.

/Noynum

Does not put numbers on the y axis.

/Xlinear

Draws a linear x axis.

/Ylinear

Draws a linear y axis.

/Yvertical

Draws the numbers vertically on the y axis.

/Xnum

Draws numbers on the x axis.

/Ynum

Draws numbers on the y axis.

Colour (Colour)

Defines the colour of the axis.

Size (Real)

Defines the size of the numbers.

Font (Font)

Defines the font, $Normal, $Roman, $Italic, $Script.

Line_thickness (Real)

Defines the thickness of the axis.

Line_type (LineStyle)

Defines the line_type of the axes, $Full, $Dash, $Dot-Dash, $Dot.

Object (Gobject)

Shows which axes is to be altered.

RESULT = (OneDAxes)

This returns all of the properties of the altered axes

Errors()

Displays error-bars on a plot

Note: By default the error-bars are drawn vertically.

Errors/Draw

Draws error-bars on a graphics device. If the xarray and yarray have already been defined, in either graph, histogram or markers. then it is not necessary to define them again.

Parameters:

/Vertical

Draw vertical error-bars.

/Horizontal

Draw horizontal error-bars.

Xarray (RealArray)

Defines the x points.

Yarray (RealArray)

Defines the y points

Earray (RealArray)

Defines the size of the error-bars.

Colour (Colour)

Defines the error-bars colour.

Line_thickness (Real)

Defines the error-bars width.

RESULT = (OneDVErrors or OneDHErrors)

Returns the properties of the newly created error-bars.

Errors/Alter

Alters an already created set of error bars.

Parameters:

/Vertical

Draw vertical error-bars.

/Horizontal

Draw horizontal error-bars.

Xarray (RealArray)

Not yet implemented.

Yarray (RealArray)

Not Yet Implemented.

Earray (RealArray)

Not Yet Implemented.

Colour (Colour)

Defines the error-bars colour.

Line_thickness (Real)

Defines the error-bars width.

Object (Integer)

Shows which set of error-bars are to be altered, in any one window.

RESULT = (OneDVErrors or OneDHErrors)

Returns the properties of the altered error-bars.

Graph()

Displays a graph (or line plot) on a graphics device.

Note: For graph/alter yarray and xarray are not yet implemented.

Graph/Draw

Draws a graph on a graphics device. If the xarray and yarray have already been defined, in either errors, histogram or markers. then it is not necessary to define them again.

Parameters:

Xarray (RealArray)

Defines the x points.

Yarray (RealArray)

Defines the y points

Colour (Colour)

Defines the graphs colour.

Line_type (LineStyle)

Defines the line type of the graph. Such as $full, $dash, $dot_dash and $dot.

Line_thickness (Real)

Defines the graphs line width.

RESULT = (OneDGraph)

Returns the properties of the newly created graph.

Graph/Alter

Alters a graph. The xarray and yarray are not able to be altered at this point in time.

Parameters:

Xarray (RealArray)

Not yet implemented.

Yarray (RealArray)

Not Yet Implemented.

Colour (Colour)

Defines the graph colour.

Line_type (LineStyle)

Defines the line type of the graph. Such as $full, $dash, $dot_dash and $dot.

Line_thickness (Real)

Defines the graphs line width.

Object (Gobject)

Shows which graph is to be altered.

RESULT = (OneDGraph)

Returns the properties of the altered graph.

Graticule()

Displays a graticule axis on the graphics device

Note: By default the graticule is linear.

Graticule/Draw

Draws a graticuleon a graphics device when a window is displayed previously.

Parameters:

/Xlog

Draws with a logarithmic x axis.

/Ylog

Draws with a logarithmic y axis.

/Yhoriz

Labels the numbers horizontally on the y axis..

/Noxnum

Does not put numbers on the x axis.

/Noynum

Does not put numbers on the y axis.

/Xlinear

Draws a linear x axis.

/Ylinear

Draws a linear y axis.

/Yvertical

Draws the numbers vertically on the y axis.

/Xnum

Draws numbers on the x axis.

/Ynum

Draws numbers on the y axis.

Colour (Colour)

Defines the colour of the graticule.

Size (Real)

Defines the size of the numbers.

Font (Font)

Defines the font, $Normal, $Roman, $Italic, $Script.

Line_thickness (Real)

Defines the thickness of the graticule.

Line_type (LineStyle)

Defines the line_type of the graticule, $Full, $Dash, $Dot-Dash, $Dot.

RESULT = (OneDGraticule)

This returns all of the properties of the newly created graticule.

Graticule/Alter

Alters a specified graticule, the parameter object MUST be specified.

Parameters:

/Xlog

Draws a logarithmic x axis.

/Ylog

Draws a logarithmic y axis.

/Yhoriz

Labels the numbers horizontally on the y axis..

/Noxnum

Does not put numbers on the x axis.

/Noynum

Does not put numbers on the y axis.

/Xlinear

Draws a linear x axis.

/Ylinear

Draws a linear y axis.

/Yvertical

Draws the numbers vertically on the y axis.

/Xnum

Draws numbers on the x axis.

/Ynum

Draws numbers on the y axis.

Colour (Integer)

Defines the colour of the graticule.

Size (Real)

Defines the size of the numbers.

Font (Font)

Defines the font, $Normal, $Roman, $Italic, $Script.

Line_thickness (Real)

Defines the thickness of the graticule.

Line_type (LineStyle)

Defines the line_type of the graticule, $Full, $Dash.

Object (Gobject)

Defines which graticule is to be altered, in any one window.

RESULT = (OneDGraticule)

This returns all of the properties of the altered graticule

Histogram()

Displays a histogram on a graphics device.

Note: By default the points are not centred.

Histogram/Draw

Draws a histogram on a graphics device. If the xarray and yarray have already been defined, in either errors, histogram or markers. then it is not necessary to define them again.

Parameters:

/Centre

Plots the points at the centre of the bin.

/Notcentred

Plots the points at the beginning of the bin.

Xarray (RealArray)

Defines the x points.

Yarray (RealArray)

Defines the y points.

Colour (Colour)

Defines the histogram's colour.

Line_type (LineStyle)

Defines the line type of the graph. Such as $full, $dash, $dot_dash and $dot.

Line_thickness (Real)

Defines the histogram's line width.

RESULT = (OneDHistogram)

Returns the properties of the newly created histogram.

Histogram/Alter

Alters a histogram. The xarray and yarray is not able to be altered at this point in time.

Parameters:

/Centre

Plots the points at the centre of the bin.

/Notcentred

Plots the points at the beginning of the bin.

Xarray (RealArray)

Not yet implemented.

Yarray (RealArray)

Not Yet Implemented.

Colour (Colour)

Defines the histogram colour.

Line_type (LineStyle)

Defines the line type of the graph. Such as $full, $dash, $dot_dash and $dot.

Line_thickness (Real)

Defines the histogram's line width.

Object (Gobject)

Shows which histogram is to be altered, in any one window.

RESULT = (OneDHistogram)

Returns the properties of the altered histogram.

Labels()

Displays x/y labels on the graphics device

Note: By default xlabel is labelled horizontally, and ylabel is labelled vertically.

Labels/Draw

Draws text just below the x-axis and just to the left of the y-axis.

Parameters:

/Xhorizontal

Sets the xlabels to draw the text horizontally.

/Xvertical

Sets the xlabels to draw the text vertically.

/Yhorizontal

Sets the ylabels to draw the text horizontally.

/Yvertical

Sets the ylabels to draw the text vertically.

Xlabel (String)

Sets the xlabel text.

Ylabel (String)

Sets the ylabel text.

Size (Real)

Sets the size of the text.

Colour (Colour)

Sets the colour of the text.

Font (Font)

Sets the font of the text. Such as, $normal, $roman, $italic, $script

RESULT = (OneDLabels)

Returns all of the properties of the newly created object.

Labels/Alter

Alters any drawableObject with the datatype of OneDLabels.

Parameters:

/Xhorizontal

Sets the xlabels to draw the text horizontally.

/Xvertical

Sets the xlabels to draw the text vertically.

/Yhorizontal

Sets the ylabels to draw the text horizontally.

/Yvertical

Sets the ylabels to draw the text vertically.

Xlabel (String)

Sets the xlabel text.

Ylabel (String)

Sets the ylabel text.

Size (Real)

Sets the size of the text.

Colour (Colour)

Sets the colour of the text.

Font (Font)

Sets the font of the text. Such as, $normal, $roman, $italic, $script

Object (Gobject)

Shows which labels are to be altered, in any one window.

RESULT = (OneDLabels)

Returns all of the properties of the altered object.

Line()

Displays a line on the graphics device

Line/Draw

Draws a line in a graphics device.

Parameters:

Xstart (Real)

x co-ordinate of the starting point.

Xend (Real)

x co-ordinate of the ending point.

Ystart (Real)

y co-ordinate of the starting point.

Yend (Real)

y co-ordinate of the ending point.

Colour (Colour)

Sets the colour of the line

Line_thickness (Real)

Sets the width of the line.

RESULT = (Polyline)

Returns the properties of the newly created line.

Labels/Alter

Alters a line in a graphics device.

Parameters:

Xstart (Real)

x co-ordinate of the starting point.

Xend (Real)

x co-ordinate of the ending point.

Ystart (Real)

y co-ordinate of the starting point.

Yend (Real)

y co-ordinate of the ending point.

Colour (Colour)

Sets the colour of the line

Line_thickness (Real)

Sets the width of the line.

Object (Gobject)

Shows which line is to be altered, in any one window.

RESULT = (Polyline)

Returns the properties of the altered line.

Markers()

Displays markers on a plot

Note: For markers/alter yarray, xarray and earray are not implemented.

Markers/Draw

Draws markers on a graphics device. If the xarray and yarray have already been defined, in either graph, histogram or markers. then it is not necessary to define them again.

Parameters:

Xarray (RealArray)

Defines the x points.

Yarray (RealArray)

Defines the y points

Colour (Colour)

Defines the markers colour.

Symbol (Marker)

Defines the style of markers. Such as $point, $plus, $star, $circle, $cross, $box.

Size (Real)

Defines the markers size.

RESULT = (OneDMarkers)

Returns the properties of the newly created markers.

Markers/Alter

Alters a set of markers. The xarray and yarray are not able to be altered at this point in time.

Parameters:

Xarray (RealArray)

Not yet implemented.

Yarray (RealArray)

Not Yet Implemented.

Colour (Colour)

Defines the markers colour.

Symbol (Marker)

Defines the style of markers. Such as $point, $plus, $star, $circle, $cross, $box.

Size (Real)

Defines the markers size.

Object (Gobject)

Shows which set of markers are to be altered, in any one window.

RESULT = (OneDMarkers)

Returns the properties of the altered markers.

Polygon()

Displays a polygon on the graphics device

Note: By default the polygon is outlined.

Polygon/Draw

Draws a polygon onto a graphics device

Parameters:

/Filled

Colours the whole of the polygon.

/Outline

Colours the perimeter of the polygon.

Xarray (RealArray)

Specifies the x co-ordinates of the polygon.

Yarray (RealArray)

Specifies the y co-ordinates of the polygon.

Colour (Colour)

Sets the colour of the polygon.

Line_thickness (Real)

Sets the line thickness of the polygon.

RESULT = (Polygon)

Returns all of the properties of the newly created polygon.

Polygon/Alter

Alters a polygon previously drawn on a graphics device.

Parameters:

/Filled

Colours the whole of the polygon.

/Outline

Colours the perimeter of the polygon.

Xarray (RealArray)

Not Yet Implemented. Specifies the x co-ordinates of the polygon.

Yarray (RealArray)

Not Yet Implemented. Specifies the y co-ordinates of the polygon.

Colour (Colour)

Sets the colour of the polygon.

Line_thickness (Real)

Sets the line thickness of the polygon.

Object (Gobject)

Shows which polygon is to be altered, in any one window.

RESULT = (Polygon)

Returns all of the properties of the altered polygon.

Text()

Displays some text on the graphics device

Text/Draw

Draws some text onto a graphics device.

Parameters:

Xcoord (Real)

X co-ordinate of the position of the text.

Ycoord (Real)

Y co-ordinate of the position of the text.

Text (String)

Text to be put onto a graphics device.

Colour (Colour)

Sets the colour of the text.

Size (Real)

Sets the size of the text.

Angle (Real)

Sets the angle for the text to be written.

Font (Font)

Sets the font of the text. Such as, $normal, $roman, $italic, $script

RESULT = (Text)

Returns all of the properties of the newly created text.

Text/Alter

Alters some text already on a graphics device.

Parameters:

Xcoord (Real)

X co-ordinate of the position of the text.

Ycoord (Real)

Y co-ordinate of the position of the text.

Text (String)

Text to be put onto a graphics device.

Colour (Colour)

Sets the colour of the text.

Size (Real)

Sets the size of the text.

Angle (Real)

Sets the angle for the text to be written.

Font (Font)

Sets the font of the text. Such as, $normal, $roman, $italic, $script

Object (Gobject)

Shows which text is to be altered, in any one window.

RESULT = (Text)

Returns all of the properties of the altered text.

Title()

Displays a Title on the graphics device

Title/Draw

Draws a title onto a graphics device.

Parameters:

Text (String)

Text to be put onto a graphics device.

Colour (Colour)

Sets the colour of the text.

Size (Real)

Sets the size of the text.

Font (Font)

Sets the font of the text. Such as, $normal, $roman, $italic, $script

RESULT = (OneDTitle)

Returns all the properties of the newly created title

Title/Alter

Alters a title on a graphics device.

Parameters:

Text (String)

Text to be put onto a graphics device.

Colour (Colour)

Sets the colour of the text.

Size (Real)

Sets the size of the text.

Font (Font)

Sets the font of the text. Such as, $normal, $roman, $italic, $script

Object (Gobject)

Shows which title is to be altered, in any one window.

RESULT = (OneDTitle)

Returns all the properties of the altered title.

Cell()

Colour cell plot for gridded data.

Cell/Draw

Draws a colour cell plot. The cell plot will transform with a transformation matrix if it is given or it will assume that the data is linear and scale to fit the axes. For non-linear grids or non-gridded data see Cell_array() and Cell_function() respectively.

Parameters:

/Smooth

Interpolate colour across each cell.

/Log

Draws a logarithmic cell plot.

/Sqrt

Draws a square root cell plot.

Values (RealArray)

Defines the cell values of the cell plot, values is a two dimensional array with sufficient data to fit the grid points.

Table (Colourtable)

Defines the colour table for the cell plot.

Tr (RealArray)

Array defining a transformation between the i, j grid of the data array and the window coordinates. The window coordinates of the array point a[i,j] are given by:

x = tr[1] + tr[2] * i + tr[3] * j
y = tr[4] + tr[5] * i + tr[6] * j

Usually tr[3] and tr[5] are zero - unless the coordinate transformation involves a rotation or shear.

The default transformation if this parameter is not specified is to map linearly onto the window to fit the plot.

Valmax (Real)

Cut off maximum above which the colour table will not be mapped.

Valmin (Real)

Cut off minimum below which the colour table will not be mapped.

RESULT = (Cell)

This returns all of the properties of the Cell plot.

Cell/Alter

Alters an already drawn cell plot.

Parameters:

/Smooth

Interpolate colour across each cell.

/Log

Draws a logarithmic cell plot.

/Sqrt

Draws a square root cell plot.

Values (RealArray)

Defines the cell values of the cell plot, values is a two dimensional array with sufficient data to fit the grid points.

Table (Colourtable)

Defines the colour table for the cell plot.

Tr (RealArray)

Array defining a transformation between the i, j grid of the data array and the window coordinates. The window coordinates of the array point a[i,j] are given by:

x = tr[1] + tr[2] * i + tr[3] * j
y = tr[4] + tr[5] * i + tr[6] * j

Usually tr[3] and tr[5] are zero - unless the coordinate transformation involves a rotation or shear.

The default transformation if this parameter is not specified is to map linearly onto the window to fit the plot.

Valmax (Real)

Cut off maximum above which the colour table will not be mapped.

Valmin (Real)

Cut off minimum below which the colour table will not be mapped.

Object (Gobject)

The cell plot to alter.

RESULT = (Cell)

This returns all of the properties of the altered Cell plot.

Cell_array()

Colour cell plot for gridded data with explicit gridding.

Cell_Array/Draw

Draws a colour cell plot where the grid is non-linear but can be still be specified by two arrays. For non-gridded data see Cell_function(), for linearly gridded data you may wish to use the Cell() primitive which automatically produces a grid.

Parameters:

/Smooth

Interpolate colour across each cell.

/Log

Draws a logarithmic cell plot.

/Sqrt

Draws a square root cell plot.

Values (RealArray)

Defines the cell values of the cell plot, values is a two dimensional array with sufficient data to fit the grid points.

Table (Colourtable)

Defines the colour table for the cell plot.

Xarray (RealArray)

Defines the x gridding of the cell_array.

Yarray (RealArray)

Defines the y gridding of the cell_array.

Valmax (Real)

Cut off maximum above which the colour table will not be mapped.

Valmin (Real)

Cut off minimum below which the colour table will not be mapped.

RESULT = (CellArray)

This returns all of the properties of the Cell_array.

Cell_Array/Alter

Alters the already created cell_array.

Parameters:

/Smooth

Interpolate colour across each cell.

/Log

Draws a logarithmic cell plot.

/Sqrt

Draws a square root cell plot.

Values (RealArray)

Defines the cell values of the cell plot, values is a two dimensional array with sufficient data to fit the grid points.

Table (Colourtable)

Defines the colour table for the cell plot.

Xarray (RealArray)

Defines the x gridding of the cell_array.

Yarray (RealArray)

Defines the y gridding of the cell_array.

Valmax (Real)

Cut off maximum above which the colour table will not be mapped.

Valmin (Real)

Cut off minimum below which the colour table will not be mapped.

Object (Gobject)

The cell_array to alter.

RESULT = (CellArray)

This returns all of the properties of the altered Cell_array.

Cell_function()

Coloured cell plot for ungridded data.

Note: Need to load user function with the Module/Load command before use.

Cell_function/Draw

Draws a colour cell plot using a user written module function to supply the location of the data points, for example a non-uniform grid for S(Q) plots. This is the most general of the colour cell plotting functions and requires that the user writes or uses a pre-existing FORTRAN module to calculate the grid for the data. For more information on writing modules, see the Module() command and also the "user notes" section of this manual. If a the function can be plotted on a linear or non-linear grid, you may be able to use the Cell() or Cell_array() commands to avoid the need to use a module.

Parameters:

/Smooth

Interpolate colour across each cell.

/Log

Draws a logarithmic cell plot.

/Sqrt

Draws a square root cell plot.

Values (RealArray)

Defines the cell values of the cell plot, values is a two dimensional array with sufficient data to fit the grid points.

Table (Colourtable)

Defines the colour table for the cell plot.

Function_name (String)

This is the function name of a function previously written and compiled in fortran.

Valmax (Real)

Cut off maximum above which the colour table will not be mapped.

Valmin (Real)

Cut off minimum below which the colour table will not be mapped.

RESULT = (CellFunction)

This returns all of the properties of the Cell_function.

Cell_function/Alter

Alters an already created cell function.

Parameters:

/Smooth

Interpolate colour across each cell.

/Log

Draws a logarithmic cell plot.

/Sqrt

Draws a square root cell plot.

Values (RealArray)

Defines the cell values of the cell plot, values is a two dimensional array with sufficient data to fit the grid points.

Table (Colourtable)

Defines the colour table for the cell plot.

Function_name (String)

This is the function name of a function previously written and compiled in fortran.

Valmax (Real)

Cut off maximum above which the colour table will not be mapped.

Valmin (Real)

Cut off minimum below which the colour table will not be mapped.

Object (Gobject)

The cell function plot to be altered.

RESULT = (CellFunction)

This returns all of the properties of the Cell_function.

Cell_wedge()

Displays a cell_wedge (colour key) on the graphics device.

Note: Must be in a separate window to the cell plot. By default the wedge is vertical.

Cell_wedge/Draw

Provides colour key annotation to a cell plot if required. The cell wedge draws either a vertical or horizontal colour key using the same colour table as the cell plot it is annotating. The cell object (either a Cell, Cell_array or Cell_function) must already exist and the object reference of the Cell plot must be supplied for the wedge to be drawn.

Parameters:

/Horizontal

The cell_wedge will be drawn horizontally.

/Vertical

The cell_wedge will be drawn vertically.

Cell (Gobject)

Give a reference to the colour cell plot for which the key is required.

RESULT = (CellWedge)

This returns all of the properties of the cell_wedge.

Cell_wedge/Alter

Alters an already created wedge.

Parameters:

/Horizontal

The cell_wedge will be drawn horizontally.

/Vertical

The cell_wedge will be drawn vertically.

Object (Gobject)

Give an object reference to the cell_wedge to be altered.

RESULT = (CellWedge)

This returns all of the properties of the altered cell_wedge.

Contour()

Makes a contour plot on the graphics device.

Note: By default the contour is linear. Use contours or ncont, not both.

Contour/Draw

Draws a contour plot of the data supplied. The contour plot should be drawn in a two-D window ( see Win_twod() ). The Contour() function is the simplest of the contouring functions and draws a contour from linearly gridded data or gridding specified by a transformation matrix. For contouring non-linnearly gridded data or non-gridded data use Contour_array() and Contour_function() respectively.

If no tranformation matrix is specified, the contour assumes linear gridding based on the window in which the data is being contoured.

Parameters:

/Log

Draws a logarithmic contour plot.

/Sqrt

Draws a square root contour plot.

Values (RealArray)

Defines the cell values of the cell plot, values is a two dimensional array with sufficient data to fit the grid points.

Contours (RealArray)

Sets the contours explicity by specifying the heights (in raw data values) of the countours. If this is specified, the number of contours will be taken from the data array and Ncont is ignored.

Ncont (Integer)

Draws ncont contours, by default, evenly spaced between Valmin and Valmax

Tr (RealArray)

Array defining a transformation between the i, j grid of the data array and the window coordinates. The window coordinates of the array point a[i,j] are given by:

x = tr[1] + tr[2] * i + tr[3] * j
y = tr[4] + tr[5] * i + tr[6] * j

Usually tr[3] and tr[5] are zero - unless the coordinate transformation involves a rotation or shear.

The default transformation if this parameter is not specified is to map linearly onto the window to fit the plot.

Colour (Colour)

Sets the contour plots colour.

Line_type (LineStyle)

Sets the line type of the contour plot. Such as $full, $dash, $dot_dash and $dot.

Line_thickness (Real)

Sets the contour plots line width.

RESULT = (Contour)

Returns all of the properties of the newly created contour plot.

Contour/Alter

Alters a contour plot previously drawn on a graphics device.

Parameters:

/Log

Draws a logarithmic contour plot.

/Sqrt

Draws a square root contour plot.

Values (RealArray)

Defines the cell values of the cell plot, values is a two dimensional array with sufficient data to fit the grid points.

Contours (RealArray)

Sets the contours explicity by specifying the heights (in raw data values) of the countours. If this is specified, the number of contours will be taken from the data array and Ncont is ignored.

Ncont (Integer)

Draws ncont contours, by default, evenly spaced between Valmin and Valmax

Tr (RealArray)

Array defining a transformation between the i, j grid of the data array and the window coordinates. The window coordinates of the array point a[i,j] are given by:

x = tr[1] + tr[2] * i + tr[3] * j
y = tr[4] + tr[5] * i + tr[6] * j

Usually tr[3] and tr[5] are zero - unless the coordinate transformation involves a rotation or shear.

The default transformation if this parameter is not specified is to map linearly onto the window to fit the plot.

Colour (Colour)

Sets the contour plots colour.

Line_type (LineStyle)

Sets the line type of the contour plot. Such as $full, $dash, $dot_dash and $dot.

Line_thickness (Real)

Sets the contour plots line width.

Object (Gobject)

Shows which contour plot is to be altered.

RESULT = (Contour)

Returns all of the properties of the altered contour plot.

Contour_array()

Plots a contour_array on the graphics device

Note: Use contours or ncont, not both.

Contour_Array/Draw

Draws a contour plot of the data supplied. The contour plot should be drawn in a two-D window ( see Win_twod() ). The Contour_array() function is for contouring with non-linnearly gridded data. For countours with linearly gridded data or non-uniform gridding use the Contour() or Contour_function() commands respectively.

Parameters:

/Log

Draws a logarithmic contours.

/Sqrt

Draws square root contours.

/Linear

Draws a linear contour array.

Values (RealArray)

Defines the cell values of the cell plot, values is a two dimensional array with sufficient data to fit the grid points.

Contours (RealArray)

Sets the contours explicity by specifying the heights (in raw data values) of the countours. If this is specified, the number of contours will be taken from the data array and Ncont is ignored.

Ncont (Integer)

Draws ncont contours, by default, evenly spaced between Valmin and Valmax

Xarray (RealArray)

Defines the x gridding of the contours.

Yarray (RealArray)

Defines the y gridding of the contours.

Colour (Colour)

Sets the contour colour.

Line_type (LineStyle)

Sets the line type of the contours. Such as $full, $dash, $dot_dash and $dot.

Line_thickness (Real)

Sets the contour line width.

RESULT = (ContourArray)

Returns all of the properties of the newly created contour array.

Contour_Array/Alter

Alters a contour array previously drawn on a graphics device.

Parameters:

/Log

Draws a logarithmic contours.

/Sqrt

Draws square root contours.

/Linear

Draws a linear contour array.

Values (RealArray)

Defines the cell values of the cell plot, values is a two dimensional array with sufficient data to fit the grid points.

Contours (RealArray)

Sets the contours explicity by specifying the heights (in raw data values) of the countours. If this is specified, the number of contours will be taken from the data array and Ncont is ignored.

Ncont (Integer)

Draws ncont contours, by default, evenly spaced between Valmin and Valmax

Xarray (RealArray)

Defines the x gridding of the contours.

Yarray (RealArray)

Defines the y gridding of the contours.

Colour (Colour)

Sets the contour colour.

Line_type (LineStyle)

Sets the line type of the contours. Such as $full, $dash, $dot_dash and $dot.

Line_thickness (Real)

Sets the contour line width.

Object (Integer)

Shows which contour array is to be altered, in any one window.

RESULT = (ContourArray)

Returns all of the properties of the altered contour array.

Contour_function()

Plots contours for ungridded data.

Note: Use contours or ncont, not both.

Contour_Function/Draw

Draws a colour cell plot using a user written module function to supply the location of the data points, for example a non-uniform grid for S(Q) plots. This is the most general of the contour plotting functions and requires that the user writes or uses a pre-existing FORTRAN module to calculate the grid for the data. For more information on writing modules, see the Module() command and also the "user notes" section of this manual. If a the function can be plotted on a linear or non-linear grid, you may be able to use the Contour() or Contour_array() commands to avoid the need to use a module.

Parameters:

/Log

Draws a logarithmic contour function.

/Sqrt

Draws a square root contour function.

Values (RealArray)

Defines the values of the contour function, values=(xarray,yarray).

Contours (RealArray)

Sets the contours explicity by specifying the heights (in raw data values) of the countours. If this is specified, the number of contours will be taken from the data array and Ncont is ignored.

Ncont (Integer)

Draws ncont contours, by default, evenly spaced between Valmin and Valmax.

Function_name (String)

This is the function name of a function previously written and compiled in fortran.

Colour (Integer)

Sets the contour functions colour.

Line_type (Integer)

Sets the line type of the contour function. Such as $full, $dash, $dot_dash and $dot.

Line_thickness (Real)

Sets the contour functions line width.

RESULT = (ContourFunction)

Returns all of the properties of the newly created contour function.

Contour_Function/Alter

Alters a contour function previously drawn on a graphics device.

Parameters:

/Log

Draws a logarithmic contour function.

/Sqrt

Draws a square root contour function.

Values (RealArray)

Defines the values of the contour function, values=(xarray,yarray).

Contours (RealArray)

Sets the contours explicity by specifying the heights (in raw data values) of the countours. If this is specified, the number of contours will be taken from the data array and Ncont is ignored.

Ncont (Integer)

Draws ncont contours, by default, evenly spaced between Valmin and Valmax.

Function_name (String)

This is the function name of a function previously written and compiled in fortran.

Colour (Integer)

Sets the contour functions colour.

Line_type (Integer)

Sets the line type of the contour function. Such as $full, $dash, $dot_dash and $dot.

Line_thickness (Real)

Sets the contour functions line width.

Object (Gobject)

The contour function plot to be altered

RESULT = (ContourFunction)

Returns all of the properties of the altered contour function.

Contour_label()

Labels the contours in the contour plot

Note: Default for text is just to give the values.

Contour_Label/Draw

Add labels to the contours of the specified contour plot. The labels may be formatted by the optional "Text" parameter if required.

Parameters:

Text (String)

Sets the format of the labels if required. The default is just to print the numbers but by adding a format string it is possible to gain full control over the label format. A "%g" in the formatting string converts numbers in general format (G format in FORTRAN). A "%f" formats in floating point (F) format and "%e" formats in scientific (E) format.

Start (Integer)

Allows label values to be specified explicitly starting here.

End (Integer)

Allows label values to be specified explicitly.

St (Integer)

Allows label values to be specified explicitly, the steps between labels here.

Intval (Integer)

The number of cells crossed by a contour before another label is drawn. Gives control over the number of labels drawn on any one contour. The default is 20.

Minint (Integer)

The minium number of cells to be crossed by a contour to justify adding a label. Contours crossing less than this number of cells will remain unlabelled. The default is 10.

Font (Font)

Sets the labels font.

Size (Real)

Sets the label size.

Colour (Colour)

Sets the label colour.

Contour (Gobject)

Specifies the contour plot for the labels to draw on.

RESULT = (ContourLabels)

Returns all of the properties of the newly created contour labels.

Contour_Label/Alter

Alters previously drawn contour labels.

Parameters:

Text (String)

Sets the format of the labels if required. The default is just to print the numbers but by adding a format string it is possible to gain full control over the label format. A "%g" in the formatting string converts numbers in general format (G format in FORTRAN). A "%f" formats in floating point (F) format and "%e" formats in scientific (E) format.

Start (Integer)

Allows label values to be specified explicitly starting here.

End (Integer)

Allows label values to be specified explicitly ending here.

St (Integer)

Allows label values to be specified explicitly, the steps between labels here..

Intval (Integer)

The number of cells crossed by a contour before another label is drawn. Gives control over the number of labels drawn on any one contour. The default is 20.

Minint (Integer)

The minium number of cells to be crossed by a contour to justify adding a label. Contours crossing less than this number of cells will remain unlabelled. The default is 10.

Font (Font)

Sets the labels font.

Size (Real)

Sets the label size.

Colour (Colour)

Sets the label colour.

Object (Gobject)

Specifies the contour label to alter.

RESULT = (ContourLabels)

Returns all of the properties of the altered contour labels.

Multi_plot()

Controls multiplot creation and plotting

Note: Multiplot window must be created after the multi_plot but before drawing.

Multi_Plot/Create

Creates a multiplot without adding the data.

Parameters:

/Bincentre

Centres the data before plotting (for point mode data)

/Notcentred

Plots the data as it is. (by default the data is not centred).

Data (RealArray)

Sets the x data points, these must be identical for all Y data

Numhist (Integer)

Sets the number of histograms wanted, otherwise defaults to all the Y arrays

Chmin (Integer)

Sets an X data minimum cutoff.

Chmax (Integer)

Sets an X data maximum cutoff.

Ygap (RealArray)

Sets an array of gap values between the data points

Colour (Colour)

Sets the colour of the multiplot.

Line_type (LineStyle)

Sets the line type of the multiplot.

Line_thickness (Integer)

Sets the line thickness of the multiplot.

RESULT = (Multiplot)

Returns all of the properties of the newly created multiplot.

Multi_plot/Spectra

Adds the all of the y data to the already created multiplot.

Parameters:

Data (RealArray or Range)

Sets the Y data. A two dimensional array with the second dimension the same as the X-array (or one less for bin-mode data). For example, x[4000] will require y[n, 4000] or y[n,3999] for histogram mode.

For an already open data file, a Range may be specified as an integer array of spectrum numbers to be read from the raw data file. See Range data type. This is used where it would not be possible to hold all of the data for the multiplot in memory.

Multi_plot/Draw

Draws the multiplot. Note that a window must be created before the Multiplot/Draw command is given but after the multiplot has been created and scaled with the Multiplot/Create and Multiplot/Spectra commands.

Multi_plot/Alter

Alters the multiplot. The ydata and xdata cannot be altered.

Parameters:

/Bincentre

Centres the data.

/Notcentred

Plots the data as it is. (by default the data is not centred).

Numhist (Integer)

Sets the number of histograms wanted.

Chmin (Integer)

Sets the data point to start from..

Chmax (Integer)

Sets the data point to finish at.

Ygap (RealArray)

Sets an array of gap values between the data points

Colour (Colour)

Sets the colour of the multiplot.

Line_type (Integer)

Sets the line type of the multiplot.

Line_thickness (Integer)

Sets the line thickness of the multiplot.

Object (Gobject)

Shows which multiplot is to be altered, in any one window.

RESULT = (Multiplot)

Returns all of the properties of the altered multiplot.

Colour()

Define a new graphics colour based on one of several models

Note: The number of simultaneous colours available depends on the display hardware.

Colour:Rgb()

Define a new colour index value given a set of RGB (Red, Green, Blue) values. The values of R, G and B are real numbers in the range 0.0-1.0.

Parameters:

r (Real)

Colour intensity value for red

g (Real)

Colour intensity value for green

b (Real)

Colour intensity value for blue

RESULT = (Colour)

Returns a colour index value which may be used instead of the fixed colours (eg $RED, $GREEN) anywhere a colour parameter is required in the Open GENIE graphics system. The index is only valid in the current Open GENIE session.

Colour:Hls()

Define a new colour index value given a set of HLS (Hue, Light, Saturation) values.

Parameters:

h (Real)

H is an angle in degrees with Blue=0.0 (or 360.0), Red=120.0, Green=240.0

l (Real)

L ranges from 0.0 (black) to 1.0 (white)

s (Real)

S ranges from 0.0 (gray) to 1.0 (pure colour)

RESULT = (Colour)

Returns a colour index value which may be used instead of the fixed colours (eg $RED, $GREEN) anywhere a colour parameter is required in the Open GENIE graphics system. The index is only valid in the current Open GENIE session.

Colour:Named()

Look up and instantiate a colour table instance of the named colour

Parameters:

Name (String)

Looks up the named colour on the display colour palette. This may change depending on the windowing system and graphics hardware so care should be taken or code using this may become device dependent.

RESULT = (Colour)

Returns a colour index value which may be used instead of the fixed colours (eg $RED, $GREEN) anywhere a colour parameter is required in the Open GENIE graphics system. The index is only valid in the current Open GENIE session.

Colourtable()

Manipulate graphics colour tables (used with Cell() commands).

Note: The data in the real arrays will be interpolated if ncolours
exceeds the number of elements in the arrays.

Colourtable:Create()

This command creates a colourtable given three arrays of colour values, one each for red, green and blue. The created colourtable will normally be used to provide a colour scale for a cell array style plot and will provide "ncolours" different colours for the plot using it, note that the colour arrays need not have ncolours elements, the colourtable command will interpolate to provide intermediate colours if necessary.

Where possible the Colourtable() command will allocate colours which are already being used to save on a potentially limited number of colour indices. As colour slots can be relatively short on some devices, it is usually a good idea to deallocate colourtables immediately after they have been used.

Parameters:

/Noshare

If this qualifiers is specified, the colourtable command avoids sharing similar colours between colourtables. The most likely use of this is if one plot is assigning colour tables with the intention of colour cycling (it would not be desireable to colour cycle any shared colours!). Note that colour slot usage will be much higher with this qualifier.

Red (RealArray)

This array specifies how much red goes into the new colour, values must be between 0.0 and 1.0.

Green (RealArray)

This array specifies how much green goes into the new colour, values must be between 0.0 and 1.0.

Blue (RealArray)

This array specifies how much blue goes into the new colour, values must be between 0.0 and 1.0.

Ncolours (Real)

Number of elements in the colour arrays.

Contrast (Real)

Allows an adjustment of the contrast by scaling each colour value by a power (default 1.0).

Brightness (Real)

Allows an adjustment of the brightness by scaling each colour by a number (default 1.0).

RESULT = (ColourTable)

Returns the newly created colour table.

Colourtable/Delete

Deallocates a previously allocated colourTable, this allows new colourTables to be allocated with the correct number of colours. (only allows 84 colours in total)

Parameters:

Table (ColourTable)

This array decides how much red goes into the new colour.

Dev()

Locates and returns device object given its index.

Dev

This is one of four functions which return a reference to a graphical object when given index information about the location of the object in the graphics object subsystem ( Dev(), Pic(), Win() and Obj() ).

Positive numbers give the number of the object in its list, starting at 1. Negative numbers give the number of the object starting from the last item in the list and counting backwards, starting at -1 (this is often the easiest way to find objects). Zero represents the last object created, normally the current object.

All open genie devices are stored in a single device list so it is only necesary to specify from a small number of devices. By default, device windows are labelled with the number of the device.

Parameters:

Devnum (Integer)

The position within the device list of the required device.

RESULT = (Gobject)

Returns the device specified.

Obj()

Locates and returns a graphics primitive object given its location.

Obj

This is one of four functions which return a reference to a graphical object when given index information about the location of the object in the graphics object subsystem ( Dev(), Pic(), Win() and Obj() ).

Positive numbers give the number of the object in its list, starting at 1. Negative numbers give the number of the object starting from the last item in the list and counting backwards, starting at -1 (this is often the easiest way to find objects). Zero represents the last object created, normally the current object.

All Open GENIE primitive graphical objects are stored within a window which itself is stored within a picture, this means that to refer to a primitive object, say a line, it is necessary to specify the index of the picture and the window in which the line was drawn. Normally references are within the current picture and window so these values can be set to zero.

Parameters:

Picnum (Integer)

The position within the picture list of the required picture.

Winnum (Integer)

The position within the window list of the required window.

Objnum (Integer)

The position within the primitive object list of the required primitive.

RESULT = (Gobject)

Returns the graphics primitive specified.

Pic()

Locates and returns a picture object given its index.

Pic

This is one of four functions which return a reference to a graphical object when given index information about the location of the object in the graphics object subsystem ( Dev(), Pic(), Win() and Obj() ).

Positive numbers give the number of the object in its list, starting at 1. Negative numbers give the number of the object starting from the last item in the list and counting backwards, starting at -1 (this is often the easiest way to find objects). Zero represents the last object created, normally the current object.

All Open GENIE pictures are stored in a single picture list, regardless of the number of devices opened (pictures may be redrawn to one or more devices using the Redraw() command).

Parameters:

Picnum (Integer)

The position within the picture list of the required picture.

RESULT = (Gobject)

Returns the picture object specified.

Pic()

Locates and returns a picture object given its index.

Pic

This is one of four functions which return a reference to a graphical object when given index information about the location of the object in the graphics object subsystem ( Dev(), Pic(), Win() and Obj() ).

Positive numbers give the number of the object in its list, starting at 1. Negative numbers give the number of the object starting from the last item in the list and counting backwards, starting at -1 (this is often the easiest way to find objects). Zero represents the last object created, normally the current object.

All Open GENIE pictures are stored in a single picture list, regardless of the number of devices opened (pictures may be redrawn to one or more devices using the Redraw() command).

Parameters:

Picnum (Integer)

The position within the picture list of the required picture.

RESULT = (Gobject)

Returns the picture object specified.

Win()

Locates and returns a graphics window object given its location.

Win

This is one of four functions which return a reference to a graphical object when given index information about the location of the object in the graphics object subsystem ( Dev(), Pic(), Win() and Obj() ).

Positive numbers give the number of the object in its list, starting at 1. Negative numbers give the number of the object starting from the last item in the list and counting backwards, starting at -1 (this is often the easiest way to find objects). Zero represents the last object created, normally the current object.

All Open GENIE window objects are stored within a picture, this means that to refer to a window, it is necessary to specify the index of the picture as well. If the window is in the current picture zero can be used for the "picnum" parameter.

Parameters:

Picnum (Integer)

The position within the picture list of the required picture.

Winnum (Integer)

The position within the window list of the required window.

RESULT = (Gobject)

Returns the graphics window specified.