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.
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.