| 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 |
<chapter id="Overview" label="1"> |
| 15 |
<title>Overview</title> |
| 16 |
|
| 17 |
<xi:include href="../phrases/chapterinfo_mod.xml" |
| 18 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 19 |
|
| 20 |
<section id="Overview_Introduction"> |
| 21 |
<title>Introduction to Magics</title> |
| 22 |
|
| 23 |
<para>The Meteorological Applications Graphics Integrated Colour System |
| 24 |
(<productname>MAGICS</productname>) is a software system that permits the |
| 25 |
plotting of contours, wind fields, observations, satellite images, |
| 26 |
symbols, <remark>streamlines, isotachs, </remark>text, axis and graphs <remark>and pie charts</remark>. |
| 27 |
|
| 28 |
<productname>Magics</productname> is developed by the Meteorological Visualisation Section at <orgname>ECMWF</orgname> |
| 29 |
and is used to generate many of its plots - on the |
| 30 |
web, in the MetOps room, for data monitoring and verification. <productname>Magics</productname> |
| 31 |
is the graphics engine used in <orgname>ECMWF</orgname>'s meteorological workstation Metview and |
| 32 |
<orgname>Meteo-France</orgname>'s Synergie meteorological workstation. It is used within many |
| 33 |
<orgname>ECMWF</orgname>'s Member States and other organisations around the world.</para> |
| 34 |
|
| 35 |
<para><remark><productname>Magics</productname> contouring is based on |
| 36 |
CONICON, developed by the University of Bath in the United Kingdom. Linear |
| 37 |
contouring is also available.</remark></para> |
| 38 |
|
| 39 |
<para><remark><productname>Magics</productname> observation plotting is |
| 40 |
based on a package developed by <remark>the Meteorological services of |
| 41 |
Denmark and</remark> Sweden. <productname>Magics</productname> streamline plotting is based on an |
| 42 |
algorithm supplied by Florida State University, Florida, |
| 43 |
USA.</remark></para> |
| 44 |
|
| 45 |
<para><productname>Magics</productname> is meteorological oriented and forecasts and analysis fields may be read in various formats, for |
| 46 |
instance GRIB and NetCDF. Observations can be read from BUFR files or retrieved from an ODB |
| 47 |
database. For more details, see <olink targetdoc="Magics_data" targetptr="Data_Input" />.</para> |
| 48 |
|
| 49 |
<para>The following diagram shows the top-level architecture of <productname>Magics++</productname>:</para> |
| 50 |
<para/> |
| 51 |
<para/> |
| 52 |
|
| 53 |
<mediaobject id="magics_architecture_diagram"> |
| 54 |
<imageobject role="fo"> |
| 55 |
<imagedata fileref="../diagrams/Magics_overview.png" format="PNG" width="14cm" align="center" /> |
| 56 |
</imageobject> |
| 57 |
|
| 58 |
<imageobject role="html"> |
| 59 |
<imagedata fileref="images/diagrams/Magics_overview.png" format="PNG" width="500" align="center" /> |
| 60 |
</imageobject> |
| 61 |
</mediaobject> |
| 62 |
|
| 63 |
</section> |
| 64 |
|
| 65 |
<section id="History"> |
| 66 |
<title>MAGICS History</title> |
| 67 |
|
| 68 |
<para>The first pre-release of <productname>MAGICS</productname>, |
| 69 |
version 0.3, was released as a FORTRAN library in July 1985 on a trial |
| 70 |
basis. This release contained facilities for plot layout as well as |
| 71 |
contouring, coastlines and text headings. At the same time the first |
| 72 |
versions of the |
| 73 |
<productname><productname>MAGICS</productname></productname> manuals |
| 74 |
were released. With minor enhancements, this version became operational |
| 75 |
in December 1985. The first full release of |
| 76 |
<productname><productname>MAGICS</productname></productname>, version |
| 77 |
1.0, became available in December 1987 and incorporated many new |
| 78 |
features. Subsequent releases have introduced extra features as they |
| 79 |
became available, such as linear contouring, axis plotting, streamlines |
| 80 |
and isotachs, graph and pie charts, symbol plotting and satellite image |
| 81 |
plotting.</para> |
| 82 |
<para>Development of <productname>MAGICS 6</productname> was frozen in 2008; |
| 83 |
development of <productname>Magics++</productname> started in 2004.</para> |
| 84 |
</section> |
| 85 |
|
| 86 |
<section id="Current_Release"> |
| 87 |
<title>Magics++</title> |
| 88 |
|
| 89 |
<para><productname>Magics++</productname> represents a |
| 90 |
complete re-write of the <productname>Magics</productname> source code. |
| 91 |
Whereas previous versions were |
| 92 |
written mainly in FORTRAN with some C++ code for the output drivers, |
| 93 |
<productname>Magics++</productname> is written entirely in C++. This development makes |
| 94 |
<productname>Magics</productname> more flexible, allowing new features |
| 95 |
to be added more easily. Although <productname>Magics++</productname> is |
| 96 |
intended to be as backwardly compatible as possible with the previous |
| 97 |
Fortran interface, there are new ways of doing some things - these will be |
| 98 |
highlighted in the text of this manual with the following notation:</para> |
| 99 |
|
| 100 |
<important> <title>Magics++</title>This is new to, or has been changed in Magics++.</important> |
| 101 |
|
| 102 |
<para>Perhaps the biggest change is that |
| 103 |
<productname>Magics</productname> is no longer just a FORTRAN library. |
| 104 |
Plot descriptions can now also be written in an XML-based format called |
| 105 |
<firstterm>MagML</firstterm> and programs can now also be written in |
| 106 |
C and Python.</para> |
| 107 |
|
| 108 |
<para><productname>Magics</productname> can now read data from a wider |
| 109 |
variety of sources.<!-- Notably, data from an ODB database can be retrieved |
| 110 |
and plotted from within a <productname>Magics</productname> program (see |
| 111 |
<olink targetdoc="Magics_data" targetptr="ODB_Input" />).--> |
| 112 |
NetCDF data is supported (see |
| 113 |
<olink targetdoc="Magics_data" targetptr="NetCDF_Data_Input" />). |
| 114 |
By using the new GRIB_API library, <productname>Magics</productname> |
| 115 |
is able to read GRIB 2 files as well as GRIB 1 files. |
| 116 |
Note that <productname>Magics</productname> currently does not support |
| 117 |
interpolation of grids - all GRIB data must be in regular or reduced Gaussian or Lat/Long grid. |
| 118 |
<remark> |
| 119 |
WHEN WILL WE HAVE INTERPOLATION? |
| 120 |
</remark> |
| 121 |
</para> |
| 122 |
|
| 123 |
<para>The output drivers have also been expanded. PostScript remains, |
| 124 |
and in addition there are drivers that can produce plots in PDF, EPS, |
| 125 |
PNG, GIF and SVG formats amongst others. <productname>Magics</productname> |
| 126 |
now has the ability to produce multiple outputs from a single program by |
| 127 |
using multiple drivers 'simultaneously', delivering significant speed |
| 128 |
benefits over using an external tool to convert PostScript output or |
| 129 |
running a program twice to produce different outputs.</para> |
| 130 |
|
| 131 |
<para>The CONICON contouring package formerly used by |
| 132 |
<productname>Magics</productname> has been replaced with a method using |
| 133 |
the Akima interpolation algorithms. By default, |
| 134 |
<productname>Magics</productname> will try to choose a level of |
| 135 |
interpolation that gives good quality results without sacrificing |
| 136 |
performance; the user can also set the interpolation level manually if |
| 137 |
needed. Linear contouring is still available.</para> |
| 138 |
|
| 139 |
<para>The user now has more flexibility in determining the resolution of |
| 140 |
coastlines used in plots. <productname>Magics++</productname> comes with |
| 141 |
higher resolution coastline files than previous versions but uses |
| 142 |
lower-resolution files where appropriate in order to save time and |
| 143 |
reduce the size of the output file; this behaviour is |
| 144 |
user-configurable. These coastline files now include basic |
| 145 |
support for rivers and lakes.</para> |
| 146 |
|
| 147 |
<para><remark>Legend? Text & annotation?</remark></para> |
| 148 |
|
| 149 |
<itemizedlist> |
| 150 |
<listitem> |
| 151 |
<para><ulink url="http://www.ecmwf.int/publications/manuals/magics/">Magics webpage</ulink></para> |
| 152 |
</listitem> |
| 153 |
<listitem> |
| 154 |
<para><ulink url="http://www.ecmwf.int/publications/manuals/magics/magplus/docs/Magics++_Newsletter_110_Article.pdf">Magics++ Overview</ulink></para> |
| 155 |
</listitem> |
| 156 |
<listitem> |
| 157 |
<para><ulink url="http://www.ecmwf.int/publications/manuals/magics/magplus/docs/Magics++_Newsletter_122_Article.pdf">Magics++ 2.8 - New developments</ulink></para> |
| 158 |
</listitem> |
| 159 |
</itemizedlist> |
| 160 |
|
| 161 |
</section> |
| 162 |
|
| 163 |
<section id="MAGICS Features"> |
| 164 |
<title>Magics Features</title> |
| 165 |
|
| 166 |
<para>Magics contains many powerful features:</para> |
| 167 |
|
| 168 |
<itemizedlist> |
| 169 |
<listitem> |
| 170 |
<para>Comprehensive list of simple English language parameters</para> |
| 171 |
</listitem> |
| 172 |
|
| 173 |
<listitem> |
| 174 |
<para>Extensive use of colour</para> |
| 175 |
</listitem> |
| 176 |
|
| 177 |
<listitem> |
| 178 |
<para>Flexible programming interface (API) for multiple languages (Fortran, C, Python, XML)</para> |
| 179 |
</listitem> |
| 180 |
|
| 181 |
<listitem> |
| 182 |
<para>Selection of geographical area and direct projection of |
| 183 |
data</para> |
| 184 |
</listitem> |
| 185 |
|
| 186 |
<listitem> |
| 187 |
<para>Matrix, GRIB, BUFR, ODB and NetCDF data input(see <olink targetdoc="Magics_data" targetptr="Data_Input" />)</para> |
| 188 |
</listitem> |
| 189 |
|
| 190 |
<listitem> |
| 191 |
<para>Coastline rendering with automatic quality-selection for |
| 192 |
high quality with minimal output file size.</para> |
| 193 |
</listitem> |
| 194 |
|
| 195 |
<listitem> |
| 196 |
<para>High quality contouring based on Akima interpolation and lower |
| 197 |
quality linear contouring (see <olink targetdoc="Magics_contour" targetptr="Contouring"/>) </para> |
| 198 |
</listitem> |
| 199 |
|
| 200 |
<listitem> |
| 201 |
<para>Shading between contour lines</para> |
| 202 |
</listitem> |
| 203 |
|
| 204 |
<listitem> |
| 205 |
<para>Wind fields directly projected, as arrows or WMO flags (see <olink targetdoc="Magics_wind" targetptr="Wind_Plotting" />)</para> |
| 206 |
</listitem> |
| 207 |
|
| 208 |
<remark> |
| 209 |
<listitem> |
| 210 |
<para>Streamline and Isotach plotting</para> |
| 211 |
</listitem> |
| 212 |
</remark> |
| 213 |
|
| 214 |
<listitem> |
| 215 |
<para>Observation plotting <!-- (see <olink targetdoc="Magics_obs" targetptr="ObservationPlotting" />) --></para> |
| 216 |
</listitem> |
| 217 |
|
| 218 |
<listitem> |
| 219 |
<para>Graph and Axis plotting, with advanced features such as Boxplots</para> |
| 220 |
</listitem> |
| 221 |
|
| 222 |
<listitem> |
| 223 |
<para>Symbol plotting</para> |
| 224 |
</listitem> |
| 225 |
|
| 226 |
<listitem> |
| 227 |
<para>Satellite image plotting</para> |
| 228 |
</listitem> |
| 229 |
|
| 230 |
<listitem> |
| 231 |
<para>High quality text plotting (see <olink targetdoc="Magics_text" targetptr="Text_Plotting" />)</para> |
| 232 |
</listitem> |
| 233 |
|
| 234 |
<listitem> |
| 235 |
<para>Advanced legend plotting</para> |
| 236 |
</listitem> |
| 237 |
|
| 238 |
</itemizedlist> |
| 239 |
|
| 240 |
</section> |
| 241 |
|
| 242 |
|
| 243 |
<section id="Overview_Page_Layout"> |
| 244 |
<title>Page Layout</title> |
| 245 |
|
| 246 |
<para>To make the positioning of user's plots simple, |
| 247 |
<productname>Magics</productname> has introduced the concepts of |
| 248 |
subpage, page and super-page.</para> |
| 249 |
|
| 250 |
<para>A super-page corresponds to the plotting area to be used on a |
| 251 |
plotting device. With the plot layout facilities, pages can be |
| 252 |
positioned automatically or by the user inside the super-page. |
| 253 |
Similarly, one or more subpages can be plotted inside a page.</para> |
| 254 |
|
| 255 |
<para>Page Layout is fully described in |
| 256 |
<olink targetdoc="Magics_layout_mapping_coastlines" targetptr="Layout_Mapping_and_Coastlines" />.</para> |
| 257 |
</section> |
| 258 |
|
| 259 |
|
| 260 |
<section id="Overview_Programming_Concepts"> |
| 261 |
<title>Programming Interfaces</title> |
| 262 |
|
| 263 |
<para>A typical FORTRAN <productname>Magics</productname> program |
| 264 |
consists of a series of parameter-setting, action and pseudo action |
| 265 |
routines. The parameters required by an action routine should be set, if |
| 266 |
required, before that action routine is called.</para> |
| 267 |
|
| 268 |
<para>An alternative, XML-based plot description language is also available. |
| 269 |
It is called <firstterm>MagML</firstterm> and permits simple yet powerful plot |
| 270 |
descriptions to be used to generate plots without the need for a compile/link |
| 271 |
cycle.</para> |
| 272 |
|
| 273 |
<para>The programming interfaces offered by <productname>Magics</productname> are |
| 274 |
fully described in <olink targetdoc="Magics_using" targetptr="Using_MAGICS"/>.</para> |
| 275 |
</section> |
| 276 |
|
| 277 |
</chapter> |