Symbol Plotting
Introduction
Symbol plotting in Magics is the plotting
of different types of symbols at selected locations. A symbol in this
context is a number, a text string, a Magics
marker (see marker symbols in Figure XII-2 on page
XII-13) or a wind flag/arrow.
To plot symbols, it is necessary to pass information to
Magics that describes the symbols as well as
the positions where the symbols are to be plotted. All this information is
passed to Magics via arrays, which may consist
of one or more elements. The position of a symbol may be defined by its
geographical location (latitude/longitude), by its position in centimetres
from the bottom left hand corner of the SUBPAGE or by its position, in
axis units, within an axis system. Only those symbols whose positions are
within the subpage will be plotted. There are facilities in symbol
plotting that allow the user to control the height and colour of each
symbol and, if required, a legend describing the symbols may be plotted.
Examples of symbol plotting can be found in Symbol Program
Examples.
Action Routine PSYMB
Symbol plotting is achieved in Magics by
calling action routine PSYMB which, like all
Magics action routines, has no arguments.
Parameters associated with Symbol plotting may be set before
PSYMB is called. PSYMB will take
into account only those parameters which have been set before it is
called. All other symbol parameters will be assigned their default values,
if they exist. Details of any errors that may be detected by
PSYMB are given in SYMBOL Plotting : Error
Codes.
Methods of Symbol Plotting
There are three methods for plotting symbols: TABLE,
INDIVIDUAL and ADVANCED. The required method may be
specified by setting the parameter SYMBOL_TABLE_MODE to
'ON' (TABLE mode),
'OFF' (INDIVIDUAL mode) which is the default, or
'ADVANCED'. Following is a description of the three
different modes.
INDIVIDUAL Mode
Symbol plotting in INDIVIDUAL mode means that the
colour and height of the symbols to be plotted are controlled by the
values set in the Magics parameters
SYMBOL_COLOUR and
SYMBOL_HEIGHT. All the symbols, for each
PSYMB call, are plotted with the same colour and
height. To plot symbols in INDIVIDUAL mode the parameter
SYMBOL_TABLE_MODE should be set to
'OFF'.
TABLE Mode
TABLE mode allows users to plot symbols within specified ranges of
values and with varying colours and heights. Wind symbols are not
available in table mode. To plot symbols in TABLE mode, the parameter
SYMBOL_TABLE_MODE should be set to
'ON'. When calling PSYMB in TABLE
mode, the user must pass information to
Magics to describe the minimum and maximum of
each range required and may also pass information to describe the height
and/or colour for each of the desired ranges. All this information
should be passed in the form of tables and
Magics parameters exist to enable this.
The parameters for passing the minimum and maximum of the ranges
are SYMBOL_MIN_TABLE and
SYMBOL_MAX_TABLE, respectively. The minimum
values of the required ranges may be passed to
Magics as follows:
CALL PSET1R ('SYMBOL_MIN_TABLE',RMIN,N)
where RMIN is a real array of N
elements. The maximum values should be placed in the corresponding
elements of an array and passed to Magics as
follows:
CALL PSET1R ('SYMBOL_MAX_TABLE',RMAX,N)
where RMAX is a real array of N
elements. The colour to be used for each of the ranges may be passed
using the parameter SYMBOL_COLOUR_TABLE ,
e.g.
CALL PSET1C ('SYMBOL_COLOUR_TABLE',COLTAB,N)
where COLTAB is a character array of N
elements. Similarly, the heights for each range may be passed as
follows:
CALL PSET1R ('SYMBOL_HEIGHT_TABLE',HGTAB,N)
The input data and plotting positions required to use these tables should be passed using
the parameters described in .
Only those symbols, whose values in
SYMBOL_INPUT_NUMBER_LIST fit within one of the
specified ranges, will be plotted. To fit within a range, the values
must be greater than or equal to the minimum of the range and less than
the maximum of the range. If ranges overlap, a symbol will be plotted in
the first range in the table into which it fits.
Parameters Required in TABLE Mode
To plot symbols in table mode the parameter
SYMBOL_TABLE_MODE should be set to
'ON'. When in TABLE mode, it is necessary to pass the
information relating to the minimum and maximum of the ranges
(SYMBOL_MIN_TABLE /
SYMBOL_MAX_TABLE) as well as the input number
data (SYMBOL_INPUT_NUMBER_LIST). The tables
containing the colours and heights of the ranges
(SYMBOL_COLOUR_TABLE /
SYMBOL_HEIGHT_TABLE) may be passed if required.
If these are not passed the values set in
SYMBOL_COLOUR and
SYMBOL_HEIGHT will be used for all the
ranges.
ADVANCED Mode
Symbol plotting in ADVANCED mode means that the
colour and height of the plotted symbols are determined
automatically according to configurable rules.
First, the data values can be clumped into ranges, by setting
SYMBOL_ADVANCED_TABLE_SELECTION_TYPE to one of
the following:
COUNT: specify the number of ranges
INTERVAL: specify the data value interval size
LIST: specify a list of ranges
Also configurable is the way that the colours are selected; by setting
SYMBOL_ADVANCED_TABLE_COLOUR_METHOD to one of the following,
different strategies can be used:
CALCULATE: automatically create a colour gradient
using the HSL colour wheel
LIST: specify a user-defined list of colours
Likewise, the symbol heights can be specified in different ways by setting
SYMBOL_ADVANCED_TABLE_HEIGHT_METHOD to one of the following:
CALCULATE: automatically create a height gradient
LIST: specify a user-defined list of heights
TABLE Mode Types
TABLE mode may be used with the symbol types NUMBER, TEXT and
MARKER but not with WIND. The symbol type required must be passed by
setting the parameter SYMBOL_TYPE to one of the
above valid values. Following is a description of how each of the symbol
types is used in TABLE mode.
NUMBER Data
The minimum and maximum values of the ranges and the input NUMBER
data and position data should be passed to
Magics as described above. Each number in the
input NUMBER data will be checked against the values in the minimum and
maximum tables to find the range in which this number falls, thus
finding the appropriate index to the tables. If a colour table has been
passed to Magics, the index is used to find
the corresponding colour in the
SYMBOL_COLOUR_TABLE. Likewise, the appropriate
height may be found in SYMBOL_HEIGHT_TABLE. The
number will then be plotted at the position given by the POSITION arrays
with the colour and height extracted from the tables. If the colour
and/or height tables have not been passed, the number will be plotted
with the attributes given by SYMBOL_COLOUR and/or
SYMBOL_HEIGHT. The following are diagrams showing
the mechanism for plotting NUMBER symbols in TABLE mode
Do we really need these table examples here? Surely a couple of
good examples (code & output) would be better...
TEXT Data
To plot TEXT data in TABLE mode, a table of text strings
corresponding to the ranges required must be passed as follows:
CALL PSET1C ('SYMBOL_TEXT_TABLE',TEXTAB,N)
where TEXTAB is a character array of N
elements. The colours and heights for the various ranges and the input
data should be passed as described for NUMBER data. The mechanism for
plotting TEXT data is the same as for NUMBER data except that instead of
plotting the number the appropriate text string from
SYMBOL_TEXT_TABLE is plotted. The following are
diagrams showing the mechanism for plotting TEXT symbols in TABLE
mode.
Tables? Surely not...!
MARKER Data
The method of plotting MARKER data is the same as for TEXT data
except that markers are plotted. The user must pass a table of marker
indices corresponding to the required ranges, e.g.
CALL PSET1I ('SYMBOL_MARKER_TABLE',MTAB,N)
No tables please...!