# Contouring

## Introduction

Contour mapping is a technique for the presentation of the variation of a two dimensional function. In mathematical terms, the contour at level h is the solution of the equation:

                                 f(x,y) = h

where `(x,y)` are the coordinates of a point in the plane and `f` is the function to be contoured.

In reality the function `f` is known only through observations or model output. In general the values of f are known at a set of distinct points which may be scattered irregularly in the plane. Most techniques for drawing the contour lines require values of `f` to be available on a rectangular grid. When the values of `f` are known only at scattered data points, a random-to-grid interpolation or smoothing is needed to estimate the values of f on a regular grid. The random-to-grid interpolation or smoothing can be performed in many different ways and commonly used methods are kriging, distance weighted average and natural neighbour spline interpolation.

### Contouring Methods in Magics

#### Automatic Contouring

By default, Magics automatically selects a contouring method for a particlar plot by comparing the resolution of the input data with the size of the geographic area selected and the the physical size of the page to be plotted. In the simplest case, `LINEAR` contouring is used. If the data's resolution is much higher then required, then both speed and file size are improved by using the `SAMPLE` method. If the data's resolution is too low for smooth contouring to be generated, then the `AKIMA760` what about 474? why 760?method will be used. As automatic selection is the default method, no user action is required to activate it. For completeness, the following code shows how to set it:

        CALL PSETC ('CONTOUR_METHOD', 'AUTOMATIC')

The following sections describe each of these contouring methods and how to set them manually.

#### Linear Contouring

The simplest and fastest form of contouring available in Magics is linear contouring, obtained by calling:

        CALL PSETC ('CONTOUR_METHOD', 'LINEAR')

This method is essentially a 'join-the-dots' exercise and the smoothness of the results depends on the resolution of the input data and the size of the area being contoured, ie how many points there are per cm. This method is only available for regular gridded data.

#### Akima Contouring

Magics++

With Magics++, Magics uses a new set of contouring algorithms based on a set of algorithms developed by Hiroshi Akima.

The Akima algorithms can, between them, handle regular grids, irregular grids and scattered data. They are documented in ACM Transactions on Mathematical Software.

Three of the Akima algorithms are available - Algorithms 474 and 760 handle gridded data whilst Algorithm 761 handles scattered data. The following diagram illustrates the process by which gridded data is contoured: a denser grid is created from the original, then a simple linear contouring is applied.

The Akima algorithms perform bivariate interpolation and have the accuracy of a bicubic polynomial.

The default value for CONTOUR_METHOD is '`AUTOMATIC`'. When in this mode, Magics will perform a check to compare the resolution of the input data with the size of the geographical area and the physical size of the page to be plotted. If the grid points will be sufficiently close together in the generated plot then Magics will internally use the basic linear contouring, bypassing any Akima interpolation. Otherwise, AKIMA760 will be selected and a simple algorithm used to determine the resolution of the interpolated grid; this will be based on a compromise between quality and performance, with the emphasis on quality.

The user may override this automatic mode by manually setting the parameters as illustrated in the following FORTRAN code fragment:

        CALL PSETC ('CONTOUR_METHOD', 'AKIMA760')
        CALL PSETR ('CONTOUR_AKIMA_X_RESOLUTION', 0.8)
        CALL PSETR ('CONTOUR_AKIMA_Y_RESOLUTION', 0.8)

See for further information on these parameters.

#### Sample Contouring

When plotting high resolution data on a global map, much of the detail in the data will be redundant. The '`SAMPLE`' contouring method uses just a subsample of data points. The interval (e.g. every fourth point) can be set independently for the x and y directions. The following code shows how to set it up:

        CALL PSETC ('CONTOUR_METHOD', 'SAMPLE')
        CALL PSETI ('CONTOUR_SAMPLE_X_INTERVAL', 4)
        CALL PSETI ('CONTOUR_SAMPLE_Y_INTERVAL', 4)

Magics will now use linear contouring on the subsampled data.

## Action Routine PCONT

