# Magics Output Drivers

## Introduction

Magics is capable of producing plots in a number of different file formats, detailed in the following sections. By default, PostScript output will be produced.

As other parts of Magics the code is structured modular to allow easier maintenance and to add easily new output formats. Each module is called a driver and supports at least one output format.

Please be aware that not all output drivers might be installed on your system. Some output drivers dependent on third-party libraries. If these are missing at compilation time Magics++ cannot support all formats. Please consult the installation guide for more information.

The output drivers have undergone major changes since MAGICS 6. Please be aware that some default values have changed and are not backwards compatible. For example, in previous versions PostScript output was by default shrunken to 95% of its actual size to be resilient against changes in printer setups. This is not as much as an issue anymore and therefore the default scaling has been set to 100% again.

A special output driver is generating Qt which is only intended for screen display. This driver is used by Metview and is not documented further here.

### Controlling the output formats

Parameters can be set to influence how the output formats are generated. Some parameters are effective on all format, such as file name, and some are specific for each format.

Magics++

The interface has been revised to increase consistency and simplify user code. The old MAGICS 6 'DEVICE' parameters have been kept for backwards compatibility, but the use of the new parameters is strongly recommended.

## Selecting output formats and their naming

This section will describe how file formats can be chosen and output names are control by Magics.

By default, the output format for a Magics plot is PostScript (`PS`). You may select a different output format by setting parameter OUTPUT_FORMAT to any of the following:

Output Formats

Value | Graphics File Format | Pages | Driver
--- | --- | --- | ---
PS | vector | produces a single file* | PostScript
EPS | vector | produces multiple files | PostScript
PDF | vector | produces a single file | Cairo
PNG | raster | produces multiple files | Cairo
GIF | raster | produces multiple files | GD
GIF_ANIMATION | raster | produces a single file | GD
JPEG | raster | produces multiple files** | GD
SVG | vector | produces multiple files | SVG
KML | vector | produces single KMZ file | KML

*It is also possible to produce multiple single-page PostScript files, see below.

**The JPEG format uses a lossy compression algorithm, resulting in lost quality.

To set in a Fortran program the output format to PNG type:

        CALL PSETC ('OUTPUT_FORMAT',  'PNG')

The PostScript based vector formats (PS, EPS, PDF) are the most appropriate for high-quality hard-copy printing; the raster formats are more suitable for web pages. The SVG driver produces SVG files suitable for interactive visualisation or the dynamic generation of raster plots at different scales. EPS is a vector format most suited for inclusion in Office and Latex documents.

### Selecting Multiple Output Formats

Magics can generate plots in multiple output formats simultaneous. For instance, a single Magics program can create the same plot in both PostScript and PNG formats in a single run. This approach has a performance advantage over running the program separately for each output format as much of the processing is performed only once. The parameter to set is OUTPUT_FORMATS (note the 'S' on the end). The following code shows how to set two output devices:

Selecting Multiple Output Formats

FORTRAN |
        CHARACTER*10 FORMATS
        DIMENSION    FORMATS(2)
        DATA         FORMATS /'PS', 'PNG'/

        CALL POPEN
        CALL PSET1C ('OUTPUT_FORMATS', FORMATS, 2)
        CALL PSETC  ('OUTPUT_NAME',    'multiformat')
C |
        const char *formats [NumFormats] = {"PS", "PNG"};

        mag_open  ();
        mag_set1c ("OUTPUT_FORMATS", formats, 2);
        mag_setc  ("OUTPUT_NAME",    "multiformat");
MagML |
       <drivers>
          <ps scale = '95' />
          <png />
       <drivers/>

For a single-page plot, the above code will produce two files: `multiformat.ps` and `multiformat.1.png`. The following section explains the file-naming rules in more detail.

### Filenames

For a single-file plot, as produced by `PS`, `PDF` and `GIF_ANIMATION`, the default output filename will be `magics.<ext>` where <ext> is replaced by the extension appropriate to the output format. For the default format (PostScript) this would produce the file `magics.ps`, for animated PNG it would be `magics.png` and so on. The following code shows how to change the filename:

        CALL PSETC ('OUTPUT_NAME', 'plot')

In this case if the output format is PDF, then the output filename will be `plot.pdf` and so on.

When producing a multiple-file plot, a number is also added to each page, although this can be deactivated for the first page. So for instance, if the following parameters are set for a three-page plot:

Filename Examples

