Debian Codegraph @

docs/manual/chapters/drivers.xml

raw
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3 (C) Copyright 1996-2016 ECMWF.
4
5 This software is licensed under the terms of the Apache Licence Version 2.0
6 which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
7 In applying this licence, ECMWF does not waive the privileges and immunities
8 granted to it by virtue of its status as an intergovernmental organisation nor
9 does it submit to any jurisdiction.
10 -->
11
12 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
13 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
14
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 &lt;<classname>drivers</classname>&gt;
218 &lt;<classname>ps</classname> <parameter>scale</parameter> = '95' /&gt;
219 &lt;<classname>png</classname> /&gt;
220 &lt;<classname>drivers</classname>/&gt;
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.&lt;ext&gt;</filename>
239 where &lt;ext&gt; 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 &lt;<classname>drivers</classname>&gt;
681 &lt;<classname>gif</classname> <parameter>xml</parameter> = 'OFF' /&gt;
682
683 &lt;<classname>gif_animation</classname> <parameter>gif_delay</parameter> = '100'
684 <parameter>xml</parameter> = 'OFF' /&gt;
685
686 &lt;<classname>png</classname> <parameter>png_transparent</parameter> = 'OFF'
687 <parameter>xml</parameter> = 'OFF' /&gt;
688 &lt;<classname>drivers</classname>/&gt;
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>