Layout, Mapping and Coastlines
Plot Layout - Basic Entities
The Magics plot layout facility provides
a simple means by which users can plot several maps at arbitrary positions
on the plotting page. It can also be used in a fully automatic mode,
whereby Magics will position the user's maps in
a predetermined order.
To describe Magics plot layout it is
necessary to define the naming convention for the entities that comprise
any plotted output from the system. Please refer to Diagram
III-1 throughout this description.
SUPER-PAGE , PAGE and
SUBPAGE are the entities used to define the
plotting areas in Magics:
Super-pages are defined by their X and Y
axis lengths. A super-page can be thought of as the paper sheet on
which the work will be produced. The position of the bottom left hand
corner of the super-page is (0.0, 0.0).
Pages subdivide a Super-page - any number
of pages may be defined by the user, provided they fit within the
limits of the current super-page. The position of a page on a
super-page, which can be controlled by
Magics or be defined by the user, is
relative to the bottom left hand corner of the super-page. A
user-controlled page is defined by its bottom left hand corner
position and its X and Y axis lengths.
Subpages are the smallest entity - they
can contain one chart, e.g. contours superimposed on a background map
of coast lines and grid lines. One or more subpages can be plotted on
a page, provided that they fit within the limits assigned to that
page. Subpages can be of varying sizes. A subpage is defined by the
position of its bottom left hand corner and its lengths in the
horizontal (X) and vertical (Y) directions. The position of the
subpage is relative to the bottom left hand corner of the page.
Plot Layout Default Values
Default values exist for all the plot layout parameters. The default
value for the size of the super-page is A4 (horizontal), i.e. the length
in the X direction is 29.7cm and the length in the Y direction is 21cm.
Super-pages will be placed either sequentially along the plotter paper, or
on separate sheets, depending on the output device. The default value for
the page size is A4 (horizontal), i.e. X length is 29.7cm and the Y length
is 21cm. These defaults mean that the super-page and the page are the same
size. The default values for the subpage size and position depends on
whether the user sets some of the parameters:
If the user defines one or more of the subpage size or position
parameters, then Magics assumes that all the
subpage parameters have been defined and will use the current value of
these subpage parameters to plot the subpage. In this case, if any of the
parameters are not set, the defaults are calculated as follows:
The default values for the X and Y subpage lengths are 85% of the X
and Y page lengths. This corresponds to 25.24cm and 17.85cm respectively
for the default page size. The default subpage X position is 7.5% of the X
page length and the default subpage Y position is 5% of the Y page length.
This corresponds to 2.08cm and 1.05cm for the default page size.
If the user does not define any of the subpage parameters,
Magics will set the subpage parameters to
default values that depend on the values of the current page parameters.
Using fixed percentages of the page parameters to set the subpage values
ensures that the defaulted subpage fits neatly into the page and makes
maximum use of the plotting space. The percentages used are 85% for the X
and Y lengths, 7.5% for the subpage X position and 5% for subpage Y
position.
Users should be aware that the lengths of the subpage may be
affected by the type of map that is to be plotted in the subpage.
Magics will always try to fit subpages as
neatly as possible in the user's page but the requested projection, map,
scale etc. could mean that the subpage lengths are adjusted to fit the
requested map correctly. Therefore, users should be aware that certain
mapping parameters could affect the lengths of the subpage.
Plot Layout for Pages
There are two methods of handling plot layout of pages in
Magics : 'POSITIONAL' and
'AUTOMATIC', the default being
'AUTOMATIC'.
Automatic Mode
If a user wishes to make maximum use of the plotting paper, he
may request Magics to do the plot layout
for him by putting the system in automatic mode, which is the default
positioning mode. Pages will then be positioned in an organised way,
depending on the instructions given by the user.
When in automatic mode, a user can specify three instructions
which define the type of layout required.
The user can instruct Magics to
start positioning from the bottom or top of the plotting paper by
setting the PLOT_START parameter to
'BOTTOM' or 'TOP'.
The default value for PLOT_START is
'BOTTOM'.
The direction in which plotting is required is defined by
setting the PLOT_DIRECTION parameter to
either 'HORIZONTAL' or
'VERTICAL'.
The default value for PLOT_DIRECTION
is 'VERTICAL'.
The gaps between the pages in the horizontal and vertical
directions are set by PAGE_X_GAP and
PAGE_Y_GAP.
The default values for PAGE_X_GAP and
PAGE_Y_GAP are both
0.0cm.
When PLOT_DIRECTION is set to
'VERTICAL' (default), Magics
will place the user's pages one over the other (or one under the
other, if starting at the top of the paper) until the limits of the
super-page are reached
(SUPER_PAGE_Y_LENGTH).
The next page is then placed alongside the first page in a
horizontal direction and subsequent pages are placed on top of (or
underneath) this. The mechanism is repeated until the limits of the
super-page are reached (SUPER_PAGE_X_LENGTH). A
new super-page is then allocated and the above procedure is repeated
until all the user's pages are plotted.
The gaps between the pages in both directions will be as defined
by the user (PAGE_X_GAP,
PAGE_Y_GAP) or the default values (both
0.0cm). See Diagram III-5(a) for an
example of page plotting in the vertical direction.
If the user specifies PLOT_DIRECTION as
'HORIZONTAL', Magics will
place the pages horizontally along the super-page with a gap between
the pages, as defined by the user (PAGE_X_GAP),
which defaults to 0.0cm. See Diagram
III-5(b) for an example.
When the super-page limit
(SUPER_PAGE_X_LENGTH) is reached, the next page
will be placed directly above the first page to be plotted. Subsequent
pages will be placed horizontally along the paper directly above the
first row of pages, with a gap between the rows, as defined by the
user (PAGE_Y_GAP which defaults to
0.0cm). This mechanism continues until the super-page
limits are reached. A new super-page is then allocated by
Magics and the above procedure is repeated
until all the user's pages are plotted.
The user may start at the top of the paper if required, and the
same procedure as above will apply except that the rows of pages are
in descending order. If the user requires only one row of pages, the
length of the super-page in the Y direction may be set by the user to
a value which will limit the number of pages in the Y direction to
one.
A similar mechanism can be used to limit the number of pages in
the X direction.
Positional Mode
In positional mode, the responsibility for organising the
position and size of plotted output rests with the user. He may,
however, use Magics defaults, if
suitable.
To define the position of a page, the user must define the
bottom left hand corner of the page
(PAGE_X_POSITION,
PAGE_Y_POSITION). He may also, if the default
A4 is not suitable, define the lengths of the page in the horizontal
and vertical directions (PAGE_X_LENGTH,
PAGE_Y_LENGTH).
The values given for the page position are relative to the
bottom left hand corner of the super-page. A user can define one or
more pages within a super-page, but any page or part of a page
exceeding the super-page limits will not be plotted.
The user may define a super-page by defining the length in the X
and Y directions (SUPER_PAGE_X_LENGTH,
SUPER_PAGE_Y_LENGTH). The position of the
bottom left hand corner of the super-page is always (0.0, 0.0).
Plot Layout for Subpages
Subpages may be defined within a page by defining the bottom left
hand corner of the subpage (SUBPAGE_X_POSITION,
SUBPAGE_Y_POSITION) and the lengths in the X and Y
directions (SUBPAGE_X_LENGTH,
SUBPAGE_Y_LENGTH). The values for the subpage are
relative to the bottom left hand corner of the current page.
A user may define one or more subpages within a page. When a user
defines a subpage where all or some of the subpage is outside the limits
of the current page, Magics will issue an error
message but will plot any part of the user's subpage that comes within the
limits of the page. The rest of the plot will be lost.
Pseudo Action Routine PNEW
Pseudo action routine PNEW informs
Magics that the user wishes to change from one
subpage, page or super-page to another.
No immediate action is performed when PNEW is
called, hence the name pseudo action. The change to a new subpage, page or
super-page is actually performed when the next action routine is
called.
The format of the call to PNEW is as follows:
CALL PNEW( 'key' )
where 'key' can be 'SUBPAGE', 'PAGE' or
'SUPER_PAGE'.
For example, CALL PNEW('PAGE') will cause
Magics to terminate plotting on the currently
defined page and move to the next page.
In automatic mode, the positioning of the new page is done by
Magics. In positional mode, the user must
specify the position of the next page. The actual movement to a new page
does not occur until the first action routine following the call to
PNEW. Moving from one subpage or one super-page to
another is achieved in a similar manner.
The pseudo action routine, PNEW, must be used
to change from one subpage or one page to another. It is not necessary for
users to define super-pages as Magics will do
so automatically. However, to achieve a special type of layout, users may
define their own super-page. In this case, if they wish to change from one
super-page to another before the super-page is full, they must use pseudo
action routine PNEW.
Plot Frames
By default, Magics will draw frames
around pages and subpages, but not around super-pages unless requested by
the user. Plot framing may be controlled by the user in all three
cases.
For the page and subpage, Magics allows
the user to control the colour, thickness and line style of the frame, as
well as providing facilities for turning it on and off. For the
super-page, the only control allowed is the facility for turning the frame
on and off. The parameters are summarised in Diagram III-2,
Diagram III-3 and Diagram III-6.
Page Identification Line
Magics will, by default, plot an
identification line and the ECMWF logo on the bottom of every page
plotted. The user may inhibit the plotting of these if he wishes.
The identification line consists of such items as the
Magics version number, the user's job name, the
current date and time, error numbers and an optional text string which the
user may define. The user also has control over the height and quality of
the characters in the identification line. However,
Magics defaults ensure that the height of the
characters are always reasonable.
The identification line is positioned on the bottom of each page,
starting in the bottom left hand corner. The ECMWF logo is plotted in the
bottom right hand corner of the page. Plotting of the identification line
and logo is controlled by the Magics parameter
PAGE_ID_LINE, which may be set 'ON' or
'OFF', the default being 'ON'.
The identification line can be split into 5 different parts; system
information, date/time. user text, error plotting and ECMWF logo. Each of
these parts can be turned on or off by using the following
parameters:
PAGE_ID_LINE_SYSTEM_PLOT
PAGE_ID_LINE_DATE_PLOT
PAGE_ID_LINE_USER_TEXT_PLOT
PAGE_ID_LINE_ERRORS_PLOT
PAGE_ID_LINE_LOGO_PLOT
The valid values for the above parameters are 'ON' and
'OFF', with 'ON' being the default for all five.
Any combination of the parts can be selected for plotting.
Other parameters controlling PAGE_ID_LINE
plotting are
PAGE_ID_LINE_HEIGHT
PAGE_ID_LINE_QUALITY
PAGE_ID_LINE_USER_TEXT
Magics++ 2.10
From version 2.10 onwards the option to set a USER_LOGO has been deprecated.
Users should use the PIMPORT action routine instead.
Useful Hints on Plot Layout
For plotting one field, users should use default values for
(SUBPAGE_X_POSITION,
SUBPAGE_Y_POSITION) and
(PAGE_X_POSITION,
PAGE_Y_POSITION). It is sufficient to define the
lengths of the plot, if the defaults are not suitable, i.e.
(PAGE_X_LENGTH,
PAGE_Y_LENGTH) and/or
(SUBPAGE_X_LENGTH,
SUBPAGE_Y_LENGTH).
In positional mode users can superimpose plots, one on top of the
other, by not changing the subpage, page or super-page definitions between
action routines.
Users may only change from one subpage or page to another by calling
the pseudo action routine PNEW. A change to a new
super-page can also be achieved by calling PNEW but
will happen automatically if plot layout is in automatic mode and there is
insufficient room for the next page in the current super-page.
The size of the super-page can be used to achieve the desired layout
of plots, i.e. by limiting the number of plots in the X and Y
directions.
The first action routine to be called sets up the user's subpage.
All parameters affecting the subpage definition should be set, if
required, before the first action routine is called. These parameters
include those mapping parameters with the prefix
SUBPAGE_MAP.
The lengths of the subpage may be affected by the type of map that
is to be plotted in the subpage. Magics will
always try to fit subpages as neatly as possible in the user's page but
the requested projection, map, scale etc. could mean that the subpage
lengths are adjusted to fit the requested map correctly. Therefore, users
should be aware that certain mapping parameters could affect the lengths
of the subpage.
Map projections
Four types of projections are catered for in
Magics, cylindrical (default), polar
stereographic, Mercator and satellite. Input data, especially if it is GRIB data, does not have to be in the
same projection as the generated map. Also, it is not necessary for users
to extract data for the required geographical area before passing the
input data. Magics can perform both those
functions. Magics can deal with input GRIB
data in cylindrical, polar stereographic and satellite projections but
not with Mercator. If the input field is passed in the form of an array,
Magics can only deal with cylindrical and
satellite projections.
Magics parameters exist to enable users
to specify the area, scale, etc, required. Mapping parameters have been
given the prefix SUBPAGE_MAP to remind users that
these parameters must be set before any action routines are
called.
To define the map, users should specify the projection, scale etc,
if the default values are not applicable. The parameter
SUBPAGE_MAP_PROJECTION may be set to
'CYLINDRICAL', 'POLAR_STEREOGRAPHIC',
'MERCATOR', 'TAYLOR' or
'CARTASIAN', the default being
'CYLINDRICAL'.
If SUBPAGE_MAP_PROJECTION is set to
'NONE', Magics will not apply
any projection to the user's input field.
Cylindrical and Mercator projection
An area on a cylindrical or Mercator Projection may be defined by specifying the latitude and
longitude coordinates of the lower left hand and top right hand
corners of the required area. The data for contouring for this area
may be for a smaller or larger area than the one specified but should
contain data which covers at least part of this area.
Magics can perform the extraction of data
to fit the area.
Users should always take care to ensure that the dimensions of
the subpage (SUBPAGE_X_LENGTH,
SUBPAGE_Y_LENGTH) are reasonable and
approximately match the area required.
Magics will always fit the required area to
the user's subpage in the best possible way.
Magics++
New to Magics++ is the ability to plot
an area with more than 360
degrees of longitude. By specifying an area which crosses the 180
degree 'boundary', locations of interest can be more easily studied.
Polar Stereographic Projection
If SUBPAGE_MAP_PROJECTION is set to
'POLAR_STEREOGRAPHIC', users may select a method for the
defining the area by setting SUBPAGE_MAP_AREA_DEFINITION to
'CORNERS' (default) or 'CENTRE'.
CORNERS
The first, (default) method allows users to specify the
latitude and longitude of the lower left hand corner and the upper
right hand corner of the area required. The vertical longitude may
also be specified if required.
There is no need to specify a map scale in this case as
Magics will fill the user's subpage with
the area required. Users should take care, however, to ensure that
the dimensions of the subpage
(SUBPAGE_X_LENGTH,
SUBPAGE_Y_LENGTH) are reasonable and
approximately match the area required.
Magics will always fit the required area
to the user's subpage in the best possible way.
Initially, Magics will use the
user's SUBPAGE_X_LENGTH as a basis and from
this calculate the correct map scale. It will then calculate the
correct SUBPAGE_Y_LENGTH for the map. If,
however, the calculated SUBPAGE_Y_LENGTH is
greater than the SUBPAGE_Y_LENGTH specified
by the user, Magics will calculate the
map scale and SUBPAGE_X_LENGTH based on the
defined SUBPAGE_Y_LENGTH.
This method ensures that the requested area will always fit in
the user's subpage. It also shows the importance of defining
suitable dimensions for SUBPAGE_X_LENGTH and
SUBPAGE_Y_LENGTH.
Using this method, data for contouring will usually be in
cylindrical format. MAGICS will project
the required contour lines, providing that the input data covers at
least part of the requested area. It is also possible for the input
data to be in polar stereographic format providing that it fits the
exact area to be projected.
gives full
details of input data formats.
When SUBPAGE_MAP_AREA_DEFINITION is set
to 'CORNERS', a polar stereographic map should be
defined by setting:
SUBPAGE_LOWER_LEFT_LATITUDE
SUBPAGE_LOWER_LEFT_LONGITUDE
SUBPAGE_UPPER_RIGHT_LATITUDE
SUBPAGE_UPPER_RIGHT_LONGITUDE
SUBPAGE_MAP_VERTICAL_LONGITUDE may also
be set, if desired, but setting
SUBPAGE_MAP_SCALE in this case will have no
affect on the area.
CENTRE
The second method of defining polar stereographic maps is to
specify the latitude and longitude of the centre of the area and the
scale of the map.
The default value for the scale is 50E6 (true at
60 north) and this corresponds to 500 kilometres being represented
on the map by 1cm. The vertical longitude may also be specified, if
the default (0.0) is not suitable. Users should be
aware that the selection of the vertical longitude is an important
element and will affect the area to be projected.
It is possible, by varying the vertical longitude, to rotate
an area. The area to be projected may be increased or decreased by
varying the map scale.
The lengths of the current subpage
(SUBPAGE_X_LENGTH,
SUBPAGE_Y_LENGTH), together with the map
scale and the vertical longitude will determine the actual area to
be projected onto the user's subpage.
Users should be careful in setting the map scale. If the map
scale is too large, e.g. 200E6 for full hemisphere, the
map plotted will be very small. When the map scale is too small,
e.g. 5E6 for a full hemisphere, some of the map may not
be plotted, as it may not be possible to fit it in the defined
subpage.
To be able to estimate the map scale as a function of page
size for a full polar stereographic map, the following formula may
be used.
SUBPAGE_Y_LENGTH * SUBPAGE_MAP_SCALE = 24E8
When SUBPAGE_MAP_AREA_DEFINITION is set
to 'CENTRE' a polar stereographic map may be defined by
setting SUBPAGE_MAP_CENTRE_LATITUDE and
SUBPAGE_MAP_CENTRE_LONGITUDE.
SUBPAGE_MAP_VERTICAL_LONGITUDE and
SUBPAGE_MAP_SCALE may also be defined if the
default values are not suitable.
Satellite Projection
A satellite projection is fully defined to
Magics by the information in the GRIB code
headers. It is sufficient for the user to set the parameter
SUBPAGE_MAP_PROJECTION to
'SATELLITE' and to pass the GRIB code data to
Magics.
Magics only caters for geostationary
satellite projections at present.
The satellite projection will by default make the satellite
image fill the subpage area. The user can specify a subarea
(rectangle) of the image by specifying the centre point and one corner
of the subarea, for example the bottom left hand or top right hand
corner (in latitude/longitude). The parameter
IMAGE_SUBAREA_SELECTION should be set to
'ON' if a subarea is required. The default is
'OFF' (full satellite projection).
The following parameter settings show how to plot a subarea in
the satellite projection:
CALL PSETC ('IMAGE_SUBAREA_SELECTION','ON')
CALL PSETR ('SUBPAGE_MAP_CENTRE_LONGITUDE', value)
CALL PSETR ('SUBPAGE_MAP_CENTRE_LATITUDE', value)
CALL PSETR ('SUBPAGE_MAP_CORNER_LATITUDE', value)
CALL PSETR ('SUBPAGE_MAP_CORNER_LONGITUDE', value)
Satellite projection is described fully in Chapter XIII-
Satellite Image Plotting.
Coastlines and Gridlines
Magics will project coastlines and
latitude/longitude grid lines onto requested areas, as defined by the
user.
The plotting of coastlines and grid lines is achieved by calling the
action routine PCOAST. Mapping, coastline and grid
parameters should be set, if required, before PCOAST
is called.
Parameters exist in Magics to enable
users to control the plotting of coastlines and grid lines and these
parameters should be set before PCOAST is called.
Users can control the line style, colour, shading, resolution etc of
coastlines as well as the number, colour and quality of grid lines. Users
also have control over the plotting of grid line labels.
Magics default values for coastline,
grids and labels ensure that users always achieve a reasonable plot.
However, if these default values are not suitable, users can set any or
all of the parameters to their own chosen value.
Coastline Activation
By default, coastlines are enabled, ie they are drawn
when PCOAST is called. To deactivate the coastline
drawing, set MAP_COASTLINE to 'OFF'.
Coastline Attributes
The parameters
MAP_COASTLINE_THICKNESS,
MAP_COASTLINE_STYLE and
MAP_COASTLINE_COLOUR control the coastline
thickness line style and colour respectively.
Magics++Previous versions of Magics
plotted yellow coastlines and gridlines by default. This worked well on old dark monitors,
but Magics++ has updated these defaults to black in order
to give better default plots on modern monitors and paper.
Coastline Automatic Selection
Magics++New to Magics++
is a flexible set of differing resolution coastlines. The new mechanisms are explained below.
Magics++ incorporates a new set of high-resolution coastlines which were provided by
http://www.naturalearthdata.com . By default, Magics will select an appropriate coastline
file automatically, using the lowest resolution file that will give high
quality output. This ensures high quality whilst improving speed and reducing
the size of the output file. In the majority of cases this should be
sufficient for most users' purposes.
Specifying the coastline resolution
The first parameter that can change which coastline file is used is
MAP_COASTLINE_RESOLUTION. When set to AUTOMATIC
(its default value), the coastline file will be chosen automatically as above.
The possible alternatives are LOW, MEDIUM and HIGH.
This behaviour can be overridden by manually specifying one of the existing coastline files in the Magics++
share directory by setting the MAP_COASTLINE_PATH parameter.
If you have a coastline file in another directory, you can specify
a complete path to it in the MAP_COASTLINE_PATH parameter.
Note that it is not generally recommended to use a high resolution coastline
file with a large geographical area plot - the increase in quality will be hard to see
and the increase in plotting time may be significant.
Land and Sea Shading
Magics allows the shading of the land
and sea in coastline plotting by means of two parameters
MAP_COASTLINE_LAND_SHADE and
MAP_COASTLINE_SEA_SHADE. The default value for
both is 'OFF'. If land/sea shading is required, either or
both those parameters should be set to 'ON' before
PCOAST is called. By default, land will be shaded
green and the sea blue. The user may change this by setting the
parameters MAP_COASTLINE_LAND_SHADE_COLOUR and
MAP_COASTLINE_SEA_SHADE_COLOUR to the desired
colours. Land and sea shading can be turned on or off independently
of each other.
Magics++
Previous versions of Magics could not plot
both the coast outline and shading with a single call to PCOAST -
two calls were required.
Magics++ will plot both if shading is on. To achieve the
effect of land or sea shading without the outlines visible, set the coastline colour
to be the same as the land or sea shading.
Political boundaries and rivers
Magics offers users to extend the display of coastlines
with rivers and political boundaries. The data for these services are, as with the coastlines,
taken from http://www.naturalearthdata.com . ECMWF is not responsible for the accuracy and content of the
data sets and uses as they are provided by the owners.
Gridline Parameters
To change the default grid values, users could, for example, set
MAP_GRID_LATITUDE_REFERENCE to 6.0
and MAP_GRID_LATITUDE_INCREMENT to
5.0. This would result in the latitude lines being drawn on
the map every 5 degrees using the 6 degree line as a reference, e.g. the
lines drawn could be 1, 6, 11, 16 etc. The default values for these
parameters are 0 and 10 respectively, which
results in grid lines being drawn at 0, 10, 20, 30, 40 etc. The
parameters MAP_GRID_LONGITUDE_REFERENCE and
MAP_GRID_LONGITUDE_INCREMENT perform the same
function for the map longitude.
The parameter MAP_LABEL_LATITUDE_FREQUENCY
enables users to have control over the lines on which latitude labels
appear. If this parameter is set to 4, for example, then
labels will be plotted on every fourth latitude line. The parameter
MAP_LABEL_LONGITUDE_FREQUENCY performs the same
function for the map longitude. Users may inhibit the plotting of grids
and labels by setting both the parameters,
MAP_GRID and MAP_LABEL to
'OFF', the default for both being 'ON'.
Very often, three action routines are required to plot a full map,
e.g. PCOAST, PCONT and
PTEXT. The first action routine to be called will set
up the user's subpage, on which all subsequent plotting takes place. Users
may call the action routines in any order, providing that the parameters
required have been previously set.
It is essential that mapping parameters which affect the user's
subpage, i.e. those with the prefix SUBPAGE_MAP, be
set, if required, before the first action routine is called, e.g.
SUBPAGE_LOWER_LEFT_LONGITUDE,
SUBPAGE_MAP_SCALE.