Default |
      CALL PSETC ('OUTPUT_FORMAT', 'PNG')
      CALL PSETC ('OUTPUT_NAME',   'plot')
the resultant files will be:
            plot.1.png
            plot.2.png
            plot.3.png
Note that even if the plot has only one page and therefore produces just one file, the name of that file still obeys the rules in the table above.
First page numbering OFF |
      CALL PSETC ('OUTPUT_FORMAT',                 'PNG')
      CALL PSETC ('OUTPUT_NAME',                   'plot')
      CALL PSETC ('OUTPUT_NAME_FIRST_PAGE_NUMBER', 'OFF')
the resultant files will be:
            plot.png
            plot.2.png
            plot.3.png

The formatting of the numbers can be modified through the parameter OUTPUT_FILE_MINIMAL_WIDTH. For instance, setting this to `2` would produce a filename such as `plot.02.png` instead of `plot.2.png`.

The character between the root and the number can be changed by setting the parameter OUTPUT_FILE_SEPARATOR. For instance, setting this to `_` (underscore) would produce a filename such as `plot_2.png` instead of `plot.2.png`.

#### Filenames - Legacy and Fine Control

The above file-naming control should be enough for most purposes and is recommended for the most consistent naming of output files.

However, an extra degree of control is available by not using OUTPUT_NAME, but instead:

- OUTPUT_FULLNAME : does not add an extension to the supplied filename, instead it needs to be supplied with the file name

- OUTPUT_LEGACY_NAME : behaves similar to MAGICS 6 filenaming

### Common parameters for all drivers

## The PostScript driver

PostScript was developed by Adobe and is still the main format for printers under UNIX. Since traditionally meteorological maps were aimed for print-outs, PostScript is historically the default output of Magics. No third-party library is required to generate PostScript files and the driver is always available to users.

### Page Splitting

By default, a multi-page plot will result in a single output file containing those multiple pages. It is possible to alter this behaviour by setting the OUTPUT_PS_SPLIT parameter:

        CALL PSETC ('OUTPUT_PS_SPLIT', 'ON')

When this is set, each page will be plotted to a new PostScript file, following the filenaming rules in the table above.

Magics++

This behaviour differs from previous versions of Magics where the environment variable `PS_SPLIT` was used instead of a Magics parameter.

### Page Scaling

Even though printers support standardised page sizes, such as A4 and A3, they often are not able to print on the full page. Depending on the printer an border area surrounding the page cannot be printed on. This needs to be kept in mind if designing maps to be printed. To help with this Magics provides an option to shrink/rescale a PostScript page to fit to the printer.

Magics++

In previous versions PostScript output was by default shrunken to 95% of its actual size to be resilient against changes in printer setups. This is not an issue anymore and therefore the default scaling has been set to 100% again. Please use 'OUTPUT_PS_SCALE' and set it to '0.95' if this kind of scaling is still required.

### EPS

The EPS file format does not support multiple pages, so if a multi-page plot is created in EPS format, multiple files are generated using the rules above, as if 'OUTPUT_PS_SPLIT' is on. EPS is best if maps need to be used within Word and Latex documents.

### MagML Templates for PostScript Output

## The SVG driver

This output driver produces vector graphics in the SVG format as defined by the W3C. The SVG output can be viewed by many web browsers directly (Firefox, Opera, Safari) or can be viewed within Internet Explorer, with the help of a plug-in, such as the Renesis Player, or a JavaScript library, such as SVGWeb. SVG is also used by many graphics programs as input format (Inkscape or Adobe Illustrator). SVG is not only a static format, but also allows for interactivity. This is used by Magics to optionally implement features such as the toggling of layers.

By default the generated maps are scalable. This means that the image is rendered according to the viewers size. If the user changes the size of the browser window also the image is rescaled to fit in. In many viewers, such as Firefox, the key combination 'Crtl +', 'Crtl -' and 'Crtl 0' allows to zoom in/out of a SVG graphics.

Since SVG is based on XML it is, to a degree, human readable and can also be parsed by search engines. As with all XML derived formats, SVG allows the processing through various XML technologies, such as XSLT or the manipulation through JavaScript (AJAX).

On the web server side there is a Batik, a Java-based toolkit for applications or applets that want to use images in the SVG format for various purposes, such as display, generation or manipulation.

### SVG served on the web

On most web servers SVG can be used like any other graphics file format. However, sometimes SVG and especially its compressed form of SVGZ are not configured correctly on web servers. To serve SVG and SVGZ files correctly you should have following lines added to your `.htaccess` file (on Apache servers):

    AddType image/svg+xml svg svgz
    AddEncoding gzip svgz