Contouring is achieved by calling the action routine `PCONT`, i.e. `CALL PCONT` . The call may be preceded by one or more calls to Magics parameter setting routines. PCONT will only take into account those parameters set before the routine is called. Any calls to Magics parameter setting routines after `PCONT` is called are only relevant to future action routines.

If the parameter CONTOUR_SHADE is set to '`ON`' , then shading will be performed when `PCONT` is called. It is possible for users to shade selected bands in individual styles by calling `PCONT` for each band. Shading without contouring lines may also be achieved by setting the parameter CONTOUR to '`OFF`' and CONTOUR_SHADE to '`ON`' , before calling `PCONT`. If CONTOUR is set to '`ON`' and CONTOUR_SHADE is set to '`ON`', the shading will be done first.

### Data Input

When the action routine `PCONT` is called, it will plot contours based on the input data supplied and according to the user's instructions. The input data may have one of four different organizations: GRIB code data, regular latitude/longitude grid, gaussian grid or fitted data. Before `PCONT` is called, the user must define how he wants the data to be contoured, i.e. location of the data, dimensions of the array, input field organization etc. This is done by calling Magics parameter setting routines. Data may be passed in an array or in GRIB format.

To plot a contouring field users must pass the field in matrix form using the INPUT_FIELD parameter. A user can pass data as a matrix through calling:

        CALL PSET2R ('INPUT_FIELD', CARRAY, M, N)

Isotachs, which are contour lines of wind speed, can be presented to Magics as a matrix of wind speed values using the INPUT_WIND_SPEED parameter, or as a pair of U and V wind component matrices using the INPUT_WIND_U_COMPONENT and INPUT_WIND_V_COMPONENT parameters. They may also be presented in GRIB code format, in which case VORTICITY and DIVERGENCE components may also be presented.

Alternatively, the data may be passed in GRIB code format or netCDF format. A full description of data input organization is given in .

Isotachs passed as a single wind speed component:

        CALL PSETC ('CONTOUR_DATA_TRANSFORMATION', 'ISOTACHS')
        CALL PSET2R ('INPUT_WIND_SPEED', WSARRAY, M, N)

Isotachs passed as a pair of U and V wind components:

        CALL PSETC ('CONTOUR_DATA_TRANSFORMATION', 'ISOTACHS')
        CALL PSET2R ('INPUT_WIND_U_COMPONENT', WUARRAY, M, N)
        CALL PSET2R ('INPUT_WIND_V_COMPONENT', WVARRAY, M, N)

The parameter CONTOUR_DATA_TRANSFORMATION informs Magics that the data being passed is either '`NORMAL`' , which is the default, or '`ISOTACHS`' . Full details of isotachs plotting can be found in Chapter VIII- Streamline / Isotach Plotting.

## Contour Levels

Each time the action routine `PCONT` is called, it will plot a contour level or a set of contour levels based on the values assigned to the relevant Magics contour parameters, e.g. CONTOUR_INTERVAL, CONTOUR_LINE_COLOUR. `PCONT` will use the last values assigned to those parameters before it was called and will use the default value for parameters that are not set by the user. Users may assign values to the Magics contour parameters in two ways. Firstly, by calling the parameter setting routines to assign the value and, secondly, by retrieving a contour specification group. Full information concerning specification groups is contained in Chapter XVI- Specification Groups.

Default values for all the Magics contour parameters ensure that users may achieve a well presented plot without having to set any of the parameters. Facilities exist to enable the highlighting of certain contour levels, the default being to highlight every 4th level. A separate set of parameters is available for highlighting, to enable users to distinguish this feature from other levels, e.g. CONTOUR_HIGHLIGHT_COLOUR.

The setting of the parameters CONTOUR_MAX_LEVEL and CONTOUR_MIN_LEVEL will confine the plotting of contours to within these two limits. However, depending on the CONTOUR_REFERENCE_LEVEL and CONTOUR_INTERVAL chosen, the two levels specified may not be plotted but they will still be used as a maximum and minimum in all cases. The default values of CONTOUR_MAX_LEVEL and CONTOUR_MIN_LEVEL are set to very high and very low values respectively, so that normally all contours will be plotted.

