| 1 |
<?xml version="1.0" encoding="UTF-8"?> |
| 2 |
<!-- |
| 3 |
(C) Copyright 1996-2016 ECMWF. |
| 4 |
|
| 5 |
This software is licensed under the terms of the Apache Licence Version 2.0 |
| 6 |
which can be obtained at http://www.apache.org/licenses/LICENSE-2.0. |
| 7 |
In applying this licence, ECMWF does not waive the privileges and immunities |
| 8 |
granted to it by virtue of its status as an intergovernmental organisation nor |
| 9 |
does it submit to any jurisdiction. |
| 10 |
--> |
| 11 |
|
| 12 |
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" |
| 13 |
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> |
| 14 |
<chapter id="MAGICS_Polylines" label="11"> |
| 15 |
<title>Polyline Plotting</title> |
| 16 |
|
| 17 |
<xi:include href="../phrases/chapterinfo_mod.xml" |
| 18 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 19 |
|
| 20 |
<section id="Polyline_Introduction"> |
| 21 |
<title>Introduction</title> |
| 22 |
|
| 23 |
<para>Polylines provide the ability to draw arbitrary polylines |
| 24 |
(polylines if not closed, polygons if closed) |
| 25 |
over a geographic area. These can be shaded or not, and various |
| 26 |
attribute parameters are available to specify their appearance. |
| 27 |
The data for polylines can come directly from arrays stored in memory |
| 28 |
or from text files of specified format. The action routine |
| 29 |
<function>PLINE</function> draws the polygons.</para> |
| 30 |
|
| 31 |
<para>Example uses of polylines include:</para> |
| 32 |
|
| 33 |
<itemizedlist> |
| 34 |
<listitem> |
| 35 |
<para>Highlighting an area of interest on a map.</para> |
| 36 |
</listitem> |
| 37 |
<listitem> |
| 38 |
<para>Colour-coding different catchement areas with shaded polygons.</para> |
| 39 |
</listitem> |
| 40 |
<listitem> |
| 41 |
<para>Shading precomputed data on an irregular grid.</para> |
| 42 |
</listitem> |
| 43 |
</itemizedlist> |
| 44 |
<important> |
| 45 |
<title>Magics++</title> |
| 46 |
Polyline plotting was introduces with Magics++ version 2.0. |
| 47 |
</important> |
| 48 |
|
| 49 |
<remark> |
| 50 |
Is polyline plotting not very similiar to mapgen boundary plotting? What are the differences? |
| 51 |
</remark> |
| 52 |
|
| 53 |
</section> <!-- Polyline_Introduction --> |
| 54 |
|
| 55 |
|
| 56 |
|
| 57 |
<section id="Polyline_Input_Data"> |
| 58 |
<title>Input Data</title> |
| 59 |
|
| 60 |
<para>Input data for polyline plotting can be passed to |
| 61 |
<productname>Magics</productname> in one of two ways: |
| 62 |
in-memory arrays or separate coordinate and value |
| 63 |
text files. In both cases, the interpretation of the data is the same: |
| 64 |
the coordinate lists contain the x and y positions for each polyline, with |
| 65 |
a special indicator, set by <parameter>POLYLINE_INPUT_BREAK_INDICATOR</parameter>, |
| 66 |
denoting the end of each polyline and hence the start of another. Any point |
| 67 |
with either an x or a y coordinate equal to this value will not be used in |
| 68 |
plotting, but will tell <productname>Magics</productname> to finish the current |
| 69 |
polyline. Subsequent data will belong to a new polyline. It follows, then, |
| 70 |
that input data should end with this break indicator. The number of |
| 71 |
polylines should be matched by the number of values. Note that |
| 72 |
<productname>Magics</productname> will not automatically close polylines - |
| 73 |
if you wish to have a closed polygon, you must duplicate the first coordinate |
| 74 |
as the last. |
| 75 |
</para> |
| 76 |
|
| 77 |
<!-- XXX how to you call PLINE multiple times? It seems you have to reset |
| 78 |
the coord/data arrays each time, though this does not always seem to work. --> |
| 79 |
|
| 80 |
<section id="Polygon_Input_Arrays"> |
| 81 |
<title>Input Data via Arrays</title> |
| 82 |
|
| 83 |
<para>It is possible to generate the polygon data in arrays |
| 84 |
and pass these to <productname>Magics</productname>. See |
| 85 |
<olink targetdoc="Magics_polyline" targetptr="Polyline_Program_Examples"/> |
| 86 |
for a full example, but here is a snippet of code which demonstrates |
| 87 |
the passing of these arrays to <productname>Magics</productname>: |
| 88 |
</para> |
| 89 |
|
| 90 |
<programlisting> |
| 91 |
CALL <function>PSET1R</function> ('<parameter>POLYLINE_INPUT_LONGITUDES</parameter>', RX, NPOINTS) |
| 92 |
CALL <function>PSET1R</function> ('<parameter>POLYLINE_INPUT_LATITUDES</parameter>', RY, NPOINTS) |
| 93 |
CALL <function>PSET1R</function> ('<parameter>POLYLINE_INPUT_VALUES</parameter>', RVALS, NPOLYS) |
| 94 |
</programlisting> |
| 95 |
|
| 96 |
</section> |
| 97 |
|
| 98 |
|
| 99 |
<section id="Polygon_Input_Files"> |
| 100 |
<title>Input Data via Files</title> |
| 101 |
|
| 102 |
<para>It is possible to pass <productname>Magics</productname> the |
| 103 |
names of two files which contain respectively the coordinates of the polygon |
| 104 |
points and the values associated with those polygons. The coordinate file |
| 105 |
is a simple text file with each point's coordinates on a separate line. |
| 106 |
The coordinates are presented as x then y, with whitespace in-between. |
| 107 |
The values file is also a simple text file; each line contains one value |
| 108 |
which is associated with the corresponding polygon. The locations of these |
| 109 |
files are presented to <productname>Magics</productname> as shown in |
| 110 |
the following code snippet:</para> |
| 111 |
|
| 112 |
<programlisting> |
| 113 |
CALL <function>PSETC</function>('<parameter>POLYLINE_INPUT_POSITIONS_FILENAME</parameter>', 'data/catchment.pos') |
| 114 |
CALL <function>PSETC</function>('<parameter>POLYLINE_INPUT_VALUES_FILENAME</parameter>', 'data/catchment.val') |
| 115 |
</programlisting> |
| 116 |
|
| 117 |
|
| 118 |
<para>A section of the positions file might look like the following. |
| 119 |
Note that this excerpt shows just the last few points from one polyline, |
| 120 |
a separator and then the first few points of a new polyline. The numbers are |
| 121 |
in scientific notation, but they need not be. In this example, |
| 122 |
<parameter>POLYLINE_INPUT_BREAK_INDICATOR</parameter> was set to -999.</para> |
| 123 |
|
| 124 |
<programlisting> |
| 125 |
2.5407444e+01 6.9562798e+01 |
| 126 |
2.5431995e+01 6.9560699e+01 |
| 127 |
2.5431995e+01 6.9560699e+01 |
| 128 |
-9.9900000e+02 -9.9900000e+02 |
| 129 |
2.8455135e+01 6.9875870e+01 |
| 130 |
2.8479740e+01 6.9873390e+01 |
| 131 |
</programlisting> |
| 132 |
|
| 133 |
<para>A section of the corresponding values file follows. Remember that |
| 134 |
in this file we have one value per polyline.</para> |
| 135 |
|
| 136 |
<programlisting> |
| 137 |
8.8014221e+00 |
| 138 |
1.7295614e+00 |
| 139 |
</programlisting> |
| 140 |
|
| 141 |
</section> |
| 142 |
|
| 143 |
</section> <!-- Polyline_Input_Data --> |
| 144 |
|
| 145 |
|
| 146 |
|
| 147 |
<section id="Polyline_Plotting"> |
| 148 |
<title>Polyline Plotting</title> |
| 149 |
|
| 150 |
<para>Plotting of polylines is in some ways similar to the plotting |
| 151 |
of contours (see <olink targetdoc="Magics_contour" targetptr="Contouring"/>).</para> |
| 152 |
|
| 153 |
|
| 154 |
<para>See <olink targetdoc="Magics_polyline" targetptr="pline_tables"/> |
| 155 |
and |
| 156 |
<olink targetdoc="Magics_polyline" targetptr="Polyline_Program_Examples"/> |
| 157 |
for details, but there are various parameters both for specifying |
| 158 |
the line plotting and the shading attributes. All polylines drawn with |
| 159 |
a single call to <function>PLINE</function> will share the same |
| 160 |
line attributes; however, they may be shaded differently if desired. |
| 161 |
Because this is a little more complicated, it is dealt with in more |
| 162 |
detail now.</para> |
| 163 |
|
| 164 |
<section id="Polyline_Shading_Bands"> |
| 165 |
<title>Polyline Shading Bands</title> |
| 166 |
|
| 167 |
<para>When polygons are shaded, they are done so according to their |
| 168 |
corresponding value. An internal table is set up which maps ranges |
| 169 |
of values to colours; each range is called a <firstterm>band</firstterm>. |
| 170 |
This table may be set up in a number of ways, |
| 171 |
and is bounded by the parameters |
| 172 |
<parameter>POLYLINE_SHADE_MIN_LEVEL</parameter> and |
| 173 |
<parameter>POLYLINE_SHADE_MAX_LEVEL</parameter>; polygons with |
| 174 |
values outside this range will not be shaded.</para> |
| 175 |
|
| 176 |
<para>To plot one level only, users should simply set the parameters |
| 177 |
<parameter>POLYLINE_MAX_LEVEL</parameter> and |
| 178 |
<parameter>POLYLINE_MIN_LEVEL</parameter> to the level required.</para> |
| 179 |
|
| 180 |
<para>There are three ways of specifying how the colour table |
| 181 |
should be generated, set with the parameter |
| 182 |
<parameter>POLYLINE_SHADE_LEVEL_SELECTION_TYPE</parameter> which can |
| 183 |
have one of the following values: <code>COUNT</code>, <code>INTERVAL</code> |
| 184 |
or <code>LEVEL_LIST</code>, described in more detail below.</para> |
| 185 |
|
| 186 |
<section id="Polyline_Count"> |
| 187 |
<title>Polyline Shading Levels Specified by 'COUNT'</title> |
| 188 |
|
| 189 |
<para>The number of shading levels may be set by the user by setting the |
| 190 |
parameter <parameter>POLYLINE_SHADE_LEVEL_SELECTION_TYPE</parameter> to |
| 191 |
'<code>COUNT</code>' (default) and |
| 192 |
<parameter>POLYLINE_LEVEL_COUNT</parameter> to the number of levels to be |
| 193 |
shaded. <productname>Magics</productname> will then calculate the |
| 194 |
size of the interval and the user's plot will consist of the number of |
| 195 |
levels specified with a regular shading interval. This is the default |
| 196 |
method and the default number of levels is 10. The exact number of |
| 197 |
levels plotted may not be |
| 198 |
<parameter>POLYLINE_LEVEL_COUNT</parameter> as <function>PLINE</function> |
| 199 |
will always use the value stored in |
| 200 |
<parameter>POLYLINE_REFERENCE_LEVEL</parameter> as a starting point and |
| 201 |
will try to pick reasonable values for the interval.</para> |
| 202 |
|
| 203 |
</section> |
| 204 |
|
| 205 |
|
| 206 |
<section id="Polyline_Levels_Selected_by_INTERVAL"> |
| 207 |
<title>Polyline Shading Levels Selected by 'INTERVAL'</title> |
| 208 |
|
| 209 |
<para>If the parameter |
| 210 |
<parameter>POLYLINE_SHADE_LEVEL_SELECTION_TYPE</parameter> is set to |
| 211 |
'<code>INTERVAL</code>', <productname>Magics</productname> will shade |
| 212 |
polygons at regularly spaced intervals using the value of |
| 213 |
<parameter>POLYLINE_REFERENCE_LEVEL</parameter> as a base and the value |
| 214 |
in <parameter>POLYLINE_INTERVAL</parameter> as the interval between |
| 215 |
levels.</para> |
| 216 |
|
| 217 |
</section> |
| 218 |
|
| 219 |
|
| 220 |
<section id="Polyline_Levels_Selected_by_LEVEL_LIST"> |
| 221 |
<title>Polyline Shading Levels Selected by 'LEVEL_LIST'</title> |
| 222 |
|
| 223 |
<para>Users may supply a list of the polygon shading levels to be plotted by |
| 224 |
setting the parameter |
| 225 |
<parameter>POLYLINE_SHADE_LEVEL_SELECTION_TYPE</parameter> to |
| 226 |
'<code>LEVEL_LIST</code>' and passing an array of level values. |
| 227 |
The passing of the array of values is achieved by calling the routine |
| 228 |
<function>PSET1R</function> thus</para> |
| 229 |
|
| 230 |
<programlisting> CALL <function>PSET1R</function>('<parameter>POLYLINE_LEVEL_LIST</parameter>',ARRAY,N) </programlisting> |
| 231 |
|
| 232 |
<para>where '<code>ARRAY</code>' is the name of the array and |
| 233 |
'<code>N</code>' is the number of values in the array. This method |
| 234 |
enables users to shade polygons with irregular intervals.</para> |
| 235 |
</section> |
| 236 |
|
| 237 |
</section> <!-- Polyline_Shading_Bands --> |
| 238 |
|
| 239 |
|
| 240 |
|
| 241 |
|
| 242 |
<section id="Polyline_Shading_Colours"> |
| 243 |
<title>Polyline Shading Colours</title> |
| 244 |
|
| 245 |
<para>Users may control the colour of the shading by setting the |
| 246 |
parameters <parameter>POLYLINE_SHADE_MAX_LEVEL_COLOUR</parameter> and |
| 247 |
<parameter>POLYLINE_SHADE_MIN_LEVEL_COLOUR</parameter> to the required |
| 248 |
values, default values being <code>BLUE</code> and <code>RED</code> |
| 249 |
respectively.</para> |
| 250 |
|
| 251 |
<para>Colour shading is performed in such a way that, starting with |
| 252 |
<parameter>POLYLINE_SHADE_MIN_LEVEL_COLOUR</parameter>, the colour of |
| 253 |
each subsequent shading band will vary from the preceding band by a |
| 254 |
factor that depends on the number of bands to be shaded.</para> |
| 255 |
|
| 256 |
<para>The colour of the last band to be shaded will be |
| 257 |
<parameter>POLYLINE_SHADE_MAX_LEVEL_COLOUR</parameter> and the shading |
| 258 |
colour of the intermediate bands will be calculated internally by |
| 259 |
modifying the hue, saturation or intensity. These may or may not be |
| 260 |
discreet colours, e.g. red, blue etc, depending on the number of bands |
| 261 |
to be shaded.</para> |
| 262 |
|
| 263 |
<para>Normally, the colour shading sequence will progress in an |
| 264 |
anti-clockwise direction, e.g. red, yellow, green, cyan, blue. The |
| 265 |
parameter <parameter>POLYLINE_SHADE_COLOUR_DIRECTION</parameter> may be |
| 266 |
set to '<code>CLOCKWISE</code>' to alter the sequence, i.e. blue, cyan, |
| 267 |
green, yellow, red. The colour sequence is circular so that it is |
| 268 |
possible, for example, to shade from green to yellow in an |
| 269 |
anti-clockwise direction or from red to green in a clockwise |
| 270 |
direction.</para> |
| 271 |
|
| 272 |
<para>Black and white are not included in the normal sequence of shading |
| 273 |
colours but are treated in a special manner. If |
| 274 |
<parameter>POLYLINE_SHADE_MIN_LEVEL_COLOUR</parameter> is set to white |
| 275 |
and <parameter>POLYLINE_SHADE_MAX_LEVEL_COLOUR</parameter> is set to one |
| 276 |
of the sequencing colours, e.g. red, the shading colour sequence will |
| 277 |
start with white and subsequent colours will be increasingly red, the |
| 278 |
last colour in the sequence being pure red. The reverse, i.e. shading |
| 279 |
from red to white, is performed in the same way, starting with red and |
| 280 |
ending with white.</para> |
| 281 |
|
| 282 |
<para>Shading between black and any other sequencing colour is treated |
| 283 |
similarly. Grey scaling can be achieved by shading from black to white |
| 284 |
or from white to black.</para> |
| 285 |
</section> <!-- Polyline_Shading_Colours --> |
| 286 |
|
| 287 |
<!-- XXX is this true??? |
| 288 |
<section id="Colour_Table_for_Polyline_Shading"> |
| 289 |
<title>Colour Table for Polyline Shading</title> |
| 290 |
|
| 291 |
<para>Users may have a different colour table for each new <productname>Magics</productname> |
| 292 |
Superpage. To achieve this, the user should set the min and max colour |
| 293 |
settings for contour shading or imaging before starting the new |
| 294 |
Superpage, e.g. <parameter>CONTOUR_SHADE_MIN_LEVEL_COLOUR</parameter> |
| 295 |
and <parameter>CONTOUR_SHADE_MAX_LEVEL_COLOUR</parameter>. It is |
| 296 |
necessary that either <function>PCONT</function>, |
| 297 |
<function>PCOAST</function> or <function>PIMAGE</function> be the first |
| 298 |
action routine called in the new Superpage.</para> |
| 299 |
</section> |
| 300 |
--> |
| 301 |
|
| 302 |
<section id="Polyline_Shade_Colour_Methods"> |
| 303 |
<title>Polyline Shade Colour Methods</title> |
| 304 |
|
| 305 |
<para>There are two methods for determining the colours to be used in |
| 306 |
polyline shading. The parameter |
| 307 |
<parameter>POLYLINE_SHADE_COLOUR_METHOD</parameter> should be used to |
| 308 |
define which method is required. Valid values are <code>LIST</code> and |
| 309 |
<code>CALCULATE</code> (default). In the default method |
| 310 |
(<code>CALCULATE</code>), the colour of bands is calculated |
| 311 |
automatically from the |
| 312 |
values in <parameter>POLYLINE_SHADE_MIN_LEVEL</parameter>, |
| 313 |
<parameter>POLYLINE_SHADE_MAX_LEVEL</parameter>, |
| 314 |
<parameter>POLYLINE_SHADE_MIN_LEVEL_COLOUR</parameter> and |
| 315 |
<parameter>POLYLINE_SHADE_MAX_LEVEL_COLOUR</parameter>.</para> |
| 316 |
|
| 317 |
<para>For manual control, the method <code>LIST</code> allows the user |
| 318 |
to pass an array of colours to be used in the shading, |
| 319 |
for example,</para> |
| 320 |
|
| 321 |
<programlisting> CALL <function>PSET1C</function>('<parameter>POLYLINE_SHADE_COLOUR_LIST</parameter>',CLIST,N)</programlisting> |
| 322 |
|
| 323 |
<para><code>CLIST</code> is an array of type character and length |
| 324 |
<code>N</code> containing a list of colours to be used in |
| 325 |
shading. The colour in <code>CLIST</code> will be used in a cyclic way: |
| 326 |
<code>CLIST(I)</code>, <code>CLIST(I+1)</code> will be used to shade the |
| 327 |
<code>I</code> th , <code>I</code>+1 th shading bands etc. |
| 328 |
<!-- XXX true?? However, if |
| 329 |
there are more bands to be shaded than there are colours in the list, |
| 330 |
the colours will be used again starting at <code>CLIST(1)</code> . If an |
| 331 |
empty array is passed in |
| 332 |
<parameter>POLYLINE_SHADE_COLOUR_LIST</parameter>, the default method |
| 333 |
(<code>CALCULATE</code>) will be used. --></para> |
| 334 |
|
| 335 |
</section> <!-- Polyline_Shade_Colour_Methods --> |
| 336 |
|
| 337 |
|
| 338 |
</section> <!-- Polyline_Plotting --> |
| 339 |
|
| 340 |
|
| 341 |
|
| 342 |
|
| 343 |
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 344 |
Parameter tables and examples |
| 345 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --> |
| 346 |
|
| 347 |
|
| 348 |
|
| 349 |
<xi:include href="../paramtables/pline_tables.xml" |
| 350 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 351 |
|
| 352 |
|
| 353 |
<section id = 'SimplePolylineInput_polyline_input_magml_all_tables'> |
| 354 |
<title>MagML Templates for Polyline Input</title> |
| 355 |
|
| 356 |
<xi:include href="../paramtables/SimplePolylineInput_polyline_input_magml_tables.xml" |
| 357 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 358 |
|
| 359 |
<xi:include href="../paramtables/SimplePolylineInput_polyline_input_magml_flat_tables.xml" |
| 360 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 361 |
</section> |
| 362 |
|
| 363 |
|
| 364 |
<section id = 'SimplePolyline_polyline_magml_all_tables'> |
| 365 |
<title>MagML Templates for Polyline Plotting</title> |
| 366 |
|
| 367 |
<xi:include href="../paramtables/SimplePolyline_polyline_magml_tables.xml" |
| 368 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 369 |
|
| 370 |
<xi:include href="../paramtables/SimplePolyline_polyline_magml_flat_tables.xml" |
| 371 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 372 |
</section> |
| 373 |
|
| 374 |
|
| 375 |
|
| 376 |
<section id="Polyline_Program_Examples"> |
| 377 |
<title>Program Examples</title> |
| 378 |
|
| 379 |
<para>The following examples demonstrate the use of polylines.</para> |
| 380 |
<para>The first example shows a set of catchement areas whose boundaries |
| 381 |
are defined in a text file. Another text file provides values for |
| 382 |
each of these areas.</para> |
| 383 |
</section> |
| 384 |
|
| 385 |
<xi:include href="../examples/manual/xml/pline_examples.xml" |
| 386 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 387 |
|
| 388 |
</chapter> |