Debian Codegraph @

docs/manual/chapters/using.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="Using_MAGICS" label="2">
15 <title>Using Magics</title>
16
17 <xi:include href="../phrases/chapterinfo_mod.xml"
18 xmlns:xi="http://www.w3.org/2001/XInclude" />
19
20 <section id="Using_MAGICS_Introduction">
21 <title>Introduction</title>
22
23 <para>There are four interfaces to <productname>Magics</productname>. A FORTRAN interface (see
24 <olink targetdoc="Magics_using" targetptr="FORTRAN_Interface" />) provides
25 the usage familiar to users of MAGICS 6; C and Python interfaces (see <olink
26 targetdoc="Magics_using" targetptr="C_Interface" /> and <olink
27 targetdoc="Magics_using" targetptr="Python_Interface" />) provide
28 identical functionality for C and Python programmers; and an XML-based
29 interface, MagML (see <olink targetdoc="Magics_using"
30 targetptr="MagML_Interface" />), is an interpreted plot description that
31 can be parsed and run without the need for a compile/link cycle.<!--A new object-oriented C++ interface is provided for
32 embedding <productname>Magics</productname> in applications.--></para>
33
34 <para>A <productname>Magics</productname> program consists of calls to
35 <firstterm>action routines</firstterm>, each of which is configured by
36 changing zero or more <firstterm>parameters</firstterm>. Parameters in
37 <productname>Magics</productname> are the attributes to be assigned to the
38 various items that make up plotted output, such as line style, colour and
39 size of plot. They can also be used to define such items as map
40 projection, contouring minimum/maximum levels. Sensible default values for
41 most parameters exist, so it may be the case that very few parameters need
42 to be set in order to obtain meaningful output. An example of a parameter
43 that has no default value is <parameter>GRIB_INPUT_FILE_NAME</parameter> -
44 if loading a GRIB file, this parameter must first be set.</para>
45
46 <para>Exactly how parameters are set and action routines are called
47 depends on which interface is used. Most examples in this manual will use
48 the FORTRAN interface, but enough information will be given to enable the
49 user to perform all tasks using MagML, C and Python.</para>
50
51 <para>This chapter also describes various tools Magics++ provides to work with the Magics library.
52 These tools are the <application>MagML_interpretor</application>, the
53 <application>magics-config</application> script and the <application>magicsCompatibilityChecker</application>.
54 </para>
55
56 </section>
57
58 <section id="FORTRAN_Interface">
59 <title>FORTRAN Interface</title>
60
61 <para>A short example program is the best introduction to
62 <productname>Magics</productname> programming. The following code contains
63 enough comments to describe what the program is doing, and is followed by
64 the plot that it generates.</para>
65
66 <section id="Program_using_fortran1">
67 <title>Program: Using FORTRAN</title>
68
69 <programlisting>
70 <xi:include href="../examples/manual/fortran/source/using_fortran1.f_cc"
71 xmlns:xi="http://www.w3.org/2001/XInclude" />
72 </programlisting>
73
74 <?pagebreak ?>
75
76 <section id="using_fortran1Plot_Output">
77 <title>Resultant Plot</title>
78
79 <mediaobject id="using_fortran1Plot">
80 <imageobject role="html">
81 <imagedata fileref="images/fortran/using_fortran1_01.png"
82 format="PNG" />
83 </imageobject>
84
85 <imageobject role="fo">
86 <imagedata fileref="../examples/manual/fortran/png/using_fortran1_01.png"
87 format="PNG" depth="10cm"/>
88 </imageobject>
89 </mediaobject>
90 </section>
91
92 <?pagebreak ?>
93 </section>
94
95 <section id="FORTRAN_InitRoutines">
96 <title>Magics Initialisation Routines in FORTRAN</title>
97
98 <para>The first <productname>Magics</productname> routine to be called
99 must be <function>POPEN</function> and the last to be called must be
100 <function>PCLOSE</function>. These two routines perform mandatory
101 initialisation and termination functions. The formats of
102 <function>POPEN</function> and <function>PCLOSE</function>, which have
103 no arguments, are:</para>
104
105 <programlisting>
106 CALL <function>POPEN</function>
107 CALL <function>PCLOSE</function>
108 </programlisting>
109 </section>
110
111 <section id="FORTRAN_ActionRoutines">
112 <title>Magics Action Routines in FORTRAN</title>
113
114 <para>In order to plot something, an action routine must be called. In
115 the example program, three plotting commands are called:
116 <function>PCOAST</function>, <function>PCONT</function> and
117 <function>PTEXT</function>. The following table shows all of the
118 available action routines.</para>
119
120 <para>
121 <table id="table_action_routines">
122 <title>Magics Action Routines</title>
123
124 <tgroup cols="2">
125 <colspec align="left" />
126
127 <thead>
128 <row>
129 <entry align="left">Syntax</entry>
130
131 <entry align="left">Description</entry>
132 </row>
133 </thead>
134
135 <tbody>
136 <row>
137 <entry>
138 <code>CALL <function>PCOAST</function></code>
139 </entry>
140
141 <entry>Plots coastlines and grids</entry>
142 </row>
143
144 <row>
145 <entry>
146 <code>CALL <function>PCONT</function></code>
147 </entry>
148
149 <entry>Plots contour fields</entry>
150 </row>
151
152 <row>
153 <entry>
154 <code>CALL <function>PWIND</function></code>
155 </entry>
156
157 <entry>Plots wind fields</entry>
158 </row>
159
160 <row>
161 <entry>
162 <code>CALL <function>POBS</function></code>
163 </entry>
164
165 <entry>Plots observations</entry>
166 </row>
167
168 <row>
169 <entry>
170 <code>CALL <function>PIMAGE</function></code>
171 </entry>
172
173 <entry>Plots images, for example satellite</entry>
174 </row>
175
176 <row>
177 <entry>
178 <code>CALL <function>PTEXT</function></code>
179 </entry>
180
181 <entry>Plots text</entry>
182 </row>
183
184 <row>
185 <entry>
186 <code>CALL <function>PGRAPH</function></code>
187 </entry>
188
189 <entry>Plots graphs</entry>
190 </row>
191
192 <row>
193 <entry>
194 <code>CALL <function>PAXIS</function></code>
195 </entry>
196
197 <entry>Plots axes</entry>
198 </row>
199
200 <row>
201 <entry>
202 <code>CALL <function>PSYMB</function></code>
203 </entry>
204
205 <entry>Plots marker symbols</entry>
206 </row>
207
208 <row>
209 <entry>
210 <code>CALL <function>PLINE</function></code>
211 </entry>
212
213 <entry>Plots lines and shapes over geographic areas</entry>
214 </row>
215
216 <row>
217 <entry>
218 <code>CALL <function>PBOXPLOT</function></code>
219 </entry>
220
221 <entry>Plots boxplots</entry>
222 </row>
223
224 <!-- <row>
225 <entry><code>CALL <function>PTAYLOR</function></code></entry>
226 <entry>Plots Taylor diagrams</entry>
227 </row>-->
228 </tbody>
229 </tgroup>
230 </table>
231 </para>
232
233 <para>Each action routine has its own set of parameters which have a
234 unique prefix to identify them. For instance, the parameter
235 <parameter>CONTOUR_LINE_STYLE</parameter> affects the operation of
236 <function>PCONT</function>. These parameters can be set by the user and,
237 if not set, the default values will be used.</para>
238
239 <tip>
240 <para>Even though parameters can be set anywhere in the user program,
241 action routines will always use the last value assigned to a parameter
242 before the action routine is called.</para>
243 </tip>
244 </section>
245
246 <section id="FORTRAN_ParameterRoutines">
247 <title>Magics Parameter Setting in FORTRAN</title>
248
249 <para>In <productname>Magics</productname>, plots generated using action
250 routines will be drawn using information from the relevant
251 <productname>Magics</productname> parameters. These parameter values can
252 be changed dynamically by calling parameter-setting routines. There are
253 only a few parameter-setting routines in
254 <productname>Magics</productname>, one for each data type.</para>
255
256 <para>The names of the parameters are passed as parameters using FORTRAN
257 character strings. This method allows easy-to-remember, English language
258 keywords and the list of keywords can be easily extended. The set of
259 routines for parameter setting is divided into four subsets: single
260 parameter setting, single parameter resetting, array parameter setting
261 and multiple parameter setting.</para>
262
263 <para>Values of <productname>Magics</productname> parameters can also be retrieved by using the function
264 <function>ENQR</function> and passing it the parameter name as an input parameter.</para>
265
266
267 <section id="Single_Parameter_Setting">
268 <title>Single Parameter Setting and Resetting</title>
269
270 <para>There are three subroutines to assign a single value to a
271 parameter, each postfixed with a <code>C</code> , <code>I</code> or
272 <code>R</code> , corresponding to a different argument type:</para>
273
274 <para>
275 <table id="table_single_param_routines">
276 <title>Magics Single Parameter Setting Routines</title>
277
278 <tgroup cols="2">
279 <colspec align="left" colwidth="260" />
280
281 <thead>
282 <row>
283 <entry align="left">Function Call Syntax</entry>
284
285 <entry align="left">Description</entry>
286 </row>
287 </thead>
288
289 <tbody>
290 <row>
291 <entry>
292 <code>CALL <function>PSETC</function> ( MAGICS_PARAMETER,
293 CVALUE )</code>
294 </entry>
295
296 <entry>For setting character arguments</entry>
297 </row>
298
299 <row>
300 <entry>
301 <code>CALL <function>PSETI</function> ( MAGICS_PARAMETER,
302 IVALUE )</code>
303 </entry>
304
305 <entry>For setting integer arguments</entry>
306 </row>
307
308 <row>
309 <entry>
310 <code>CALL <function>PSETR</function> ( MAGICS_PARAMETER,
311 RVALUE )</code>
312 </entry>
313
314 <entry>For setting real arguments</entry>
315 </row>
316 </tbody>
317 </tgroup>
318 </table>
319 </para>
320
321 <para>The first argument should be a character variable or constant
322 specifying the <productname>Magics</productname> parameter to be
323 set.The <code>VALUE</code> argument should be of the corresponding
324 type for the chosen subroutine.</para>
325
326 <para>A parameter may be reset to its default value using the function
327 <function>PRESET</function>:</para>
328
329 <para>There are three subroutines to assign a single value to a
330 parameter, each postfixed with a <function>C</function>,
331 <function>I</function> or <function>R</function> , corresponding to a
332 different argument type:</para>
333
334 <para>
335 <table id="table_single_param_reset_routines">
336 <title>Magics Single Parameter Resetting Routine</title>
337
338 <tgroup cols="2">
339 <colspec align="left" colwidth="300" />
340
341 <thead>
342 <row>
343 <entry align="left">Function Call Syntax</entry>
344
345 <entry align="left">Description</entry>
346 </row>
347 </thead>
348
349 <tbody>
350 <row>
351 <entry>
352 <code>CALL <function>PRESET</function>( MAGICS_PARAMETER
353 )</code>
354 </entry>
355
356 <entry>For resetting a parameter of any data type</entry>
357 </row>
358 </tbody>
359 </tgroup>
360 </table>
361 </para>
362 <!--
363 <remark>
364 <para>
365 This subroutine is preferable to resetting a parameter to
366 its default value with a normal parameter setting routine since it
367 also resets an internal <productname>Magics</productname> flag that
368 indicates that the parameter has or has not been assigned a user
369 value. This means that parameters which have more than one default
370 value, depending on the setting of another parameter, can be
371 correctly reset.
372 </para>
373 </remark>
374 -->
375 </section>
376
377 <section id="Array_Parameter_Setting">
378 <title>Array Parameter Setting</title>
379
380 <para>There are seven subroutines for passing information to Magics in
381 the form of arrays:</para>
382
383 <para>
384 <table id="table_array_param_routines">
385 <title>Magics Array Parameter Setting Routines</title>
386
387 <tgroup cols="2">
388 <colspec align="left" colwidth="330" />
389
390 <thead>
391 <row>
392 <entry align="left">Syntax</entry>
393
394 <entry align="left">Description</entry>
395 </row>
396 </thead>
397
398 <tbody>
399 <row>
400 <entry>
401 <code>CALL <function>PSET1C</function> ( MAGICS_PARAMETER,
402 CARRAY, N1 )</code>
403 </entry>
404
405 <entry>For 1-dimensional character array arguments</entry>
406 </row>
407
408 <row>
409 <entry>
410 <code>CALL <function>PSET1I</function> ( MAGICS_PARAMETER,
411 IARRAY, N1 )</code>
412 </entry>
413
414 <entry>For 1-dimensional integer array arguments</entry>
415 </row>
416
417 <row>
418 <entry>
419 <code>CALL <function>PSET2I</function> ( MAGICS_PARAMETER,
420 IARRAY, N1, N2 )</code>
421 </entry>
422
423 <entry>For 2-dimensional integer array arguments</entry>
424 </row>
425
426 <row>
427 <entry>
428 <code>CALL <function>PSET3I</function> ( MAGICS_PARAMETER,
429 IARRAY, N1, N2, N3 )</code>
430 </entry>
431
432 <entry>For 3-dimensional integer array arguments</entry>
433 </row>
434
435 <row>
436 <entry>
437 <code>CALL <function>PSET1R</function> ( MAGICS_PARAMETER,
438 RARRAY, N1 )</code>
439 </entry>
440
441 <entry>For 1-dimensional real array arguments</entry>
442 </row>
443
444 <row>
445 <entry>
446 <code>CALL <function>PSET2R</function> ( MAGICS_PARAMETER,
447 RARRAY, N1, N2 )</code>
448 </entry>
449
450 <entry>For 2-dimensional real array arguments</entry>
451 </row>
452
453 <row>
454 <entry>
455 <code>CALL <function>PSET3R</function> ( MAGICS_PARAMETER,
456 RARRAY, N1, N2, N3 )</code>
457 </entry>
458
459 <entry>For 3-dimensional real array arguments</entry>
460 </row>
461 </tbody>
462 </tgroup>
463 </table>
464 </para>
465
466 <para>The fifth character of the subroutine name indicates that an
467 array is being passed and also indicates its dimensionality. The sixth
468 character indicates the FORTRAN type of the array, i.e. Character,
469 Integer or Real.</para>
470
471 <para>The first argument should be a character variable or constant
472 specifying the <productname>Magics</productname> parameter to be
473 set.The <code>VALUE</code> argument should be of the corresponding
474 type for the chosen subroutine.</para>
475
476 <para>The second argument should be an array of the appropriate data
477 type containing the data to be assigned to the
478 <productname>Magics</productname> parameter.</para>
479
480 <para>Arguments N1, N2, N3 are integers which inform
481 <productname>Magics</productname> of the size of the array being
482 passed, i.e. number of elements in each dimension of the array.</para>
483
484 <para>This type of subroutine can be used, for example, to pass lists
485 of contour levels to <productname>Magics</productname>, e.g.</para>
486
487 <programlisting> CALL <function>PSET1R</function>('<parameter>CONTOUR_LEVEL_LIST</parameter>', RLIST, 25)</programlisting>
488
489 <para>where the real array <code>RLIST</code> contains a list of 25
490 contour levels.</para>
491
492 <!--
493 <para>They can also be used, for example, to assign values to arrays
494 of two or more dimensions. For example, it may be used for passing
495 data arrays to Magics for contouring, e.g. CALL
496 PSET2R('INPUT_FIELD',RARRAY, 240, 121) where RARRAY is the array to be
497 contoured and the dimensions of the array are (240,121) . In the
498 interests of efficiency, Magics will not copy the data arrays passed
499 to it by the array parameter setting routines, it will only set up a
500 pointer to the user array. It is therefore essential that users do not
501 change the content of arrays passed to Magics until after they have
502 made a call to the action routine that uses the data.</para>
503 -->
504 </section>
505 </section>
506
507 <!--
508 <section>
509 Multiple Parameter Setting
510 </section>
511
512 <section>
513 Enquiry Routines
514 </section>
515 -->
516
517 <section id="FORTRAN_PseudoActionRoutines">
518 <title>Magics Pseudo-Action Routines in FORTRAN</title>
519
520 <para>As distinct from action routines, the pseudo action routines
521 perform a type of action that does not result in plotted output but
522 signifies a change of state in <productname>Magics</productname>, such
523 as moving to a new page.</para>
524
525 <para>Pseudo action routine <function>PNEW</function> will change from
526 one plot area to another. The format of <function>PNEW</function>
527 is:</para>
528
529 <para>
530 <table id="table_pseudo_action_routines">
531 <title>Magics Pseudo-Action Routines</title>
532
533 <tgroup cols="2">
534 <colspec align="left" />
535
536 <thead>
537 <row>
538 <entry align="left">Function Call</entry>
539
540 <entry align="left">Description</entry>
541 </row>
542 </thead>
543
544 <tbody>
545 <row>
546 <entry>
547 <code>CALL <function>PNEW</function> ( 'SUPER_PAGE' )</code>
548 </entry>
549
550 <entry>To start a new super-page</entry>
551 </row>
552
553 <row>
554 <entry>
555 <code>CALL <function>PNEW</function> ( 'PAGE' )</code>
556 </entry>
557
558 <entry>To start a new page</entry>
559 </row>
560
561 <row>
562 <entry>
563 <code>CALL <function>PNEW</function> ( 'SUBPAGE' )</code>
564 </entry>
565
566 <entry>To start a new subpage</entry>
567 </row>
568 </tbody>
569 </tgroup>
570 </table>
571 </para>
572
573 <para>The change of plotting area does not take place when
574 <function>PNEW</function> is called but when the next action routine is
575 called. Pseudo action routine <function>PNEW</function> is described in
576 <olink targetdoc="Magics_layout_mapping_coastlines"
577 targetptr="Layout_Mapping_and_Coastlines" />.</para>
578 </section>
579
580 <!--
581 <section>
582 Specification Groups
583 </section>
584
585 -->
586
587 <section id="MAGICS_Data_Loading_Routines_in_FORTRAN">
588 <title>Magics Data Loading Routines in FORTRAN</title>
589
590 <para>The following action routines are used to read data:</para>
591
592 <para>
593 <table id="table_data_reading_routines">
594 <title>Magics Data Reading Routines</title>
595
596 <tgroup cols="2">
597 <colspec align="left" />
598
599 <thead>
600 <row>
601 <entry align="left">Function Call</entry>
602
603 <entry align="left">Description</entry>
604 </row>
605 </thead>
606
607 <tbody>
608 <row>
609 <entry>
610 <code>CALL <function>PGRIB</function></code>
611 </entry>
612
613 <entry>Reads contouring and wind fields presented to Magics in
614 the form of WMO standard GRIB code</entry>
615 </row>
616
617 <row>
618 <entry>
619 <code>CALL <function>PNETCDF</function></code>
620 </entry>
621
622 <entry>Reads data from a NetCDF file</entry>
623 </row>
624
625 <row>
626 <entry>
627 <code>CALL <function>PBUFR</function></code>
628 </entry>
629
630 <entry>Reads observation data from a BUFR file. Note that this
631 replaces POBS from <productname>MAGICS
632 6</productname>.</entry>
633 </row>
634 <!--
635 <row>
636 <entry>
637 <code>CALL <function>PODB</function></code>
638 </entry>
639
640 <entry>Reads data from an ODB database using an SQL
641 query</entry>
642 </row>
643 -->
644 </tbody>
645 </tgroup>
646 </table>
647 </para>
648
649 <para />
650 </section>
651
652 <section id="magicsCompatibilityChecker">
653 <title>The magicsCompatibilityChecker</title>
654
655 <para>
656 With its Fortran interface, Magics++ tries to be as backwards compatible as possible to MAGICS 6.
657 Unfortunately this was not always possible and changes in the API have occurred. To help users to
658 access if their Magics Fortran programs need changing a script is provided.
659 This script is called <application>magicsCompatibilityChecker</application> and is called from the
660 command line followed by the name of code file to be checked. An output will be printed to alert users of changes in the Fortran API.
661 </para>
662 <para>
663 <command>magicsCompatibilityChecker <replaceable>mycode.f</replaceable> </command>
664 </para>
665
666 </section>
667 </section>
668
669
670
671 <section id="C_Interface">
672 <title>C Interface</title>
673
674 <para><productname>Magics</productname> provides a C programming
675 interface. This interface is identical to the FORTRAN interface in terms
676 of functionality, but with different action routine names in order to
677 avoid conflicts with some C standard library names.</para>
678
679 <section id="Converting_From_FORTRAN_to_C">
680 <title>Converting From FORTRAN to C</title>
681
682 <para>If you wish to copy an existing FORTRAN
683 <productname>Magics</productname> program and change it to C, then here
684 are the things that you will need to change within the body of the
685 program:</para>
686
687 <itemizedlist>
688 <listitem>
689 <para>In order to derive the C form of an action routine, take the
690 FORTRAN routine name, change it to lower case and replace the
691 initial <code>P</code> with <code>mag_</code>. For example,
692 <function>POPEN</function> becomes
693 <function>mag_open</function>.</para>
694 </listitem>
695
696 <listitem>
697 <para>Strings in C use double quotes, not single quotes
698 (<code>"</code> not <code>'</code>).</para>
699 </listitem>
700
701 <listitem>
702 <para>Remember to place a semicolon at the end of each line.</para>
703 </listitem>
704
705 <listitem>
706 <para>Remember that in C, function names are case-sensitive, but the
707 <productname>Magics</productname> parameter names are not.</para>
708 </listitem>
709
710 <listitem>
711 <para>In FORTRAN, if a 2-dimensional array is declared as
712 <code>DIMENSION FIELD (NLON,NLAT)</code>, the equivalent in C would
713 be <code>double Field[NumLat][NumLon]</code>, ie the array indices
714 are 'the other way around'.</para>
715 </listitem>
716 </itemizedlist>
717 </section>
718
719 <section id="C_Example">
720 <title>C Interface Example</title>
721
722 <para>The following example shows how to use
723 <productname>Magics</productname> in a C program.</para>
724
725 <programlisting>
726 <xi:include href="../examples/manual/c/source/cont_colours.c_cc"
727 xmlns:xi="http://www.w3.org/2001/XInclude" />
728 </programlisting>
729
730 <figure id="figure_using_c1Plot_Output">
731 <title>Resultant plot from example C program</title>
732
733 <mediaobject id="using_cPlot">
734 <imageobject role="html">
735 <imagedata fileref="images/c/cont_colours_01.png" format="PNG" />
736 </imageobject>
737
738 <imageobject role="fo">
739 <imagedata fileref="../examples/manual/c/png/cont_colours_01.png"
740 format="PNG" depth="10cm" />
741 </imageobject>
742 </mediaobject>
743 </figure>
744 </section>
745 </section>
746
747 <section id="Python_Interface">
748 <title>Python Interfaces</title>
749
750
751 <section id="Python_Interface_procedural">
752 <title>Procedural Python interface</title>
753
754 <para>From version 2.7 onwards <productname>Magics</productname>
755 provides a procedural Python programming interface. This interface is identical to
756 the FORTRAN and C interfaces in terms of functionality, with action
757 routine names similar to the Fortran interface. </para>
758
759 <section id="Converting_From_FORTRAN_to_Python">
760 <title>Converting From FORTRAN to Python</title>
761
762 <para>If you wish to copy an existing FORTRAN
763 <productname>Magics</productname> program and change it to Python, then
764 here are the things that you will need to change within the body of the
765 program:</para>
766
767 <itemizedlist>
768 <listitem>
769 <para>The <productname>Magics</productname> interface needs to be imported at the start of your script using
770 <code>import Magics</code> and all <productname>Magics</productname> commands need to be prefix with the namespace <productname>Magics.</productname>.
771 This is not strictly necessary but keeps a clear separation of Magics and other code.</para>
772 </listitem>
773
774 <listitem>
775 <para>In order to derive the Python form of an action routine, take the
776 FORTRAN routine name, change it to lower case and replace the
777 initial <code>P</code> with the namespace <code>Magics</code>. There are few exception such as,
778 <function>POPEN</function> becomes <function>Magics.init()</function> and <function>PCLOSE</function> becomes <function>Magics.finalize()</function>.</para>
779 </listitem>
780
781 <listitem>
782 <para>Strings in Python use double quotes, not single quotes
783 (<code>"</code> not <code>'</code>).</para>
784 </listitem>
785
786 <listitem>
787 <para>In Python, function names are case-sensitive, but the
788 <productname>Magics</productname> parameter names are not.</para>
789 </listitem>
790
791 <listitem>
792 <para>In FORTRAN, if a 2-dimensional array is declared as
793 <code>DIMENSION FIELD (NLON,NLAT)</code>, the equivalent in Python and follows the same convention as C. Please be aware that for arrays Magics uses NumPy.</para>
794 </listitem>
795 </itemizedlist>
796 </section>
797
798 <section id="Python_Example">
799 <title>Python Interface Example</title>
800
801 <para>The following example shows how to use
802 <productname>Magics</productname> in a Python program.</para>
803
804 <programlisting>
805 <xi:include href="../examples/manual/python/source/using_python01.py_cc"
806 xmlns:xi="http://www.w3.org/2001/XInclude" />
807 </programlisting>
808
809 <figure id="figure_using_py1Plot_Output_01">
810 <title>Page 1 of resultant plot from example Python program</title>
811
812 <mediaobject id="using_pyPlot_01">
813 <imageobject role="html">
814 <imagedata fileref="images/python/using_python01_01.png" format="PNG" />
815 </imageobject>
816
817 <imageobject role="fo">
818 <imagedata fileref="../examples/manual/python/png/using_python01_01.png"
819 format="PNG" depth="10cm"/>
820 </imageobject>
821 </mediaobject>
822 </figure>
823 <figure id="figure_using_py1Plot_Output_02">
824 <title>Page 2 of resultant plot from example Python program</title>
825
826 <mediaobject id="using_pyPlot_02">
827 <imageobject role="html">
828 <imagedata fileref="images/python/using_python01_02.png" format="PNG" />
829 </imageobject>
830
831 <imageobject role="fo">
832 <imagedata fileref="../examples/manual/python/png/using_python01_02.png"
833 format="PNG" depth="10cm"/>
834 </imageobject>
835 </mediaobject>
836 </figure>
837 </section>
838 </section>
839 <section id="Python_other">
840 <title>Higher-level Python Interfaces</title>
841 <para>Additional to the procedural Python interface, <productname>Magics</productname> also offers since version 2.9
842 a higher level Python interface called <productname>MagMacro</productname>. This interface offers a more higher level
843 and object-oriented interface, based on <productname>Metview</productname> Macro.
844 </para>
845 <!--
846 <section id="Python_magmacro">
847 <title>magmacro.py</title>
848 <para></para>
849 </section>
850 -->
851 <section id="magmacro_Example">
852 <title>Python Interface Example</title>
853
854 <para>The following example shows how to use
855 <productname>Magics</productname> in a Python program.</para>
856
857 <programlisting>
858 <xi:include href="../examples/manual/python/source/using_python02.py_cc"
859 xmlns:xi="http://www.w3.org/2001/XInclude" />
860 </programlisting>
861
862 <figure id="figure_using_py2Plot_Output_02">
863 <title>Resultant plot from above example Python program</title>
864
865 <mediaobject id="using_pyPlot2_02">
866 <imageobject role="html">
867 <imagedata fileref="images/python/using_python02_01.png" format="PNG" />
868 </imageobject>
869
870 <imageobject role="fo">
871 <imagedata fileref="../examples/manual/python/png/using_python02_01.png"
872 format="PNG" depth="10cm"/>
873 </imageobject>
874 </mediaobject>
875 </figure>
876 </section>
877
878 </section>
879 </section>
880
881
882 <section id="User_Setup">
883 <title>User setup and compilation</title>
884 <para>This section will discuss the setup needed by users to use the installed <productname>Magics</productname> library and its applications.</para>
885
886 <section id="environment_variables">
887 <title>Magics++ environment variables</title>
888 <para>The variable $MAGPLUS_HOME is the path where <productname>Magics</productname> will find all auxillary data at runtime.
889 If <productname>Magics</productname> is installed where the configure prefix option was set to, this variable does NOT need to be set.
890 Otherwise the variable needs to be set for all users of Magics programs. If <productname>Magics</productname> reports problems at run-time
891 about missing coastlines or fonts this variable might not be set correctly.</para>
892 <para>Magics++ provides feedback on the console. You can control the messages plotted by setting any of the following environment variables:</para>
893 <para> $MAGPLUS_INFO - Information and hints to what Magics++ is doing</para>
894 <para> $MAGPLUS_DEBUG - Debug information</para>
895 <para> $MAGPLUS_QUIET - suppresses the Magics++ header, footer and info output – only errors and warnings will cause output</para>
896 </section>
897 <section id="system_enviro">
898 <title>System environment variables</title>
899 <para>Hint: If you choose a standard system folder, such as /usr/local/, for your installation you might not have to change any system environment variables. </para>
900 <para>$LD_LIBRARY_PATH - To work with shared libraries the locations of these libraries need to be known at run time. This environment variable contains a list of paths where at run-time the system loader will look for libraries. To use the shared library version of Magics++ the location of the library needs to be set in $LD_LIBRARY_PATH. If the variable is not set correctly the loader might pick up a version of Magics++ which was not intended.</para>
901 <para>If EmosLib is compiled with Pgf90, it binds in libpgc.so dynamically at runtime and so the path to this library needs to be in $LD_LIBRARY_PATH.</para>
902 <para>$PATH - Magics++ provides not only libraries, but also some executables. To use these, the $PATH needs to include the location of these programs. Usually this will be $MAGPLUS_HOME/bin. </para>
903 </section>
904
905 <section id="magics_config">
906 <title>magics-config</title>
907 <para>To simplify the user setup Magics++ installs a script called magics-config, which prints out the options to compile Magics++ programs. The options are based on the options used to compile Magics++. The program outputs the compilation and linkage options which can be used directly in the compilation instruction, as shown below.</para>
908 <para/>
909 <para>To compile a C program and link it to Magics++ you only need to type</para>
910 <programlisting>
911 gcc shade.c -o shade `magics-config --clibs --cxxflags`
912 </programlisting>
913 <para>
914 To compile simple Magics Fortran programs you can use <code>magics-config</code> by typing
915 <programlisting>
916 magics-config --compile=test.f
917 </programlisting>
918 In case a different suffix is used for Fortran code the call can be extended to
919 <programlisting>
920 magics-config --compile=test.F90 --suffix=F90
921 </programlisting>
922 There is a similar shortcut for C code called <code>--compileC=test.c</code>.
923 </para>
924 <para>To do so $MAGPLUS_HOME/bin needs to be added to the $PATH first or magics-config called with its full path. Please be
925 aware that the option '--print-setup' will tell you which environment variables you need to set before you can compile and
926 run Magics++ programs. You might want to add this setup in your shell or start-up scripts. Below you find the usage help for
927 magics-config.</para>
928
929 <programlisting>
930 Usage: magics-config [OPTION] ...
931
932 Uses by default version 2.12.5 of Magics++.
933
934 Generic options
935 --version output Magics++ version information.
936 --help display this help and exit.
937 --print-setup print how the environment can be set up
938
939 Compilation support options
940 --cxxflags print pre-processor and compiler flags for C/C++
941 --libs print linking flags for C++
942 --clibs print linking flags for C
943 --f90static print library linking information (static)
944 --f90shared print library linking information (shared)
945
946 --compile compile simple Magics++ Fortran programs (default single precision!)
947 Example: magics-config --compile=wind.f
948 --compileC compile simple Magics++ C programs
949 Example: magics-config --compileC=wind.c
950 --suffix set suffix of Fortran or C code files
951
952 --double include compiler option for fortran double precision
953 (default single - only for interface - internally only double is used)
954 --64bit include fortran option for 64 bit
955
956 C/C++ flags use shared libraries if possible, otherwise static libraries are used. '--double' has
957 NO effect on C/C++ programs.
958
959 Install directories Magics++ was configured to
960 --prefix[=DIR]
961 </programlisting>
962 <para/>
963 </section>
964
965 <section id="pkg-config-compiling">
966 <title>Compiling with pkg-config</title>
967 <para><firstterm>pkg-config</firstterm> is a script that provides a unified interface for querying installed
968 libraries for the purpose of compiling software from its source code. <code>pkg-config</code> was originally designed for
969 Linux but is now also available for the various BSDs, Microsoft Windows, Mac OS X, and Solaris. It outputs various
970 information about installed libraries. This information may include parameters for C or C++ compiler and parameters
971 for linker.</para>
972 <para>This script is very similar to what <code>magics-config</code> offers, but <code>pkg-config</code> is more
973 general while <code>magics-config</code> has very Magics specific options.
974 </para>
975 <programlisting>
976 gcc -o test test.c $(pkg-config --libs --cflags magics)
977 </programlisting>
978 <para>
979 To find the information about Magics compilation the environment variable PKG_CONFIG_PATH
980 needs to contain the directory <code>$MAGPLUS_HOME/lib/pkgconfig</code>. For more information
981 visit <ulink url="http://en.wikipedia.org/wiki/Pkg-config">pkg-config on Wikipedia</ulink>.
982 </para>
983 </section>
984 <section id="magicsm4">
985 <title>Using Magics++ in your own configure scripts [advanced]</title>
986 To simplify the use of the Magics library in software also using the <firstterm>autotools</firstterm> package, a script called
987 <code>magics.m4</code> is provided. The file can be found in the Magics++ install directory under <code>share/aclocal/</code>.
988 It is recommended to copy the file into the own project and include it in the <code>configure.ac</code> file by typing
989 <programlisting>
990 m4_include(m4/magics.m4)
991 </programlisting>
992 This will provide the configure script with the option <code>--with-magics</code> to query Magics on the system.
993 Internally <code>magics.m4</code> uses <code>magics-config</code>.
994 </section>
995 </section>
996
997
998 <section id="MagML_Interface">
999 <title>MagML Interface</title>
1000
1001 <para>New in <productname>Magics++</productname> is an interface, based on
1002 XML, for describing plots. This interface is different to other
1003 interfaces, which use programming languages to describe a plot. In
1004 contrast to programming languages, <firstterm>MagML</firstterm> cannot
1005 offer procedural programming. However, flexibility is provided by the use
1006 of <firstterm>templates</firstterm> - see <olink targetdoc="Magics_using"
1007 targetptr="MagML_Templates" />.</para>
1008
1009 <para>MagML offers users a way to describe their plots in a text file. The
1010 MagML interpreter program reads this text file and generates the plots;
1011 this process eliminates the need for compiling a FORTRAN or C program.
1012 Variable elements such as the path to a data file can be supplied on the
1013 command line.</para>
1014
1015 <para>A plot is described through a hierarchy of objects. Data access is
1016 possible by defining an input data file or a database request.</para>
1017
1018 <section id="The_MagML_Interpreter">
1019 <title>The MagML Interpreter</title>
1020
1021 <para>To generate <productname>Magics</productname> plots from MagML
1022 files, a program called <application>magmlx</application> is provided.
1023 The program will be available to the user after the
1024 <productname>Magics</productname> environment is set up.</para>
1025
1026 <para>The command-line usage of the interpreter is as follows:</para>
1027
1028 <para>
1029 <command>magmlx <replaceable>file.magml</replaceable> <option>
1030 [-varname1=value1 ...]</option></command>
1031 </para>
1032
1033 <para>The parameters shown as <option>-varname1=value1</option> are
1034 described in <olink targetdoc="Magics_using"
1035 targetptr="MagML_Templates" />.</para>
1036
1037 <para>A short example program is the best introduction to
1038 <productname>Magics</productname> programming with MagML. The MagML
1039 source is followed by the plot that it generates. The important parts of
1040 the code will then be discussed.</para>
1041 </section>
1042
1043 <section id="Program_using_MagML1">
1044 <title>Program: Using MagML</title>
1045
1046 <programlisting>
1047 <xi:include href="../examples/manual/magml/source/using_magml1.magml_cc"
1048 xmlns:xi="http://www.w3.org/2001/XInclude" />
1049 </programlisting>
1050
1051 <figure id="figure_using_magml1Plot_Output">
1052 <title>Resultant plot from example MagML program</title>
1053
1054 <mediaobject id="using_magml1Plot">
1055 <imageobject role="html">
1056 <imagedata fileref="images/magml/using_magml1.png" format="PNG" />
1057 </imageobject>
1058
1059 <imageobject role="fo">
1060 <imagedata fileref="../examples/manual/magml/png/using_magml1.png"
1061 format="PNG" depth="10cm" />
1062 </imageobject>
1063 </mediaobject>
1064 </figure>
1065 </section>
1066
1067 <!-- id="Program_using_MagML1" -->
1068
1069 <?pagebreak ?>
1070
1071 <section id="MagML_Discussion">
1072 <title>MagML Discussion</title>
1073
1074 <para>First we establish that we are describing a
1075 <productname>Magics</productname> plot by providing a
1076 <classname>magics</classname> tag, and that the version of MagML we are
1077 compatible with is 3.0. Future versions of the MagML specification may
1078 break or cause unexpected results in existing MagML plots, and so the
1079 <parameter>version</parameter> attribute can be used by the MagML
1080 interpreter to inform the user of any relevant changes. Page dimensions
1081 can also be specified here.</para>
1082
1083 <para>The <classname>drivers</classname> object defines the output
1084 files. See <olink targetdoc="Magics_drivers"
1085 targetptr="MAGICS_Output_Drivers" /> for details of the output drivers.
1086 In this example, we produce two output files: one in PostScript format
1087 and one in GIF format. Filenames are given without extensions - these
1088 will be added automatically.</para>
1089
1090 <para>Now we define a <classname>page</classname> object which will
1091 contain all the plots to be made on a single page of output.</para>
1092
1093 <para>The <classname>map</classname> object sets up an actual plot area
1094 within the page. Geographic view parameters are set here with the
1095 <classname>cylindrical</classname> object which is set to use its
1096 default parameters - our plot will be in cylindrical projection.</para>
1097
1098 <para>Next the coastlines are set up - the <classname>coast</classname>
1099 and <classname>grid</classname> are sub-objects of the
1100 <classname>coastlines</classname> object and have attributes which may
1101 be set.</para>
1102
1103 <para>Next we define a <firstterm>plot</firstterm>. A plot contains two
1104 things: a description of the data we want to plot and a description of
1105 how we want to plot it. Here we define a <classname>grib</classname>
1106 object with its path specified. Then we define a contouring object
1107 (<classname>contour</classname>) which contains the information needed
1108 to plot it. This object contains a sub-object
1109 (<classname>isoline</classname>) which sets the properties of the
1110 isolines.
1111 <!--
1112 To overlay two meteorological variables in the same plot we
1113 could define another layer within the page. A
1114 <classname>layer</classname> object sets up a layer in geographical
1115 coordinates; an <classname>xylayer</classname> object sets up a layer in
1116 user coordinates for x/y plots.
1117 -->
1118 </para>
1119
1120 <para>Finally, two <classname>text</classname> objects set up an
1121 automatic and a user title.</para>
1122 </section>
1123
1124 <!-- id="MagML_Discussion" -->
1125
1126 <section id="MagML_Templates">
1127 <title>MagML Templates</title>
1128
1129 <para>The flexibility of MagML is greatly enhanced by the use of
1130 <firstterm>templates</firstterm>. A template is a MagML description file
1131 which contains zero or more <firstterm>variables</firstterm>,
1132 placeholders which are replaced by user-defined text supplied to the
1133 <application>magml</application> program on the command line.</para>
1134
1135 <para>For instance, instead of giving a contour colour in the MagML file
1136 as:</para>
1137
1138 <programlisting> &lt;<classname>isoline</classname> <parameter>colour</parameter>='red'&gt;</programlisting>
1139
1140 <para>you could declare that this attribute will be specified on the
1141 command line:</para>
1142
1143 <programlisting> &lt;<classname>isoline</classname> <parameter>colour</parameter>='$iso_colour'&gt;</programlisting>
1144
1145 <para>This value can then be supplied on the command line, for
1146 example:</para>
1147
1148 <para>
1149 <command>magmlx <replaceable>file.magml</replaceable>
1150 <option>-iso_colour=green</option></command>
1151 </para>
1152
1153 <para />
1154
1155 <para>A default value can be provided in order to deal with cases where
1156 no value is given on the command line:</para>
1157
1158 <programlisting> &lt;<classname>isoline</classname> <parameter>colour</parameter>='${iso_colour=red}'&gt;</programlisting>
1159
1160 <para>If passing a string which contains spaces, place quotes around
1161 it:</para>
1162
1163 <para>
1164 <command>magmlx <replaceable>file.magml</replaceable>
1165 <option>-title_text="2m Temperature, 1st December
1166 2007"</option></command>
1167 </para>
1168
1169 <para />
1170
1171 <tip>Note that a 'standard' MagML description file is simply a special
1172 case of a template - one with zero variables to be replaced!</tip>
1173 </section>
1174
1175 <!-- id="MagML_Templates" -->
1176
1177 <section id="MagML_Definitions">
1178 <title>MagML Definitions</title>
1179
1180 <para>It is possible to predefine some elements at the start of a MagML
1181 file and then reference them later in the same file. This technique
1182 allows you to re-use elements within a MagML description as demonstrated
1183 in the following example:</para>
1184
1185 <programlisting>
1186 <xi:include href="../examples/manual/magml/source/using_magml2.magml_cc"
1187 xmlns:xi="http://www.w3.org/2001/XInclude" />
1188 </programlisting>
1189
1190 <para>The <classname>definitions</classname> element contains all the
1191 elements we may wish to re-use. Each one is assigned a unique
1192 <parameter>id</parameter> which is then referenced by setting it as the
1193 value of a <parameter>use_id</parameter> attribute as shown above. This
1194 idea can be expanded to re-use an element multiple times.</para>
1195
1196 <para>Another use for definitions is to generate fixed variations of a
1197 plot. This is especially powerful when combined with the idea of
1198 templates (see <olink targetdoc="Magics_using"
1199 targetptr="MagML_Templates" />). In the following example, we set up two
1200 different map views - one displays a global area, the other is
1201 restricted to Europe. The <parameter>id</parameter> of the area to use
1202 is determined by the variable <code>area</code>. This is set to a
1203 default value of <code>globe</code> but can also be set on the command
1204 line.</para>
1205
1206 <programlisting>
1207 <xi:include href="../examples/manual/magml/source/using_magml3.magml_cc"
1208 xmlns:xi="http://www.w3.org/2001/XInclude" />
1209 </programlisting>
1210
1211 <para>If this MagML description is stored in a file called
1212 <filename>plotmap.magml</filename>, then it could be invoked on the
1213 command line in any of the following three ways:</para>
1214
1215 <para><command>magmlx <replaceable>plotmap.magml</replaceable></command>
1216 (will plot a global map)</para>
1217
1218 <para><command>magmlx <replaceable>plotmap.magml</replaceable>
1219 <option>-area=globe</option></command> (will plot a global map)</para>
1220
1221 <para><command>magmlx <replaceable>plotmap.magml</replaceable>
1222 <option>-area=europe</option></command> (will plot a European
1223 map)</para>
1224 </section>
1225
1226 <!-- id="MagML_Definitions" -->
1227
1228 <section id="MagML_ParamTables">
1229 <title>MagML Parameter Tables</title>
1230
1231 <para>Each chapter contains complete descriptions of one or more MagML
1232 elements relating to that chapter's topic. All possible attributes and
1233 sub-elements are listed in MagML format. This means that it is possible
1234 to copy and paste those elements into your own MagML code. All
1235 attributes are listed with their default values, meaning that you can
1236 delete all the elements and attributes that you do not wish to
1237 alter.</para>
1238
1239 <para>The following listing gives the overall structure of a MagML
1240 description. If you copy this, you will need to edit it, as it contains
1241 more information than a simple skeleton of a MagML element.</para>
1242
1243 <xi:include href="../paramtables/magml_outline.xml"
1244 xmlns:xi="http://www.w3.org/2001/XInclude" />
1245
1246 <para>Elements in this table have comments showing whether they can be
1247 repeated or not in a single MagML description. A
1248 <classname>plot</classname> may contain only one element to describe the
1249 data source, but multiple elements to visualise the data. For instance a
1250 single data source may be plotted with contours, text and a
1251 legend.</para>
1252
1253 <para>Some of the above elements are hyperlinked to their detailed
1254 descriptions in their respective chapters. In the PDF documents, this
1255 may take you to the start of the chapter; you will then need to click on
1256 the appropriate link in the table of contents to see the
1257 description.</para>
1258 </section>
1259
1260 <!-- id="MagML_ParamTables" -->
1261
1262 <section id="Flexible_MagML-Styles">
1263 <title> MagML Coding Styles</title>
1264
1265 <para>MagML version 3 has an important difference from previous
1266 versions. Whilst backward-compatibility has been mostly retained, a new
1267 flexibility has been introduced. Versions 1 and 2 used a strict system
1268 of hierarchical objects with short attribute names linked to their tag.
1269 Version 3 of MagML maintains this system, but also allows for a more
1270 'flat' expression of objects. An example follows, and then some
1271 explanation.</para>
1272 <!--
1273 <section id="Example_gribloop_magml_all_tables">
1274 <title>MagML Templates for GRIB Loop Input</title>
1275 -->
1276 <xi:include href="../paramtables/GribLoop_gribloop_magml_tables.xml"
1277 xmlns:xi="http://www.w3.org/2001/XInclude" />
1278
1279 <xi:include href="../paramtables/GribLoop_gribloop_magml_flat_tables.xml"
1280 xmlns:xi="http://www.w3.org/2001/XInclude" />
1281 <!-- </section>
1282 -->
1283 <para>The first version shows the deepest possible hierarchy of objects.
1284 This was the only option available in MagML versions 1 and 2. The second
1285 version of the code shows a completely flat structure with just one
1286 object - the attribute names are fully expanded in order to uniquely
1287 identify them.</para>
1288
1289 <para>Which format you use is largely a matter of personal preference,
1290 but there are some issues which may affect your decision. The
1291 hierarchical format has the advantage that definitions (see <olink
1292 targetdoc="Magics_using" targetptr="MagML_Definitions" />) can be more
1293 precisely targeted at a sub-object. The flat format shows the attribute
1294 names in their fully expanded form and will be more familiar to users of
1295 the Fortran or C interfaces. It will also be more familiar to users of
1296 Metview, as it also uses these expanded names.</para>
1297 </section>
1298 <!--
1299 <section id="User_Selectable_Layers">
1300 <title>User-Selectable Layers</title>
1301
1302 <para>Interactive output formats such as SVG and KML allow graphical
1303 layers to be independently toggled on and off. Layers are specified in
1304 MagML by the <classname>layer</classname> tag. Simply embed one or more
1305 <classname>plot</classname> objects within a
1306 <classname>layer</classname> tag in order to group them into a layer.
1307 Plots which are not within a layer cannot be controlled by the user, and
1308 will always be visible. Multiple plots within the same layer will be
1309 controlled as one. In order to allow all plots to be controlled
1310 independently, embed all the <classname>plot</classname> objects into
1311 their own <classname>layer</classname> tag. When drawing to a raster
1312 output format such as GIF, each layer will be output to a separate file.
1313 An example using layers follows.</para>
1314
1315 <programlisting>
1316 <xi:include href="../examples/manual/magml/source/using_magml4.magml_cc"
1317 xmlns:xi="http://www.w3.org/2001/XInclude" />
1318 </programlisting>
1319
1320 <figure id="figure_using_magml4Plot_Output">
1321 <title>Multi-layer SVG plot from MagML program</title>
1322
1323 <mediaobject id="using_magml4Plot">
1324 <imageobject role="html">
1325 <imagedata fileref="images/magml/using_magml4_svg_screenshot.png"
1326 format="PNG" />
1327 </imageobject>
1328
1329 <imageobject role="fo">
1330 <imagedata fileref="../examples/manual/magml/png/using_magml4_svg_screenshot.png"
1331 format="PNG" />
1332 </imageobject>
1333 </mediaobject>
1334 </figure>
1335 </section>
1336 -->
1337 <!-- id='User_Selectable_Layers' -->
1338
1339 <section id="GRIB_loop_in_MagML">
1340 <title>Using GRIB loops in Magml</title>
1341
1342 <para>MagML has a feature which allows for the automatic production of a
1343 series of plots, overlays or an animation from the fields in a single GRIB file.</para>
1344
1345 <section id='Producing_one_plot_per_field'>
1346 <title>Producing one plot per field</title>
1347 <para>Animations are generated when the output driver is <code>'kml'</code> or
1348 <code>'animated_gif'</code>. The PostScript driver (<code>'ps'</code>)
1349 produces a single file with each plot on a separate page. The single-page
1350 drivers such as '<code>png</code>' and '<code>svg</code>' produce one file
1351 for each plot. Note that in all cases except <code>'kml'</code>, this
1352 facility can be used to generate multiple plots per page by setting
1353 the map dimensions to be less than 50% of the page width or height.
1354 This provides a simple way to plot, for instance, thumbnails
1355 of all fields in a GRIB file.</para>
1356
1357 <para>A GRIB loop is enabled by placing a
1358 <classname>gribloop</classname> object just below the
1359 <classname>page</classname> level. The following example shows how to
1360 set it up, and an explanation follows.</para>
1361
1362 <programlisting>
1363 <xi:include href="../examples/manual/magml/source/using_magml5.magml_cc"
1364 xmlns:xi="http://www.w3.org/2001/XInclude" />
1365 </programlisting>
1366
1367 <para>The layer within the <classname>gribloop</classname> will be
1368 repeated over the fields of the GRIB file. The
1369 <code>'loop_step_span'</code> parameter is used in KML output to specify
1370 the duration of the validity of the field; this allows fields with
1371 different base times to be overlaid in applications such as Google
1372 Earth.</para>
1373
1374
1375 </section> <!-- Producing_one_plot_per_field -->
1376
1377
1378 <section id='Producing_one_plot_in_total'>
1379 <title>Producing one plot in total</title>
1380 <para>When placed inside the <classname>map</classname> level,
1381 the <classname>gribloop</classname> will cause all fields to be
1382 overlaid on the one map. The following example shows how to do this.</para>
1383
1384 <programlisting>
1385 <xi:include href="../examples/manual/magml/source/using_magml6.magml_cc"
1386 xmlns:xi="http://www.w3.org/2001/XInclude" />
1387 </programlisting>
1388
1389 </section> <!-- Producing_one_plot_in_total -->
1390
1391
1392 <para>See <olink targetdoc="Magics_data"
1393 targetptr="GRIBloop_input_magml_all_tables" /> for the complete set of
1394 MagML objects and parameters that are available for this purpose.</para>
1395
1396
1397 </section> <!-- GRIB_loop_in_MagML -->
1398
1399
1400
1401
1402
1403 <section id="MagML_Page_Layout">
1404 <title>MagML Page Layout</title>
1405
1406 <para>Some elements of a plot are positionable and resizeable. These are the
1407 <classname>page</classname>, <classname>map</classname>, <classname>legend</classname>
1408 and <classname>text</classname> objects. See <olink targetdoc="Magics_using"
1409 targetptr="MagML_ParamTables" /> for the specific attributes but, for example,
1410 specifying <code>&lt;<classname>map</classname> <parameter>width</parameter>='50%'&gt;</code>
1411 will produce a map which occupies half of the width of the page. More specifically,
1412 this is 50% of the <classname>map</classname> object's parent <classname>page</classname>
1413 object, which may also have a non-default size and position. If the size does
1414 not include a percentage sign, then it is assumed to be given in centimetres.</para>
1415
1416 <para>By default, an object's position is
1417 '<code>inline</code>'. In this case, the ordering of the objects in the MagML code
1418 is important - they will be automatically arranged left-to-right and top-to-bottom: if
1419 there is sufficient space to the right of the previous object, then that is where the
1420 current one will be placed; otherwise, it will go below. The <parameter>top</parameter>
1421 and <parameter>left</parameter> attributes of the object will not be considered in this mode.</para>
1422
1423 <para>An alternative is to position an object as '<code>block</code>'. Here, the object
1424 will be placed below the previously specified one. This mode has the property that
1425 the layout of the objects on screen roughly follows their layout in the source MagML code
1426 (since an object's MagML code will be below that of the preceding object's code).
1427 The object's <parameter>top</parameter> attribute will not be considered in this mode,
1428 but its <parameter>left</parameter> attribute will.</para>
1429
1430 <para>The final alternative is to specify an object's position as '<code>absolute</code>' in which
1431 case the positional attributes for that object will be used - remember that the position
1432 is relative to the parent object. In this case, both the <parameter>top</parameter>
1433 and <parameter>left</parameter> attributes of the object will be considered.</para>
1434
1435 </section> <!-- id="MagML_Page_Layout" -->
1436
1437 </section> <!-- id="MagML_Interface" -->
1438
1439
1440
1441
1442 <!--
1443 <remark>
1444 <section id="Metgrams">
1445 <title>Metgrams</title>
1446
1447 <para>The Metgram application is a specialised MagML interpreter which
1448 takes high level parameters from a specialised XML-based description language called
1449 <firstterm>EPSML</firstterm> and generates one of a number of styles of metgrams from
1450 a MagML-based template. The EPSML description
1451 should provide details of the following:</para>
1452
1453 <itemizedlist>
1454 <listitem>
1455 <para>a template to use: either a path to a local file or else, if only
1456 a filename is given, then <application>metgram</application> will search the
1457 <filename>templates</filename> directory in the <productname>Magics</productname>
1458 installation; there are a number of predefined metgram templates installed here.</para>
1459 </listitem>
1460
1461 <listitem>
1462 <para>a path to a spot database where the data for the metgram can be found.</para>
1463 </listitem>
1464
1465 <listitem>
1466 <para>details of a station: the location will be used when retrieving the data,
1467 the name is used in the metgram's title. Output file names are specified here.</para>
1468 </listitem>
1469
1470 <!++ at time of writing, this does not really work that well... XXXXXXX
1471 <listitem>
1472 <para>there can be multiple stations specified in the file; for each station,
1473 a metgram is produced.</para>
1474 </listitem>
1475 ++>
1476 </itemizedlist>
1477
1478 <section id="The_Metgram_Application">
1479 <title>The Metgram Application</title>
1480 <para>To generate metgrams from MagML descriptions a program
1481 called <application>metgram</application> is provided. The program will
1482 be available to the user after the <productname>Magics</productname> environment is set up.</para>
1483
1484 <para>The command-line usage of <application>metgram</application> is as follows:</para>
1485
1486 <para><command>metgram <replaceable>file.epsml</replaceable></command></para>
1487
1488 </section>
1489
1490
1491 <section id="Metgram_Description_Files">
1492 <title>Metgram Description Files</title>
1493 <para>The only command-line parameter required is the name of the metgram description file.
1494 This is in EPSML format, illustrated by an example:</para>
1495
1496 <programlisting>
1497 <xi:include href="../examples/manual/metgram/source/metgram-helsinki.epsml_cc" parse="xml"
1498 xmlns:xi="http://www.w3.org/2001/XInclude" />
1499 </programlisting>
1500
1501 <para></para>
1502 </section>
1503
1504
1505 </section>
1506
1507 </remark>
1508 -->
1509 <section id="metgrams">
1510 <title>Metgrams from Weather Parameter files</title>
1511
1512 <para>Magics' Python interface allows users to visualise Weather Parameter files. These files are a product of ECMWF and are disseminated
1513 in BUFR format. A more detailed description of the format can be found at</para>
1514 <itemizedlist>
1515 <listitem>http://www.ecmwf.int/services/dissemination/3.1/Meteorological_Bulletin_M3_1_20.html</listitem>
1516 </itemizedlist>
1517
1518 <para>To reproduce what is called a <code>classic metgram</code> as shown below, a small python script needs to be written.</para>
1519
1520 <mediaobject id="metgram_example">
1521 <imageobject role="fo">
1522 <imagedata fileref="../diagrams/metgram.png" format="PNG" depth="14cm" />
1523 </imageobject>
1524
1525 <imageobject role="html">
1526 <imagedata fileref="images/diagrams/metgram.png" format="PNG" depth="14cm" />
1527 </imageobject>
1528 </mediaobject>
1529
1530 <para>The user can control a few parameters such as:</para>
1531 <itemizedlist>
1532 <listitem>The PostScript filename for the output </listitem>
1533 <listitem>The station position and title. ( Note that the position should be in the BUFR input file)</listitem>
1534 <listitem>The list of parameters to be displayed </listitem>
1535 </itemizedlist>
1536
1537 <para>Example code:</para>
1538
1539 <programlisting>
1540 from metgram import *
1541
1542 #Definition of the output
1543 ps = ps({"output_fullname":"metgram.ps"})
1544
1545 #definition of the Station
1546 mystation = station({"input_filename":"GRA07041200071412001",
1547 "station_latitude":"40.62",
1548 "station_longitude":"35.82",
1549 "station_name":"My Test Station"})
1550
1551 metgram(ps, mystation, cloud, humidity, precip, msl, wind, temperature)
1552 </programlisting>
1553
1554 <para>The script can be excuted by typing</para>
1555
1556 <para><programlisting> python myexample.py</programlisting></para>
1557
1558 <para>In the first version (<productname>Magics</productname> 2.12), the user can create a PostScript using the function <code>ps</code>. In this function,
1559 the user can further specify the name of the PostScript file using the parameter key <code>output_fullname</code>: </para>
1560
1561 <para><programlisting> ps = ps({"output_fullname":"metgram.ps"})</programlisting></para>
1562
1563 <para>The metgram application is expecting a BUFR file as input, and a location to extract from this file. The location is defined by its
1564 latitude and longitude, and its name will appear in the title:</para>
1565 <programlisting>
1566 mystation = station({"input_filename":"GRA07041200071412001",
1567 "station_latitude":"40.62",
1568 "station_longitude":"35.82",
1569 "station_name":"My Test Station"})
1570 </programlisting>
1571
1572 <para>The table below gives an overview of the parameters currently supported:</para>
1573
1574 <table id="table_metgram_params">
1575 <title>Metgram parameters</title>
1576
1577 <tgroup cols="5">
1578 <colspec align="left" />
1579
1580 <thead>
1581 <row>
1582 <entry align="left">name</entry>
1583 <entry align="left">BUFR descriptor</entry>
1584 <entry align="left">scaling</entry>
1585 <entry align="left">offset</entry>
1586 <entry align="left">visualisation</entry>
1587 </row>
1588 </thead>
1589
1590 <tbody>
1591
1592 <row>
1593 <entry>cloud</entry>
1594 <entry>20010</entry>
1595 <entry>1</entry>
1596 <entry>0</entry>
1597 <entry>blue bar</entry>
1598 </row>
1599 <row>
1600 <entry>humidity</entry>
1601 <entry>13003</entry>
1602 <entry>1</entry>
1603 <entry>0</entry>
1604 <entry>red curve</entry>
1605 </row>
1606 <row>
1607 <entry>precip</entry>
1608 <entry>13011</entry>
1609 <entry>1</entry>
1610 <entry>0</entry>
1611 <entry>blue bar</entry>
1612 </row>
1613 <row>
1614 <entry>msl</entry>
1615 <entry>10051</entry>
1616 <entry>0.01</entry>
1617 <entry>0</entry>
1618 <entry>red curve</entry>
1619 </row>
1620 <row>
1621 <entry>wind</entry>
1622 <entry><para>u:11003</para><para>v:11004</para></entry>
1623 <entry>1</entry>
1624 <entry>0</entry>
1625 <entry>red flags</entry>
1626 </row>
1627 <row>
1628 <entry>temperature</entry>
1629 <entry><para>T2m: 12004</para><para>T850:12001</para></entry>
1630 <entry>1</entry>
1631 <entry>-273.15</entry>
1632 <entry><para>T2m as red curve<para></para>T850 as blue curve</para></entry>
1633 </row>
1634
1635 </tbody>
1636 </tgroup>
1637 </table>
1638 <para>For future releases it is planned to add more parameters and to allow users to specify their own tailored parameters and visualisations.</para>
1639
1640 </section>
1641
1642
1643
1644 <section id="Colours">
1645 <title>Setting colours</title>
1646 <para>Various parameters let the user set colours for different action routines. <productname>Magics</productname> offers various ways to specify a colour value:</para>
1647 <itemizedlist>
1648 <listitem>By name - A list of 56 predefined colour names, such as <code>BLUE</code>, <code>RED</code>, <code>RED_ORANGE</code>.</listitem>
1649 <listitem>By RGB(A) values - The user specifies the colours by their Red-Green-Blue(-Alpha) value. Examples: <code>RGB(1.,0.,0.)</code> for red,
1650 <code>RGB(1.,0,1.)</code> for purple.</listitem>
1651 <listitem>By RGB(A) Hex values - Similar as above the RGB(A) components are expressed in HTML hex notation. Examples: <code>#FF0000</code> for red.</listitem>
1652 <listitem>By HSL(A) values - These are three numbers: the first is an angle from 0 to 360 representing Hue,
1653 then two numbers from 0 to 1 representing Saturation and Lightness.
1654 The following diagram shows the HSL colour wheel:
1655
1656 <mediaobject id="colourwheel_diagram">
1657 <imageobject role="fo">
1658 <imagedata fileref="../diagrams/hsl_colour_wheel.png" format="PNG" />
1659 </imageobject>
1660
1661 <imageobject role="html">
1662 <imagedata fileref="images/diagrams/hsl_colour_wheel.png" format="PNG" depth="4cm" />
1663 </imageobject>
1664 </mediaobject>
1665 </listitem>
1666 </itemizedlist>
1667
1668
1669 <para>However the colours are specified, when <productname>Magics</productname> generates a colour scale from one
1670 colour to another, it internally traverses the HSL wheel either in a clockwise or anti-clockwise direction
1671 (this is user-configurable). This is important in order to understand the series of colours produced.</para>
1672
1673 <tip>
1674 <para>Magics++ now also supports transparency. Unfortunately not all output formats (PostScript) support this feature.</para>
1675 </tip>
1676 <para>Please be aware that colours might be converted to a different colour space, dependent
1677 on the selected (graphical) output format.</para>
1678
1679 <para>The following is a chart showing all available named colours in Magics.</para>
1680
1681 <mediaobject id="colourchart_diagram">
1682 <imageobject role="fo">
1683 <imagedata fileref="../diagrams/col_table.png" format="PNG" />
1684 </imageobject>
1685
1686 <imageobject role="html">
1687 <imagedata fileref="images/diagrams/col_table.png" format="PNG" />
1688 </imageobject>
1689 </mediaobject>
1690
1691 </section>
1692
1693 </chapter>