To plot one contour level only, users should set the parameters CONTOUR_MAX_LEVEL and CONTOUR_MIN_LEVEL to the level required. It is not necessary, in this case, to set CONTOUR_REFERENCE_LEVEL or CONTOUR_INTERVAL.

THIS DOES NOT WORK ON 02/09/2009: Users may prevent data values beyond a certain value in the input field from being used in the calculation of contour levels, by using the suppress parameters INPUT_FIELD_SUPPRESS_ABOVE and INPUT_FIELD_SUPPRESS_BELOW. This may be necessary when the user is aware that some of his data are invalid above or below a certain value. For example, by setting INPUT_FIELD_SUPPRESS_ABOVE to `1.0E20` , all contour levels above 1.0E20 would be suppressed. Please note that the suppress parameters should only be used to suppress invalid data. If used wrongly, the data plotted may not be accurate, particularly maxima/minima values.

The parameter CONTOUR_LEVEL_SELECTION_TYPE is used to control the method which Magics uses to decide which contour levels to plot. Three valid values exist for this parameter: '`COUNT`' , '`INTERVAL`' and '`LEVEL_LIST`' , the default being '`COUNT`'.

### Contour Levels Selected by 'COUNT'

The number of contour levels may be set by the user by setting the parameter CONTOUR_LEVEL_SELECTION_TYPE to '`COUNT`' (default) and CONTOUR_LEVEL_COUNT to the number of levels to be plotted. Magics will then calculate the contour interval and the user's plot will consist of the number of levels specified with a regular contour interval. This is the default method and the default number of levels is 10. The exact number of contour levels plotted may not be CONTOUR_LEVEL_COUNT as `PCONT` will always use the value stored in CONTOUR_REFERENCE_LEVEL as a starting point and will pick reasonable values for the contour interval.

### Contour Levels Selected by 'INTERVAL'

If the parameter CONTOUR_LEVEL_SELECTION_TYPE is set to '`INTERVAL`', Magics will plot contours at regularly spaced intervals using the value of CONTOUR_REFERENCE_LEVEL as a base and the value in CONTOUR_INTERVAL as the interval between levels.

### Contour Levels Selected by 'LEVEL_LIST'

Users may supply a list of the contour levels to be plotted by setting the parameter CONTOUR_LEVEL_SELECTION_TYPE to '`LEVEL_LIST`' and passing an array of contour level values. The passing of the array of values is achieved by calling the routine `PSET1R` thus

      CALL PSET1R('CONTOUR_LEVEL_LIST',ARRAY,N)

where '`ARRAY`' is the name of the array and '`N`' is the number of values in the array. This method enables users to plot contours with irregular intervals.

## Contour Labels

The action routine `PCONT` will plot labels on contour lines either by default or as directed by the user. Contour labels may be plotted with different attributes from the contour line, e.g. colour and thickness. Contour labels are, by default, plotted on every 2nd contour line, but this may be changed by the user if desired.

THIS DOES NOT WORK AT 02/09/2009: Facilities exist to plot contour labels as numbers or text, or both. The parameter CONTOUR_LABEL_TYPE is used to control this feature. The default value is '`NUMBER`'.

If either '`TEXT`' or '`BOTH`' is specified, then the user may supply a text to be plotted on the labels by setting the parameter CONTOUR_LABEL_TEXT, the default being no label text. If '`BOTH`' is specified, then the numerical value of the label is plotted, followed by the text contained in CONTOUR_LABEL_TEXT. For example, if the level is 500 and the LABEL_TEXT is '`hPa`' , then the label will consist of '`500 hPa`'.

## Contour Maxima/Minima

Facilities exist within the action routine `PCONT` for plotting maxima/minima values. Again, these may be plotted by using the Magics defaults or as directed by the user. Maxima/minima may be plotted as text and/or as numerical values, default being symbols (`H` and `L`). The user may, by calling the parameter setting routines, plot maxima/minima values in various colours, heights, qualities etc. Users have facilities for plotting only one of these values, i.e. local maxima or local minima.

