| 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> <<classname>isoline</classname> <parameter>colour</parameter>='red'></programlisting> |
| 1139 |
|
| 1140 |
<para>you could declare that this attribute will be specified on the |
| 1141 |
command line:</para> |
| 1142 |
|
| 1143 |
<programlisting> <<classname>isoline</classname> <parameter>colour</parameter>='$iso_colour'></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> <<classname>isoline</classname> <parameter>colour</parameter>='${iso_colour=red}'></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><<classname>map</classname> <parameter>width</parameter>='50%'></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> |