| 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 |
|
| 15 |
<chapter id="MAGICS_Output_Drivers" label="3"> |
| 16 |
<title>Magics Output Drivers</title> |
| 17 |
|
| 18 |
<xi:include href="../phrases/chapterinfo_mod.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 19 |
|
| 20 |
|
| 21 |
<section id="Drivers_Introduction"> |
| 22 |
<title>Introduction</title> |
| 23 |
|
| 24 |
<para><productname>Magics</productname> is capable of producing plots in a number of different file |
| 25 |
formats, detailed in the following sections. By default, PostScript output will be produced.</para> |
| 26 |
|
| 27 |
<para>As other parts of <productname>Magics</productname> the code is structured modular to allow |
| 28 |
easier maintenance and to add easily new output formats. Each module is called a driver and supports |
| 29 |
at least one output format.</para> |
| 30 |
|
| 31 |
<para> |
| 32 |
Please be aware that not all output drivers might be installed on your system. Some output drivers dependent on third-party libraries. |
| 33 |
If these are missing at compilation time <productname>Magics++</productname> cannot support all formats. |
| 34 |
Please consult the installation guide for more information. |
| 35 |
</para> |
| 36 |
|
| 37 |
<para> |
| 38 |
The output drivers have undergone major changes since <productname>MAGICS 6</productname>. |
| 39 |
Please be aware that some default values have changed and are not backwards compatible. For example, |
| 40 |
in previous versions PostScript output was by default shrunken to 95% of its actual size to be |
| 41 |
resilient against changes in printer setups. This is not as much as an issue anymore and therefore the default |
| 42 |
scaling has been set to 100% again. |
| 43 |
</para> |
| 44 |
|
| 45 |
<para>A special output driver is generating Qt which is only intended for screen display. This driver is |
| 46 |
used by <productname>Metview</productname> and is not documented further here. |
| 47 |
</para> |
| 48 |
|
| 49 |
<section id="Output_Parameters"> |
| 50 |
<title>Controlling the output formats</title> |
| 51 |
|
| 52 |
<para>Parameters can be set to influence how the output formats are generated. |
| 53 |
Some parameters are effective on all format, such as file name, and some are |
| 54 |
specific for each format.</para> |
| 55 |
|
| 56 |
<important> |
| 57 |
<title>Magics++</title> |
| 58 |
The interface has been revised to increase consistency and simplify user |
| 59 |
code. The old MAGICS 6 'DEVICE' parameters have been kept for backwards |
| 60 |
compatibility, but the use of the new parameters is strongly recommended. |
| 61 |
</important> |
| 62 |
</section> |
| 63 |
|
| 64 |
</section> |
| 65 |
|
| 66 |
<section id="Output_Formats"> |
| 67 |
<title>Selecting output formats and their naming</title> |
| 68 |
|
| 69 |
<para>This section will describe how file formats can be chosen and output names are control |
| 70 |
by <productname>Magics</productname>.</para> |
| 71 |
|
| 72 |
<para>By default, the output format for a <productname>Magics</productname> plot is |
| 73 |
PostScript (<code>PS</code>). |
| 74 |
You may select a different output format by setting parameter |
| 75 |
<parameter>OUTPUT_FORMAT</parameter> to any of the following:</para> |
| 76 |
|
| 77 |
<table border="1" id="table_Output_Formats"> |
| 78 |
<title>Output Formats</title> |
| 79 |
<tgroup cols="4"> |
| 80 |
<colspec colwidth="130" /> |
| 81 |
<colspec colwidth="60" /> |
| 82 |
<colspec colwidth="140" /> |
| 83 |
<colspec colwidth="90" /> |
| 84 |
<thead> |
| 85 |
<row> |
| 86 |
<entry align="center">Value</entry> |
| 87 |
<entry align="center">Graphics File Format</entry> |
| 88 |
<entry align="center">Pages</entry> |
| 89 |
<entry align="center">Driver</entry> |
| 90 |
</row> |
| 91 |
</thead> |
| 92 |
<tbody> |
| 93 |
|
| 94 |
<row> |
| 95 |
<entry>PS</entry> |
| 96 |
<entry>vector</entry> |
| 97 |
<entry>produces a single file*</entry> |
| 98 |
<entry>PostScript</entry> |
| 99 |
</row> |
| 100 |
|
| 101 |
<row> |
| 102 |
<entry>EPS</entry> |
| 103 |
<entry>vector</entry> |
| 104 |
<entry>produces multiple files</entry> |
| 105 |
<entry>PostScript</entry> |
| 106 |
</row> |
| 107 |
|
| 108 |
<row> |
| 109 |
<entry>PDF</entry> |
| 110 |
<entry>vector</entry> |
| 111 |
<entry>produces a single file</entry> |
| 112 |
<entry>Cairo</entry> |
| 113 |
</row> |
| 114 |
|
| 115 |
<row> |
| 116 |
<entry>PNG</entry> |
| 117 |
<entry>raster</entry> |
| 118 |
<entry>produces multiple files</entry> |
| 119 |
<entry>Cairo</entry> |
| 120 |
</row> |
| 121 |
|
| 122 |
<row> |
| 123 |
<entry>GIF</entry> |
| 124 |
<entry>raster</entry> |
| 125 |
<entry>produces multiple files</entry> |
| 126 |
<entry>GD</entry> |
| 127 |
</row> |
| 128 |
|
| 129 |
<row> |
| 130 |
<entry>GIF_ANIMATION</entry> |
| 131 |
<entry>raster</entry> |
| 132 |
<entry>produces a single file</entry> |
| 133 |
<entry>GD</entry> |
| 134 |
</row> |
| 135 |
|
| 136 |
<row> |
| 137 |
<entry>JPEG</entry> |
| 138 |
<entry>raster</entry> |
| 139 |
<entry>produces multiple files**</entry> |
| 140 |
<entry>GD</entry> |
| 141 |
</row> |
| 142 |
|
| 143 |
<row> |
| 144 |
<entry>SVG</entry> |
| 145 |
<entry>vector</entry> |
| 146 |
<entry>produces multiple files</entry> |
| 147 |
<entry>SVG</entry> |
| 148 |
</row> |
| 149 |
|
| 150 |
<row> |
| 151 |
<entry>KML</entry> |
| 152 |
<entry>vector</entry> |
| 153 |
<entry>produces single KMZ file</entry> |
| 154 |
<entry>KML</entry> |
| 155 |
</row> |
| 156 |
</tbody> |
| 157 |
</tgroup> |
| 158 |
</table> |
| 159 |
|
| 160 |
<para>*It is also possible to produce multiple single-page PostScript files, see |
| 161 |
<olink targetdoc="Magics_drivers" targetptr="PostScript_Page_Splitting" /> |
| 162 |
below.</para> |
| 163 |
<para>**The JPEG format uses a lossy compression algorithm, resulting in |
| 164 |
lost quality.</para> |
| 165 |
|
| 166 |
<para>To set in a Fortran program the output format to PNG type:</para> |
| 167 |
|
| 168 |
<programlisting> |
| 169 |
CALL <function>PSETC</function> ('<parameter>OUTPUT_FORMAT</parameter>', 'PNG') |
| 170 |
</programlisting> |
| 171 |
|
| 172 |
<para>The PostScript based vector formats (PS, EPS, PDF) are the most appropriate for high-quality |
| 173 |
hard-copy printing; the raster formats are more suitable for web pages. |
| 174 |
The SVG driver produces SVG files suitable for interactive |
| 175 |
visualisation or the dynamic generation of raster plots at different scales. |
| 176 |
EPS is a vector format most suited for inclusion in Office and Latex documents.</para> |
| 177 |
|
| 178 |
<section id="Selecting_Multiple_Output_Formats"> |
| 179 |
<title>Selecting Multiple Output Formats</title> |
| 180 |
|
| 181 |
<para><productname>Magics</productname> can generate plots in multiple output formats simultaneous. |
| 182 |
For instance, a single <productname>Magics</productname> program can create the same plot in |
| 183 |
both PostScript and PNG formats in a single run. This approach has a performance advantage over running |
| 184 |
the program separately for each output format as much of the processing is performed |
| 185 |
only once. The parameter to set is <parameter>OUTPUT_FORMATS</parameter> (note the 'S' on the end). |
| 186 |
The following code shows how to set two output devices:</para> |
| 187 |
|
| 188 |
<table border="1" id="table_Multiple_Output_Formats"> |
| 189 |
<title>Selecting Multiple Output Formats</title> |
| 190 |
<tgroup cols="2"> |
| 191 |
<colspec colwidth="70" /> |
| 192 |
<colspec colwidth="400" /> |
| 193 |
<tbody> |
| 194 |
|
| 195 |
<row><entry>FORTRAN</entry> |
| 196 |
<entry><programlisting> |
| 197 |
CHARACTER*10 FORMATS |
| 198 |
DIMENSION FORMATS(2) |
| 199 |
DATA FORMATS /'PS', 'PNG'/ |
| 200 |
|
| 201 |
CALL <function>POPEN</function> |
| 202 |
CALL <function>PSET1C</function> ('<parameter>OUTPUT_FORMATS</parameter>', FORMATS, 2) |
| 203 |
CALL <function>PSETC</function> ('<parameter>OUTPUT_NAME</parameter>', 'multiformat') |
| 204 |
</programlisting></entry> |
| 205 |
</row> |
| 206 |
<row><entry>C</entry> |
| 207 |
<entry><programlisting> |
| 208 |
const char *formats [NumFormats] = {"PS", "PNG"}; |
| 209 |
|
| 210 |
<function>mag_open</function> (); |
| 211 |
<function>mag_set1c</function> ("<parameter>OUTPUT_FORMATS</parameter>", formats, 2); |
| 212 |
<function>mag_setc</function> ("<parameter>OUTPUT_NAME</parameter>", "multiformat"); |
| 213 |
</programlisting></entry> |
| 214 |
</row> |
| 215 |
<row><entry>MagML</entry> |
| 216 |
<entry><programlisting> |
| 217 |
<<classname>drivers</classname>> |
| 218 |
<<classname>ps</classname> <parameter>scale</parameter> = '95' /> |
| 219 |
<<classname>png</classname> /> |
| 220 |
<<classname>drivers</classname>/> |
| 221 |
</programlisting></entry> |
| 222 |
</row> |
| 223 |
</tbody> |
| 224 |
</tgroup> |
| 225 |
</table> |
| 226 |
|
| 227 |
<para>For a single-page plot, the above code will produce two files: |
| 228 |
<filename>multiformat.ps</filename> and <filename>multiformat.1.png</filename>. |
| 229 |
The following section explains the file-naming rules in more detail.</para> |
| 230 |
</section> |
| 231 |
|
| 232 |
|
| 233 |
|
| 234 |
<section id="Filenames_Conventions"> |
| 235 |
<title>Filenames</title> |
| 236 |
<para>For a single-file plot, as produced by |
| 237 |
<code>PS</code>, <code>PDF</code> and <code>GIF_ANIMATION</code>, |
| 238 |
the default output filename will be <filename>magics.<ext></filename> |
| 239 |
where <ext> is replaced by the extension appropriate to the output format. |
| 240 |
For the default format (PostScript) this would produce the file <filename>magics.ps</filename>, |
| 241 |
for animated PNG it would be <filename>magics.png</filename> and so on. The following |
| 242 |
code shows how to change the filename:</para> |
| 243 |
<para></para> |
| 244 |
<programlisting> CALL <function>PSETC</function> ('<parameter>OUTPUT_NAME</parameter>', 'plot')</programlisting> |
| 245 |
<para></para> |
| 246 |
|
| 247 |
<para>In this case if the output format is PDF, then the output filename |
| 248 |
will be <filename>plot.pdf</filename> and so on.</para> |
| 249 |
|
| 250 |
<para>When producing a multiple-file plot, a number is also added to each page, |
| 251 |
although this can be deactivated for the first page. So for instance, |
| 252 |
if the following parameters are set for a three-page plot:</para> |
| 253 |
|
| 254 |
|
| 255 |
<table border="1" id="table_Filename_Examples"> |
| 256 |
<title>Filename Examples</title> |
| 257 |
<tgroup cols="2"> |
| 258 |
<colspec colwidth="80" /> |
| 259 |
<colspec colwidth="400" /> |
| 260 |
<tbody> |
| 261 |
|
| 262 |
<row><entry>Default</entry> |
| 263 |
<entry><programlisting> |
| 264 |
CALL <function>PSETC</function> ('<parameter>OUTPUT_FORMAT</parameter>', 'PNG') |
| 265 |
CALL <function>PSETC</function> ('<parameter>OUTPUT_NAME</parameter>', 'plot') |
| 266 |
</programlisting>the resultant files will be: |
| 267 |
<programlisting> |
| 268 |
plot.1.png |
| 269 |
plot.2.png |
| 270 |
plot.3.png |
| 271 |
</programlisting>Note that even if the plot has only one page and therefore produces |
| 272 |
just one file, the name of that file still obeys the rules in the table above. |
| 273 |
</entry> |
| 274 |
</row> |
| 275 |
<row><entry>First page numbering OFF</entry> |
| 276 |
<entry><programlisting> |
| 277 |
CALL <function>PSETC</function> ('<parameter>OUTPUT_FORMAT</parameter>', 'PNG') |
| 278 |
CALL <function>PSETC</function> ('<parameter>OUTPUT_NAME</parameter>', 'plot') |
| 279 |
CALL <function>PSETC</function> ('<parameter>OUTPUT_NAME_FIRST_PAGE_NUMBER</parameter>', 'OFF') |
| 280 |
</programlisting>the resultant files will be: |
| 281 |
<programlisting> |
| 282 |
plot.png |
| 283 |
plot.2.png |
| 284 |
plot.3.png |
| 285 |
</programlisting></entry> |
| 286 |
</row> |
| 287 |
|
| 288 |
</tbody> |
| 289 |
</tgroup> |
| 290 |
</table> |
| 291 |
|
| 292 |
<para>The formatting of the numbers can be modified through the parameter |
| 293 |
<parameter>OUTPUT_FILE_MINIMAL_WIDTH</parameter>. For instance, setting this to |
| 294 |
<code>2</code> would produce a filename such as <filename>plot.02.png</filename> |
| 295 |
instead of <filename>plot.2.png</filename>.</para> |
| 296 |
|
| 297 |
<para>The character between the root |
| 298 |
and the number can be changed by setting the parameter |
| 299 |
<parameter>OUTPUT_FILE_SEPARATOR</parameter>. For instance, setting this to |
| 300 |
<code>_</code> (underscore) would produce a filename such as <filename>plot_2.png</filename> |
| 301 |
instead of <filename>plot.2.png</filename>.</para> |
| 302 |
|
| 303 |
<section id="Filenames_Legacy_and_Fine_Control"> |
| 304 |
<title>Filenames - Legacy and Fine Control</title> |
| 305 |
|
| 306 |
<para>The above file-naming control should be enough for most purposes |
| 307 |
and is recommended for the most consistent naming of output files.</para> |
| 308 |
|
| 309 |
<para>However, an extra degree of control is available by not using |
| 310 |
<parameter>OUTPUT_NAME</parameter>, but instead:</para> |
| 311 |
|
| 312 |
<itemizedlist> |
| 313 |
<listitem> |
| 314 |
<para><parameter>OUTPUT_FULLNAME</parameter> : does not add an extension to the |
| 315 |
supplied filename, instead it needs to be supplied with the file name</para> |
| 316 |
</listitem> |
| 317 |
<listitem> |
| 318 |
<para><parameter>OUTPUT_LEGACY_NAME</parameter> : behaves similar to |
| 319 |
<productname>MAGICS 6</productname> filenaming</para> |
| 320 |
</listitem> |
| 321 |
</itemizedlist> |
| 322 |
</section> |
| 323 |
|
| 324 |
</section> |
| 325 |
|
| 326 |
|
| 327 |
<section id="Common_Drivers_Parameters"> |
| 328 |
<title>Common parameters for all drivers</title> |
| 329 |
<xi:include href="../paramtables/BaseDriver_tables.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 330 |
</section> |
| 331 |
|
| 332 |
</section> |
| 333 |
|
| 334 |
<section id="PostScript_Driver"> |
| 335 |
<title>The PostScript driver</title> |
| 336 |
|
| 337 |
<para>PostScript was developed by Adobe and is still the main format for printers under UNIX. Since traditionally |
| 338 |
meteorological maps were aimed for print-outs, PostScript is historically the default |
| 339 |
output of <productname>Magics</productname>. No third-party library is required |
| 340 |
to generate PostScript files and the driver is always available to users.</para> |
| 341 |
|
| 342 |
<section id="PostScript_Page_Splitting"> |
| 343 |
<title>Page Splitting</title> |
| 344 |
<para>By default, a multi-page plot will result in a single output file containing |
| 345 |
those multiple pages. It is possible to alter this behaviour by setting |
| 346 |
the <parameter>OUTPUT_PS_SPLIT</parameter> parameter:</para> |
| 347 |
|
| 348 |
<programlisting> |
| 349 |
CALL <function>PSETC</function> ('<parameter>OUTPUT_PS_SPLIT</parameter>', 'ON') |
| 350 |
</programlisting> |
| 351 |
|
| 352 |
<para>When this is set, each page will be plotted to a new PostScript file, |
| 353 |
following the filenaming rules in the table above.</para> |
| 354 |
|
| 355 |
<important> <title>Magics++</title> |
| 356 |
<para>This behaviour differs from previous versions of |
| 357 |
<productname>Magics</productname> where the environment variable |
| 358 |
<envar>PS_SPLIT</envar> was used instead of a |
| 359 |
<productname>Magics</productname> parameter.</para> |
| 360 |
</important> |
| 361 |
</section> |
| 362 |
|
| 363 |
<section id="PostScript_Page_Scaling"> |
| 364 |
<title>Page Scaling</title> |
| 365 |
|
| 366 |
<para>Even though printers support standardised page sizes, such as A4 and A3, they |
| 367 |
often are not able to print on the full page. Depending on the printer an border |
| 368 |
area surrounding the page cannot be printed on. This needs to be kept in mind if |
| 369 |
designing maps to be printed. To help with this <productname>Magics</productname> |
| 370 |
provides an option to shrink/rescale a PostScript page to fit to the printer.</para> |
| 371 |
|
| 372 |
<important> <title>Magics++</title> |
| 373 |
In previous versions PostScript output was by default shrunken to 95% of its actual size to be |
| 374 |
resilient against changes in printer setups. This is not an issue anymore and therefore the default |
| 375 |
scaling has been set to 100% again. Please use '<parameter>OUTPUT_PS_SCALE</parameter>' and set |
| 376 |
it to '0.95' if this kind of scaling is still required. |
| 377 |
</important> |
| 378 |
</section> |
| 379 |
|
| 380 |
<section id="Generating_EPS_output"> |
| 381 |
<title>EPS</title> |
| 382 |
|
| 383 |
<para>The EPS file format does not support multiple pages, so if a |
| 384 |
multi-page plot is created in EPS format, multiple files are generated |
| 385 |
using the rules above, as if '<parameter>OUTPUT_PS_SPLIT</parameter>' is on. EPS is best if maps need to be used within <productname>Word</productname> and <productname>Latex</productname> documents. |
| 386 |
</para> |
| 387 |
</section> |
| 388 |
|
| 389 |
<xi:include href="../paramtables/PostScript_tables.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 390 |
|
| 391 |
<section id = 'PostScriptDriver_magml_all_tables'> |
| 392 |
<title>MagML Templates for PostScript Output</title> |
| 393 |
|
| 394 |
<xi:include href="../paramtables/PostScriptDriver_ps_magml_tables.xml" |
| 395 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 396 |
<!-- |
| 397 |
<xi:include href="../paramtables/PostScriptDriver_ps_magml_flat_tables.xml" |
| 398 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 399 |
--> |
| 400 |
</section> |
| 401 |
</section> <!-- End of PS --> |
| 402 |
|
| 403 |
|
| 404 |
<section id="SVG_Driver"> |
| 405 |
<title>The SVG driver</title> |
| 406 |
|
| 407 |
<para> |
| 408 |
This output driver produces vector graphics in the SVG format as defined by the W3C. The |
| 409 |
SVG output can be viewed by many web browsers directly (Firefox, Opera, Safari) or can be |
| 410 |
viewed within Internet Explorer, with the help of a plug-in, such as the Renesis Player, |
| 411 |
or a JavaScript library, such as SVGWeb. |
| 412 |
SVG is also used by many graphics programs as input format (Inkscape or Adobe Illustrator). |
| 413 |
SVG is not only a static format, but also allows for interactivity. This is used by <productname>Magics</productname> |
| 414 |
to optionally implement features such as the toggling of layers. |
| 415 |
</para> |
| 416 |
|
| 417 |
<para> |
| 418 |
By default the generated maps are scalable. This means that the image is rendered according |
| 419 |
to the viewers size. If the user changes the size of the browser window also the image is |
| 420 |
rescaled to fit in. In many viewers, such as Firefox, the key combination '<keysym>Crtl +</keysym>', |
| 421 |
'<keysym>Crtl -</keysym>' and '<keysym>Crtl 0</keysym>' allows to zoom in/out of a SVG graphics. |
| 422 |
</para> |
| 423 |
|
| 424 |
<para> |
| 425 |
Since SVG is based on XML it is, to a degree, human readable and can also be parsed by search engines. |
| 426 |
As with all XML derived formats, SVG allows the processing through various XML technologies, such |
| 427 |
as XSLT or the manipulation through JavaScript (AJAX). |
| 428 |
</para> |
| 429 |
|
| 430 |
<para> |
| 431 |
On the web server side there is a <productname>Batik</productname>, a Java-based toolkit for |
| 432 |
applications or applets that want to use images in the SVG format for various purposes, such |
| 433 |
as display, generation or manipulation. |
| 434 |
</para> |
| 435 |
<!-- |
| 436 |
<section id="Interactivity_in_SVG"> <title>Interactivity in SVG</title> |
| 437 |
<para> |
| 438 |
All SVG files produced by <productname>Magics</productname> have |
| 439 |
basic interactivity by default. Typing '<keysym>c</keysym>' or |
| 440 |
'<keysym>C</keysym>' (browser-dependent) toggles coastlines on and off. |
| 441 |
Typing '<keysym>d</keysym>' or '<keysym>D</keysym>' toggles the hi/low |
| 442 |
text in the drawing area. Clicking on the ID line opens the external |
| 443 |
<productname>Magics</productname> web page is opened. These features are |
| 444 |
simply demonstrations of what is possible; more sophisticated features |
| 445 |
will be implemented in the next version of <productname>Magics</productname>. |
| 446 |
</para> |
| 447 |
</section> |
| 448 |
--> |
| 449 |
<section id="Serving_SVG"><title>SVG served on the web</title> |
| 450 |
<para> |
| 451 |
On most web servers SVG can be used like any other graphics file format. |
| 452 |
However, sometimes SVG and especially its compressed form of SVGZ are not configured correctly on |
| 453 |
web servers. To serve SVG and SVGZ files correctly you should have following lines added to your |
| 454 |
<filename>.htaccess</filename> file (on Apache servers): |
| 455 |
</para> |
| 456 |
<programlisting> |
| 457 |
AddType image/svg+xml svg svgz |
| 458 |
AddEncoding gzip svgz |
| 459 |
</programlisting> |
| 460 |
</section> |
| 461 |
|
| 462 |
<para>For more information on SVG, please have the look at following resources:</para> |
| 463 |
|
| 464 |
<itemizedlist> |
| 465 |
<listitem><ulink url="http://www.w3.org/Graphics/SVG/">W3C - SVG standard</ulink></listitem> |
| 466 |
<listitem><ulink url="http://xmlgraphics.apache.org/batik/">Apache - Batik</ulink></listitem> |
| 467 |
<listitem><ulink url="http://code.google.com/p/svgweb/">SVGweb - Javascript module to view SVG in Internet Explorer</ulink></listitem> |
| 468 |
<!-- <listitem><ulink url="http://www.examotion.com">Renesis Player for Internet Explorer</ulink></listitem> --> |
| 469 |
<listitem><ulink url="http://www.inkscape.org/">Inkscape - SVG editor</ulink></listitem> |
| 470 |
<listitem><ulink url="http://code.google.com/p/svg-edit/">Web based SVG editor</ulink></listitem> |
| 471 |
</itemizedlist> |
| 472 |
|
| 473 |
<xi:include href="../paramtables/SVG_tables.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 474 |
|
| 475 |
<section id = 'SVGDriver_magml_all_tables'> |
| 476 |
<title>MagML Templates for SVG Output</title> |
| 477 |
<xi:include href="../paramtables/SVGDriver_svg_magml_tables.xml" |
| 478 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 479 |
<!-- |
| 480 |
<xi:include href="../paramtables/SVGDriver_svg_magml_flat_tables.xml" |
| 481 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 482 |
--> |
| 483 |
</section> |
| 484 |
|
| 485 |
</section> |
| 486 |
|
| 487 |
|
| 488 |
<section id="Cairo_Driver"> |
| 489 |
<title>The Cairo driver (PDF, EPS, PNG)</title> |
| 490 |
|
| 491 |
<para>This driver uses the <productname>Cairo</productname> graphics library to |
| 492 |
generate various output formats. The library is quite new and might not be installed |
| 493 |
on older or non-mainstream systems. However the situation is improving with <productname>Firefox</productname> |
| 494 |
and <productname>Inkscape</productname> requiring Cairo being installed. Cairo works |
| 495 |
internally with vectors and produces high quality output. |
| 496 |
</para> |
| 497 |
|
| 498 |
<section id="Cairo_pdf"> |
| 499 |
<title>Cairo's vector output - PDF, CAIRO_PS, CAIRO_EPS, CAIRO_SVG</title> |
| 500 |
<para>Cairo produces high quality vector outputs. However there are some disadvantages: CAIRO_PS and CAIRO_EPS |
| 501 |
support only <parameter>RGB</parameter> (not <parameter>CYMK</parameter>) and <parameter>CAIRO_SVG</parameter> are non-scalable and do not support interactivity. |
| 502 |
Therefore it is still recommended to use <parameter>PS</parameter> and <parameter>EPS</parameter> (from PostScript driver) and <parameter>SVG</parameter> (from SVG driver).</para> |
| 503 |
</section> |
| 504 |
|
| 505 |
<section id="Cairo_png"> |
| 506 |
<title>Cairo's raster output - PNG</title> |
| 507 |
<para>The Cairo driver offers <parameter>PNG</parameter> as a raster output. This output is intended for use on web pages. |
| 508 |
PNG output has two extra feature compared to the other outputs: possible |
| 509 |
transparent background and the return of meta information about the plot inside the PNG. |
| 510 |
Both features are intended for when PNGs are used for web pages. The transparent overlay |
| 511 |
allows overlays of multiple images. The meta information generated by Magics++ allows |
| 512 |
JavaScript developer navigate the PNG and implement interactions on top of the PNGs content.</para> |
| 513 |
</section> |
| 514 |
|
| 515 |
<section id="Cairo_screen"> |
| 516 |
<title>Cairo's screen dump - X</title> |
| 517 |
<para>The Cairo driver can also be used do visualise a plot directly on the screen |
| 518 |
setting the format to <parameter>X</parameter>.</para> |
| 519 |
</section> |
| 520 |
|
| 521 |
<section id="Cairo_context"> |
| 522 |
<title>Setting your own Cairo context [Advanced]</title> |
| 523 |
|
| 524 |
<para>In some cases it might be useful to hand <productname>Magics</productname> |
| 525 |
an own Cairo graphics context. This might be useful if the Magics Program wants to access directly |
| 526 |
Cairo and add its own drawing operations to be displayed in a separate widget.</para> |
| 527 |
|
| 528 |
<table border="1" id="cairo_context"> |
| 529 |
<title>Handing cairo an own context</title> |
| 530 |
<tgroup cols="1"> |
| 531 |
<colspec colwidth="450" /> |
| 532 |
<tbody> |
| 533 |
<row> |
| 534 |
<entry><programlisting> |
| 535 |
... |
| 536 |
cr = cairo_create(surface); |
| 537 |
... |
| 538 |
mag_open(); |
| 539 |
mag_setc("output_format","cairo"); |
| 540 |
mag_setp("output_cairo_drawing_context", cr); |
| 541 |
... |
| 542 |
</programlisting></entry> |
| 543 |
</row> |
| 544 |
</tbody> |
| 545 |
</tgroup> |
| 546 |
</table> |
| 547 |
</section> |
| 548 |
|
| 549 |
<para>For more information on Cairo, see the documentation at:</para> |
| 550 |
|
| 551 |
<itemizedlist> |
| 552 |
<listitem> |
| 553 |
<ulink url="http://www.cairographics.org">Cairo home page</ulink> |
| 554 |
</listitem> |
| 555 |
</itemizedlist> |
| 556 |
|
| 557 |
<xi:include href="../paramtables/Cairo_tables.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 558 |
|
| 559 |
<!-- |
| 560 |
|
| 561 |
<section id = 'CairoDriver_magml_all_tables'> |
| 562 |
<title>MagML Templates for usage of the Cairo driver</title> |
| 563 |
<xi:include href="../paramtables/CairoDriver_png_magml_tables.xml" |
| 564 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 565 |
|
| 566 |
<xi:include href="../paramtables/CairoDriver_png_magml_flat_tables.xml" |
| 567 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 568 |
|
| 569 |
<xi:include href="../paramtables/CairoDriver_pdf_magml_tables.xml" |
| 570 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 571 |
|
| 572 |
<xi:include href="../paramtables/CairoDriver_pdf_magml_flat_tables.xml" |
| 573 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 574 |
</section> |
| 575 |
--> |
| 576 |
|
| 577 |
</section> |
| 578 |
|
| 579 |
|
| 580 |
<section id="KML"> |
| 581 |
<title>The KML driver (KMZ/KML) [new]</title> |
| 582 |
|
| 583 |
<para>KML is an XML-based file format used to display describe vector data in a geospatial browser, |
| 584 |
such as <productname>Google Earth</productname>, <productname>Google Maps</productname>, and |
| 585 |
<productname>Microsoft Virtual Earth</productname>. KML is very |
| 586 |
different from the others formats supported in <productname>Magics</productname>. Even though it is |
| 587 |
a vector format it has dimensions for expressing height and time (for animations). |
| 588 |
The height is expressed in kilometres, not pressure levels, and is set through a parameter for all data. |
| 589 |
Different layers of information can be stored and controlled by the Google Earth user interface. |
| 590 |
</para> |
| 591 |
|
| 592 |
<para>KML uses often external (raster) files to optimise the file size. In case of <productname>Magics</productname>, it |
| 593 |
uses PNG files to express cell shading and satellite data. The <productname>Magics</productname> logo is also stored in |
| 594 |
a external file. Therefore <productname>Magics</productname> generates zip archives of all generated files (KML, PNGs and logo) |
| 595 |
in the so-called KMZ files. The resulting KMZ files can be read by all KML readers and the GNU zip tools (you might want to change |
| 596 |
the files extension to .zip first). |
| 597 |
</para> |
| 598 |
|
| 599 |
<para> |
| 600 |
Please be aware that KML does not support all forms of display offered by <productname>Magics</productname>. |
| 601 |
For example graph plotting is not supported in KML. Colours might also need |
| 602 |
adjusting, since <productname>Google Earth</productname>'s background is generally darker compared |
| 603 |
to the white (paper) background of other <productname>Magics</productname> output formats. |
| 604 |
</para> |
| 605 |
|
| 606 |
<para> |
| 607 |
<productname>Magics</productname> offers parameters to give meta information, such as author and |
| 608 |
descriptions and an initial focus point. |
| 609 |
</para> |
| 610 |
|
| 611 |
<para> |
| 612 |
Please be further aware that KML currently does only generate valid output for cylindrical and |
| 613 |
Mercator projection. This is because KML's co-ordinate system is based on Longitude/Latitude. For |
| 614 |
projections different to the mentioned above a different co-ordinate system is used inside |
| 615 |
<productname>Magics</productname>. |
| 616 |
</para> |
| 617 |
|
| 618 |
<para>For more information on Google Earth, see the documentation at:</para> |
| 619 |
|
| 620 |
<itemizedlist> |
| 621 |
<listitem><ulink url="http://earth.google.com">Google Earth</ulink></listitem> |
| 622 |
</itemizedlist> |
| 623 |
|
| 624 |
<xi:include href="../paramtables/KML_tables.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 625 |
|
| 626 |
<section id = 'KMLDriver_magml_all_tables'> |
| 627 |
<title>MagML Templates for KML Output</title> |
| 628 |
<xi:include href="../paramtables/KMLDriver_kml_magml_tables.xml" |
| 629 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 630 |
<!-- |
| 631 |
<xi:include href="../paramtables/KMLDriver_kml_magml_flat_tables.xml" |
| 632 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 633 |
--> |
| 634 |
</section> |
| 635 |
|
| 636 |
</section> |
| 637 |
|
| 638 |
|
| 639 |
<section id="GD_Driver"> |
| 640 |
<title>The GD driver (PNG,GIF,JPEG)</title> |
| 641 |
|
| 642 |
<para>The GD driver provides output in various raster formats. The used GD library is more |
| 643 |
lightweight but also lower quality than the Cairo library. |
| 644 |
</para> |
| 645 |
|
| 646 |
<section id="Generating_an_animated_GIF"> |
| 647 |
<title>Generating an Animated GIF</title> |
| 648 |
|
| 649 |
<para>In order to obtain an animated GIF image as output, you should use the format |
| 650 |
<code>GIF_ANIMATION</code>. In this case, you may set the delay between pages of the |
| 651 |
animation by setting the parameter <parameter>OUTPUT_GIF_DELAY</parameter> to a value |
| 652 |
representing a time-scale in 100ths of a second. For instance, to create an animated |
| 653 |
GIF called animated_plot.gif with a delay of half a second between pages, use the |
| 654 |
following code:</para> |
| 655 |
|
| 656 |
<programlisting> |
| 657 |
CALL <function>PSETC</function> ('<parameter>OUTPUT_FORMAT</parameter>', 'GIF_ANIMATION') |
| 658 |
CALL <function>PSETI</function> ('<parameter>OUTPUT_GIF_DELAY</parameter>', 50) |
| 659 |
CALL <function>PSETC</function> ('<parameter>OUTPUT_NAME</parameter>', 'animated_plot') |
| 660 |
</programlisting> |
| 661 |
|
| 662 |
<tip> |
| 663 |
<para>Note that animated GIF images are not properly supported by |
| 664 |
<application>xv</application> and <application>display</application>. Therefore, |
| 665 |
in order to view your GIF animation correctly, a web browser such as |
| 666 |
<application>Firefox</application>, <application>Internet Explorer</application> or |
| 667 |
<application>Konqueror</application> should be used. Also note that |
| 668 |
<application>xv</application> does not support PNG on many platforms |
| 669 |
very well. You can use <application>display</application> |
| 670 |
to view PNG files properly.</para> |
| 671 |
</tip> |
| 672 |
</section> |
| 673 |
<!-- |
| 674 |
<section id="Raster_Output_In_MagML"> |
| 675 |
<title>Raster Output In MagML</title> |
| 676 |
<para>The following example illustrates the MagML elements required to generate raster output |
| 677 |
from a MagML program; their attributes are set here to their default values.</para> |
| 678 |
|
| 679 |
<programlisting> |
| 680 |
<<classname>drivers</classname>> |
| 681 |
<<classname>gif</classname> <parameter>xml</parameter> = 'OFF' /> |
| 682 |
|
| 683 |
<<classname>gif_animation</classname> <parameter>gif_delay</parameter> = '100' |
| 684 |
<parameter>xml</parameter> = 'OFF' /> |
| 685 |
|
| 686 |
<<classname>png</classname> <parameter>png_transparent</parameter> = 'OFF' |
| 687 |
<parameter>xml</parameter> = 'OFF' /> |
| 688 |
<<classname>drivers</classname>/> |
| 689 |
</programlisting> |
| 690 |
</section> |
| 691 |
--> |
| 692 |
<xi:include href="../paramtables/GD_tables.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 693 |
|
| 694 |
|
| 695 |
<!-- |
| 696 |
<section id = 'GDDriver_magml_all_tables'> |
| 697 |
<title>MagML Templates for GD related output</title> |
| 698 |
<xi:include href="../paramtables/GDDriver_kml_magml_tables.xml" |
| 699 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 700 |
|
| 701 |
<xi:include href="../paramtables/GDDriver_kml_magml_flat_tables.xml" |
| 702 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 703 |
</section> |
| 704 |
--> |
| 705 |
</section> |
| 706 |
|
| 707 |
</chapter> |