### Maxima/Minima Markers

The position of a maxima/minima value may be marked by plotting a symbol on the precise location. Users may define their own symbol by setting the parameter CONTOUR_HILO_MARKER_INDEX (see Plotting Attributes and Diagram XVII-2), or may use the default symbols (`H` or `L`).

By default, the plotting of the marker symbol is turned off but it may be activated by setting the parameter CONTOUR_HILO_MARKER to '`ON`' . The marker, if set '`ON`', is always plotted on the exact location of the maxima/minima value. The text or number is plotted above the marker. If the user requests that both text and number are plotted, as well as the marker symbol, the text is plotted above the marker and the number is plotted below.

When the marker is not plotted, the text or number is centred on the exact location of the maxima/minima value. However if both text and number are to be plotted, but no marker, the text will be plotted above the location and the number plotted below. In this case the exact location is not marked but is the midpoint between the text and the number. The size of the marker symbol may be controlled by setting the parameter CONTOUR_HILO_MARKER_HEIGHT.

### Maxima/Minima Defaults

Default values exist for all the keywords mentioned above, such as colour, height, range. Keywords associated with local maxima/minima are prefixed by the letters HILO for easy identification, e.g. CONTOUR_HILO_HEIGHT. To specify text and colour for maxima and minima, keywords exist with prefix HI for maxima and LO for minima, e.g. CONTOUR_HI_TEXT, CONTOUR_LO_COLOUR.

### Maxima/Minima Suppression

To suppress the plotting of extremes above and below certain values, the parameters CONTOUR_HILO_MAX_VALUE and CONTOUR_HILO_MIN_VALUE are used.

These values will be used to prevent the plotting of maxima/minima in the same way as CONTOUR_MAX_LEVEL and CONTOUR_MIN_LEVEL are used to prevent the plotting of contour levels. More precise control over the plotting of maxima and minima can be obtained by using the parameters CONTOUR_HI_MAX_VALUE, CONTOUR_HI_MIN_VALUE, CONTOUR_LO_MAX_VALUE and CONTOUR_LO_MIN_VALUE.

### Maxima/Minima Thinning

The extreme points (highs/lows) found by the contouring algorithm are the maxima/minima points of the fitted function, which means that their positions will not necessarily be on a grid point. The following method is used for the suppression (or thinning) of the plotting of some of the local maxima/minima points.

These steps may have changed with Magics++

1. These steps may have changed with Magics++

### Maxima/Minima Position File

It is possible to generate a geopoints file containing the positions and values of the maxima/minima by setting the parameter CONTOUR_HILO_POSITION_WRITE to '`ON` ' and specifying a filename with the parameter CONTOUR_HILO_POSITION_FILE_NAME.

## Contour Shading

Contour shading allows users to shade the areas between contour levels using various techniques and methods. This enables users to produce shading with varying intensities, patterns and colours.

Magics parameters exist to control all the features and options in shading. These parameters all start with the prefix CONTOUR_SHADE and their default values should ensure that, for most plots, a reasonable shaded plot can usually be achieved without having to set most of the shading parameters.

Shading may be requested by setting the parameter CONTOUR_SHADE to '`ON`' before calling action routine `PCONT`, the default being '`OFF`'.

### Shading Bands

The area between two contour levels to be shaded is called a shading band.

The number of bands to be shaded is determined by the number of contour levels requested and may be further controlled by setting the parameters CONTOUR_SHADE_MAX_LEVEL and CONTOUR_SHADE_MIN_LEVEL to the maximum and minimum levels required. The default value for CONTOUR_SHADE_MAX_LEVEL is one level above the highest level in the current plot and the default for CONTOUR_SHADE_MIN_LEVEL is one level below the lowest level. This means that, by default, all bands in a plot will be shaded.

The number of bands to be shaded also depends on the contour interval required and users should ensure that the maximum and minimum shading values are compatible with their contour interval. Specifically, the parameters CONTOUR_SHADE_MAX_LEVEL and CONTOUR_SHADE_MIN_LEVEL should be set to levels that will actually be contoured.

