Debian Codegraph @

docs/manual/chapters/intro.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 <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 &amp; 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>