Debian Codegraph @

docs/manual/chapters/contour.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="Contouring" label="6">
15 <title>Contouring</title>
16
17 <xi:include href="../phrases/chapterinfo_mod.xml"
18 xmlns:xi="http://www.w3.org/2001/XInclude" />
19
20 <section id="Contour_Introduction">
21 <title>Introduction</title>
22
23 <para>Contour mapping is a technique for the presentation of the variation
24 of a two dimensional function. In mathematical terms, the contour at level
25 h is the solution of the equation:</para>
26
27 <para></para>
28 <programlisting> f(x,y) = h</programlisting>
29
30 <para>where <code>(x,y)</code> are the coordinates of a point in the plane
31 and <code>f</code> is the function to be contoured.</para>
32
33 <para>In reality the function <code>f</code> is known only through
34 observations or model output. In general the values of f are known at a
35 set of distinct points which may be scattered irregularly in the plane.
36 Most techniques for drawing the contour lines require values of
37 <code>f</code> to be available on a rectangular grid. When the values of
38 <code>f</code> are known only at scattered data points, a random-to-grid
39 interpolation or smoothing is needed to estimate the values of f on a
40 regular grid. The random-to-grid interpolation or smoothing can be
41 performed in many different ways and commonly used methods are kriging,
42 distance weighted average and natural neighbour spline
43 interpolation.</para>
44
45 <section id="Contouring_Methods">
46 <title>Contouring Methods in Magics</title>
47
48 <section id="Automatic_Contouring">
49 <title>Automatic Contouring</title>
50
51 <para>By default, <productname>Magics</productname> automatically selects a contouring method
52 for a particlar plot by comparing the resolution of the input data with the size of the
53 geographic area selected and the the physical size of the page to be plotted. In the simplest
54 case, <code>LINEAR</code> contouring is used. If the data's resolution is much higher then required,
55 then both speed and file size are improved by using the <code>SAMPLE</code> method.
56 If the data's resolution is too low for smooth contouring to be generated, then the
57 <code>AKIMA760</code> <remark>what about 474? why 760?</remark>method will be used.
58 As automatic selection is the default method, no
59 user action is required to activate it. For completeness, the following code shows how to
60 set it: </para>
61
62 <programlisting>
63 CALL <function>PSETC</function> ('<parameter>CONTOUR_METHOD</parameter>', 'AUTOMATIC')
64 </programlisting>
65
66 <para>The following sections describe each of these contouring methods and how to set them manually.</para>
67
68 </section>
69
70 <section id="Linear_Contouring">
71 <title>Linear Contouring</title>
72
73 <para>The simplest and fastest form of contouring available in
74 <productname>Magics</productname> is linear contouring, obtained by
75 calling:</para>
76
77 <programlisting>
78 CALL <function>PSETC</function> ('<parameter>CONTOUR_METHOD</parameter>', 'LINEAR')
79 </programlisting>
80
81 <para>This method is essentially a 'join-the-dots' exercise and the
82 smoothness of the results depends on the resolution of the input data
83 and the size of the area being contoured, ie how many points there are
84 per cm. This method is only available for regular gridded data.</para>
85 </section>
86
87 <section id="Akima_Contouring">
88 <title>Akima Contouring</title>
89
90
91 <important> <title>Magics++</title>
92 With <productname>Magics++</productname>, <productname>Magics</productname> uses a new
93 set of contouring algorithms based on a set of algorithms developed by
94 Hiroshi Akima.</important>
95
96 <para></para>
97
98 <para>The Akima algorithms can, between them, handle regular grids,
99 irregular grids and scattered data. They are documented in <citation>ACM
100 Transactions on Mathematical Software</citation>.</para>
101
102 <para>Three of the Akima algorithms are available - Algorithms 474 and
103 760 handle gridded data whilst Algorithm 761 handles scattered data. The
104 following diagram illustrates the process by which gridded data is
105 contoured: a denser grid is created from the original, then a simple
106 linear contouring is applied.</para>
107
108 <mediaobject id="akima_diagram">
109 <imageobject role="fo">
110 <imagedata fileref="../diagrams/akima.gif" format="GIF" />
111 </imageobject>
112
113 <imageobject role="html">
114 <imagedata fileref="images/diagrams/akima.gif" format="GIF" />
115 </imageobject>
116 </mediaobject>
117
118
119 <para>The Akima algorithms perform bivariate interpolation and have the
120 accuracy of a bicubic polynomial.</para>
121
122 <para>The default value for <parameter>CONTOUR_METHOD</parameter> is
123 '<code>AUTOMATIC</code>'. When in this mode,
124 <productname>Magics</productname> will perform a check to compare the
125 resolution of the input data with the size of the geographical area and
126 the physical size of the page to be plotted. If the grid points will be
127 sufficiently close together in the generated plot then
128 <productname>Magics</productname> will internally use the basic linear
129 contouring, bypassing any Akima interpolation. Otherwise, AKIMA760 will
130 be selected and a simple algorithm used to determine the resolution of
131 the interpolated grid; this will be based on a compromise between
132 quality and performance, with the emphasis on quality.</para>
133
134 <para>The user may override this automatic mode by manually setting the
135 parameters as illustrated in the following FORTRAN code fragment:</para>
136
137 <programlisting>
138 CALL <function>PSETC</function> ('<parameter>CONTOUR_METHOD</parameter>', 'AKIMA760')
139 CALL <function>PSETR</function> ('<parameter>CONTOUR_AKIMA_X_RESOLUTION</parameter>', 0.8)
140 CALL <function>PSETR</function> ('<parameter>CONTOUR_AKIMA_Y_RESOLUTION</parameter>', 0.8)
141 </programlisting>
142
143 <para>See <olink targetdoc="Magics_contour" targetptr="table_Contour_parameters" />
144 for further information on these parameters.</para>
145 </section>
146
147 <section id="Sample_Contouring">
148 <title>Sample Contouring</title>
149
150 <para>When plotting high resolution data on a global map, much of the detail in the
151 data will be redundant. The '<code>SAMPLE</code>' contouring method uses just a subsample
152 of data points. The interval (e.g. every fourth point) can be set independently for
153 the x and y directions. The following code shows how to set it up:</para>
154
155 <programlisting>
156 CALL <function>PSETC</function> ('<parameter>CONTOUR_METHOD</parameter>', 'SAMPLE')
157 CALL <function>PSETI</function> ('<parameter>CONTOUR_SAMPLE_X_INTERVAL</parameter>', 4)
158 CALL <function>PSETI</function> ('<parameter>CONTOUR_SAMPLE_Y_INTERVAL</parameter>', 4)
159 </programlisting>
160
161 <para><productname>Magics</productname> will now use linear contouring on the
162 subsampled data.</para>
163 </section>
164 </section>
165 </section>
166
167
168 <section id="Action_Routine_PCONT">
169 <title>Action Routine PCONT</title>
170
171 <para>Contouring is achieved by calling the action routine
172 <function>PCONT</function>, i.e. <code>CALL PCONT</code> . The call may be
173 preceded by one or more calls to <productname>Magics</productname>
174 parameter setting routines. PCONT will only take into account those
175 parameters set before the routine is called. Any calls to
176 <productname>Magics</productname> parameter setting routines after
177 <function>PCONT</function> is called are only relevant to future action
178 routines.</para>
179
180 <para>If the parameter <parameter>CONTOUR_SHADE</parameter> is set to
181 '<code>ON</code>' , then shading will be performed when
182 <function>PCONT</function> is called. It is possible for users to shade
183 selected bands in individual styles by calling <function>PCONT</function>
184 for each band. Shading without contouring lines may also be achieved by
185 setting the parameter <parameter>CONTOUR</parameter> to '<code>OFF</code>'
186 and <parameter>CONTOUR_SHADE</parameter> to '<code>ON</code>' , before
187 calling <function>PCONT</function>. If <parameter>CONTOUR</parameter> is
188 set to '<code>ON</code>' and <parameter>CONTOUR_SHADE</parameter> is set
189 to '<code>ON</code>', the shading will be done first.</para>
190
191 <section id="Contour_Data_Input">
192 <title>Data Input</title>
193
194 <para>When the action routine <function>PCONT</function> is called, it
195 will plot contours based on the input data supplied and according to the
196 user's instructions. The input data may have one of four different
197 organizations: GRIB code data, regular latitude/longitude grid, gaussian
198 grid or fitted data. Before <function>PCONT</function> is called, the user
199 must define how he wants the data to be contoured, i.e. location of the
200 data, dimensions of the array, input field organization etc. This is done
201 by calling <productname>Magics</productname> parameter setting routines.
202 Data may be passed in an array or in GRIB format.</para>
203
204 <para>To plot a contouring field users must pass the field in matrix form
205 using the <parameter>INPUT_FIELD</parameter> parameter. A user can pass data as a matrix through calling:</para>
206
207 <programlisting> CALL <function>PSET2R</function> ('<parameter>INPUT_FIELD</parameter>', CARRAY, M, N)</programlisting>
208
209 <remark>
210 <para>Isotachs, which are contour lines of wind speed, can be presented to
211 <productname>Magics</productname> as a matrix of wind speed values using
212 the <parameter>INPUT_WIND_SPEED</parameter> parameter, or as a pair of U
213 and V wind component matrices using the
214 <parameter>INPUT_WIND_U_COMPONENT</parameter> and
215 <parameter>INPUT_WIND_V_COMPONENT</parameter> parameters. They may also be
216 presented in GRIB code format, in which case VORTICITY and DIVERGENCE
217 components may also be presented.</para>
218 </remark>
219
220
221 <para> Alternatively, the data may be passed in GRIB code format or netCDF format. A full description of data input organization is given in
222 <olink targetdoc="Magics_data" targetptr="Data_Input" />.</para>
223
224
225 <remark>
226 <para>Isotachs passed as a single wind speed component:</para>
227
228 <programlisting> CALL <function>PSETC</function> ('<parameter>CONTOUR_DATA_TRANSFORMATION</parameter>', 'ISOTACHS')
229 CALL <function>PSET2R</function> ('<parameter>INPUT_WIND_SPEED</parameter>', WSARRAY, M, N)</programlisting>
230
231 <para>Isotachs passed as a pair of U and V wind components:</para>
232
233 <programlisting> CALL <function>PSETC</function> ('<parameter>CONTOUR_DATA_TRANSFORMATION</parameter>', 'ISOTACHS')
234 CALL <function>PSET2R</function> ('<parameter>INPUT_WIND_U_COMPONENT</parameter>', WUARRAY, M, N)
235 CALL <function>PSET2R</function> ('<parameter>INPUT_WIND_V_COMPONENT</parameter>', WVARRAY, M, N)</programlisting>
236 </remark>
237
238
239 <remark>
240 <para>The parameter <parameter>CONTOUR_DATA_TRANSFORMATION</parameter>
241 informs <productname>Magics</productname> that the data being passed is
242 either '<code>NORMAL</code>' , which is the default, or
243 '<code>ISOTACHS</code>' . Full details of isotachs plotting can be found
244 in <remark>Chapter VIII- Streamline / Isotach Plotting</remark>.</para>
245 </remark>
246
247 </section>
248
249
250 </section>
251
252
253
254
255 <section id="Contour_Levels">
256 <title>Contour Levels</title>
257
258 <para>Each time the action routine <function>PCONT</function> is called,
259 it will plot a contour level or a set of contour levels based on the
260 values assigned to the relevant <productname>Magics</productname> contour
261 parameters, e.g. <parameter>CONTOUR_INTERVAL</parameter>,
262 <parameter>CONTOUR_LINE_COLOUR</parameter>. <function>PCONT</function>
263 will use the last values assigned to those parameters before it was called
264 and will use the default value for parameters that are not set by the
265 user.
266 <remark>
267 Users may assign values to the <productname>Magics</productname>
268 contour parameters in two ways. Firstly, by calling the parameter setting
269 routines to assign the value and, secondly, by retrieving a contour
270 specification group. Full information concerning specification groups is
271 contained in <remark>Chapter XVI- Specification Groups</remark>.
272 </remark>
273 </para>
274
275 <para>Default values for all the <productname>Magics</productname> contour
276 parameters ensure that users may achieve a well presented plot without
277 having to set any of the parameters. Facilities exist to enable the
278 highlighting of certain contour levels, the default being to highlight
279 every 4th level. A separate set of parameters is available for
280 highlighting, to enable users to distinguish this feature from other
281 levels, e.g. <parameter>CONTOUR_HIGHLIGHT_COLOUR</parameter>.</para>
282
283 <para>The setting of the parameters
284 <parameter>CONTOUR_MAX_LEVEL</parameter> and
285 <parameter>CONTOUR_MIN_LEVEL</parameter> will confine the plotting of
286 contours to within these two limits. However, depending on the
287 <parameter>CONTOUR_REFERENCE_LEVEL</parameter> and
288 <parameter>CONTOUR_INTERVAL</parameter> chosen, the two levels specified
289 may not be plotted but they will still be used as a maximum and minimum in
290 all cases. The default values of <parameter>CONTOUR_MAX_LEVEL</parameter>
291 and <parameter>CONTOUR_MIN_LEVEL</parameter> are set to very high and very
292 low values respectively, so that normally all contours will be
293 plotted.</para>
294
295 <para>To plot one contour level only, users should set the parameters
296 <parameter>CONTOUR_MAX_LEVEL</parameter> and
297 <parameter>CONTOUR_MIN_LEVEL</parameter> to the level required. It is not
298 necessary, in this case, to set
299 <parameter>CONTOUR_REFERENCE_LEVEL</parameter> or
300 <parameter>CONTOUR_INTERVAL</parameter>.</para>
301
302 <remark>
303 <para>THIS DOES NOT WORK ON 02/09/2009: Users may prevent data values beyond a certain value in the input
304 field from being used in the calculation of contour levels, by using the
305 suppress parameters <parameter>INPUT_FIELD_SUPPRESS_ABOVE</parameter> and
306 <parameter>INPUT_FIELD_SUPPRESS_BELOW</parameter>. This may be necessary
307 when the user is aware that some of his data are invalid above or below a
308 certain value. For example, by setting
309 <parameter>INPUT_FIELD_SUPPRESS_ABOVE</parameter> to <code>1.0E20</code> ,
310 all contour levels above 1.0E20 would be suppressed. Please note that the
311 suppress parameters should only be used to suppress invalid data. If used
312 wrongly, the data plotted may not be accurate, particularly maxima/minima
313 values.</para>
314 </remark>
315
316 <para>The parameter <parameter>CONTOUR_LEVEL_SELECTION_TYPE</parameter> is
317 used to control the method which <productname>Magics</productname> uses to
318 decide which contour levels to plot. Three valid values exist for this
319 parameter: '<code>COUNT</code>' , '<code>INTERVAL</code>' and
320 '<code>LEVEL_LIST</code>' , the default being '<code>COUNT</code>'.</para>
321
322 <section id="Contour_Levels_Selected_by_COUNT">
323 <title>Contour Levels Selected by 'COUNT'</title>
324
325 <para>The number of contour levels may be set by the user by setting the
326 parameter <parameter>CONTOUR_LEVEL_SELECTION_TYPE</parameter> to
327 '<code>COUNT</code>' (default) and
328 <parameter>CONTOUR_LEVEL_COUNT</parameter> to the number of levels to be
329 plotted. <productname>Magics</productname> will then calculate the
330 contour interval and the user's plot will consist of the number of
331 levels specified with a regular contour interval. This is the default
332 method and the default number of levels is 10. The exact number of
333 contour levels plotted may not be
334 <parameter>CONTOUR_LEVEL_COUNT</parameter> as <function>PCONT</function>
335 will always use the value stored in
336 <parameter>CONTOUR_REFERENCE_LEVEL</parameter> as a starting point and
337 will pick reasonable values for the contour interval.</para>
338 </section>
339
340 <section id="Contour_Levels_Selected_by_INTERVAL">
341 <title>Contour Levels Selected by 'INTERVAL'</title>
342
343 <para>If the parameter
344 <parameter>CONTOUR_LEVEL_SELECTION_TYPE</parameter> is set to
345 '<code>INTERVAL</code>', <productname>Magics</productname> will plot
346 contours at regularly spaced intervals using the value of
347 <parameter>CONTOUR_REFERENCE_LEVEL</parameter> as a base and the value
348 in <parameter>CONTOUR_INTERVAL</parameter> as the interval between
349 levels.</para>
350
351 </section>
352
353 <section id="Contour_Levels_Selected_by_LEVEL_LIST">
354 <title>Contour Levels Selected by 'LEVEL_LIST'</title>
355
356 <para>Users may supply a list of the contour levels to be plotted by
357 setting the parameter
358 <parameter>CONTOUR_LEVEL_SELECTION_TYPE</parameter> to
359 '<code>LEVEL_LIST</code>' and passing an array of contour level values.
360 The passing of the array of values is achieved by calling the routine
361 <function>PSET1R</function> thus</para>
362
363 <programlisting> CALL <function>PSET1R</function>('<parameter>CONTOUR_LEVEL_LIST</parameter>',ARRAY,N) </programlisting>
364
365 <para>where '<code>ARRAY</code>' is the name of the array and
366 '<code>N</code>' is the number of values in the array. This method
367 enables users to plot contours with irregular intervals.</para>
368 </section>
369
370 <!--
371 <section id="Plotting_of_Split_Contour_Levels">
372 <title>Plotting of Split Contour Levels</title>
373
374 <para />
375
376 <highlights>
377 <para>Need new description here since it looks like this will be
378 deprecated in Magics++.</para>
379 </highlights>
380 </section>
381 -->
382 </section>
383
384 <section id="Contour_Labels">
385 <title>Contour Labels</title>
386
387 <para>The action routine <function>PCONT</function> will plot labels on
388 contour lines either by default or as directed by the user. Contour labels
389 may be plotted with different attributes from the contour line, e.g.
390 colour and thickness. Contour labels are, by default, plotted on every 2nd
391 contour line, but this may be changed by the user if desired.</para>
392
393 <remark>
394 <para>THIS DOES NOT WORK AT 02/09/2009: Facilities exist to plot contour labels as numbers or text, or both.
395 The parameter <parameter>CONTOUR_LABEL_TYPE</parameter> is used to control
396 this feature. The default value is '<code>NUMBER</code>'.</para>
397
398 <para>If either '<code>TEXT</code>' or '<code>BOTH</code>' is specified,
399 then the user may supply a text to be plotted on the labels by setting the
400 parameter <parameter>CONTOUR_LABEL_TEXT</parameter>, the default being no
401 label text. If '<code>BOTH</code>' is specified, then the numerical value
402 of the label is plotted, followed by the text contained in
403 <parameter>CONTOUR_LABEL_TEXT</parameter>. For example, if the level is
404 500 and the <parameter>LABEL_TEXT</parameter> is '<code>hPa</code>' , then
405 the label will consist of '<code>500 hPa</code>'.</para>
406 </remark>
407
408 </section>
409
410 <section id="Maxima_Minima">
411 <title id="Contour_Maxima_Minima">Contour Maxima/Minima</title>
412
413 <para>Facilities exist within the action routine
414 <function>PCONT</function> for plotting maxima/minima values. Again, these
415 may be plotted by using the <productname>Magics</productname> defaults or
416 as directed by the user. Maxima/minima may be plotted as text and/or as
417 numerical values, default being symbols (<code>H</code> and
418 <code>L</code>). The user may, by calling the parameter setting routines,
419 plot maxima/minima values in various colours, heights, qualities etc.
420 Users have facilities for plotting only one of these values, i.e. local
421 maxima or local minima.</para>
422
423 <section id="Maxima_Minima_Markers">
424 <title>Maxima/Minima Markers</title>
425
426 <para>The position of a maxima/minima value may be marked by plotting a
427 symbol on the precise location. Users may define their own symbol by
428 setting the parameter <parameter>CONTOUR_HILO_MARKER_INDEX</parameter>
429 (<remark>see Plotting Attributes and Diagram XVII-2</remark>), or may
430 use the default symbols (<code>H</code> or <code>L</code>).</para>
431
432 <para>By default, the plotting of the marker symbol is turned off but it
433 may be activated by setting the parameter
434 <parameter>CONTOUR_HILO_MARKER</parameter> to '<code>ON</code>' . The
435 marker, if set '<code>ON</code>', is always plotted on the exact
436 location of the maxima/minima value. The text or number is plotted above
437 the marker. If the user requests that both text and number are plotted,
438 as well as the marker symbol, the text is plotted above the marker and
439 the number is plotted below.</para>
440
441 <para>When the marker is not plotted, the text or number is centred on
442 the exact location of the maxima/minima value. However if both text and
443 number are to be plotted, but no marker, the text will be plotted above
444 the location and the number plotted below. In this case the exact
445 location is not marked but is the midpoint between the text and the
446 number. The size of the marker symbol may be controlled by setting the
447 parameter <parameter>CONTOUR_HILO_MARKER_HEIGHT</parameter>.</para>
448 </section>
449
450 <section id="Maxima_Minima_Defaults">
451 <title>Maxima/Minima Defaults</title>
452
453 <para>Default values exist for all the keywords mentioned above, such as
454 colour, height, range. Keywords associated with local maxima/minima are
455 prefixed by the letters <parameter>HILO</parameter> for easy
456 identification, e.g. <parameter>CONTOUR_HILO_HEIGHT</parameter>. To
457 specify text and colour for maxima and minima, keywords exist with
458 prefix <parameter>HI</parameter> for maxima and
459 <parameter>LO</parameter> for minima, e.g.
460 <parameter>CONTOUR_HI_TEXT</parameter>,
461 <parameter>CONTOUR_LO_COLOUR</parameter>.</para>
462 </section>
463
464 <section id="Maxima_Minima_Suppression">
465 <title>Maxima/Minima Suppression</title>
466
467 <para>To suppress the plotting of extremes above and below certain
468 values, the parameters <parameter>CONTOUR_HILO_MAX_VALUE</parameter> and
469 <parameter>CONTOUR_HILO_MIN_VALUE</parameter> are used.</para>
470
471 <para>These values will be used to prevent the plotting of maxima/minima
472 in the same way as <parameter>CONTOUR_MAX_LEVEL</parameter> and
473 <parameter>CONTOUR_MIN_LEVEL</parameter> are used to prevent the
474 plotting of contour levels. More precise control over the plotting of
475 maxima and minima can be obtained by using the parameters
476 <parameter>CONTOUR_HI_MAX_VALUE</parameter>,
477 <parameter>CONTOUR_HI_MIN_VALUE</parameter>,
478 <parameter>CONTOUR_LO_MAX_VALUE</parameter> and
479 <parameter>CONTOUR_LO_MIN_VALUE</parameter>.</para>
480
481 <para />
482 </section>
483
484 <remark>
485 <section id="Maxima_Minima_Thinning">
486 <title>Maxima/Minima Thinning</title>
487
488 <para>The extreme points (highs/lows) found by the contouring algorithm
489 are the maxima/minima points of the fitted function, which means that
490 their positions will not necessarily be on a grid point. The following
491 method is used for the suppression (or thinning) of the plotting of some
492 of the local maxima/minima points.</para>
493
494 <highlights>
495 <para>These steps may have changed with Magics++</para>
496 </highlights>
497
498 <orderedlist>
499 <listitem>
500 <para>These steps may have changed with Magics++</para>
501 </listitem>
502 </orderedlist>
503 </section>
504 </remark>
505
506 <section id="Maxima_Minima_Position_File">
507 <title>Maxima/Minima Position File</title>
508
509 <para>It is possible to generate a geopoints file containing the
510 positions and values of the maxima/minima by setting the parameter
511 <parameter>CONTOUR_HILO_POSITION_WRITE</parameter> to '<code>ON</code> '
512 and specifying a filename with the parameter
513 <parameter>CONTOUR_HILO_POSITION_FILE_NAME</parameter>.</para>
514 </section>
515 </section>
516
517 <section id="Contour_Shading">
518 <title>Contour Shading</title>
519
520 <para>Contour shading allows users to shade the areas between contour
521 levels using various techniques and methods. This enables users to produce
522 shading with varying intensities, patterns and colours.</para>
523
524 <para><productname>Magics</productname> parameters exist to control all
525 the features and options in shading. These parameters all start with the
526 prefix <parameter>CONTOUR_SHADE</parameter> and their default values
527 should ensure that, for most plots, a reasonable shaded plot can usually
528 be achieved without having to set most of the shading parameters.</para>
529
530 <para>Shading may be requested by setting the parameter
531 <parameter>CONTOUR_SHADE</parameter> to '<code>ON</code>' before calling
532 action routine <function>PCONT</function>, the default being
533 '<code>OFF</code>'.</para>
534
535 <section id="Shading_Bands">
536 <title>Shading Bands</title>
537
538 <para>The area between two contour levels to be shaded is called a
539 <firstterm>shading band</firstterm>.</para>
540
541 <para>The number of bands to be shaded is determined by the number of
542 contour levels requested and may be further controlled by setting the
543 parameters <parameter>CONTOUR_SHADE_MAX_LEVEL</parameter> and
544 <parameter>CONTOUR_SHADE_MIN_LEVEL</parameter> to the maximum and
545 minimum levels required. The default value for
546 <parameter>CONTOUR_SHADE_MAX_LEVEL</parameter> is one level above the
547 highest level in the current plot and the default for
548 <parameter>CONTOUR_SHADE_MIN_LEVEL</parameter> is one level below the
549 lowest level. This means that, by default, all bands in a plot will be
550 shaded.</para>
551
552 <para>The number of bands to be shaded also depends on the contour
553 interval required and users should ensure that the maximum and minimum
554 shading values are compatible with their contour interval. Specifically,
555 the parameters <parameter>CONTOUR_SHADE_MAX_LEVEL</parameter> and
556 <parameter>CONTOUR_SHADE_MIN_LEVEL</parameter> should be set to levels
557 that will actually be contoured.</para>
558 </section>
559
560 <section id="Shading_Techniques">
561 <title>Shading Techniques</title>
562
563 <para>There are three shading techniques available:
564 <code>POLYGON_SHADING</code> (default), <code>CELL_SHADING</code> and
565 <code>MARKER</code> shading. The required techniques should be indicated
566 by setting the parameter <parameter>CONTOUR_SHADE_TECHNIQUE</parameter>
567 to one of the above three values.</para>
568
569 <section id="Polygon_Shading">
570 <title>Polygon Shading</title>
571
572 <para>This is the default shading technique. The contours are formed
573 into closed polygons and the area within the polygons are shaded.There
574 are three shading methods used for polygon shading:
575 <code>AREA_FILL</code>, <code>HATCH</code> and <code>DOT</code>
576 (default).</para>
577
578 <section id="Area_Fill_Shading">
579 <title>AREA_FILL</title>
580
581 <para><code>AREA_FILL</code> is, in fact, solid shading and will
582 completely fill the polygons with the selected colours.</para>
583 </section>
584
585 <section id="Hatch_Shading">
586 <title>HATCH</title>
587
588 <para><code>HATCH</code> shading is similar to
589 <code>AREA_FILL</code> except that the polygons are filled with
590 varying hatched shapes in the selected colours. The thickness of the
591 hatch lines may be set with the parameter
592 <parameter>CONTOUR_SHADE_HATCH_THICKNESS</parameter> , default
593 <code>1</code>. The density of the hatch lines, i.e. the number of
594 hatch lines per cm, may be set using the parameter
595 <parameter>CONTOUR_SHADE_HATCH_DENSITY</parameter>, default
596 <code>18.0</code>. The following figure shows the hatch shading
597 patterns. Setting <parameter>CONTOUR_SHADE_HATCH_INDEX</parameter>
598 to <code>1</code> (default) provides an automatic sequence of
599 patterns; other values set a constant hatch pattern across all
600 contour bands.</para>
601
602 <remark>
603 <para>Figure 1 (hatch patterns). Also check for new Magics++
604 behaviour with hatch patterns.</para>
605 </remark>
606 </section>
607
608 <section id="DOT">
609 <title>DOT</title>
610
611 <para><code>DOT</code> shading will fill the polygons with dots of
612 varying density, size and colour.</para>
613
614 <para>The size of the shading dots may be defined by setting the
615 parameter <parameter>CONTOUR_SHADE_DOT_SIZE</parameter>, the default
616 being <code>0.02cm</code>. The size of the dots determines how
617 <productname>Magics</productname> will actually draw the
618 dots.</para>
619
620 <para>When the dot size is less than or equal to 0.02cm , dots are
621 drawn as vectors with length equal to the dot size. If the dot size
622 is greater than 0.02cm , the dots are drawn as circles with diameter
623 equal to the dot size. If a dot size that is greater than the
624 distance between dots is requested the dot size will be adjusted to
625 the dot distance.</para>
626
627 <para>Users should be aware that large dot sizes could use more CPU
628 time to draw than smaller dot sizes and that dot sizes of 0.1cm or
629 more should only be used for high quality plotting.</para>
630
631 <para>Users may select the density of the shading dots by setting
632 the parameters
633 <parameter>CONTOUR_SHADE_MAX_LEVEL_DENSITY</parameter> and
634 <parameter>CONTOUR_SHADE_MIN_LEVEL_DENSITY</parameter> to the
635 required values. The <parameter>MAX_LEVEL</parameter> and
636 <parameter>MIN_LEVEL</parameter> referred to here are as set in the
637 parameters <parameter>CONTOUR_SHADE_MAX_LEVEL</parameter> and
638 <parameter>CONTOUR_SHADE_MIN_LEVEL</parameter>. Densities are given
639 in dots per square centimetre and the default values for the maximum
640 and minimum densities are <code>50.0</code> and <code>0.0</code>
641 respectively.</para>
642
643 <para>If more than one band is to be shaded when
644 <function>PCONT</function> is called, the dot density for each band
645 will be automatically calculated. The maximum density will occur in
646 the band between <parameter>CONTOUR_SHADE_MAX_LEVEL</parameter> and
647 the level immediately below it and the minimum density in the band
648 between <parameter>CONTOUR_SHADE_MIN_LEVEL</parameter> and the level
649 immediately above it. The density of dots in the bands between the
650 minimum and maximum levels will increase progressively from minimum
651 to maximum.</para>
652
653 <para>However, if the user requires the lowest band to have the
654 highest density of dots,
655 <parameter>CONTOUR_SHADE_MIN_LEVEL_DENSITY</parameter> may be set to
656 a higher value than
657 <parameter>CONTOUR_SHADE_MAX_LEVEL_DENSITY</parameter> and, in this
658 case, the density of dots in the bands will increase progressively
659 from maximum to minimum.</para>
660
661 <para>The density assigned to each band is used to calculate the
662 distance between dots, and all the dots in that band will be equally
663 spaced by that distance.</para>
664
665 <para>The actual position of the dots in a band depends on the
666 density of dots and the angle of the shading line.</para>
667
668 <para>All shading dots are drawn in parallel lines where the
669 distance between the lines is the same as the distance between dots
670 in the band. The angle of the shading line may be defined by the
671 user by setting <parameter>CONTOUR_SHADE_ANGLE</parameter> to the
672 value required. The default value of the shading angle is 45 degrees
673 and all shading angles are given in degrees from the horizontal in
674 an anti-clockwise direction. The shading angle should be between 0
675 and 180 degrees.</para>
676
677 </section>
678 </section>
679
680 <section id="Cell_Shading">
681 <title>Cell Shading</title>
682
683 <para>Cell shading is similar to satellite imaging and shades each
684 cell (pixel) according to the value of the field at that cell. The
685 colour of a cell may be interpolated from the value of the four
686 surrounding grid points in the field or it may be set to the colour of
687 the nearest grid point. The parameter
688 <parameter>CONTOUR_SHADE_CELL_METHOD</parameter> should be set to the
689 one of the valid values, <code>INTERPOLATE</code> or
690 <code>NEAREST</code> (default).</para>
691
692 <para>The parameter
693 <parameter>CONTOUR_SHADE_CELL_RESOLUTION</parameter> determines the
694 number of cells per cm in the plot, the default being <code>10</code>.
695 The other contour shade parameters should be used as before. Cell
696 shading is available with all projections except, for the time being,
697 Mercator and Satellite projections.</para>
698 </section>
699
700 <section id="Marker_Shading">
701 <title>Marker Shading</title>
702
703 <para>Marker shading plots markers on the grid points where the
704 colour, height and type of marker depend on the value at the grid
705 point. This shading can be achieved by setting the following
706 parameters:</para>
707
708 <programlisting>
709 CALL <function>PSET1C</function> ('<parameter>CONTOUR_SHADE_COLOUR_TABLE</parameter>', CTAB, N)
710 CALL <function>PSET1R</function> ('<parameter>CONTOUR_SHADE_HEIGHT_TABLE</parameter>', HTAB, N)
711 CALL <function>PSET1I</function> ('<parameter>CONTOUR_SHADE_MARKER_TABLE</parameter>', MTAB, N)</programlisting>
712
713 <para>where <code>N</code> is the number of values in each table.
714 <code>CTAB</code> is a table of colours, <code>HTAB</code> is a table
715 of heights and <code>MTAB</code> is a table of marker numbers. These
716 tables will be associated with the bands that are to be shaded. For
717 example, the first band to be shaded will plot markers at those grid
718 points whose values are within the lower and upper bound of the first
719 band. The properties of markers are controlled by the values in the
720 first entries of each of the three tables. The shading bands should be
721 selected in the normal way
722 (<parameter>CONTOUR_LEVEL_SELECTION_TYPE</parameter> set to
723 <code>INTERVAL</code>, <code>LEVEL_LIST</code> or <code>COUNT</code>
724 (default)). The recommended method is to use <code>LEVEL_LIST</code>
725 where the number of levels should be one more than the number of
726 values in each of the three tables.</para>
727
728 <important id="Marker_Shading_Differences"> <title>Magics++</title>
729 <productname>Magics++</productname> exhibits different behaviour to previous versions
730 when plotting with marker shading attribute tables which have fewer entries than
731 there are shading bands. Under old versions, the behaviour was to simply repeat the
732 last entry in each table which was too short. <productname>Magics++</productname>
733 loops back to the beginning of each table, so the plotting attributes are repeated
734 from the beginning.
735 </important>
736
737 <para>If the number of table entries exceeds the
738 number of bands, the excess table entries are not used.</para>
739
740 </section>
741 </section>
742
743 <section id="Colour_Shading">
744 <title>Colour Shading</title>
745
746 <para>Users may control the colour of the shading by setting the
747 parameters <parameter>CONTOUR_SHADE_MAX_LEVEL_COLOUR</parameter> and
748 <parameter>CONTOUR_SHADE_MIN_LEVEL_COLOUR</parameter> to the required
749 values, default values being <code>BLUE</code> and <code>RED</code>
750 respectively.</para>
751
752 <para>Internally, <productname>Magics</productname> defines a colour by
753 its hue, saturation and intensity and can adjust the values of these
754 three factors to define the colour of each shading band. It is not
755 necessary for users to have a knowledge of hue, saturation and
756 intensity.</para>
757
758 <!-->
759 <para>Is the above paragraph still true???</para>
760 <-->
761
762 <para>Colour shading is performed in such a way that, starting with
763 <parameter>CONTOUR_SHADE_MIN_LEVEL_COLOUR</parameter>, the colour of
764 each subsequent shading band will vary from the preceding band by a
765 factor that depends on the number of bands to be shaded.</para>
766
767 <para>The colour of the last band to be shaded will be
768 <parameter>CONTOUR_SHADE_MAX_LEVEL_COLOUR</parameter> and the shading
769 colour of the intermediate bands will be calculated internally by
770 modifying the hue, saturation or intensity. These may or may not be
771 discreet colours, e.g. red, blue etc, depending on the number of bands
772 to be shaded.</para>
773
774 <para>Normally, the colour shading sequence will progress in an
775 anti-clockwise direction, e.g. red, yellow, green, cyan, blue. The
776 parameter <parameter>CONTOUR_SHADE_COLOUR_DIRECTION</parameter> may be
777 set to '<code>CLOCKWISE</code>' to alter the sequence, i.e. blue, cyan,
778 green, yellow, red. The colour sequence is circular so that it is
779 possible, for example, to shade from green to yellow in an
780 anti-clockwise direction or from red to green in a clockwise
781 direction.</para>
782
783 <para>Black and white are not included in the normal sequence of shading
784 colours but are treated in a special manner. If
785 <parameter>CONTOUR_SHADE_MIN_LEVEL_COLOUR</parameter> is set to white
786 and <parameter>CONTOUR_SHADE_MAX_LEVEL_COLOUR</parameter> is set to one
787 of the sequencing colours, e.g. red, the shading colour sequence will
788 start with white and subsequent colours will be increasingly red, the
789 last colour in the sequence being pure red. The reverse, i.e. shading
790 from red to white, is performed in the same way, starting with red and
791 ending with white.</para>
792
793 <para>Shading between black and any other sequencing colour is treated
794 similarly. Grey scaling can be achieved by shading from black to white
795 or from white to black. For further information on colour shading,
796 see <remark>NEED APPENDIX CHAPTER: Plotting Attributes and </remark> the next section (effects
797 of MIN/MAX values in contouring and shading).</para>
798 </section>
799
800 <section id="Colour_Table_for_Contour_Shading">
801 <title>Colour Table for Contour Shading</title>
802
803 <para>Users may have a different colour table for each new Magics
804 Superpage. To achieve this, the user should set the min and max colour
805 settings for contour shading or imaging before starting the new
806 Superpage, e.g. <parameter>CONTOUR_SHADE_MIN_LEVEL_COLOUR</parameter>
807 and <parameter>CONTOUR_SHADE_MAX_LEVEL_COLOUR</parameter>. It is
808 necessary that either <function>PCONT</function>,
809 <function>PCOAST</function> or <function>PIMAGE</function> be the first
810 action routine called in the new Superpage.</para>
811 </section>
812
813 <section id="Contour_Shade_Colour_Methods">
814 <title>Contour Shade Colour Methods</title>
815
816 <para>There are two methods for determining the colours to be used in
817 contour shading. The parameter
818 <parameter>CONTOUR_SHADE_COLOUR_METHOD</parameter> should be used to
819 define which method is required. Valid values are <code>LIST</code> and
820 <code>CALCULATE</code> (default). In the default method
821 (<code>CALCULATE</code>) the colour of bands is calculated from the
822 values in <parameter>CONTOUR_SHADE_MIN_LEVEL</parameter>,
823 <parameter>CONTOUR_SHADE_MAX_LEVEL</parameter>,
824 <parameter>CONTOUR_SHADE_MIN_LEVEL_COLOUR</parameter> and
825 <parameter>CONTOUR_SHADE_MAX_LEVEL_COLOUR</parameter>.</para>
826
827 <para>The new method (<code>LIST</code>) allows the use of a
828 new parameter to pass a list of colours to be used in contour shading,
829 i.e.,</para>
830
831 <programlisting> CALL <function>PSET1C</function>('<parameter>CONTOUR_SHADE_COLOUR_LIST</parameter>',CLIST,N)</programlisting>
832
833 <para><code>CLIST</code> is an array of type character and length
834 <code>N</code> containing a list of colours to be used in contour
835 shading. The colour in <code>CLIST</code> will be used in a cyclic way:
836 <code>CLIST(I)</code>, <code>CLIST(I+1)</code> will be used to shade the
837 <code>I</code> th , <code>I</code>+1 th shading bands etc. However, if
838 there are more bands to be shaded than there are colours in the list,
839 the colours will be used again starting at <code>CLIST(1)</code> . If an
840 empty array is passed in
841 <parameter>CONTOUR_SHADE_COLOUR_LIST</parameter>, the default method
842 (<code>CALCULATE</code>) will be used.</para>
843 </section>
844
845 <remark>
846 <section id="Contour_Label_Blanking">
847 <title>Label Blanking</title>
848
849 <para>THIS DOES NOT WORK AT 02/09/2009: Blanking of contour labels and highs and lows is performed
850 automatically, but may be turned off by setting the parameter
851 <parameter>CONTOUR_SHADE_LABEL_BLANKING</parameter> to
852 '<code>OFF</code>', the default being '<code>ON</code>'.</para>
853 </section>
854 </remark>
855
856 <section id="Contour_Labels_with_Shading">
857 <title>Contour Labels with Shading</title>
858
859 <para>Contour labels can be plotted on shaded contours when no contour
860 lines are drawn. This is achieved by setting the
861 <productname>Magics</productname> parameter
862 <parameter>CONTOUR</parameter> to '<code>OFF</code>' and
863 <parameter>CONTOUR_LABEL</parameter> to '<code>ON</code>'.</para>
864 </section>
865
866 <!--
867 <section id="Contour_CPU_Time">
868 <title>CPU Time</title>
869
870 <para>Users should be aware that certain factors can affect the amount
871 of CPU time required for shading. <code>DOT</code> shading requires more
872 CPU time than either <code>AREA_FILL</code> or
873 <code>HATCH</code>.</para>
874
875 <para>The following factors are the ones most likely to be
876 time-consuming: the physical size of the user's subpage, the number of
877 shading bands, the density and size of dots requested (if using
878 <code>DOT</code> shading) and the blanking of labels. Users should take
879 care to ensure that these factors have reasonable values.</para>
880
881 <highlights>
882 <para>Is the above still true?</para>
883 </highlights>
884 </section>
885 -->
886 </section>
887
888 <section id="Grid_Point_Value_Plotting">
889 <title>Grid Point Value Plotting</title>
890
891 <para>Facilities exist for plotting the actual values of a field at the
892 exact location of the values. The plotting of the values is controlled by
893 the parameter <parameter>CONTOUR_GRID_VALUE_PLOT</parameter>. The user may
894 also control the colour and height of the values as well as the format of
895 the number.</para>
896
897 <para><productname>Magics</productname> normally expands GRIB fields into
898 a regular matrix, even fields coded in quasi-regular grids. When a user
899 requests the plotting of grid point values, the values are taken from the
900 regular matrix. It is possible to plot the quasi-regular grid point values
901 by setting the parameter <parameter>CONTOUR_GRID_VALUE_TYPE</parameter> to
902 <code>REDUCED</code>.</para>
903
904 <remark>
905 <para>THIS DOES NOT WORK ON 02/09/2009: Suppressed values, i.e values above
906 <parameter>INPUT_FIELD_SUPPRESS_ABOVE</parameter> and values below
907 <parameter>INPUT_FIELD_SUPPRESS_BELOW</parameter>, are not plotted when
908 plotting grid point values. This will happen automatically and there is no
909 need to set any extra parameters.</para>
910 </remark>
911
912 <para>A marker symbol may be plotted instead of (or as well as) the grid
913 point value by setting the parameter
914 <parameter>CONTOUR_GRID_VALUE_PLOT_TYPE</parameter> to
915 '<code>MARKER</code>' (or '<code>BOTH</code>'), the default being
916 '<code>VALUE</code>' . The relevant marker symbol may be chosen by setting
917 the parameter <parameter>CONTOUR_GRID_VALUE_MARKER_SYMBOL</parameter> to
918 the required value. The default is <code>3</code> (cross). A full list of
919 marker symbols can be found in <remark>Diagram XVII-2
920 (Appendix)</remark>.</para>
921
922 <para>The number of grid point values plotted may be controlled by
923 selecting the frequency of the number of lines of longitude and latitude
924 to be plotted. The parameters
925 <parameter>CONTOUR_GRID_VALUE_MIN_FREQUENCY</parameter> and
926 <parameter>CONTOUR_GRID_VALUE_LAT_FREQUENCY</parameter> should be used for
927 that purpose. The default in both cases is <code>1</code>, i.e. all lines
928 are plotted.</para>
929
930 <para>The setting of the parameters,
931 <parameter>CONTOUR_GRID_VALUE_MIN</parameter> and
932 <parameter>CONTOUR_GRID_VALUE_MAX</parameter> , will confine the plotting
933 of grid point values to within these two limits. The default values are
934 <code>-1.0E21</code> and <code>1.0E21</code> respectively.</para>
935
936 </section>
937
938 <!-- <section id="Control_of_CONICON_Gradient_Estimation">
939 <title>Control of CONICON Gradient Estimation</title>
940
941 <highlights>
942 <para>Not relevant to Magics++</para>
943 </highlights>
944 </section>
945 -->
946 <!-- <section id="Memory_Management_Within_Contouring">
947 <title>Memory Management Within Contouring</title>
948
949 <highlights>
950 <para>Not relevant to Magics++</para>
951 </highlights>
952 </section>
953 -->
954 <xi:include href="../paramtables/pcont_tables.xml"
955 xmlns:xi="http://www.w3.org/2001/XInclude" />
956
957
958 <xi:include href="../paramtables/Contour_contour_magml_tables.xml"
959 xmlns:xi="http://www.w3.org/2001/XInclude" />
960
961 <xi:include href="../paramtables/Contour_contour_magml_flat_tables.xml"
962 xmlns:xi="http://www.w3.org/2001/XInclude" />
963
964 <section id="Contour_Program_Examples">
965 <title>Program Examples</title>
966
967 <para>These examples illustrate the use of the contouring
968 facilities in <productname>Magics</productname>.</para>
969 </section>
970
971 <xi:include href="../examples/manual/xml/contour_examples.xml"
972 xmlns:xi="http://www.w3.org/2001/XInclude" />
973
974 </chapter>