### Shading Techniques

There are three shading techniques available: `POLYGON_SHADING` (default), `CELL_SHADING` and `MARKER` shading. The required techniques should be indicated by setting the parameter CONTOUR_SHADE_TECHNIQUE to one of the above three values.

#### Polygon Shading

This is the default shading technique. The contours are formed into closed polygons and the area within the polygons are shaded.There are three shading methods used for polygon shading: `AREA_FILL`, `HATCH` and `DOT` (default).

##### AREA_FILL

`AREA_FILL` is, in fact, solid shading and will completely fill the polygons with the selected colours.

##### HATCH

`HATCH` shading is similar to `AREA_FILL` except that the polygons are filled with varying hatched shapes in the selected colours. The thickness of the hatch lines may be set with the parameter CONTOUR_SHADE_HATCH_THICKNESS , default `1`. The density of the hatch lines, i.e. the number of hatch lines per cm, may be set using the parameter CONTOUR_SHADE_HATCH_DENSITY, default `18.0`. The following figure shows the hatch shading patterns. Setting CONTOUR_SHADE_HATCH_INDEX to `1` (default) provides an automatic sequence of patterns; other values set a constant hatch pattern across all contour bands.

Figure 1 (hatch patterns). Also check for new Magics++ behaviour with hatch patterns.

##### DOT

`DOT` shading will fill the polygons with dots of varying density, size and colour.

The size of the shading dots may be defined by setting the parameter CONTOUR_SHADE_DOT_SIZE, the default being `0.02cm`. The size of the dots determines how Magics will actually draw the dots.

When the dot size is less than or equal to 0.02cm , dots are drawn as vectors with length equal to the dot size. If the dot size is greater than 0.02cm , the dots are drawn as circles with diameter equal to the dot size. If a dot size that is greater than the distance between dots is requested the dot size will be adjusted to the dot distance.

Users should be aware that large dot sizes could use more CPU time to draw than smaller dot sizes and that dot sizes of 0.1cm or more should only be used for high quality plotting.

Users may select the density of the shading dots by setting the parameters CONTOUR_SHADE_MAX_LEVEL_DENSITY and CONTOUR_SHADE_MIN_LEVEL_DENSITY to the required values. The MAX_LEVEL and MIN_LEVEL referred to here are as set in the parameters CONTOUR_SHADE_MAX_LEVEL and CONTOUR_SHADE_MIN_LEVEL. Densities are given in dots per square centimetre and the default values for the maximum and minimum densities are `50.0` and `0.0` respectively.

If more than one band is to be shaded when `PCONT` is called, the dot density for each band will be automatically calculated. The maximum density will occur in the band between CONTOUR_SHADE_MAX_LEVEL and the level immediately below it and the minimum density in the band between CONTOUR_SHADE_MIN_LEVEL and the level immediately above it. The density of dots in the bands between the minimum and maximum levels will increase progressively from minimum to maximum.

However, if the user requires the lowest band to have the highest density of dots, CONTOUR_SHADE_MIN_LEVEL_DENSITY may be set to a higher value than CONTOUR_SHADE_MAX_LEVEL_DENSITY and, in this case, the density of dots in the bands will increase progressively from maximum to minimum.

The density assigned to each band is used to calculate the distance between dots, and all the dots in that band will be equally spaced by that distance.

The actual position of the dots in a band depends on the density of dots and the angle of the shading line.

All shading dots are drawn in parallel lines where the distance between the lines is the same as the distance between dots in the band. The angle of the shading line may be defined by the user by setting CONTOUR_SHADE_ANGLE to the value required. The default value of the shading angle is 45 degrees and all shading angles are given in degrees from the horizontal in an anti-clockwise direction. The shading angle should be between 0 and 180 degrees.

#### Cell Shading

Cell shading is similar to satellite imaging and shades each cell (pixel) according to the value of the field at that cell. The colour of a cell may be interpolated from the value of the four surrounding grid points in the field or it may be set to the colour of the nearest grid point. The parameter CONTOUR_SHADE_CELL_METHOD should be set to the one of the valid values, `INTERPOLATE` or `NEAREST` (default).

