# 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.0`cm.

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.0`cm). 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.0`cm. 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.0`cm). 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.