Debian Codegraph @

docs/manual/chapters/symbol.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 <chapter id="Symbol_Plotting" label="14">
13 <title>Symbol Plotting</title>
14
15 <xi:include href="../phrases/chapterinfo_mod.xml"
16 xmlns:xi="http://www.w3.org/2001/XInclude" />
17
18 <section id="Symbol_Introduction">
19 <title>Introduction</title>
20
21 <para>Symbol plotting in <productname>Magics</productname> is the plotting
22 of different types of symbols at selected locations. A symbol in this
23 context is a number, a text string, a <productname>Magics</productname>
24 marker <remark>(see marker symbols in Figure XII-2 on page
25 XII-13)</remark> or a wind flag/arrow.</para>
26
27 <para>To plot symbols, it is necessary to pass information to
28 <productname>Magics</productname> that describes the symbols as well as
29 the positions where the symbols are to be plotted. All this information is
30 passed to <productname>Magics</productname> via arrays, which may consist
31 of one or more elements. The position of a symbol may be defined by its
32 geographical location (latitude/longitude), by its position in centimetres
33 from the bottom left hand corner of the SUBPAGE or by its position, in
34 axis units, within an axis system. Only those symbols whose positions are
35 within the subpage will be plotted. There are facilities in symbol
36 plotting that allow the user to control the height and colour of each
37 symbol and, if required, a legend describing the symbols may be plotted.
38 Examples of symbol plotting can be found in <remark>Symbol Program
39 Examples</remark>.</para>
40 </section>
41
42 <section id="Action_Routine_PSYMB">
43 <title>Action Routine PSYMB</title>
44
45 <para>Symbol plotting is achieved in <productname>Magics</productname> by
46 calling action routine <function>PSYMB</function> which, like all
47 <productname>Magics</productname> action routines, has no arguments.
48 Parameters associated with Symbol plotting may be set before
49 <function>PSYMB</function> is called. <function>PSYMB</function> will take
50 into account only those parameters which have been set before it is
51 called. All other symbol parameters will be assigned their default values,
52 if they exist. <remark>Details of any errors that may be detected by
53 <function>PSYMB</function> are given in SYMBOL Plotting : Error
54 Codes</remark>.</para>
55 </section>
56
57 <section id="Symbol_Input_Data_Section">
58 <title>Input Data</title>
59
60 <para></para>
61
62 <section id="Symbol_Position_Data">
63 <title>Position Data</title>
64
65 <para>All input data for symbol plotting are passed to
66 <productname>Magics</productname> via arrays. The parameter
67 <parameter>SYMBOL_POSITION_MODE</parameter> is used to describe the
68 input position data. Valid values are <code>GEOGRAPHIC</code>,
69 <code>PAPER</code> and <code>GRAPH</code>, the default value being
70 <code>GEOGRAPHIC</code>. Two arrays are used to pass the position
71 information, e.g.</para>
72
73 <programlisting>
74 CALL <function>PSET1R</function> ('<parameter>SYMBOL_INPUT_X_POSITION</parameter>',AR1,N)
75 CALL <function>PSET1R</function> ('<parameter>SYMBOL_INPUT_Y_POSITION</parameter>',AR2,N)
76 </programlisting>
77
78 <para>where <code>AR1</code> and <code>AR2</code> are arrays of
79 <code>N</code> elements.</para>
80
81 <para>In <code>GEOGRAPHIC</code> mode, the parameter
82 <parameter>SYMBOL_INPUT_X_POSITION</parameter> should be used to pass
83 the longitudes of the symbols and
84 <parameter>SYMBOL_INPUT_Y_POSITION</parameter> should be used to pass
85 the latitudes.</para>
86
87 <para>In <code>PAPER</code> mode,
88 <parameter>SYMBOL_INPUT_X_POSITION</parameter> and
89 <parameter>SYMBOL_INPUT_Y_POSITION</parameter> should be used to pass
90 the X and Y positions respectively of the symbols in centimetres, these
91 positions being relative to the lower left corner of the SUBPAGE.</para>
92
93 <para>In <code>GRAPH</code> mode,
94 <parameter>SYMBOL_INPUT_X_POSITION</parameter> and
95 <parameter>SYMBOL_INPUT_Y_POSITION</parameter> should be used to pass
96 the X and Y positions in axis units. The X and Y values, i.e. the
97 longitude and latitude positions or the paper coordinates, should be in
98 the corresponding pair of array elements. If the position specified for
99 a symbol does not fall within the current subpage, that symbol is not
100 plotted.</para>
101 </section>
102
103 <section id="Symbol_Input_Data">
104 <title>Symbol Input Data</title>
105
106 <para>There are four different types of SYMBOL input data, i.e. numbers,
107 text, wind and markers. The parameter <parameter>SYMBOL_TYPE</parameter>
108 is used to define the type of symbol required,e.g.</para>
109
110 <programlisting> CALL <function>PSETC</function> ('<parameter>SYMBOL_TYPE</parameter>','MARKER')</programlisting>
111
112 <para>It can have one of four values: <code>NUMBER</code>,
113 <code>TEXT</code>, <code>WIND</code> or <code>MARKER</code>, the default
114 being <code>NUMBER</code>. Only one of the above four types can be
115 plotted in any one call to <function>PSYMB</function>.
116 <code>NUMBER</code> input data are the actual numbers to be plotted and
117 are passed as follows:</para>
118
119 <programlisting> CALL <function>PSET1R</function> ('<parameter>SYMBOL_INPUT_NUMBER_LIST</parameter>',RARAY,N)</programlisting>
120
121 <para>where <code>RARAY</code> is a real array of <code>N</code>
122 elements. <code>TEXT</code> input data consists of text strings which
123 are to be plotted and are passed as follows:</para>
124
125 <programlisting> CALL <function>PSET1C</function> ('<parameter>SYMBOL_INPUT_TEXT_LIST</parameter>',CARAY,N)</programlisting>
126
127 <para>where <code>CARAY</code> is a character array of <code>N</code>
128 elements. <code>MARKER</code> input data consists of indices to
129 <productname>Magics</productname> MARKERS (<remark>see marker symbols in
130 Figure XII-2 on page XII-13</remark>) and are passed as follows:</para>
131
132 <programlisting> CALL <function>PSET1I</function> ('<parameter>SYMBOL_INPUT_MARKER_LIST</parameter>',IARAY,N)</programlisting>
133
134 <para>where <code>IARAY</code> is an integer array of <code>N</code>
135 elements. <code>WIND</code> data consists of the wind speed and
136 direction and are passed as follows:</para>
137
138 <programlisting> CALL <function>PSETR</function> ('<parameter>SYMBOL_INPUT_WIND_SPEED</parameter>',SPARAY,N)
139 CALL <function>PSETR</function> ('<parameter>SYMBOL_INPUT_WIND_DIRECTION</parameter>',DARAY',N)</programlisting>
140
141 <para>where <code>SPARAY</code> and <code>DARAY</code> are real arrays
142 of <code>N</code> elements. Please note that wind symbols are only
143 available in <code>INDIVIDUAL</code> mode.</para>
144
145 <para>The POSITION arrays and the DATA INPUT arrays should all have the
146 same number of elements. The symbol in the i'th element of the DATA
147 array will be plotted in the position given by the i'th elements of the
148 POSITION arrays. It is the user's responsibility to ensure that they
149 correspond correctly. If the arrays are of different lengths,
150 <productname>Magics</productname> will limit all the arrays to the size
151 of the smallest array and a warning message will be printed. There is an
152 exception to this as <parameter>SYMBOL_INPUT_MARKER_LIST</parameter> may
153 consist of only one element and, if it does, the marker indexed by this
154 one value will be plotted for all the values in the data arrays.</para>
155
156 </section>
157 </section>
158
159 <section id="Methods_of_Symbol_Plotting">
160 <title>Methods of Symbol Plotting</title>
161
162 <para>There are three methods for plotting symbols: <code>TABLE</code>,
163 <code>INDIVIDUAL</code> and <code>ADVANCED</code>. The required method may be
164 specified by setting the parameter <parameter>SYMBOL_TABLE_MODE</parameter> to
165 '<code>ON</code>' (<code>TABLE</code> mode),
166 '<code>OFF</code>' (<code>INDIVIDUAL</code> mode) which is the default, or
167 '<code>ADVANCED</code>'. Following is a description of the three
168 different modes.</para>
169
170 <section id="INDIVIDUAL_Mode">
171 <title>INDIVIDUAL Mode</title>
172
173 <para>Symbol plotting in <code>INDIVIDUAL</code> mode means that the
174 colour and height of the symbols to be plotted are controlled by the
175 values set in the <productname>Magics</productname> parameters
176 <parameter>SYMBOL_COLOUR</parameter> and
177 <parameter>SYMBOL_HEIGHT</parameter>. All the symbols, for each
178 <function>PSYMB</function> call, are plotted with the same colour and
179 height. To plot symbols in <code>INDIVIDUAL</code> mode the parameter
180 <parameter>SYMBOL_TABLE_MODE</parameter> should be set to
181 '<code>OFF</code>'.</para>
182 </section>
183
184 <section id="TABLE_Mode">
185 <title>TABLE Mode</title>
186
187 <para>TABLE mode allows users to plot symbols within specified ranges of
188 values and with varying colours and heights. Wind symbols are not
189 available in table mode. To plot symbols in TABLE mode, the parameter
190 <parameter>SYMBOL_TABLE_MODE</parameter> should be set to
191 '<code>ON</code>'. When calling <function>PSYMB</function> in TABLE
192 mode, the user must pass information to
193 <productname>Magics</productname> to describe the minimum and maximum of
194 each range required and may also pass information to describe the height
195 and/or colour for each of the desired ranges. All this information
196 should be passed in the form of tables and
197 <productname>Magics</productname> parameters exist to enable this.</para>
198
199
200 <para>The parameters for passing the minimum and maximum of the ranges
201 are <parameter>SYMBOL_MIN_TABLE</parameter> and
202 <parameter>SYMBOL_MAX_TABLE</parameter>, respectively. The minimum
203 values of the required ranges may be passed to
204 <productname>Magics</productname> as follows:</para>
205
206 <programlisting> CALL <function>PSET1R</function> ('<parameter>SYMBOL_MIN_TABLE</parameter>',RMIN,N)</programlisting>
207
208 <para>where <code>RMIN</code> is a real array of <code>N</code>
209 elements. The maximum values should be placed in the corresponding
210 elements of an array and passed to <productname>Magics</productname> as
211 follows:</para>
212
213 <programlisting> CALL <function>PSET1R</function> ('<parameter>SYMBOL_MAX_TABLE</parameter>',RMAX,N)</programlisting>
214
215 <para>where <code>RMAX</code> is a real array of <code>N</code>
216 elements. The colour to be used for each of the ranges may be passed
217 using the parameter <parameter>SYMBOL_COLOUR_TABLE</parameter> ,
218 e.g.</para>
219
220 <programlisting> CALL <function>PSET1C</function> ('<parameter>SYMBOL_COLOUR_TABLE</parameter>',COLTAB,N)</programlisting>
221
222 <para>where <code>COLTAB</code> is a character array of <code>N</code>
223 elements. Similarly, the heights for each range may be passed as
224 follows:</para>
225
226 <programlisting> CALL <function>PSET1R</function> ('<parameter>SYMBOL_HEIGHT_TABLE</parameter>',HGTAB,N)</programlisting>
227
228 <para>The input data and plotting positions required to use these tables should be passed using
229 the parameters described in <olink targetdoc="Magics_symbol" targetptr="Symbol_Input_Data" />.
230 Only those symbols, whose values in
231 <parameter>SYMBOL_INPUT_NUMBER_LIST</parameter> fit within one of the
232 specified ranges, will be plotted. To fit within a range, the values
233 must be greater than or equal to the minimum of the range and less than
234 the maximum of the range. If ranges overlap, a symbol will be plotted in
235 the first range in the table into which it fits.</para>
236
237 <section id="Parameters_Required_in_TABLE_Mode">
238 <title>Parameters Required in TABLE Mode</title>
239
240 <para>To plot symbols in table mode the parameter
241 <parameter>SYMBOL_TABLE_MODE</parameter> should be set to
242 '<code>ON</code>'. When in TABLE mode, it is necessary to pass the
243 information relating to the minimum and maximum of the ranges
244 (<parameter>SYMBOL_MIN_TABLE</parameter> /
245 <parameter>SYMBOL_MAX_TABLE</parameter>) as well as the input number
246 data (<parameter>SYMBOL_INPUT_NUMBER_LIST</parameter>). The tables
247 containing the colours and heights of the ranges
248 (<parameter>SYMBOL_COLOUR_TABLE</parameter> /
249 <parameter>SYMBOL_HEIGHT_TABLE</parameter>) may be passed if required.
250 If these are not passed the values set in
251 <parameter>SYMBOL_COLOUR</parameter> and
252 <parameter>SYMBOL_HEIGHT</parameter> will be used for all the
253 ranges.</para>
254 </section>
255 </section>
256 </section> <!-- TABLE_Mode -->
257
258 <section id="ADVANCED_Mode">
259 <title>ADVANCED Mode</title>
260
261 <para>Symbol plotting in <code>ADVANCED</code> mode means that the
262 colour and height of the plotted symbols are determined
263 automatically according to configurable rules.
264 First, the data values can be clumped into ranges, by setting
265 <parameter>SYMBOL_ADVANCED_TABLE_SELECTION_TYPE</parameter> to one of
266 the following:</para>
267
268 <para><code>COUNT</code>: specify the number of ranges</para>
269 <para><code>INTERVAL</code>: specify the data value interval size</para>
270 <para><code>LIST</code>: specify a list of ranges</para>
271 <para></para>
272
273 <para>Also configurable is the way that the colours are selected; by setting
274 <parameter>SYMBOL_ADVANCED_TABLE_COLOUR_METHOD</parameter> to one of the following,
275 different strategies can be used:</para>
276
277 <para><code>CALCULATE</code>: automatically create a colour gradient
278 using the HSL colour wheel</para>
279 <para><code>LIST</code>: specify a user-defined list of colours</para>
280 <para></para>
281
282
283 <para>Likewise, the symbol heights can be specified in different ways by setting
284 <parameter>SYMBOL_ADVANCED_TABLE_HEIGHT_METHOD</parameter> to one of the following:</para>
285
286 <para><code>CALCULATE</code>: automatically create a height gradient</para>
287 <para><code>LIST</code>: specify a user-defined list of heights</para>
288
289 <!-- outliers -->
290
291 </section>
292
293
294
295
296 <section id="TABLE_Mode_Types">
297 <title>TABLE Mode Types</title>
298
299 <para>TABLE mode may be used with the symbol types NUMBER, TEXT and
300 MARKER but not with WIND. The symbol type required must be passed by
301 setting the parameter <parameter>SYMBOL_TYPE</parameter> to one of the
302 above valid values. Following is a description of how each of the symbol
303 types is used in TABLE mode.</para>
304
305 <section id="NUMBER_Data">
306 <title>NUMBER Data</title>
307
308 <para>The minimum and maximum values of the ranges and the input NUMBER
309 data and position data should be passed to
310 <productname>Magics</productname> as described above. Each number in the
311 input NUMBER data will be checked against the values in the minimum and
312 maximum tables to find the range in which this number falls, thus
313 finding the appropriate index to the tables. If a colour table has been
314 passed to <productname>Magics</productname>, the index is used to find
315 the corresponding colour in the
316 <parameter>SYMBOL_COLOUR_TABLE</parameter>. Likewise, the appropriate
317 height may be found in <parameter>SYMBOL_HEIGHT_TABLE</parameter>. The
318 number will then be plotted at the position given by the POSITION arrays
319 with the colour and height extracted from the tables. If the colour
320 and/or height tables have not been passed, the number will be plotted
321 with the attributes given by <parameter>SYMBOL_COLOUR</parameter> and/or
322 <parameter>SYMBOL_HEIGHT</parameter>. The following are diagrams showing
323 the mechanism for plotting NUMBER symbols in TABLE mode</para>
324
325 <highlights>
326 <para>Do we really need these table examples here? Surely a couple of
327 good examples (code &amp; output) would be better...</para>
328 </highlights>
329 </section>
330
331 <section id="TEXT_Data">
332 <title>TEXT Data</title>
333
334 <para>To plot TEXT data in TABLE mode, a table of text strings
335 corresponding to the ranges required must be passed as follows:</para>
336
337 <programlisting> CALL <function>PSET1C</function> ('<parameter>SYMBOL_TEXT_TABLE</parameter>',TEXTAB,N)</programlisting>
338
339 <para>where <code>TEXTAB</code> is a character array of <code>N</code>
340 elements. The colours and heights for the various ranges and the input
341 data should be passed as described for NUMBER data. The mechanism for
342 plotting TEXT data is the same as for NUMBER data except that instead of
343 plotting the number the appropriate text string from
344 <parameter>SYMBOL_TEXT_TABLE</parameter> is plotted. The following are
345 diagrams showing the mechanism for plotting TEXT symbols in TABLE
346 mode.</para>
347
348 <highlights>
349 <para>Tables? Surely not...!</para>
350 </highlights>
351 </section>
352
353 <section id="MARKER_Data">
354 <title>MARKER Data</title>
355
356 <para>The method of plotting MARKER data is the same as for TEXT data
357 except that markers are plotted. The user must pass a table of marker
358 indices corresponding to the required ranges, e.g.</para>
359
360 <programlisting> CALL <function>PSET1I</function> ('<parameter>SYMBOL_MARKER_TABLE</parameter>',MTAB,N)</programlisting>
361
362 <highlights>
363 <para>No tables please...!</para>
364 </highlights>
365 </section>
366 </section>
367
368 <!--
369 <section id="Border_Check">
370 <title>Border Check</title>
371
372 <para>The plotting of symbols on or close to the subpage border may be
373 controlled by setting the parameter
374 <parameter>SYMBOL_BORDER_CHECK</parameter>. If set to '<code>ON</code>',
375 symbols on or close to the subpage border will be plotted. The default is
376 '<code>OFF</code>'.</para>
377 </section>
378 -->
379
380 <!--
381 <section id="Distance_Between_Symbols">
382 <title>Distance Between Symbols</title>
383
384 <para>There is a parameter, <parameter>SYMBOL_DISTANCE_APART</parameter>,
385 to control the minimum distance between the centres of any two symbols.
386 When a symbol is plotted and <parameter>SYMBOL_DISTANCE_APART</parameter>
387 is set to <code>X</code> cm, no other symbol will be plotted within a
388 radius of <code>X</code> cm of the first symbol.</para>
389 </section>
390 -->
391
392 <section id="SYMBOL_INPUT_MARKER_LIST">
393 <title>SYMBOL_INPUT_MARKER_LIST</title>
394
395 <para>If only one symbol marker is required to be plotted at one or more
396 positions, it is sufficient to pass a marker list with just one marker
397 number, e.g.</para>
398
399 <programlisting> CALL <function>PSET1I</function> ('<parameter>SYMBOL_INPUT_MARKER_LIST</parameter>',IMARK,1)</programlisting>
400 </section>
401
402 <!--
403 <section id="Symbol_Legend">
404 <title>Symbol Legend</title>
405
406 <para>In TABLE mode only, it is possible to plot a legend describing the
407 symbols plotted. This may be achieved by setting the parameter
408 <parameter>LEGEND</parameter> to '<code>ON</code>' , e.g.</para>
409
410 <programlisting>CALL PSETC ('LEGEND','ON')</programlisting>
411
412 <para>The legend plotted depends on the type of symbols required - number,
413 text or marker. It will basically consist of a description of the
414 MINIMUM/MAXIMUM tables passed to <productname>Magics</productname>, i.e.
415 <parameter>SYMBOL_MIN_TABLE</parameter>,
416 <parameter>SYMBOL_MAX_TABLE</parameter>, and a sample of the relevant
417 symbol for each entry in those tables. For marker symbols, the sample will
418 be a replica of the marker plotted where the height and colour of each
419 sample marker will be identical to the plotted marker. The sample marker
420 symbol will be taken from the relevant entry in the
421 <parameter>SYMBOL_MARKER_TABLE</parameter> passed to
422 <productname>Magics</productname> and height and colour will be taken from
423 the <parameter>SYMBOL_HEIGHT_TABLE</parameter> and
424 <parameter>SYMBOL_COLOUR_TABLE</parameter>, if these are passed by the
425 user. If these tables are not passed, the height and colour are taken from
426 the parameters <parameter>SYMBOL_HEIGHT</parameter> and
427 <parameter>SYMBOL_COLOUR</parameter> respectively. Number legend plotting
428 is identical to marker legend plotting except that, instead of a sample
429 marker symbol, a fixed marker (X) will be plotted. This marker will have
430 the same height and colour as the appropriate entry in
431 <parameter>SYMBOL_MIN_TABLE</parameter> and
432 <parameter>SYMBOL_MAX_TABLE</parameter>. Text legend plotting will be the
433 same as number legend plotting except that the fixed marker plotted is a
434 square. All the standard legend plotting features are available in symbol
435 legend plotting and a full description of general legend plotting may be
436 found in <remark>Chapter XV- Legend Plotting</remark>.</para>
437 </section>
438 -->
439
440 <xi:include href="../paramtables/psymb_tables.xml"
441 xmlns:xi="http://www.w3.org/2001/XInclude" />
442
443 <xi:include href="../paramtables/SymbolPlotting_symbol_magml_tables.xml"
444 xmlns:xi="http://www.w3.org/2001/XInclude" />
445
446 <xi:include href="../paramtables/SymbolPlotting_symbol_magml_flat_tables.xml"
447 xmlns:xi="http://www.w3.org/2001/XInclude" />
448
449 </chapter>