The parameter CONTOUR_SHADE_CELL_RESOLUTION determines the number of cells per cm in the plot, the default being `10`. The other contour shade parameters should be used as before. Cell shading is available with all projections except, for the time being, Mercator and Satellite projections.

#### Marker Shading

Marker shading plots markers on the grid points where the colour, height and type of marker depend on the value at the grid point. This shading can be achieved by setting the following parameters:

        CALL PSET1C ('CONTOUR_SHADE_COLOUR_TABLE', CTAB, N)
        CALL PSET1R ('CONTOUR_SHADE_HEIGHT_TABLE', HTAB, N)
        CALL PSET1I ('CONTOUR_SHADE_MARKER_TABLE', MTAB, N)

where `N` is the number of values in each table. `CTAB` is a table of colours, `HTAB` is a table of heights and `MTAB` is a table of marker numbers. These tables will be associated with the bands that are to be shaded. For example, the first band to be shaded will plot markers at those grid points whose values are within the lower and upper bound of the first band. The properties of markers are controlled by the values in the first entries of each of the three tables. The shading bands should be selected in the normal way (CONTOUR_LEVEL_SELECTION_TYPE set to `INTERVAL`, `LEVEL_LIST` or `COUNT` (default)). The recommended method is to use `LEVEL_LIST` where the number of levels should be one more than the number of values in each of the three tables.

Magics++

Magics++ exhibits different behaviour to previous versions when plotting with marker shading attribute tables which have fewer entries than there are shading bands. Under old versions, the behaviour was to simply repeat the last entry in each table which was too short. Magics++ loops back to the beginning of each table, so the plotting attributes are repeated from the beginning.

If the number of table entries exceeds the number of bands, the excess table entries are not used.

### Colour Shading

Users may control the colour of the shading by setting the parameters CONTOUR_SHADE_MAX_LEVEL_COLOUR and CONTOUR_SHADE_MIN_LEVEL_COLOUR to the required values, default values being `BLUE` and `RED` respectively.

Internally, Magics defines a colour by its hue, saturation and intensity and can adjust the values of these three factors to define the colour of each shading band. It is not necessary for users to have a knowledge of hue, saturation and intensity.

Is the above paragraph still true???

<-->

Colour shading is performed in such a way that, starting with CONTOUR_SHADE_MIN_LEVEL_COLOUR, the colour of each subsequent shading band will vary from the preceding band by a factor that depends on the number of bands to be shaded.

The colour of the last band to be shaded will be CONTOUR_SHADE_MAX_LEVEL_COLOUR and the shading colour of the intermediate bands will be calculated internally by modifying the hue, saturation or intensity. These may or may not be discreet colours, e.g. red, blue etc, depending on the number of bands to be shaded.

Normally, the colour shading sequence will progress in an anti-clockwise direction, e.g. red, yellow, green, cyan, blue. The parameter CONTOUR_SHADE_COLOUR_DIRECTION may be set to '`CLOCKWISE`' to alter the sequence, i.e. blue, cyan, green, yellow, red. The colour sequence is circular so that it is possible, for example, to shade from green to yellow in an anti-clockwise direction or from red to green in a clockwise direction.

Black and white are not included in the normal sequence of shading colours but are treated in a special manner. If CONTOUR_SHADE_MIN_LEVEL_COLOUR is set to white and CONTOUR_SHADE_MAX_LEVEL_COLOUR is set to one of the sequencing colours, e.g. red, the shading colour sequence will start with white and subsequent colours will be increasingly red, the last colour in the sequence being pure red. The reverse, i.e. shading from red to white, is performed in the same way, starting with red and ending with white.

Shading between black and any other sequencing colour is treated similarly. Grey scaling can be achieved by shading from black to white or from white to black. For further information on colour shading, see NEED APPENDIX CHAPTER: Plotting Attributes and the next section (effects of MIN/MAX values in contouring and shading).

### Colour Table for Contour Shading

