Debian Codegraph @

docs/manual/chapters/polyline.xml

raw
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>