For more information on SVG, please have the look at following resources:

- W3C - SVG standard
- Apache - Batik
- SVGweb - Javascript module to view SVG in Internet Explorer
- Inkscape - SVG editor
- Web based SVG editor

### MagML Templates for SVG Output

## The Cairo driver (PDF, EPS, PNG)

This driver uses the Cairo graphics library to generate various output formats. The library is quite new and might not be installed on older or non-mainstream systems. However the situation is improving with Firefox and Inkscape requiring Cairo being installed. Cairo works internally with vectors and produces high quality output.

### Cairo's vector output - PDF, CAIRO_PS, CAIRO_EPS, CAIRO_SVG

Cairo produces high quality vector outputs. However there are some disadvantages: CAIRO_PS and CAIRO_EPS support only RGB (not CYMK) and CAIRO_SVG are non-scalable and do not support interactivity. Therefore it is still recommended to use PS and EPS (from PostScript driver) and SVG (from SVG driver).

### Cairo's raster output - PNG

The Cairo driver offers PNG as a raster output. This output is intended for use on web pages. PNG output has two extra feature compared to the other outputs: possible transparent background and the return of meta information about the plot inside the PNG. Both features are intended for when PNGs are used for web pages. The transparent overlay allows overlays of multiple images. The meta information generated by Magics++ allows JavaScript developer navigate the PNG and implement interactions on top of the PNGs content.

### Cairo's screen dump - X

The Cairo driver can also be used do visualise a plot directly on the screen setting the format to X.

### Setting your own Cairo context [Advanced]

In some cases it might be useful to hand Magics an own Cairo graphics context. This might be useful if the Magics Program wants to access directly Cairo and add its own drawing operations to be displayed in a separate widget.

Handing cairo an own context

       ...
       cr = cairo_create(surface);
       ...
       mag_open();
       mag_setc("output_format","cairo");
       mag_setp("output_cairo_drawing_context", cr);
       ...

For more information on Cairo, see the documentation at:

- Cairo home page

## The KML driver (KMZ/KML) [new]

KML is an XML-based file format used to display describe vector data in a geospatial browser, such as Google Earth, Google Maps, and Microsoft Virtual Earth. KML is very different from the others formats supported in Magics. Even though it is a vector format it has dimensions for expressing height and time (for animations). The height is expressed in kilometres, not pressure levels, and is set through a parameter for all data. Different layers of information can be stored and controlled by the Google Earth user interface.

KML uses often external (raster) files to optimise the file size. In case of Magics, it uses PNG files to express cell shading and satellite data. The Magics logo is also stored in a external file. Therefore Magics generates zip archives of all generated files (KML, PNGs and logo) 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 the files extension to .zip first).

Please be aware that KML does not support all forms of display offered by Magics. For example graph plotting is not supported in KML. Colours might also need adjusting, since Google Earth's background is generally darker compared to the white (paper) background of other Magics output formats.

Magics offers parameters to give meta information, such as author and descriptions and an initial focus point.

Please be further aware that KML currently does only generate valid output for cylindrical and Mercator projection. This is because KML's co-ordinate system is based on Longitude/Latitude. For projections different to the mentioned above a different co-ordinate system is used inside Magics.

For more information on Google Earth, see the documentation at:

- Google Earth

### MagML Templates for KML Output

## The GD driver (PNG,GIF,JPEG)

The GD driver provides output in various raster formats. The used GD library is more lightweight but also lower quality than the Cairo library.

### Generating an Animated GIF

In order to obtain an animated GIF image as output, you should use the format `GIF_ANIMATION`. In this case, you may set the delay between pages of the animation by setting the parameter OUTPUT_GIF_DELAY to a value representing a time-scale in 100ths of a second. For instance, to create an animated GIF called animated_plot.gif with a delay of half a second between pages, use the following code:

        CALL PSETC ('OUTPUT_FORMAT',    'GIF_ANIMATION')
        CALL PSETI ('OUTPUT_GIF_DELAY',  50)
        CALL PSETC ('OUTPUT_NAME',      'animated_plot')

Note that animated GIF images are not properly supported by xv and display. Therefore, in order to view your GIF animation correctly, a web browser such as Firefox, Internet Explorer or Konqueror should be used. Also note that xv does not support PNG on many platforms very well. You can use display to view PNG files properly.