Users may have a different colour table for each new Magics Superpage. To achieve this, the user should set the min and max colour settings for contour shading or imaging before starting the new Superpage, e.g. CONTOUR_SHADE_MIN_LEVEL_COLOUR and CONTOUR_SHADE_MAX_LEVEL_COLOUR. It is necessary that either `PCONT`, `PCOAST` or `PIMAGE` be the first action routine called in the new Superpage.

### Contour Shade Colour Methods

There are two methods for determining the colours to be used in contour shading. The parameter CONTOUR_SHADE_COLOUR_METHOD should be used to define which method is required. Valid values are `LIST` and `CALCULATE` (default). In the default method (`CALCULATE`) the colour of bands is calculated from the values in CONTOUR_SHADE_MIN_LEVEL, CONTOUR_SHADE_MAX_LEVEL, CONTOUR_SHADE_MIN_LEVEL_COLOUR and CONTOUR_SHADE_MAX_LEVEL_COLOUR.

The new method (`LIST`) allows the use of a new parameter to pass a list of colours to be used in contour shading, i.e.,

      CALL PSET1C('CONTOUR_SHADE_COLOUR_LIST',CLIST,N)

`CLIST` is an array of type character and length `N` containing a list of colours to be used in contour shading. The colour in `CLIST` will be used in a cyclic way: `CLIST(I)`, `CLIST(I+1)` will be used to shade the `I` th , `I`+1 th shading bands etc. However, if there are more bands to be shaded than there are colours in the list, the colours will be used again starting at `CLIST(1)` . If an empty array is passed in CONTOUR_SHADE_COLOUR_LIST, the default method (`CALCULATE`) will be used.

### Label Blanking

THIS DOES NOT WORK AT 02/09/2009: Blanking of contour labels and highs and lows is performed automatically, but may be turned off by setting the parameter CONTOUR_SHADE_LABEL_BLANKING to '`OFF`', the default being '`ON`'.

### Contour Labels with Shading

Contour labels can be plotted on shaded contours when no contour lines are drawn. This is achieved by setting the Magics parameter CONTOUR to '`OFF`' and CONTOUR_LABEL to '`ON`'.

## Grid Point Value Plotting

Facilities exist for plotting the actual values of a field at the exact location of the values. The plotting of the values is controlled by the parameter CONTOUR_GRID_VALUE_PLOT. The user may also control the colour and height of the values as well as the format of the number.

Magics normally expands GRIB fields into a regular matrix, even fields coded in quasi-regular grids. When a user requests the plotting of grid point values, the values are taken from the regular matrix. It is possible to plot the quasi-regular grid point values by setting the parameter CONTOUR_GRID_VALUE_TYPE to `REDUCED`.

THIS DOES NOT WORK ON 02/09/2009: Suppressed values, i.e values above INPUT_FIELD_SUPPRESS_ABOVE and values below INPUT_FIELD_SUPPRESS_BELOW, are not plotted when plotting grid point values. This will happen automatically and there is no need to set any extra parameters.

A marker symbol may be plotted instead of (or as well as) the grid point value by setting the parameter CONTOUR_GRID_VALUE_PLOT_TYPE to '`MARKER`' (or '`BOTH`'), the default being '`VALUE`' . The relevant marker symbol may be chosen by setting the parameter CONTOUR_GRID_VALUE_MARKER_SYMBOL to the required value. The default is `3` (cross). A full list of marker symbols can be found in Diagram XVII-2 (Appendix).

The number of grid point values plotted may be controlled by selecting the frequency of the number of lines of longitude and latitude to be plotted. The parameters CONTOUR_GRID_VALUE_MIN_FREQUENCY and CONTOUR_GRID_VALUE_LAT_FREQUENCY should be used for that purpose. The default in both cases is `1`, i.e. all lines are plotted.

The setting of the parameters, CONTOUR_GRID_VALUE_MIN and CONTOUR_GRID_VALUE_MAX , will confine the plotting of grid point values to within these two limits. The default values are `-1.0E21` and `1.0E21` respectively.

## Program Examples

These examples illustrate the use of the contouring facilities in Magics.