Controlling graphical outputs

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.

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.

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:

*It is also possible to produce multiple single-page PostScript files, see “Page Splitting” 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:

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

    CALL POPEN
    CALL PSET1C ('OUTPUT_FORMATS', FORMATS, 2) CALL PSETC ('OUTPUT_NAME', 'multiformat')

const char *formats [NumFormats] = {"PS", "PNG"};

    mag_open  ();
    mag_set1c ("OUTPUT_FORMATS", formats, 2); mag_setc ("OUTPUT_NAME", "multiformat");

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

CALL PSETC ('OUTPUT_FORMAT', 'PNG') CALL PSETC ('OUTPUT_NAME', 'plot')

        plot.1.png
        plot.2.png
        plot.3.png

CALL PSETC ('OUTPUT_FORMAT', 'PNG') CALL PSETC ('OUTPUT_NAME', 'plot') CALL PSETC ('OUTPUT_NAME_FIRST_PAGE_NUMBER', 'OFF')

        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.