Debian Codegraph @

docs/manual/chapters/layout_mapping_coastlines.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="Layout_Mapping_and_Coastlines" label="4">
15 <title>Layout, Mapping and Coastlines</title>
16
17 <xi:include href="../phrases/chapterinfo_mod.xml"
18 xmlns:xi="http://www.w3.org/2001/XInclude" />
19
20 <section id="Plot_Layout_Basic_Entities">
21 <title>Plot Layout - Basic Entities</title>
22
23 <para>The <productname>Magics</productname> plot layout facility provides
24 a simple means by which users can plot several maps at arbitrary positions
25 on the plotting page. It can also be used in a fully automatic mode,
26 whereby <productname>Magics</productname> will position the user's maps in
27 a predetermined order.</para>
28
29 <para>To describe <productname>Magics</productname> plot layout it is
30 necessary to define the naming convention for the entities that comprise
31 any plotted output from the system. Please refer to <remark>Diagram
32 III-1</remark> throughout this description.</para>
33
34 <para><firstterm>SUPER-PAGE</firstterm> , <firstterm>PAGE</firstterm> and
35 <firstterm>SUBPAGE</firstterm> are the entities used to define the
36 plotting areas in <productname>Magics</productname>:</para>
37
38 <itemizedlist>
39 <listitem>
40 <para><firstterm>Super-pages</firstterm> are defined by their X and Y
41 axis lengths. A super-page can be thought of as the paper sheet on
42 which the work will be produced. The position of the bottom left hand
43 corner of the super-page is (0.0, 0.0).</para>
44 </listitem>
45
46 <listitem>
47 <para><firstterm>Pages</firstterm> subdivide a Super-page - any number
48 of pages may be defined by the user, provided they fit within the
49 limits of the current super-page. The position of a page on a
50 super-page, which can be controlled by
51 <productname>Magics</productname> or be defined by the user, is
52 relative to the bottom left hand corner of the super-page. A
53 user-controlled page is defined by its bottom left hand corner
54 position and its X and Y axis lengths.</para>
55 </listitem>
56
57 <listitem>
58 <para><firstterm>Subpages</firstterm> are the smallest entity - they
59 can contain one chart, e.g. contours superimposed on a background map
60 of coast lines and grid lines. One or more subpages can be plotted on
61 a page, provided that they fit within the limits assigned to that
62 page. Subpages can be of varying sizes. A subpage is defined by the
63 position of its bottom left hand corner and its lengths in the
64 horizontal (X) and vertical (Y) directions. The position of the
65 subpage is relative to the bottom left hand corner of the page.</para>
66 </listitem>
67 </itemizedlist>
68 </section>
69
70 <section id="Plot_Layout_Default_Values">
71 <title>Plot Layout Default Values</title>
72
73 <para>Default values exist for all the plot layout parameters. The default
74 value for the size of the super-page is A4 (horizontal), i.e. the length
75 in the X direction is 29.7cm and the length in the Y direction is 21cm.
76 Super-pages will be placed either sequentially along the plotter paper, or
77 on separate sheets, depending on the output device. The default value for
78 the page size is A4 (horizontal), i.e. X length is 29.7cm and the Y length
79 is 21cm. These defaults mean that the super-page and the page are the same
80 size. The default values for the subpage size and position depends on
81 whether the user sets some of the parameters:</para>
82
83 <!--
84 <highlights>
85 <para>Diagram 1</para>
86 </highlights>
87 -->
88
89 <para>If the user defines one or more of the subpage size or position
90 parameters, then <productname>Magics</productname> assumes that all the
91 subpage parameters have been defined and will use the current value of
92 these subpage parameters to plot the subpage. In this case, if any of the
93 parameters are not set, the defaults are calculated as follows:</para>
94
95 <para>The default values for the X and Y subpage lengths are 85% of the X
96 and Y page lengths. This corresponds to 25.24cm and 17.85cm respectively
97 for the default page size. The default subpage X position is 7.5% of the X
98 page length and the default subpage Y position is 5% of the Y page length.
99 This corresponds to 2.08cm and 1.05cm for the default page size.</para>
100
101 <para>If the user does not define any of the subpage parameters,
102 <productname>Magics</productname> will set the subpage parameters to
103 default values that depend on the values of the current page parameters.
104 Using fixed percentages of the page parameters to set the subpage values
105 ensures that the defaulted subpage fits neatly into the page and makes
106 maximum use of the plotting space. The percentages used are 85% for the X
107 and Y lengths, 7.5% for the subpage X position and 5% for subpage Y
108 position.</para>
109
110 <para>Users should be aware that the lengths of the subpage may be
111 affected by the type of map that is to be plotted in the subpage.
112 <productname>Magics</productname> will always try to fit subpages as
113 neatly as possible in the user's page but the requested projection, map,
114 scale etc. could mean that the subpage lengths are adjusted to fit the
115 requested map correctly. Therefore, users should be aware that certain
116 mapping parameters could affect the lengths of the subpage.</para>
117 </section>
118
119 <section id="Plot_Layout_for_Pages">
120 <title>Plot Layout for Pages</title>
121
122 <para>There are two methods of handling plot layout of pages in
123 <productname>Magics</productname> : '<code>POSITIONAL</code>' and
124 '<code>AUTOMATIC</code>', the default being
125 '<code>AUTOMATIC</code>'.</para>
126
127 <section id="Automatic_Mode">
128 <title>Automatic Mode</title>
129
130 <para>If a user wishes to make maximum use of the plotting paper, he
131 may request <productname>Magics</productname> to do the plot layout
132 for him by putting the system in automatic mode, which is the default
133 positioning mode. Pages will then be positioned in an organised way,
134 depending on the instructions given by the user.</para>
135
136 <para>When in automatic mode, a user can specify three instructions
137 which define the type of layout required.</para>
138
139 <itemizedlist>
140 <listitem>
141 <para>The user can instruct <productname>Magics</productname> to
142 start positioning from the bottom or top of the plotting paper by
143 setting the <parameter>PLOT_START</parameter> parameter to
144 '<code>BOTTOM</code>' or '<code>TOP</code>'.</para>
145 </listitem>
146
147 <listitem>
148 <para>The default value for <parameter>PLOT_START</parameter> is
149 '<code>BOTTOM</code>'.</para>
150 </listitem>
151
152 <listitem>
153 <para>The direction in which plotting is required is defined by
154 setting the <parameter>PLOT_DIRECTION</parameter> parameter to
155 either '<code>HORIZONTAL</code>' or
156 '<code>VERTICAL</code>'.</para>
157 </listitem>
158
159 <listitem>
160 <para>The default value for <parameter>PLOT_DIRECTION</parameter>
161 is '<code>VERTICAL</code>'.</para>
162 </listitem>
163
164 <listitem>
165 <para>The gaps between the pages in the horizontal and vertical
166 directions are set by <parameter>PAGE_X_GAP</parameter> and
167 <parameter>PAGE_Y_GAP</parameter>.</para>
168 </listitem>
169
170 <listitem>
171 <para>The default values for <parameter>PAGE_X_GAP</parameter> and
172 <parameter>PAGE_Y_GAP</parameter> are both
173 <code>0.0</code>cm.</para>
174 </listitem>
175 </itemizedlist>
176
177 <para />
178 <!--
179 <highlights>
180 <para>Diagrams 2, 3, 4</para>
181 </highlights>
182 -->
183
184 <para>When <parameter>PLOT_DIRECTION</parameter> is set to
185 '<code>VERTICAL</code>' (default), <productname>Magics</productname>
186 will place the user's pages one over the other (or one under the
187 other, if starting at the top of the paper) until the limits of the
188 super-page are reached
189 (<parameter>SUPER_PAGE_Y_LENGTH</parameter>).</para>
190
191 <para>The next page is then placed alongside the first page in a
192 horizontal direction and subsequent pages are placed on top of (or
193 underneath) this. The mechanism is repeated until the limits of the
194 super-page are reached (<parameter>SUPER_PAGE_X_LENGTH</parameter>). A
195 new super-page is then allocated and the above procedure is repeated
196 until all the user's pages are plotted.</para>
197
198 <para>The gaps between the pages in both directions will be as defined
199 by the user (<parameter>PAGE_X_GAP</parameter>,
200 <parameter>PAGE_Y_GAP</parameter>) or the default values (both
201 <code>0.0</code>cm). <remark>See Diagram III-5(a)</remark> for an
202 example of page plotting in the vertical direction.</para>
203
204 <para>If the user specifies <parameter>PLOT_DIRECTION</parameter> as
205 '<code>HORIZONTAL</code>', <productname>Magics</productname> will
206 place the pages horizontally along the super-page with a gap between
207 the pages, as defined by the user (<parameter>PAGE_X_GAP</parameter>),
208 which defaults to <code>0.0</code>cm. <remark>See Diagram
209 III-5(b)</remark> for an example.</para>
210
211 <para>When the super-page limit
212 (<parameter>SUPER_PAGE_X_LENGTH</parameter>) is reached, the next page
213 will be placed directly above the first page to be plotted. Subsequent
214 pages will be placed horizontally along the paper directly above the
215 first row of pages, with a gap between the rows, as defined by the
216 user (<parameter>PAGE_Y_GAP</parameter> which defaults to
217 <code>0.0</code>cm). This mechanism continues until the super-page
218 limits are reached. A new super-page is then allocated by
219 <productname>Magics</productname> and the above procedure is repeated
220 until all the user's pages are plotted.</para>
221
222 <para>The user may start at the top of the paper if required, and the
223 same procedure as above will apply except that the rows of pages are
224 in descending order. If the user requires only one row of pages, the
225 length of the super-page in the Y direction may be set by the user to
226 a value which will limit the number of pages in the Y direction to
227 one.</para>
228
229 <para>A similar mechanism can be used to limit the number of pages in
230 the X direction.</para>
231 </section>
232
233 <section id="Positional_Mode">
234 <title>Positional Mode</title>
235
236 <para>In positional mode, the responsibility for organising the
237 position and size of plotted output rests with the user. He may,
238 however, use <productname>Magics</productname> defaults, if
239 suitable.</para>
240
241 <para>To define the position of a page, the user must define the
242 bottom left hand corner of the page
243 (<parameter>PAGE_X_POSITION</parameter>,
244 <parameter>PAGE_Y_POSITION</parameter>). He may also, if the default
245 A4 is not suitable, define the lengths of the page in the horizontal
246 and vertical directions (<parameter>PAGE_X_LENGTH</parameter>,
247 <parameter>PAGE_Y_LENGTH</parameter>).</para>
248
249 <para>The values given for the page position are relative to the
250 bottom left hand corner of the super-page. A user can define one or
251 more pages within a super-page, but any page or part of a page
252 exceeding the super-page limits will not be plotted.</para>
253
254 <para>The user may define a super-page by defining the length in the X
255 and Y directions (<parameter>SUPER_PAGE_X_LENGTH</parameter>,
256 <parameter>SUPER_PAGE_Y_LENGTH</parameter>). The position of the
257 bottom left hand corner of the super-page is always (0.0, 0.0).</para>
258 <!--
259 <para>See <remark>Diagram III-5(c)</remark> for an example of page
260 layout in positional mode.</para>
261
262 <highlights>
263 <para>Diagram 5</para>
264 </highlights>
265 -->
266 </section>
267 </section>
268
269 <section id="Plot_Layout_for_Subpages">
270 <title>Plot Layout for Subpages</title>
271
272 <para>Subpages may be defined within a page by defining the bottom left
273 hand corner of the subpage (<parameter>SUBPAGE_X_POSITION</parameter>,
274 <parameter>SUBPAGE_Y_POSITION</parameter>) and the lengths in the X and Y
275 directions (<parameter>SUBPAGE_X_LENGTH</parameter>,
276 <parameter>SUBPAGE_Y_LENGTH</parameter>). The values for the subpage are
277 relative to the bottom left hand corner of the current page.</para>
278
279 <para>A user may define one or more subpages within a page. When a user
280 defines a subpage where all or some of the subpage is outside the limits
281 of the current page, <productname>Magics</productname> will issue an error
282 message but will plot any part of the user's subpage that comes within the
283 limits of the page. The rest of the plot will be lost.</para>
284 </section>
285
286 <section id="Pseudo_Action_Routine_PNEW">
287 <title>Pseudo Action Routine PNEW</title>
288
289 <para>Pseudo action routine <function>PNEW</function> informs
290 <productname>Magics</productname> that the user wishes to change from one
291 subpage, page or super-page to another.</para>
292
293 <para>No immediate action is performed when <function>PNEW</function> is
294 called, hence the name pseudo action. The change to a new subpage, page or
295 super-page is actually performed when the next action routine is
296 called.</para>
297
298 <para>The format of the call to <function>PNEW</function> is as follows:</para>
299
300 <programlisting> CALL <function>PNEW</function>( 'key' )</programlisting>
301
302 <para>where 'key' can be '<code>SUBPAGE</code>', '<code>PAGE</code>' or
303 '<code>SUPER_PAGE</code>'.</para>
304
305 <para>For example, <code>CALL <function>PNEW</function>('PAGE')</code> will cause
306 <productname>Magics</productname> to terminate plotting on the currently
307 defined page and move to the next page.</para>
308
309 <para>In automatic mode, the positioning of the new page is done by
310 <productname>Magics</productname>. In positional mode, the user must
311 specify the position of the next page. The actual movement to a new page
312 does not occur until the first action routine following the call to
313 <function>PNEW</function>. Moving from one subpage or one super-page to
314 another is achieved in a similar manner.</para>
315
316 <para>The pseudo action routine, <function>PNEW</function>, must be used
317 to change from one subpage or one page to another. It is not necessary for
318 users to define super-pages as <productname>Magics</productname> will do
319 so automatically. However, to achieve a special type of layout, users may
320 define their own super-page. In this case, if they wish to change from one
321 super-page to another before the super-page is full, they must use pseudo
322 action routine <function>PNEW</function>.</para>
323 </section>
324
325 <section id="Plot_Frames">
326 <title>Plot Frames</title>
327
328 <para>By default, <productname>Magics</productname> will draw frames
329 around pages and subpages, but not around super-pages unless requested by
330 the user. Plot framing may be controlled by the user in all three
331 cases.</para>
332
333 <para>For the page and subpage, <productname>Magics</productname> allows
334 the user to control the colour, thickness and line style of the frame, as
335 well as providing facilities for turning it on and off. For the
336 super-page, the only control allowed is the facility for turning the frame
337 on and off. The parameters are summarised in <remark>Diagram III-2,
338 Diagram III-3 and Diagram III-6</remark>.</para>
339 </section>
340
341 <section id="Page_Identification_Line">
342 <title>Page Identification Line</title>
343
344 <para><productname>Magics</productname> will, by default, plot an
345 identification line and the ECMWF logo on the bottom of every page
346 plotted. The user may inhibit the plotting of these if he wishes.</para>
347
348 <para>The identification line consists of such items as the
349 <productname>Magics</productname> version number, the user's job name, the
350 current date and time, error numbers and an optional text string which the
351 user may define. The user also has control over the height and quality of
352 the characters in the identification line. However,
353 <productname>Magics</productname> defaults ensure that the height of the
354 characters are always reasonable.</para>
355
356 <para>The identification line is positioned on the bottom of each page,
357 starting in the bottom left hand corner. The ECMWF logo is plotted in the
358 bottom right hand corner of the page. Plotting of the identification line
359 and logo is controlled by the <productname>Magics</productname> parameter
360 <parameter>PAGE_ID_LINE</parameter>, which may be set '<code>ON</code>' or
361 '<code>OFF</code>', the default being '<code>ON</code>'.</para>
362
363 <para>The identification line can be split into 5 different parts; system
364 information, date/time. user text, error plotting and ECMWF logo. Each of
365 these parts can be turned on or off by using the following
366 parameters:</para>
367
368 <programlisting><parameter>
369 PAGE_ID_LINE_SYSTEM_PLOT
370 PAGE_ID_LINE_DATE_PLOT
371 PAGE_ID_LINE_USER_TEXT_PLOT
372 PAGE_ID_LINE_ERRORS_PLOT
373 PAGE_ID_LINE_LOGO_PLOT
374 </parameter></programlisting>
375
376 <para>The valid values for the above parameters are '<code>ON</code>' and
377 '<code>OFF</code>', with '<code>ON</code>' being the default for all five.
378 Any combination of the parts can be selected for plotting.</para>
379
380 <para>Other parameters controlling <parameter>PAGE_ID_LINE</parameter>
381 plotting are</para>
382
383 <programlisting><parameter>
384 PAGE_ID_LINE_HEIGHT
385 PAGE_ID_LINE_QUALITY
386 PAGE_ID_LINE_USER_TEXT
387 </parameter></programlisting>
388
389 <important> <title>Magics++ 2.10</title>
390 From version 2.10 onwards the option to set a USER_LOGO has been deprecated.
391 Users should use the PIMPORT action routine instead.
392 </important>
393
394 <!--
395 <section id="User_Logos">
396 <title>User Logos</title>
397 <important> <title>Magics++</title>
398 <productname>Magics++</productname> provides the ability to
399 easily add a different logo to its plots.</important>
400
401 <para>The following code illustrates how to set up your own logo:</para>
402 <programlisting>
403 CALL <function>PSETC</function>('<parameter>PAGE_ID_LINE_LOGO_PLOT</parameter>', 'USER')
404 CALL <function>PSETC</function>('<parameter>USER_LOGO_FILENAME</parameter>', 'DATA/LOGO_MF_VERTICAL.GIF')
405 CALL <function>PSETC</function>('<parameter>USER_LOGO_FORMAT</parameter>', 'GIF')
406 CALL <function>PSETR</function>('<parameter>USER_LOGO_X_POSITION</parameter>', 0.5)
407 CALL <function>PSETR</function>('<parameter>USER_LOGO_WIDTH</parameter>', 1.0)
408 CALL <function>PSETR</function>('<parameter>USER_LOGO_Y_POSITION</parameter>', 12.0)
409 CALL <function>PSETR</function>('<parameter>USER_LOGO_HEIGHT</parameter>', 2.0)
410 </programlisting>
411 </section>
412 -->
413
414 </section>
415
416 <section id="Useful_Hints_on_Plot_Layout">
417 <title>Useful Hints on Plot Layout</title>
418
419 <para>For plotting one field, users should use default values for
420 (<parameter>SUBPAGE_X_POSITION</parameter>,
421 <parameter>SUBPAGE_Y_POSITION</parameter>) and
422 (<parameter>PAGE_X_POSITION</parameter>,
423 <parameter>PAGE_Y_POSITION</parameter>). It is sufficient to define the
424 lengths of the plot, if the defaults are not suitable, i.e.
425 (<parameter>PAGE_X_LENGTH</parameter>,
426 <parameter>PAGE_Y_LENGTH</parameter>) and/or
427 (<parameter>SUBPAGE_X_LENGTH</parameter>,
428 <parameter>SUBPAGE_Y_LENGTH</parameter>).</para>
429
430 <para>In positional mode users can superimpose plots, one on top of the
431 other, by not changing the subpage, page or super-page definitions between
432 action routines.</para>
433
434 <para>Users may only change from one subpage or page to another by calling
435 the pseudo action routine <function>PNEW</function>. A change to a new
436 super-page can also be achieved by calling <function>PNEW</function> but
437 will happen automatically if plot layout is in automatic mode and there is
438 insufficient room for the next page in the current super-page.</para>
439
440 <para>The size of the super-page can be used to achieve the desired layout
441 of plots, i.e. by limiting the number of plots in the X and Y
442 directions.</para>
443
444 <para>The first action routine to be called sets up the user's subpage.
445 All parameters affecting the subpage definition should be set, if
446 required, before the first action routine is called. These parameters
447 include those mapping parameters with the prefix
448 <parameter>SUBPAGE_MAP</parameter>.</para>
449
450 <para>The lengths of the subpage may be affected by the type of map that
451 is to be plotted in the subpage. <productname>Magics</productname> will
452 always try to fit subpages as neatly as possible in the user's page but
453 the requested projection, map, scale etc. could mean that the subpage
454 lengths are adjusted to fit the requested map correctly. Therefore, users
455 should be aware that certain mapping parameters could affect the lengths
456 of the subpage.</para>
457
458 <!--
459 <highlights>
460 <para>Diagram 6</para>
461 </highlights>
462 -->
463 </section>
464
465 <section id="Mapping">
466 <title>Map projections</title>
467
468 <para>Four types of projections are catered for in
469 <productname>Magics</productname>, cylindrical (default), polar
470 stereographic, Mercator and satellite. Input data, especially if it is GRIB data, does not have to be in the
471 same projection as the generated map. Also, it is not necessary for users
472 to extract data for the required geographical area before passing the
473 input data. <productname>Magics</productname> can perform both those
474 functions. <productname>Magics</productname> can deal with input GRIB
475 data in cylindrical, polar stereographic and satellite projections but
476 not with Mercator. If the input field is passed in the form of an array,
477 <productname>Magics</productname> can only deal with cylindrical and
478 satellite projections.</para>
479
480 <para><productname>Magics</productname> parameters exist to enable users
481 to specify the area, scale, etc, required. Mapping parameters have been
482 given the prefix <parameter>SUBPAGE_MAP</parameter> to remind users that
483 these parameters must be set before any action routines are
484 called.</para>
485
486 <para>To define the map, users should specify the projection, scale etc,
487 if the default values are not applicable. The parameter
488 <parameter>SUBPAGE_MAP_PROJECTION</parameter> may be set to
489 '<code>CYLINDRICAL</code>', '<code>POLAR_STEREOGRAPHIC</code>',
490 '<code>MERCATOR</code>', '<code>TAYLOR</code>' or
491 '<code>CARTASIAN</code>', the default being
492 '<code>CYLINDRICAL</code>'.
493 <!-- '<code>CYLINDRICAL</code>', '<code>POLAR_STEREOGRAPHIC</code>',
494 '<code>MERCATOR</code>', '<code>SATELLITE</code>',
495 '<code>AITOFF</code>', '<code>LAMBERT</code>',
496 '<code>OCEAN_SECTION</code>' or '<code>NONE</code>', the default being
497 '<code>CYLINDRICAL</code>'. -->
498 If <parameter>SUBPAGE_MAP_PROJECTION</parameter> is set to
499 '<code>NONE</code>', <productname>Magics</productname> will not apply
500 any projection to the user's input field.</para>
501
502 <section id="Cylindrical_Projection">
503 <title>Cylindrical and Mercator projection</title>
504
505 <para>An area on a cylindrical or Mercator Projection may be defined by specifying the latitude and
506 longitude coordinates of the lower left hand and top right hand
507 corners of the required area. The data for contouring for this area
508 may be for a smaller or larger area than the one specified but should
509 contain data which covers at least part of this area.
510 <productname>Magics</productname> can perform the extraction of data
511 to fit the area.</para>
512
513 <para>Users should always take care to ensure that the dimensions of
514 the subpage (<parameter>SUBPAGE_X_LENGTH</parameter>,
515 <parameter>SUBPAGE_Y_LENGTH</parameter>) are reasonable and
516 approximately match the area required.
517 <productname>Magics</productname> will always fit the required area to
518 the user's subpage in the best possible way.</para>
519
520 <important id="Area_Greater_Than_360_Degrees"> <title>Magics++</title>
521 New to <productname>Magics++</productname> is the ability to plot
522 an area with more than 360
523 degrees of longitude. By specifying an area which crosses the 180
524 degree 'boundary', locations of interest can be more easily studied.</important>
525
526
527 </section>
528
529 <section id="Polar_Stereographic_Projection">
530 <title>Polar Stereographic Projection</title>
531
532 <para>If <parameter>SUBPAGE_MAP_PROJECTION</parameter> is set to
533 '<code>POLAR_STEREOGRAPHIC</code>', users may select a method for the
534 defining the area by setting <parameter>SUBPAGE_MAP_AREA_DEFINITION</parameter> to
535 '<code>CORNERS</code>' (default) or '<code>CENTRE</code>'.</para>
536
537 <!--
538 <highlights>
539 <para>Diagram 7</para>
540 </highlights>
541 -->
542
543 <section id="CORNERS">
544 <title>CORNERS</title>
545
546 <para>The first, (default) method allows users to specify the
547 latitude and longitude of the lower left hand corner and the upper
548 right hand corner of the area required. The vertical longitude may
549 also be specified if required.</para>
550
551 <para>There is no need to specify a map scale in this case as
552 <productname>Magics</productname> will fill the user's subpage with
553 the area required. Users should take care, however, to ensure that
554 the dimensions of the subpage
555 (<parameter>SUBPAGE_X_LENGTH</parameter>,
556 <parameter>SUBPAGE_Y_LENGTH</parameter>) are reasonable and
557 approximately match the area required.
558 <productname>Magics</productname> will always fit the required area
559 to the user's subpage in the best possible way.</para>
560
561 <para>Initially, <productname>Magics</productname> will use the
562 user's <parameter>SUBPAGE_X_LENGTH</parameter> as a basis and from
563 this calculate the correct map scale. It will then calculate the
564 correct <parameter>SUBPAGE_Y_LENGTH</parameter> for the map. If,
565 however, the calculated <parameter>SUBPAGE_Y_LENGTH</parameter> is
566 greater than the <parameter>SUBPAGE_Y_LENGTH</parameter> specified
567 by the user, <productname>Magics</productname> will calculate the
568 map scale and <parameter>SUBPAGE_X_LENGTH</parameter> based on the
569 defined <parameter>SUBPAGE_Y_LENGTH</parameter>.</para>
570
571 <para>This method ensures that the requested area will always fit in
572 the user's subpage. It also shows the importance of defining
573 suitable dimensions for <parameter>SUBPAGE_X_LENGTH</parameter> and
574 <parameter>SUBPAGE_Y_LENGTH</parameter>.</para>
575 <!--
576 <para>Users can find out the map scale and subpage dimensions
577 actually used by calling the special
578 <productname>Magics</productname> routine
579 <function>PPRINT</function> after the action routine that drew the
580 map. <remark>See chapter on Contouring for details of routine
581 PPRINT</remark>.</para>
582 -->
583 <para>Using this method, data for contouring will usually be in
584 cylindrical format. <productname>MAGICS</productname> will project
585 the required contour lines, providing that the input data covers at
586 least part of the requested area. It is also possible for the input
587 data to be in polar stereographic format providing that it fits the
588 exact area to be projected.
589 <olink targetdoc="Magics_data" targetptr="Data_Input" /> gives full
590 details of input data formats.</para>
591
592 <para>When <parameter>SUBPAGE_MAP_AREA_DEFINITION</parameter> is set
593 to '<code>CORNERS</code>', a polar stereographic map should be
594 defined by setting:</para>
595
596 <programlisting>
597 SUBPAGE_LOWER_LEFT_LATITUDE
598 SUBPAGE_LOWER_LEFT_LONGITUDE
599 SUBPAGE_UPPER_RIGHT_LATITUDE
600 SUBPAGE_UPPER_RIGHT_LONGITUDE
601 </programlisting>
602
603 <para><parameter>SUBPAGE_MAP_VERTICAL_LONGITUDE</parameter> may also
604 be set, if desired, but setting
605 <parameter>SUBPAGE_MAP_SCALE</parameter> in this case will have no
606 affect on the area.</para>
607 </section>
608
609 <section id="CENTRE">
610 <title>CENTRE</title>
611
612 <para>The second method of defining polar stereographic maps is to
613 specify the latitude and longitude of the centre of the area and the
614 scale of the map.</para>
615
616 <para>The default value for the scale is <code>50E6</code> (true at
617 60 north) and this corresponds to 500 kilometres being represented
618 on the map by 1cm. The vertical longitude may also be specified, if
619 the default (<code>0.0</code>) is not suitable. Users should be
620 aware that the selection of the vertical longitude is an important
621 element and will affect the area to be projected.</para>
622
623 <para>It is possible, by varying the vertical longitude, to rotate
624 an area. The area to be projected may be increased or decreased by
625 varying the map scale.</para>
626
627 <!--
628 <highlights>
629 <para>Diagram 8</para>
630 </highlights>
631 -->
632
633 <para>The lengths of the current subpage
634 (<parameter>SUBPAGE_X_LENGTH</parameter>,
635 <parameter>SUBPAGE_Y_LENGTH</parameter>), together with the map
636 scale and the vertical longitude will determine the actual area to
637 be projected onto the user's subpage.</para>
638
639 <para>Users should be careful in setting the map scale. If the map
640 scale is too large, e.g. <code>200E6</code> for full hemisphere, the
641 map plotted will be very small. When the map scale is too small,
642 e.g. <code>5E6</code> for a full hemisphere, some of the map may not
643 be plotted, as it may not be possible to fit it in the defined
644 subpage.</para>
645
646 <para>To be able to estimate the map scale as a function of page
647 size for a full polar stereographic map, the following formula may
648 be used.</para>
649
650 <para>
651 <code>SUBPAGE_Y_LENGTH * SUBPAGE_MAP_SCALE = 24E8</code>
652 </para>
653
654 <para>When <parameter>SUBPAGE_MAP_AREA_DEFINITION</parameter> is set
655 to '<code>CENTRE</code>' a polar stereographic map may be defined by
656 setting <code>SUBPAGE_MAP_CENTRE_LATITUDE</code> and
657 <parameter>SUBPAGE_MAP_CENTRE_LONGITUDE.</parameter></para>
658
659 <para><parameter>SUBPAGE_MAP_VERTICAL_LONGITUDE</parameter> and
660 <parameter>SUBPAGE_MAP_SCALE</parameter> may also be defined if the
661 default values are not suitable.</para>
662 </section>
663 </section>
664
665
666 <!--
667 <section id="Mercator_Projection">
668 <title>Mercator Projection</title>
669
670 <para>The Mercator projection may be defined by specifying the
671 latitude and longitude of the lower left hand and top right hand
672 corners of the required area. The data for contouring etc may be for a
673 larger area or a smaller area that the required plot area but it
674 should contain data for some part of the plot area.
675 <productname>Magics</productname> can perform the extraction of data
676 to fit the area. The default values for the Mercator projection are as
677 follows:</para>
678
679 <para>bottom left hand latitude = -85.0</para>
680
681 <para>bottom left hand longitude = -180.0</para>
682
683 <para>top right hand latitude = 85.0</para>
684
685 <para>top right hand longitude = 180.0</para>
686
687 <para>Users should always take care to ensure that the dimensions of
688 the subpage (<parameter>SUBPAGE_X_LENGTH</parameter>,
689 <parameter>SUBPAGE_Y_LENGTH</parameter>) are reasonable and
690 approximately match the area required.
691 <productname>Magics</productname> will fit the required area to the
692 user's subpage in the best possible way.</para>
693
694 <para>An example of the default Mercator projection is shown in the
695 example of SUBROUTINE PLOT02_TEN.</para>
696 </section>
697 -->
698
699 <section id="Satellite_Projection">
700 <title>Satellite Projection</title>
701
702 <para>A satellite projection is fully defined to
703 <productname>Magics</productname> by the information in the GRIB code
704 headers. It is sufficient for the user to set the parameter
705 <parameter>SUBPAGE_MAP_PROJECTION</parameter> to
706 '<code>SATELLITE</code>' and to pass the GRIB code data to
707 <productname>Magics</productname>.</para>
708
709 <para><productname>Magics</productname> only caters for geostationary
710 satellite projections at present.</para>
711
712 <para>The satellite projection will by default make the satellite
713 image fill the subpage area. The user can specify a subarea
714 (rectangle) of the image by specifying the centre point and one corner
715 of the subarea, for example the bottom left hand or top right hand
716 corner (in latitude/longitude). The parameter
717 <parameter>IMAGE_SUBAREA_SELECTION</parameter> should be set to
718 '<code>ON</code>' if a subarea is required. The default is
719 '<code>OFF</code>' (full satellite projection).</para>
720
721 <para>The following parameter settings show how to plot a subarea in
722 the satellite projection:</para>
723
724 <programlisting>
725 CALL <function>PSETC</function> ('<parameter>IMAGE_SUBAREA_SELECTION</parameter>','ON')
726 CALL <function>PSETR</function> ('<parameter>SUBPAGE_MAP_CENTRE_LONGITUDE</parameter>', value)
727 CALL <function>PSETR</function> ('<parameter>SUBPAGE_MAP_CENTRE_LATITUDE</parameter>', value)
728 CALL <function>PSETR</function> ('<parameter>SUBPAGE_MAP_CORNER_LATITUDE</parameter>', value)
729 CALL <function>PSETR</function> ('<parameter>SUBPAGE_MAP_CORNER_LONGITUDE</parameter>', value)
730 </programlisting>
731
732 <para>Satellite projection is described fully in <remark>Chapter XIII-
733 Satellite Image Plotting</remark>.</para>
734 </section>
735
736 <!--
737 <section id="Aitoff_Projection">
738 <title>Aitoff Projection</title>
739
740 <para>Aitoff projection is a simple poly-conic equal-area projection
741 and is defined by specifying the vertical longitude of the map, i.e.
742 <parameter>SUBPAGE_MAP_VERTICAL_LONGITUDE</parameter> . A full global
743 map with the specified vertical longitude in the centre of the map is
744 always plotted. Plotting of subareas is not allowed.</para>
745
746 <para>An example of the Aitoff projection is given in the example
747 program in <remark>SUBROUTINE PLOT02_FOURTEEN</remark>.</para>
748 </section>
749
750 <section id="Lambert_Projection">
751 <title>Lambert Projection</title>
752
753 <para>A Lambert projection is a conformal conic projection which is
754 defined by two standard parallels which converge at the pole. Scale is
755 true along the two standard parallels. The projection is conformal
756 everywhere but the poles and is neither equal-area nor equidistant.
757 The parallels are unequally spaced concentric circular arcs centred on
758 the pole of convergence. Spacing of the parallels increases away from
759 the central latitudes. The meridians are equally spaced lines
760 converging at one of the poles. The angles between the meridians are
761 less than true angles. A Lambert projection may be specified by
762 setting the following parameters:</para>
763
764 <programlisting>SUBPAGE_MAP_STANDARD_LATITUDE_1
765 SUBPAGE_MAP_STANDARD_LATITUDE_2
766 SUBPAGE_MAP_CENTRE_LATITUDE
767 SUBPAGE_MAP_CENTRE_LONGITUDE
768 SUBPAGE_MAP_SCALE</programlisting>
769
770 <para>An example of the Lambert projection is given in the example
771 programs in <remark>SUBROUTINE PLOT02_TWELVE and SUBROUTINE
772 PLOT02_THIRTEEN</remark>.</para>
773 </section>
774
775
776 <section id="Ocean_Section_Projection">
777 <title>Ocean Section Projection</title>
778
779 <para>The ocean_section projection enables the plotting of sections
780 and time series from the Ocean Model. To plot in this new projection,
781 users should pass GRIB code to <productname>Magics</productname>
782 containing an Ocean Model field and set the following
783 parameter:</para>
784
785 <programlisting> CALL <function>PSETC</function>('<parameter>SUBPAGE_MAP_PROJECTION</parameter>', 'OCEAN_SECTION')</programlisting>
786
787 <para>The section or time-series will be plotted in the subpage
788 defined by the user. <productname>Magics</productname> will plot the
789 appropriate axes on the bottom horizontal and left vertical lines of
790 the subpage. It is not possible to plot subareas of the sections or
791 time-series.</para>
792
793 <para>Example of ocean section plots are given in the example programs
794 in <remark>SUBROUTINE PLOT02_FIFTEEN and SUBROUTINE
795 PLOT02_SIXTEEN</remark>.</para>
796 </section>
797 -->
798 </section>
799
800 <section id="Coastlines_and_Gridlines">
801 <title>Coastlines and Gridlines</title>
802
803 <para><productname>Magics</productname> will project coastlines and
804 latitude/longitude grid lines onto requested areas, as defined by the
805 user.</para>
806
807 <xi:include href="../phrases/coastlines_origin.xml"
808 xmlns:xi="http://www.w3.org/2001/XInclude" />
809
810 <para>The plotting of coastlines and grid lines is achieved by calling the
811 action routine <function>PCOAST</function>. Mapping, coastline and grid
812 parameters should be set, if required, before <function>PCOAST</function>
813 is called.</para>
814
815 <para>Parameters exist in <productname>Magics</productname> to enable
816 users to control the plotting of coastlines and grid lines and these
817 parameters should be set before <function>PCOAST</function> is called.
818 Users can control the line style, colour, shading, resolution etc of
819 coastlines as well as the number, colour and quality of grid lines. Users
820 also have control over the plotting of grid line labels.</para>
821
822 <para><productname>Magics</productname> default values for coastline,
823 grids and labels ensure that users always achieve a reasonable plot.
824 However, if these default values are not suitable, users can set any or
825 all of the parameters to their own chosen value.</para>
826
827
828 <section id="Coastline_Activation">
829 <title>Coastline Activation</title>
830 <para> By default, coastlines are enabled, ie they are drawn
831 when <function>PCOAST</function> is called. To deactivate the coastline
832 drawing, set <parameter>MAP_COASTLINE</parameter> to '<code>OFF</code>'.
833 </para>
834 </section>
835
836 <section id="Coastline_Attributes">
837 <title>Coastline Attributes</title>
838 <para> The parameters
839 <parameter>MAP_COASTLINE_THICKNESS</parameter>,
840 <parameter>MAP_COASTLINE_STYLE</parameter> and
841 <parameter>MAP_COASTLINE_COLOUR</parameter> control the coastline
842 thickness line style and colour respectively.
843 </para>
844
845 <important id="New_Coastline_Colour_Defaults">
846 <title>Magics++</title>Previous versions of <productname>Magics</productname>
847 plotted yellow coastlines and gridlines by default. This worked well on old dark monitors,
848 but <productname>Magics++</productname> has updated these defaults to black in order
849 to give better default plots on modern monitors and paper.
850 </important>
851
852 </section>
853
854 <section id="Coastline_Automatic_Selection">
855 <title>Coastline Automatic Selection</title>
856 <important> <title>Magics++</title>New to <productname>Magics++</productname>
857 is a flexible set of differing resolution coastlines. The new mechanisms are explained below.</important>
858
859 <para> <productname>Magics++</productname> incorporates a new set of high-resolution coastlines which were provided by
860 http://www.naturalearthdata.com . By default, <productname>Magics</productname> will select an appropriate coastline
861 file automatically, using the lowest resolution file that will give high
862 quality output. This ensures high quality whilst improving speed and reducing
863 the size of the output file. In the majority of cases this should be
864 sufficient for most users' purposes.
865 </para>
866 </section>
867
868 <section id="Specifying_a_Coastline_File">
869 <title>Specifying the coastline resolution</title>
870 <para>The first parameter that can change which coastline file is used is
871 <parameter>MAP_COASTLINE_RESOLUTION</parameter>. When set to <code>AUTOMATIC</code>
872 (its default value), the coastline file will be chosen automatically as above.
873 The possible alternatives are <code>LOW</code>, <code>MEDIUM</code> and <code>HIGH</code>.
874 This behaviour can be overridden by manually specifying one of the existing coastline files in the <productname>Magics++</productname>
875 share directory by setting the <parameter>MAP_COASTLINE_PATH</parameter> parameter.
876 <!--
877 to one of the following:</para>
878 <programlisting>
879 CALL <function>PSETC</function> ('<parameter>MAP_COASTLINE_PATH</parameter>', 'coast_high.nc')
880 CALL <function>PSETC</function> ('<parameter>MAP_COASTLINE_PATH</parameter>', 'coast_medium_high.nc')
881 CALL <function>PSETC</function> ('<parameter>MAP_COASTLINE_PATH</parameter>', 'coast_medium.nc')
882 CALL <function>PSETC</function> ('<parameter>MAP_COASTLINE_PATH</parameter>', 'coast_low.nc')
883 CALL <function>PSETC</function> ('<parameter>MAP_COASTLINE_PATH</parameter>', 'coast_very_low.nc')
884 CALL <function>PSETC</function> ('<parameter>MAP_COASTLINE_PATH</parameter>', 'coast_tiny.nc')
885 </programlisting>
886 <para> -->
887 If you have a coastline file in another directory, you can specify
888 a complete path to it in the <parameter>MAP_COASTLINE_PATH</parameter> parameter.</para>
889 <para>Note that it is not generally recommended to use a high resolution coastline
890 file with a large geographical area plot - the increase in quality will be hard to see
891 and the increase in plotting time may be significant.</para>
892 </section>
893
894 <!--
895 <section id="Creating_a_Different_Resolution_Coastline_File">
896 <title>Creating a Different Resolution Coastline File</title>
897 <para> If none of the existing files are quite right for you, you can run
898 the <filename>CoastBuilder</filename> program to generate a new one.
899 The following command line will produce a low-resolution coastline file
900 called <filename>coast_0.2.nc</filename> from the original high-resolution
901 data (<filename>coast.nc</filename>):</para>
902 <programlisting> CoastBuilder -in $MAGPLUS_HOME/share/coast.nc -out coast_0.2.nc -t 0.2</programlisting>
903 <para> You can now use this file by specifying its complete path to
904 the <parameter>MAP_COASTLINE_PATH</parameter> parameter. This program works
905 by removing points from the input file; no new points are created
906 and none are moved. The <code>-t</code> parameter specifies an error
907 threshold as a lat/long distance. The larger the value, the larger
908 the acceptable error and therefore the more points that will be removed.
909 </para>
910 </section>
911 -->
912
913 <!--
914 <section id="Filtering_the_Coastlines_at_Runtime">
915 <title>Filtering the Coastlines at Run-time</title>
916 <para> For the purpose of experimenting, it is possible to filter the coastlines
917 during the running of your <productname>Magics</productname> program. This
918 procedure uses the same filtering technique discussed briefly above.
919 The following line of code specifies that a coastline is generated by
920 filtering the original high-resolution coastline file with a threshold of 0.2:</para>
921 <programlisting> CALL PSETR ('MAP_COASTLINE_SIMPLIFICATION_FACTOR', 0.2)</programlisting>
922 <para> If you specify a <parameter>MAP_COASTLINE_PATH</parameter> then that data
923 will be filtered using the algorithm.</para>
924 </section>
925 -->
926
927 <section id="Land_and_Sea_Shading">
928 <title>Land and Sea Shading</title>
929
930 <para><productname>Magics</productname> allows the shading of the land
931 and sea in coastline plotting by means of two parameters
932 <parameter>MAP_COASTLINE_LAND_SHADE</parameter> and
933 <parameter>MAP_COASTLINE_SEA_SHADE</parameter>. The default value for
934 both is '<code>OFF</code>'. If land/sea shading is required, either or
935 both those parameters should be set to '<code>ON</code>' before
936 <function>PCOAST</function> is called. By default, land will be shaded
937 green and the sea blue. The user may change this by setting the
938 parameters <parameter>MAP_COASTLINE_LAND_SHADE_COLOUR</parameter> and
939 <parameter>MAP_COASTLINE_SEA_SHADE_COLOUR</parameter> to the desired
940 colours. Land and sea shading can be turned on or off independently
941 of each other.</para>
942
943 <important id="Coastline_Outline_And_Shading"> <title>Magics++</title>
944 Previous versions of <productname>Magics</productname> could not plot
945 both the coast outline and shading with a single call to <function>PCOAST</function> -
946 two calls were required.
947 <productname>Magics++</productname> will plot both if shading is on. To achieve the
948 effect of land or sea shading without the outlines visible, set the coastline colour
949 to be the same as the land or sea shading.
950 </important>
951
952 </section>
953 <section id="Political_boundaris">
954 <title>Political boundaries and rivers</title>
955 <para><productname>Magics</productname> offers users to extend the display of coastlines
956 with rivers and political boundaries. The data for these services are, as with the coastlines,
957 taken from http://www.naturalearthdata.com . ECMWF is not responsible for the accuracy and content of the
958 data sets and uses as they are provided by the owners.
959 </para>
960 </section>
961
962
963 <section id="Gridline_Parameters">
964 <title>Gridline Parameters</title>
965
966 <para>To change the default grid values, users could, for example, set
967 <parameter>MAP_GRID_LATITUDE_REFERENCE</parameter> to <code>6.0</code>
968 and <parameter>MAP_GRID_LATITUDE_INCREMENT</parameter> to
969 <code>5.0</code>. This would result in the latitude lines being drawn on
970 the map every 5 degrees using the 6 degree line as a reference, e.g. the
971 lines drawn could be 1, 6, 11, 16 etc. The default values for these
972 parameters are <code>0</code> and <code>10</code> respectively, which
973 results in grid lines being drawn at 0, 10, 20, 30, 40 etc. The
974 parameters <parameter>MAP_GRID_LONGITUDE_REFERENCE</parameter> and
975 <parameter>MAP_GRID_LONGITUDE_INCREMENT</parameter> perform the same
976 function for the map longitude.</para>
977
978 <!--
979 <highlights>
980 <para>Diagrams 9, 10, 11</para>
981 </highlights>
982 -->
983
984 <para>The parameter <parameter>MAP_LABEL_LATITUDE_FREQUENCY</parameter>
985 enables users to have control over the lines on which latitude labels
986 appear. If this parameter is set to <code>4</code>, for example, then
987 labels will be plotted on every fourth latitude line. The parameter
988 <parameter>MAP_LABEL_LONGITUDE_FREQUENCY</parameter> performs the same
989 function for the map longitude. Users may inhibit the plotting of grids
990 and labels by setting both the parameters,
991 <parameter>MAP_GRID</parameter> and <parameter>MAP_LABEL</parameter> to
992 '<code>OFF</code>', the default for both being '<code>ON</code>'.</para>
993 </section>
994
995 <para>Very often, three action routines are required to plot a full map,
996 e.g. <function>PCOAST</function>, <function>PCONT</function> and
997 <function>PTEXT</function>. The first action routine to be called will set
998 up the user's subpage, on which all subsequent plotting takes place. Users
999 may call the action routines in any order, providing that the parameters
1000 required have been previously set.</para>
1001
1002 <para>It is essential that mapping parameters which affect the user's
1003 subpage, i.e. those with the prefix <parameter>SUBPAGE_MAP</parameter>, be
1004 set, if required, before the first action routine is called, e.g.
1005 <parameter>SUBPAGE_LOWER_LEFT_LONGITUDE</parameter>,
1006 <parameter>SUBPAGE_MAP_SCALE</parameter>.</para>
1007 </section>
1008
1009
1010 <xi:include href="../paramtables/pnew(SUPER_PAGE)_tables.xml"
1011 xmlns:xi="http://www.w3.org/2001/XInclude" />
1012
1013 <xi:include href="../paramtables/pnew(PAGE)_tables.xml"
1014 xmlns:xi="http://www.w3.org/2001/XInclude" />
1015
1016 <xi:include href="../paramtables/pnew(SUBPAGE)_tables.xml"
1017 xmlns:xi="http://www.w3.org/2001/XInclude" />
1018
1019 <xi:include href="../paramtables/pcoast_tables.xml"
1020 xmlns:xi="http://www.w3.org/2001/XInclude" />
1021
1022
1023
1024 <xi:include href="../paramtables/XmlSceneNode_page_magml_tables.xml"
1025 xmlns:xi="http://www.w3.org/2001/XInclude" />
1026
1027 <xi:include href="../paramtables/XmlSceneNode_page_magml_flat_tables.xml"
1028 xmlns:xi="http://www.w3.org/2001/XInclude" />
1029
1030 <xi:include href="../paramtables/XmlViewNode_map_magml_tables.xml"
1031 xmlns:xi="http://www.w3.org/2001/XInclude" />
1032
1033 <xi:include href="../paramtables/XmlViewNode_map_magml_flat_tables.xml"
1034 xmlns:xi="http://www.w3.org/2001/XInclude" />
1035
1036 <!--
1037 <xi:include href="../paramtables/XmlPage_magml_tables.xml"
1038 xmlns:xi="http://www.w3.org/2001/XInclude" />
1039
1040 <xi:include href="../paramtables/XmlSubPage_magml_tables.xml"
1041 xmlns:xi="http://www.w3.org/2001/XInclude" />
1042 -->
1043 <xi:include href="../paramtables/Coastlines_coastlines_magml_tables.xml"
1044 xmlns:xi="http://www.w3.org/2001/XInclude" />
1045
1046 <xi:include href="../paramtables/Coastlines_coastlines_magml_flat_tables.xml"
1047 xmlns:xi="http://www.w3.org/2001/XInclude" />
1048
1049 <xi:include href="../paramtables/TaylorGrid_taylor_grid_magml_tables.xml"
1050 xmlns:xi="http://www.w3.org/2001/XInclude" />
1051
1052 <!-- no need for flat taylor_grid tables as it is already a flat object
1053 <xi:include href="../paramtables/TaylorGrid_taylor_grid_magml_flat_tables.xml"
1054 xmlns:xi="http://www.w3.org/2001/XInclude" />
1055 -->
1056
1057 </chapter>