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