# Polyline Plotting

## Introduction

Polylines provide the ability to draw arbitrary polylines (polylines if not closed, polygons if closed) over a geographic area. These can be shaded or not, and various attribute parameters are available to specify their appearance. The data for polylines can come directly from arrays stored in memory or from text files of specified format. The action routine `PLINE` draws the polygons.

Example uses of polylines include:

- Highlighting an area of interest on a map.

- Colour-coding different catchement areas with shaded polygons.

- Shading precomputed data on an irregular grid.

Magics++

Polyline plotting was introduces with Magics++ version 2.0.
Is polyline plotting not very similiar to mapgen boundary plotting? What are the differences?

## Input Data

Input data for polyline plotting can be passed to Magics in one of two ways: in-memory arrays or separate coordinate and value text files. In both cases, the interpretation of the data is the same: the coordinate lists contain the x and y positions for each polyline, with a special indicator, set by POLYLINE_INPUT_BREAK_INDICATOR, denoting the end of each polyline and hence the start of another. Any point with either an x or a y coordinate equal to this value will not be used in plotting, but will tell Magics to finish the current polyline. Subsequent data will belong to a new polyline. It follows, then, that input data should end with this break indicator. The number of polylines should be matched by the number of values. Note that Magics will not automatically close polylines - if you wish to have a closed polygon, you must duplicate the first coordinate as the last.

### Input Data via Arrays

It is possible to generate the polygon data in arrays and pass these to Magics. See for a full example, but here is a snippet of code which demonstrates the passing of these arrays to Magics:

        CALL PSET1R ('POLYLINE_INPUT_LONGITUDES', RX,    NPOINTS)
        CALL PSET1R ('POLYLINE_INPUT_LATITUDES',  RY,    NPOINTS)
        CALL PSET1R ('POLYLINE_INPUT_VALUES',     RVALS, NPOLYS)

### Input Data via Files

It is possible to pass Magics the names of two files which contain respectively the coordinates of the polygon points and the values associated with those polygons. The coordinate file is a simple text file with each point's coordinates on a separate line. The coordinates are presented as x then y, with whitespace in-between. The values file is also a simple text file; each line contains one value which is associated with the corresponding polygon. The locations of these files are presented to Magics as shown in the following code snippet:

        CALL PSETC('POLYLINE_INPUT_POSITIONS_FILENAME', 'data/catchment.pos')
        CALL PSETC('POLYLINE_INPUT_VALUES_FILENAME',    'data/catchment.val')

A section of the positions file might look like the following. Note that this excerpt shows just the last few points from one polyline, a separator and then the first few points of a new polyline. The numbers are in scientific notation, but they need not be. In this example, POLYLINE_INPUT_BREAK_INDICATOR was set to -999.

       2.5407444e+01   6.9562798e+01
       2.5431995e+01   6.9560699e+01
       2.5431995e+01   6.9560699e+01
      -9.9900000e+02  -9.9900000e+02
       2.8455135e+01   6.9875870e+01
       2.8479740e+01   6.9873390e+01

A section of the corresponding values file follows. Remember that in this file we have one value per polyline.

       8.8014221e+00
       1.7295614e+00

## Polyline Plotting

Plotting of polylines is in some ways similar to the plotting of contours (see ).

See and for details, but there are various parameters both for specifying the line plotting and the shading attributes. All polylines drawn with a single call to `PLINE` will share the same line attributes; however, they may be shaded differently if desired. Because this is a little more complicated, it is dealt with in more detail now.

### Polyline Shading Bands

When polygons are shaded, they are done so according to their corresponding value. An internal table is set up which maps ranges of values to colours; each range is called a band. This table may be set up in a number of ways, and is bounded by the parameters POLYLINE_SHADE_MIN_LEVEL and POLYLINE_SHADE_MAX_LEVEL; polygons with values outside this range will not be shaded.

To plot one level only, users should simply set the parameters POLYLINE_MAX_LEVEL and POLYLINE_MIN_LEVEL to the level required.

There are three ways of specifying how the colour table should be generated, set with the parameter POLYLINE_SHADE_LEVEL_SELECTION_TYPE which can have one of the following values: `COUNT`, `INTERVAL` or `LEVEL_LIST`, described in more detail below.

#### Polyline Shading Levels Specified by 'COUNT'

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

#### Polyline Shading Levels Selected by 'INTERVAL'

If the parameter POLYLINE_SHADE_LEVEL_SELECTION_TYPE is set to '`INTERVAL`', Magics will shade polygons at regularly spaced intervals using the value of POLYLINE_REFERENCE_LEVEL as a base and the value in POLYLINE_INTERVAL as the interval between levels.

#### Polyline Shading Levels Selected by 'LEVEL_LIST'

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

        CALL PSET1R('POLYLINE_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 shade polygons with irregular intervals.

### Polyline Shading Colours

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

Colour shading is performed in such a way that, starting with POLYLINE_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 POLYLINE_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 POLYLINE_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 POLYLINE_SHADE_MIN_LEVEL_COLOUR is set to white and POLYLINE_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.

### Polyline Shade Colour Methods

There are two methods for determining the colours to be used in polyline shading. The parameter POLYLINE_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 automatically from the values in POLYLINE_SHADE_MIN_LEVEL, POLYLINE_SHADE_MAX_LEVEL, POLYLINE_SHADE_MIN_LEVEL_COLOUR and POLYLINE_SHADE_MAX_LEVEL_COLOUR.

For manual control, the method `LIST` allows the user to pass an array of colours to be used in the shading, for example,

        CALL PSET1C('POLYLINE_SHADE_COLOUR_LIST',CLIST,N)

`CLIST` is an array of type character and length `N` containing a list of colours to be used in 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.

## MagML Templates for Polyline Input

## MagML Templates for Polyline Plotting

## Program Examples

The following examples demonstrate the use of polylines.

The first example shows a set of catchement areas whose boundaries are defined in a text file. Another text file provides values for each of these areas.