| 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="Layout_Mapping_and_Coastlines" label="4"> |
| 15 |
<title>Layout, Mapping and Coastlines</title> |
| 16 |
|
| 17 |
<xi:include href="../phrases/chapterinfo_mod.xml" |
| 18 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 19 |
|
| 20 |
<section id="Plot_Layout_Basic_Entities"> |
| 21 |
<title>Plot Layout - Basic Entities</title> |
| 22 |
|
| 23 |
<para>The <productname>Magics</productname> plot layout facility provides |
| 24 |
a simple means by which users can plot several maps at arbitrary positions |
| 25 |
on the plotting page. It can also be used in a fully automatic mode, |
| 26 |
whereby <productname>Magics</productname> will position the user's maps in |
| 27 |
a predetermined order.</para> |
| 28 |
|
| 29 |
<para>To describe <productname>Magics</productname> plot layout it is |
| 30 |
necessary to define the naming convention for the entities that comprise |
| 31 |
any plotted output from the system. Please refer to <remark>Diagram |
| 32 |
III-1</remark> throughout this description.</para> |
| 33 |
|
| 34 |
<para><firstterm>SUPER-PAGE</firstterm> , <firstterm>PAGE</firstterm> and |
| 35 |
<firstterm>SUBPAGE</firstterm> are the entities used to define the |
| 36 |
plotting areas in <productname>Magics</productname>:</para> |
| 37 |
|
| 38 |
<itemizedlist> |
| 39 |
<listitem> |
| 40 |
<para><firstterm>Super-pages</firstterm> are defined by their X and Y |
| 41 |
axis lengths. A super-page can be thought of as the paper sheet on |
| 42 |
which the work will be produced. The position of the bottom left hand |
| 43 |
corner of the super-page is (0.0, 0.0).</para> |
| 44 |
</listitem> |
| 45 |
|
| 46 |
<listitem> |
| 47 |
<para><firstterm>Pages</firstterm> subdivide a Super-page - any number |
| 48 |
of pages may be defined by the user, provided they fit within the |
| 49 |
limits of the current super-page. The position of a page on a |
| 50 |
super-page, which can be controlled by |
| 51 |
<productname>Magics</productname> or be defined by the user, is |
| 52 |
relative to the bottom left hand corner of the super-page. A |
| 53 |
user-controlled page is defined by its bottom left hand corner |
| 54 |
position and its X and Y axis lengths.</para> |
| 55 |
</listitem> |
| 56 |
|
| 57 |
<listitem> |
| 58 |
<para><firstterm>Subpages</firstterm> are the smallest entity - they |
| 59 |
can contain one chart, e.g. contours superimposed on a background map |
| 60 |
of coast lines and grid lines. One or more subpages can be plotted on |
| 61 |
a page, provided that they fit within the limits assigned to that |
| 62 |
page. Subpages can be of varying sizes. A subpage is defined by the |
| 63 |
position of its bottom left hand corner and its lengths in the |
| 64 |
horizontal (X) and vertical (Y) directions. The position of the |
| 65 |
subpage is relative to the bottom left hand corner of the page.</para> |
| 66 |
</listitem> |
| 67 |
</itemizedlist> |
| 68 |
</section> |
| 69 |
|
| 70 |
<section id="Plot_Layout_Default_Values"> |
| 71 |
<title>Plot Layout Default Values</title> |
| 72 |
|
| 73 |
<para>Default values exist for all the plot layout parameters. The default |
| 74 |
value for the size of the super-page is A4 (horizontal), i.e. the length |
| 75 |
in the X direction is 29.7cm and the length in the Y direction is 21cm. |
| 76 |
Super-pages will be placed either sequentially along the plotter paper, or |
| 77 |
on separate sheets, depending on the output device. The default value for |
| 78 |
the page size is A4 (horizontal), i.e. X length is 29.7cm and the Y length |
| 79 |
is 21cm. These defaults mean that the super-page and the page are the same |
| 80 |
size. The default values for the subpage size and position depends on |
| 81 |
whether the user sets some of the parameters:</para> |
| 82 |
|
| 83 |
<!-- |
| 84 |
<highlights> |
| 85 |
<para>Diagram 1</para> |
| 86 |
</highlights> |
| 87 |
--> |
| 88 |
|
| 89 |
<para>If the user defines one or more of the subpage size or position |
| 90 |
parameters, then <productname>Magics</productname> assumes that all the |
| 91 |
subpage parameters have been defined and will use the current value of |
| 92 |
these subpage parameters to plot the subpage. In this case, if any of the |
| 93 |
parameters are not set, the defaults are calculated as follows:</para> |
| 94 |
|
| 95 |
<para>The default values for the X and Y subpage lengths are 85% of the X |
| 96 |
and Y page lengths. This corresponds to 25.24cm and 17.85cm respectively |
| 97 |
for the default page size. The default subpage X position is 7.5% of the X |
| 98 |
page length and the default subpage Y position is 5% of the Y page length. |
| 99 |
This corresponds to 2.08cm and 1.05cm for the default page size.</para> |
| 100 |
|
| 101 |
<para>If the user does not define any of the subpage parameters, |
| 102 |
<productname>Magics</productname> will set the subpage parameters to |
| 103 |
default values that depend on the values of the current page parameters. |
| 104 |
Using fixed percentages of the page parameters to set the subpage values |
| 105 |
ensures that the defaulted subpage fits neatly into the page and makes |
| 106 |
maximum use of the plotting space. The percentages used are 85% for the X |
| 107 |
and Y lengths, 7.5% for the subpage X position and 5% for subpage Y |
| 108 |
position.</para> |
| 109 |
|
| 110 |
<para>Users should be aware that the lengths of the subpage may be |
| 111 |
affected by the type of map that is to be plotted in the subpage. |
| 112 |
<productname>Magics</productname> will always try to fit subpages as |
| 113 |
neatly as possible in the user's page but the requested projection, map, |
| 114 |
scale etc. could mean that the subpage lengths are adjusted to fit the |
| 115 |
requested map correctly. Therefore, users should be aware that certain |
| 116 |
mapping parameters could affect the lengths of the subpage.</para> |
| 117 |
</section> |
| 118 |
|
| 119 |
<section id="Plot_Layout_for_Pages"> |
| 120 |
<title>Plot Layout for Pages</title> |
| 121 |
|
| 122 |
<para>There are two methods of handling plot layout of pages in |
| 123 |
<productname>Magics</productname> : '<code>POSITIONAL</code>' and |
| 124 |
'<code>AUTOMATIC</code>', the default being |
| 125 |
'<code>AUTOMATIC</code>'.</para> |
| 126 |
|
| 127 |
<section id="Automatic_Mode"> |
| 128 |
<title>Automatic Mode</title> |
| 129 |
|
| 130 |
<para>If a user wishes to make maximum use of the plotting paper, he |
| 131 |
may request <productname>Magics</productname> to do the plot layout |
| 132 |
for him by putting the system in automatic mode, which is the default |
| 133 |
positioning mode. Pages will then be positioned in an organised way, |
| 134 |
depending on the instructions given by the user.</para> |
| 135 |
|
| 136 |
<para>When in automatic mode, a user can specify three instructions |
| 137 |
which define the type of layout required.</para> |
| 138 |
|
| 139 |
<itemizedlist> |
| 140 |
<listitem> |
| 141 |
<para>The user can instruct <productname>Magics</productname> to |
| 142 |
start positioning from the bottom or top of the plotting paper by |
| 143 |
setting the <parameter>PLOT_START</parameter> parameter to |
| 144 |
'<code>BOTTOM</code>' or '<code>TOP</code>'.</para> |
| 145 |
</listitem> |
| 146 |
|
| 147 |
<listitem> |
| 148 |
<para>The default value for <parameter>PLOT_START</parameter> is |
| 149 |
'<code>BOTTOM</code>'.</para> |
| 150 |
</listitem> |
| 151 |
|
| 152 |
<listitem> |
| 153 |
<para>The direction in which plotting is required is defined by |
| 154 |
setting the <parameter>PLOT_DIRECTION</parameter> parameter to |
| 155 |
either '<code>HORIZONTAL</code>' or |
| 156 |
'<code>VERTICAL</code>'.</para> |
| 157 |
</listitem> |
| 158 |
|
| 159 |
<listitem> |
| 160 |
<para>The default value for <parameter>PLOT_DIRECTION</parameter> |
| 161 |
is '<code>VERTICAL</code>'.</para> |
| 162 |
</listitem> |
| 163 |
|
| 164 |
<listitem> |
| 165 |
<para>The gaps between the pages in the horizontal and vertical |
| 166 |
directions are set by <parameter>PAGE_X_GAP</parameter> and |
| 167 |
<parameter>PAGE_Y_GAP</parameter>.</para> |
| 168 |
</listitem> |
| 169 |
|
| 170 |
<listitem> |
| 171 |
<para>The default values for <parameter>PAGE_X_GAP</parameter> and |
| 172 |
<parameter>PAGE_Y_GAP</parameter> are both |
| 173 |
<code>0.0</code>cm.</para> |
| 174 |
</listitem> |
| 175 |
</itemizedlist> |
| 176 |
|
| 177 |
<para /> |
| 178 |
<!-- |
| 179 |
<highlights> |
| 180 |
<para>Diagrams 2, 3, 4</para> |
| 181 |
</highlights> |
| 182 |
--> |
| 183 |
|
| 184 |
<para>When <parameter>PLOT_DIRECTION</parameter> is set to |
| 185 |
'<code>VERTICAL</code>' (default), <productname>Magics</productname> |
| 186 |
will place the user's pages one over the other (or one under the |
| 187 |
other, if starting at the top of the paper) until the limits of the |
| 188 |
super-page are reached |
| 189 |
(<parameter>SUPER_PAGE_Y_LENGTH</parameter>).</para> |
| 190 |
|
| 191 |
<para>The next page is then placed alongside the first page in a |
| 192 |
horizontal direction and subsequent pages are placed on top of (or |
| 193 |
underneath) this. The mechanism is repeated until the limits of the |
| 194 |
super-page are reached (<parameter>SUPER_PAGE_X_LENGTH</parameter>). A |
| 195 |
new super-page is then allocated and the above procedure is repeated |
| 196 |
until all the user's pages are plotted.</para> |
| 197 |
|
| 198 |
<para>The gaps between the pages in both directions will be as defined |
| 199 |
by the user (<parameter>PAGE_X_GAP</parameter>, |
| 200 |
<parameter>PAGE_Y_GAP</parameter>) or the default values (both |
| 201 |
<code>0.0</code>cm). <remark>See Diagram III-5(a)</remark> for an |
| 202 |
example of page plotting in the vertical direction.</para> |
| 203 |
|
| 204 |
<para>If the user specifies <parameter>PLOT_DIRECTION</parameter> as |
| 205 |
'<code>HORIZONTAL</code>', <productname>Magics</productname> will |
| 206 |
place the pages horizontally along the super-page with a gap between |
| 207 |
the pages, as defined by the user (<parameter>PAGE_X_GAP</parameter>), |
| 208 |
which defaults to <code>0.0</code>cm. <remark>See Diagram |
| 209 |
III-5(b)</remark> for an example.</para> |
| 210 |
|
| 211 |
<para>When the super-page limit |
| 212 |
(<parameter>SUPER_PAGE_X_LENGTH</parameter>) is reached, the next page |
| 213 |
will be placed directly above the first page to be plotted. Subsequent |
| 214 |
pages will be placed horizontally along the paper directly above the |
| 215 |
first row of pages, with a gap between the rows, as defined by the |
| 216 |
user (<parameter>PAGE_Y_GAP</parameter> which defaults to |
| 217 |
<code>0.0</code>cm). This mechanism continues until the super-page |
| 218 |
limits are reached. A new super-page is then allocated by |
| 219 |
<productname>Magics</productname> and the above procedure is repeated |
| 220 |
until all the user's pages are plotted.</para> |
| 221 |
|
| 222 |
<para>The user may start at the top of the paper if required, and the |
| 223 |
same procedure as above will apply except that the rows of pages are |
| 224 |
in descending order. If the user requires only one row of pages, the |
| 225 |
length of the super-page in the Y direction may be set by the user to |
| 226 |
a value which will limit the number of pages in the Y direction to |
| 227 |
one.</para> |
| 228 |
|
| 229 |
<para>A similar mechanism can be used to limit the number of pages in |
| 230 |
the X direction.</para> |
| 231 |
</section> |
| 232 |
|
| 233 |
<section id="Positional_Mode"> |
| 234 |
<title>Positional Mode</title> |
| 235 |
|
| 236 |
<para>In positional mode, the responsibility for organising the |
| 237 |
position and size of plotted output rests with the user. He may, |
| 238 |
however, use <productname>Magics</productname> defaults, if |
| 239 |
suitable.</para> |
| 240 |
|
| 241 |
<para>To define the position of a page, the user must define the |
| 242 |
bottom left hand corner of the page |
| 243 |
(<parameter>PAGE_X_POSITION</parameter>, |
| 244 |
<parameter>PAGE_Y_POSITION</parameter>). He may also, if the default |
| 245 |
A4 is not suitable, define the lengths of the page in the horizontal |
| 246 |
and vertical directions (<parameter>PAGE_X_LENGTH</parameter>, |
| 247 |
<parameter>PAGE_Y_LENGTH</parameter>).</para> |
| 248 |
|
| 249 |
<para>The values given for the page position are relative to the |
| 250 |
bottom left hand corner of the super-page. A user can define one or |
| 251 |
more pages within a super-page, but any page or part of a page |
| 252 |
exceeding the super-page limits will not be plotted.</para> |
| 253 |
|
| 254 |
<para>The user may define a super-page by defining the length in the X |
| 255 |
and Y directions (<parameter>SUPER_PAGE_X_LENGTH</parameter>, |
| 256 |
<parameter>SUPER_PAGE_Y_LENGTH</parameter>). The position of the |
| 257 |
bottom left hand corner of the super-page is always (0.0, 0.0).</para> |
| 258 |
<!-- |
| 259 |
<para>See <remark>Diagram III-5(c)</remark> for an example of page |
| 260 |
layout in positional mode.</para> |
| 261 |
|
| 262 |
<highlights> |
| 263 |
<para>Diagram 5</para> |
| 264 |
</highlights> |
| 265 |
--> |
| 266 |
</section> |
| 267 |
</section> |
| 268 |
|
| 269 |
<section id="Plot_Layout_for_Subpages"> |
| 270 |
<title>Plot Layout for Subpages</title> |
| 271 |
|
| 272 |
<para>Subpages may be defined within a page by defining the bottom left |
| 273 |
hand corner of the subpage (<parameter>SUBPAGE_X_POSITION</parameter>, |
| 274 |
<parameter>SUBPAGE_Y_POSITION</parameter>) and the lengths in the X and Y |
| 275 |
directions (<parameter>SUBPAGE_X_LENGTH</parameter>, |
| 276 |
<parameter>SUBPAGE_Y_LENGTH</parameter>). The values for the subpage are |
| 277 |
relative to the bottom left hand corner of the current page.</para> |
| 278 |
|
| 279 |
<para>A user may define one or more subpages within a page. When a user |
| 280 |
defines a subpage where all or some of the subpage is outside the limits |
| 281 |
of the current page, <productname>Magics</productname> will issue an error |
| 282 |
message but will plot any part of the user's subpage that comes within the |
| 283 |
limits of the page. The rest of the plot will be lost.</para> |
| 284 |
</section> |
| 285 |
|
| 286 |
<section id="Pseudo_Action_Routine_PNEW"> |
| 287 |
<title>Pseudo Action Routine PNEW</title> |
| 288 |
|
| 289 |
<para>Pseudo action routine <function>PNEW</function> informs |
| 290 |
<productname>Magics</productname> that the user wishes to change from one |
| 291 |
subpage, page or super-page to another.</para> |
| 292 |
|
| 293 |
<para>No immediate action is performed when <function>PNEW</function> is |
| 294 |
called, hence the name pseudo action. The change to a new subpage, page or |
| 295 |
super-page is actually performed when the next action routine is |
| 296 |
called.</para> |
| 297 |
|
| 298 |
<para>The format of the call to <function>PNEW</function> is as follows:</para> |
| 299 |
|
| 300 |
<programlisting> CALL <function>PNEW</function>( 'key' )</programlisting> |
| 301 |
|
| 302 |
<para>where 'key' can be '<code>SUBPAGE</code>', '<code>PAGE</code>' or |
| 303 |
'<code>SUPER_PAGE</code>'.</para> |
| 304 |
|
| 305 |
<para>For example, <code>CALL <function>PNEW</function>('PAGE')</code> will cause |
| 306 |
<productname>Magics</productname> to terminate plotting on the currently |
| 307 |
defined page and move to the next page.</para> |
| 308 |
|
| 309 |
<para>In automatic mode, the positioning of the new page is done by |
| 310 |
<productname>Magics</productname>. In positional mode, the user must |
| 311 |
specify the position of the next page. The actual movement to a new page |
| 312 |
does not occur until the first action routine following the call to |
| 313 |
<function>PNEW</function>. Moving from one subpage or one super-page to |
| 314 |
another is achieved in a similar manner.</para> |
| 315 |
|
| 316 |
<para>The pseudo action routine, <function>PNEW</function>, must be used |
| 317 |
to change from one subpage or one page to another. It is not necessary for |
| 318 |
users to define super-pages as <productname>Magics</productname> will do |
| 319 |
so automatically. However, to achieve a special type of layout, users may |
| 320 |
define their own super-page. In this case, if they wish to change from one |
| 321 |
super-page to another before the super-page is full, they must use pseudo |
| 322 |
action routine <function>PNEW</function>.</para> |
| 323 |
</section> |
| 324 |
|
| 325 |
<section id="Plot_Frames"> |
| 326 |
<title>Plot Frames</title> |
| 327 |
|
| 328 |
<para>By default, <productname>Magics</productname> will draw frames |
| 329 |
around pages and subpages, but not around super-pages unless requested by |
| 330 |
the user. Plot framing may be controlled by the user in all three |
| 331 |
cases.</para> |
| 332 |
|
| 333 |
<para>For the page and subpage, <productname>Magics</productname> allows |
| 334 |
the user to control the colour, thickness and line style of the frame, as |
| 335 |
well as providing facilities for turning it on and off. For the |
| 336 |
super-page, the only control allowed is the facility for turning the frame |
| 337 |
on and off. The parameters are summarised in <remark>Diagram III-2, |
| 338 |
Diagram III-3 and Diagram III-6</remark>.</para> |
| 339 |
</section> |
| 340 |
|
| 341 |
<section id="Page_Identification_Line"> |
| 342 |
<title>Page Identification Line</title> |
| 343 |
|
| 344 |
<para><productname>Magics</productname> will, by default, plot an |
| 345 |
identification line and the ECMWF logo on the bottom of every page |
| 346 |
plotted. The user may inhibit the plotting of these if he wishes.</para> |
| 347 |
|
| 348 |
<para>The identification line consists of such items as the |
| 349 |
<productname>Magics</productname> version number, the user's job name, the |
| 350 |
current date and time, error numbers and an optional text string which the |
| 351 |
user may define. The user also has control over the height and quality of |
| 352 |
the characters in the identification line. However, |
| 353 |
<productname>Magics</productname> defaults ensure that the height of the |
| 354 |
characters are always reasonable.</para> |
| 355 |
|
| 356 |
<para>The identification line is positioned on the bottom of each page, |
| 357 |
starting in the bottom left hand corner. The ECMWF logo is plotted in the |
| 358 |
bottom right hand corner of the page. Plotting of the identification line |
| 359 |
and logo is controlled by the <productname>Magics</productname> parameter |
| 360 |
<parameter>PAGE_ID_LINE</parameter>, which may be set '<code>ON</code>' or |
| 361 |
'<code>OFF</code>', the default being '<code>ON</code>'.</para> |
| 362 |
|
| 363 |
<para>The identification line can be split into 5 different parts; system |
| 364 |
information, date/time. user text, error plotting and ECMWF logo. Each of |
| 365 |
these parts can be turned on or off by using the following |
| 366 |
parameters:</para> |
| 367 |
|
| 368 |
<programlisting><parameter> |
| 369 |
PAGE_ID_LINE_SYSTEM_PLOT |
| 370 |
PAGE_ID_LINE_DATE_PLOT |
| 371 |
PAGE_ID_LINE_USER_TEXT_PLOT |
| 372 |
PAGE_ID_LINE_ERRORS_PLOT |
| 373 |
PAGE_ID_LINE_LOGO_PLOT |
| 374 |
</parameter></programlisting> |
| 375 |
|
| 376 |
<para>The valid values for the above parameters are '<code>ON</code>' and |
| 377 |
'<code>OFF</code>', with '<code>ON</code>' being the default for all five. |
| 378 |
Any combination of the parts can be selected for plotting.</para> |
| 379 |
|
| 380 |
<para>Other parameters controlling <parameter>PAGE_ID_LINE</parameter> |
| 381 |
plotting are</para> |
| 382 |
|
| 383 |
<programlisting><parameter> |
| 384 |
PAGE_ID_LINE_HEIGHT |
| 385 |
PAGE_ID_LINE_QUALITY |
| 386 |
PAGE_ID_LINE_USER_TEXT |
| 387 |
</parameter></programlisting> |
| 388 |
|
| 389 |
<important> <title>Magics++ 2.10</title> |
| 390 |
From version 2.10 onwards the option to set a USER_LOGO has been deprecated. |
| 391 |
Users should use the PIMPORT action routine instead. |
| 392 |
</important> |
| 393 |
|
| 394 |
<!-- |
| 395 |
<section id="User_Logos"> |
| 396 |
<title>User Logos</title> |
| 397 |
<important> <title>Magics++</title> |
| 398 |
<productname>Magics++</productname> provides the ability to |
| 399 |
easily add a different logo to its plots.</important> |
| 400 |
|
| 401 |
<para>The following code illustrates how to set up your own logo:</para> |
| 402 |
<programlisting> |
| 403 |
CALL <function>PSETC</function>('<parameter>PAGE_ID_LINE_LOGO_PLOT</parameter>', 'USER') |
| 404 |
CALL <function>PSETC</function>('<parameter>USER_LOGO_FILENAME</parameter>', 'DATA/LOGO_MF_VERTICAL.GIF') |
| 405 |
CALL <function>PSETC</function>('<parameter>USER_LOGO_FORMAT</parameter>', 'GIF') |
| 406 |
CALL <function>PSETR</function>('<parameter>USER_LOGO_X_POSITION</parameter>', 0.5) |
| 407 |
CALL <function>PSETR</function>('<parameter>USER_LOGO_WIDTH</parameter>', 1.0) |
| 408 |
CALL <function>PSETR</function>('<parameter>USER_LOGO_Y_POSITION</parameter>', 12.0) |
| 409 |
CALL <function>PSETR</function>('<parameter>USER_LOGO_HEIGHT</parameter>', 2.0) |
| 410 |
</programlisting> |
| 411 |
</section> |
| 412 |
--> |
| 413 |
|
| 414 |
</section> |
| 415 |
|
| 416 |
<section id="Useful_Hints_on_Plot_Layout"> |
| 417 |
<title>Useful Hints on Plot Layout</title> |
| 418 |
|
| 419 |
<para>For plotting one field, users should use default values for |
| 420 |
(<parameter>SUBPAGE_X_POSITION</parameter>, |
| 421 |
<parameter>SUBPAGE_Y_POSITION</parameter>) and |
| 422 |
(<parameter>PAGE_X_POSITION</parameter>, |
| 423 |
<parameter>PAGE_Y_POSITION</parameter>). It is sufficient to define the |
| 424 |
lengths of the plot, if the defaults are not suitable, i.e. |
| 425 |
(<parameter>PAGE_X_LENGTH</parameter>, |
| 426 |
<parameter>PAGE_Y_LENGTH</parameter>) and/or |
| 427 |
(<parameter>SUBPAGE_X_LENGTH</parameter>, |
| 428 |
<parameter>SUBPAGE_Y_LENGTH</parameter>).</para> |
| 429 |
|
| 430 |
<para>In positional mode users can superimpose plots, one on top of the |
| 431 |
other, by not changing the subpage, page or super-page definitions between |
| 432 |
action routines.</para> |
| 433 |
|
| 434 |
<para>Users may only change from one subpage or page to another by calling |
| 435 |
the pseudo action routine <function>PNEW</function>. A change to a new |
| 436 |
super-page can also be achieved by calling <function>PNEW</function> but |
| 437 |
will happen automatically if plot layout is in automatic mode and there is |
| 438 |
insufficient room for the next page in the current super-page.</para> |
| 439 |
|
| 440 |
<para>The size of the super-page can be used to achieve the desired layout |
| 441 |
of plots, i.e. by limiting the number of plots in the X and Y |
| 442 |
directions.</para> |
| 443 |
|
| 444 |
<para>The first action routine to be called sets up the user's subpage. |
| 445 |
All parameters affecting the subpage definition should be set, if |
| 446 |
required, before the first action routine is called. These parameters |
| 447 |
include those mapping parameters with the prefix |
| 448 |
<parameter>SUBPAGE_MAP</parameter>.</para> |
| 449 |
|
| 450 |
<para>The lengths of the subpage may be affected by the type of map that |
| 451 |
is to be plotted in the subpage. <productname>Magics</productname> will |
| 452 |
always try to fit subpages as neatly as possible in the user's page but |
| 453 |
the requested projection, map, scale etc. could mean that the subpage |
| 454 |
lengths are adjusted to fit the requested map correctly. Therefore, users |
| 455 |
should be aware that certain mapping parameters could affect the lengths |
| 456 |
of the subpage.</para> |
| 457 |
|
| 458 |
<!-- |
| 459 |
<highlights> |
| 460 |
<para>Diagram 6</para> |
| 461 |
</highlights> |
| 462 |
--> |
| 463 |
</section> |
| 464 |
|
| 465 |
<section id="Mapping"> |
| 466 |
<title>Map projections</title> |
| 467 |
|
| 468 |
<para>Four types of projections are catered for in |
| 469 |
<productname>Magics</productname>, cylindrical (default), polar |
| 470 |
stereographic, Mercator and satellite. Input data, especially if it is GRIB data, does not have to be in the |
| 471 |
same projection as the generated map. Also, it is not necessary for users |
| 472 |
to extract data for the required geographical area before passing the |
| 473 |
input data. <productname>Magics</productname> can perform both those |
| 474 |
functions. <productname>Magics</productname> can deal with input GRIB |
| 475 |
data in cylindrical, polar stereographic and satellite projections but |
| 476 |
not with Mercator. If the input field is passed in the form of an array, |
| 477 |
<productname>Magics</productname> can only deal with cylindrical and |
| 478 |
satellite projections.</para> |
| 479 |
|
| 480 |
<para><productname>Magics</productname> parameters exist to enable users |
| 481 |
to specify the area, scale, etc, required. Mapping parameters have been |
| 482 |
given the prefix <parameter>SUBPAGE_MAP</parameter> to remind users that |
| 483 |
these parameters must be set before any action routines are |
| 484 |
called.</para> |
| 485 |
|
| 486 |
<para>To define the map, users should specify the projection, scale etc, |
| 487 |
if the default values are not applicable. The parameter |
| 488 |
<parameter>SUBPAGE_MAP_PROJECTION</parameter> may be set to |
| 489 |
'<code>CYLINDRICAL</code>', '<code>POLAR_STEREOGRAPHIC</code>', |
| 490 |
'<code>MERCATOR</code>', '<code>TAYLOR</code>' or |
| 491 |
'<code>CARTASIAN</code>', the default being |
| 492 |
'<code>CYLINDRICAL</code>'. |
| 493 |
<!-- '<code>CYLINDRICAL</code>', '<code>POLAR_STEREOGRAPHIC</code>', |
| 494 |
'<code>MERCATOR</code>', '<code>SATELLITE</code>', |
| 495 |
'<code>AITOFF</code>', '<code>LAMBERT</code>', |
| 496 |
'<code>OCEAN_SECTION</code>' or '<code>NONE</code>', the default being |
| 497 |
'<code>CYLINDRICAL</code>'. --> |
| 498 |
If <parameter>SUBPAGE_MAP_PROJECTION</parameter> is set to |
| 499 |
'<code>NONE</code>', <productname>Magics</productname> will not apply |
| 500 |
any projection to the user's input field.</para> |
| 501 |
|
| 502 |
<section id="Cylindrical_Projection"> |
| 503 |
<title>Cylindrical and Mercator projection</title> |
| 504 |
|
| 505 |
<para>An area on a cylindrical or Mercator Projection may be defined by specifying the latitude and |
| 506 |
longitude coordinates of the lower left hand and top right hand |
| 507 |
corners of the required area. The data for contouring for this area |
| 508 |
may be for a smaller or larger area than the one specified but should |
| 509 |
contain data which covers at least part of this area. |
| 510 |
<productname>Magics</productname> can perform the extraction of data |
| 511 |
to fit the area.</para> |
| 512 |
|
| 513 |
<para>Users should always take care to ensure that the dimensions of |
| 514 |
the subpage (<parameter>SUBPAGE_X_LENGTH</parameter>, |
| 515 |
<parameter>SUBPAGE_Y_LENGTH</parameter>) are reasonable and |
| 516 |
approximately match the area required. |
| 517 |
<productname>Magics</productname> will always fit the required area to |
| 518 |
the user's subpage in the best possible way.</para> |
| 519 |
|
| 520 |
<important id="Area_Greater_Than_360_Degrees"> <title>Magics++</title> |
| 521 |
New to <productname>Magics++</productname> is the ability to plot |
| 522 |
an area with more than 360 |
| 523 |
degrees of longitude. By specifying an area which crosses the 180 |
| 524 |
degree 'boundary', locations of interest can be more easily studied.</important> |
| 525 |
|
| 526 |
|
| 527 |
</section> |
| 528 |
|
| 529 |
<section id="Polar_Stereographic_Projection"> |
| 530 |
<title>Polar Stereographic Projection</title> |
| 531 |
|
| 532 |
<para>If <parameter>SUBPAGE_MAP_PROJECTION</parameter> is set to |
| 533 |
'<code>POLAR_STEREOGRAPHIC</code>', users may select a method for the |
| 534 |
defining the area by setting <parameter>SUBPAGE_MAP_AREA_DEFINITION</parameter> to |
| 535 |
'<code>CORNERS</code>' (default) or '<code>CENTRE</code>'.</para> |
| 536 |
|
| 537 |
<!-- |
| 538 |
<highlights> |
| 539 |
<para>Diagram 7</para> |
| 540 |
</highlights> |
| 541 |
--> |
| 542 |
|
| 543 |
<section id="CORNERS"> |
| 544 |
<title>CORNERS</title> |
| 545 |
|
| 546 |
<para>The first, (default) method allows users to specify the |
| 547 |
latitude and longitude of the lower left hand corner and the upper |
| 548 |
right hand corner of the area required. The vertical longitude may |
| 549 |
also be specified if required.</para> |
| 550 |
|
| 551 |
<para>There is no need to specify a map scale in this case as |
| 552 |
<productname>Magics</productname> will fill the user's subpage with |
| 553 |
the area required. Users should take care, however, to ensure that |
| 554 |
the dimensions of the subpage |
| 555 |
(<parameter>SUBPAGE_X_LENGTH</parameter>, |
| 556 |
<parameter>SUBPAGE_Y_LENGTH</parameter>) are reasonable and |
| 557 |
approximately match the area required. |
| 558 |
<productname>Magics</productname> will always fit the required area |
| 559 |
to the user's subpage in the best possible way.</para> |
| 560 |
|
| 561 |
<para>Initially, <productname>Magics</productname> will use the |
| 562 |
user's <parameter>SUBPAGE_X_LENGTH</parameter> as a basis and from |
| 563 |
this calculate the correct map scale. It will then calculate the |
| 564 |
correct <parameter>SUBPAGE_Y_LENGTH</parameter> for the map. If, |
| 565 |
however, the calculated <parameter>SUBPAGE_Y_LENGTH</parameter> is |
| 566 |
greater than the <parameter>SUBPAGE_Y_LENGTH</parameter> specified |
| 567 |
by the user, <productname>Magics</productname> will calculate the |
| 568 |
map scale and <parameter>SUBPAGE_X_LENGTH</parameter> based on the |
| 569 |
defined <parameter>SUBPAGE_Y_LENGTH</parameter>.</para> |
| 570 |
|
| 571 |
<para>This method ensures that the requested area will always fit in |
| 572 |
the user's subpage. It also shows the importance of defining |
| 573 |
suitable dimensions for <parameter>SUBPAGE_X_LENGTH</parameter> and |
| 574 |
<parameter>SUBPAGE_Y_LENGTH</parameter>.</para> |
| 575 |
<!-- |
| 576 |
<para>Users can find out the map scale and subpage dimensions |
| 577 |
actually used by calling the special |
| 578 |
<productname>Magics</productname> routine |
| 579 |
<function>PPRINT</function> after the action routine that drew the |
| 580 |
map. <remark>See chapter on Contouring for details of routine |
| 581 |
PPRINT</remark>.</para> |
| 582 |
--> |
| 583 |
<para>Using this method, data for contouring will usually be in |
| 584 |
cylindrical format. <productname>MAGICS</productname> will project |
| 585 |
the required contour lines, providing that the input data covers at |
| 586 |
least part of the requested area. It is also possible for the input |
| 587 |
data to be in polar stereographic format providing that it fits the |
| 588 |
exact area to be projected. |
| 589 |
<olink targetdoc="Magics_data" targetptr="Data_Input" /> gives full |
| 590 |
details of input data formats.</para> |
| 591 |
|
| 592 |
<para>When <parameter>SUBPAGE_MAP_AREA_DEFINITION</parameter> is set |
| 593 |
to '<code>CORNERS</code>', a polar stereographic map should be |
| 594 |
defined by setting:</para> |
| 595 |
|
| 596 |
<programlisting> |
| 597 |
SUBPAGE_LOWER_LEFT_LATITUDE |
| 598 |
SUBPAGE_LOWER_LEFT_LONGITUDE |
| 599 |
SUBPAGE_UPPER_RIGHT_LATITUDE |
| 600 |
SUBPAGE_UPPER_RIGHT_LONGITUDE |
| 601 |
</programlisting> |
| 602 |
|
| 603 |
<para><parameter>SUBPAGE_MAP_VERTICAL_LONGITUDE</parameter> may also |
| 604 |
be set, if desired, but setting |
| 605 |
<parameter>SUBPAGE_MAP_SCALE</parameter> in this case will have no |
| 606 |
affect on the area.</para> |
| 607 |
</section> |
| 608 |
|
| 609 |
<section id="CENTRE"> |
| 610 |
<title>CENTRE</title> |
| 611 |
|
| 612 |
<para>The second method of defining polar stereographic maps is to |
| 613 |
specify the latitude and longitude of the centre of the area and the |
| 614 |
scale of the map.</para> |
| 615 |
|
| 616 |
<para>The default value for the scale is <code>50E6</code> (true at |
| 617 |
60 north) and this corresponds to 500 kilometres being represented |
| 618 |
on the map by 1cm. The vertical longitude may also be specified, if |
| 619 |
the default (<code>0.0</code>) is not suitable. Users should be |
| 620 |
aware that the selection of the vertical longitude is an important |
| 621 |
element and will affect the area to be projected.</para> |
| 622 |
|
| 623 |
<para>It is possible, by varying the vertical longitude, to rotate |
| 624 |
an area. The area to be projected may be increased or decreased by |
| 625 |
varying the map scale.</para> |
| 626 |
|
| 627 |
<!-- |
| 628 |
<highlights> |
| 629 |
<para>Diagram 8</para> |
| 630 |
</highlights> |
| 631 |
--> |
| 632 |
|
| 633 |
<para>The lengths of the current subpage |
| 634 |
(<parameter>SUBPAGE_X_LENGTH</parameter>, |
| 635 |
<parameter>SUBPAGE_Y_LENGTH</parameter>), together with the map |
| 636 |
scale and the vertical longitude will determine the actual area to |
| 637 |
be projected onto the user's subpage.</para> |
| 638 |
|
| 639 |
<para>Users should be careful in setting the map scale. If the map |
| 640 |
scale is too large, e.g. <code>200E6</code> for full hemisphere, the |
| 641 |
map plotted will be very small. When the map scale is too small, |
| 642 |
e.g. <code>5E6</code> for a full hemisphere, some of the map may not |
| 643 |
be plotted, as it may not be possible to fit it in the defined |
| 644 |
subpage.</para> |
| 645 |
|
| 646 |
<para>To be able to estimate the map scale as a function of page |
| 647 |
size for a full polar stereographic map, the following formula may |
| 648 |
be used.</para> |
| 649 |
|
| 650 |
<para> |
| 651 |
<code>SUBPAGE_Y_LENGTH * SUBPAGE_MAP_SCALE = 24E8</code> |
| 652 |
</para> |
| 653 |
|
| 654 |
<para>When <parameter>SUBPAGE_MAP_AREA_DEFINITION</parameter> is set |
| 655 |
to '<code>CENTRE</code>' a polar stereographic map may be defined by |
| 656 |
setting <code>SUBPAGE_MAP_CENTRE_LATITUDE</code> and |
| 657 |
<parameter>SUBPAGE_MAP_CENTRE_LONGITUDE.</parameter></para> |
| 658 |
|
| 659 |
<para><parameter>SUBPAGE_MAP_VERTICAL_LONGITUDE</parameter> and |
| 660 |
<parameter>SUBPAGE_MAP_SCALE</parameter> may also be defined if the |
| 661 |
default values are not suitable.</para> |
| 662 |
</section> |
| 663 |
</section> |
| 664 |
|
| 665 |
|
| 666 |
<!-- |
| 667 |
<section id="Mercator_Projection"> |
| 668 |
<title>Mercator Projection</title> |
| 669 |
|
| 670 |
<para>The Mercator projection may be defined by specifying the |
| 671 |
latitude and longitude of the lower left hand and top right hand |
| 672 |
corners of the required area. The data for contouring etc may be for a |
| 673 |
larger area or a smaller area that the required plot area but it |
| 674 |
should contain data for some part of the plot area. |
| 675 |
<productname>Magics</productname> can perform the extraction of data |
| 676 |
to fit the area. The default values for the Mercator projection are as |
| 677 |
follows:</para> |
| 678 |
|
| 679 |
<para>bottom left hand latitude = -85.0</para> |
| 680 |
|
| 681 |
<para>bottom left hand longitude = -180.0</para> |
| 682 |
|
| 683 |
<para>top right hand latitude = 85.0</para> |
| 684 |
|
| 685 |
<para>top right hand longitude = 180.0</para> |
| 686 |
|
| 687 |
<para>Users should always take care to ensure that the dimensions of |
| 688 |
the subpage (<parameter>SUBPAGE_X_LENGTH</parameter>, |
| 689 |
<parameter>SUBPAGE_Y_LENGTH</parameter>) are reasonable and |
| 690 |
approximately match the area required. |
| 691 |
<productname>Magics</productname> will fit the required area to the |
| 692 |
user's subpage in the best possible way.</para> |
| 693 |
|
| 694 |
<para>An example of the default Mercator projection is shown in the |
| 695 |
example of SUBROUTINE PLOT02_TEN.</para> |
| 696 |
</section> |
| 697 |
--> |
| 698 |
|
| 699 |
<section id="Satellite_Projection"> |
| 700 |
<title>Satellite Projection</title> |
| 701 |
|
| 702 |
<para>A satellite projection is fully defined to |
| 703 |
<productname>Magics</productname> by the information in the GRIB code |
| 704 |
headers. It is sufficient for the user to set the parameter |
| 705 |
<parameter>SUBPAGE_MAP_PROJECTION</parameter> to |
| 706 |
'<code>SATELLITE</code>' and to pass the GRIB code data to |
| 707 |
<productname>Magics</productname>.</para> |
| 708 |
|
| 709 |
<para><productname>Magics</productname> only caters for geostationary |
| 710 |
satellite projections at present.</para> |
| 711 |
|
| 712 |
<para>The satellite projection will by default make the satellite |
| 713 |
image fill the subpage area. The user can specify a subarea |
| 714 |
(rectangle) of the image by specifying the centre point and one corner |
| 715 |
of the subarea, for example the bottom left hand or top right hand |
| 716 |
corner (in latitude/longitude). The parameter |
| 717 |
<parameter>IMAGE_SUBAREA_SELECTION</parameter> should be set to |
| 718 |
'<code>ON</code>' if a subarea is required. The default is |
| 719 |
'<code>OFF</code>' (full satellite projection).</para> |
| 720 |
|
| 721 |
<para>The following parameter settings show how to plot a subarea in |
| 722 |
the satellite projection:</para> |
| 723 |
|
| 724 |
<programlisting> |
| 725 |
CALL <function>PSETC</function> ('<parameter>IMAGE_SUBAREA_SELECTION</parameter>','ON') |
| 726 |
CALL <function>PSETR</function> ('<parameter>SUBPAGE_MAP_CENTRE_LONGITUDE</parameter>', value) |
| 727 |
CALL <function>PSETR</function> ('<parameter>SUBPAGE_MAP_CENTRE_LATITUDE</parameter>', value) |
| 728 |
CALL <function>PSETR</function> ('<parameter>SUBPAGE_MAP_CORNER_LATITUDE</parameter>', value) |
| 729 |
CALL <function>PSETR</function> ('<parameter>SUBPAGE_MAP_CORNER_LONGITUDE</parameter>', value) |
| 730 |
</programlisting> |
| 731 |
|
| 732 |
<para>Satellite projection is described fully in <remark>Chapter XIII- |
| 733 |
Satellite Image Plotting</remark>.</para> |
| 734 |
</section> |
| 735 |
|
| 736 |
<!-- |
| 737 |
<section id="Aitoff_Projection"> |
| 738 |
<title>Aitoff Projection</title> |
| 739 |
|
| 740 |
<para>Aitoff projection is a simple poly-conic equal-area projection |
| 741 |
and is defined by specifying the vertical longitude of the map, i.e. |
| 742 |
<parameter>SUBPAGE_MAP_VERTICAL_LONGITUDE</parameter> . A full global |
| 743 |
map with the specified vertical longitude in the centre of the map is |
| 744 |
always plotted. Plotting of subareas is not allowed.</para> |
| 745 |
|
| 746 |
<para>An example of the Aitoff projection is given in the example |
| 747 |
program in <remark>SUBROUTINE PLOT02_FOURTEEN</remark>.</para> |
| 748 |
</section> |
| 749 |
|
| 750 |
<section id="Lambert_Projection"> |
| 751 |
<title>Lambert Projection</title> |
| 752 |
|
| 753 |
<para>A Lambert projection is a conformal conic projection which is |
| 754 |
defined by two standard parallels which converge at the pole. Scale is |
| 755 |
true along the two standard parallels. The projection is conformal |
| 756 |
everywhere but the poles and is neither equal-area nor equidistant. |
| 757 |
The parallels are unequally spaced concentric circular arcs centred on |
| 758 |
the pole of convergence. Spacing of the parallels increases away from |
| 759 |
the central latitudes. The meridians are equally spaced lines |
| 760 |
converging at one of the poles. The angles between the meridians are |
| 761 |
less than true angles. A Lambert projection may be specified by |
| 762 |
setting the following parameters:</para> |
| 763 |
|
| 764 |
<programlisting>SUBPAGE_MAP_STANDARD_LATITUDE_1 |
| 765 |
SUBPAGE_MAP_STANDARD_LATITUDE_2 |
| 766 |
SUBPAGE_MAP_CENTRE_LATITUDE |
| 767 |
SUBPAGE_MAP_CENTRE_LONGITUDE |
| 768 |
SUBPAGE_MAP_SCALE</programlisting> |
| 769 |
|
| 770 |
<para>An example of the Lambert projection is given in the example |
| 771 |
programs in <remark>SUBROUTINE PLOT02_TWELVE and SUBROUTINE |
| 772 |
PLOT02_THIRTEEN</remark>.</para> |
| 773 |
</section> |
| 774 |
|
| 775 |
|
| 776 |
<section id="Ocean_Section_Projection"> |
| 777 |
<title>Ocean Section Projection</title> |
| 778 |
|
| 779 |
<para>The ocean_section projection enables the plotting of sections |
| 780 |
and time series from the Ocean Model. To plot in this new projection, |
| 781 |
users should pass GRIB code to <productname>Magics</productname> |
| 782 |
containing an Ocean Model field and set the following |
| 783 |
parameter:</para> |
| 784 |
|
| 785 |
<programlisting> CALL <function>PSETC</function>('<parameter>SUBPAGE_MAP_PROJECTION</parameter>', 'OCEAN_SECTION')</programlisting> |
| 786 |
|
| 787 |
<para>The section or time-series will be plotted in the subpage |
| 788 |
defined by the user. <productname>Magics</productname> will plot the |
| 789 |
appropriate axes on the bottom horizontal and left vertical lines of |
| 790 |
the subpage. It is not possible to plot subareas of the sections or |
| 791 |
time-series.</para> |
| 792 |
|
| 793 |
<para>Example of ocean section plots are given in the example programs |
| 794 |
in <remark>SUBROUTINE PLOT02_FIFTEEN and SUBROUTINE |
| 795 |
PLOT02_SIXTEEN</remark>.</para> |
| 796 |
</section> |
| 797 |
--> |
| 798 |
</section> |
| 799 |
|
| 800 |
<section id="Coastlines_and_Gridlines"> |
| 801 |
<title>Coastlines and Gridlines</title> |
| 802 |
|
| 803 |
<para><productname>Magics</productname> will project coastlines and |
| 804 |
latitude/longitude grid lines onto requested areas, as defined by the |
| 805 |
user.</para> |
| 806 |
|
| 807 |
<xi:include href="../phrases/coastlines_origin.xml" |
| 808 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 809 |
|
| 810 |
<para>The plotting of coastlines and grid lines is achieved by calling the |
| 811 |
action routine <function>PCOAST</function>. Mapping, coastline and grid |
| 812 |
parameters should be set, if required, before <function>PCOAST</function> |
| 813 |
is called.</para> |
| 814 |
|
| 815 |
<para>Parameters exist in <productname>Magics</productname> to enable |
| 816 |
users to control the plotting of coastlines and grid lines and these |
| 817 |
parameters should be set before <function>PCOAST</function> is called. |
| 818 |
Users can control the line style, colour, shading, resolution etc of |
| 819 |
coastlines as well as the number, colour and quality of grid lines. Users |
| 820 |
also have control over the plotting of grid line labels.</para> |
| 821 |
|
| 822 |
<para><productname>Magics</productname> default values for coastline, |
| 823 |
grids and labels ensure that users always achieve a reasonable plot. |
| 824 |
However, if these default values are not suitable, users can set any or |
| 825 |
all of the parameters to their own chosen value.</para> |
| 826 |
|
| 827 |
|
| 828 |
<section id="Coastline_Activation"> |
| 829 |
<title>Coastline Activation</title> |
| 830 |
<para> By default, coastlines are enabled, ie they are drawn |
| 831 |
when <function>PCOAST</function> is called. To deactivate the coastline |
| 832 |
drawing, set <parameter>MAP_COASTLINE</parameter> to '<code>OFF</code>'. |
| 833 |
</para> |
| 834 |
</section> |
| 835 |
|
| 836 |
<section id="Coastline_Attributes"> |
| 837 |
<title>Coastline Attributes</title> |
| 838 |
<para> The parameters |
| 839 |
<parameter>MAP_COASTLINE_THICKNESS</parameter>, |
| 840 |
<parameter>MAP_COASTLINE_STYLE</parameter> and |
| 841 |
<parameter>MAP_COASTLINE_COLOUR</parameter> control the coastline |
| 842 |
thickness line style and colour respectively. |
| 843 |
</para> |
| 844 |
|
| 845 |
<important id="New_Coastline_Colour_Defaults"> |
| 846 |
<title>Magics++</title>Previous versions of <productname>Magics</productname> |
| 847 |
plotted yellow coastlines and gridlines by default. This worked well on old dark monitors, |
| 848 |
but <productname>Magics++</productname> has updated these defaults to black in order |
| 849 |
to give better default plots on modern monitors and paper. |
| 850 |
</important> |
| 851 |
|
| 852 |
</section> |
| 853 |
|
| 854 |
<section id="Coastline_Automatic_Selection"> |
| 855 |
<title>Coastline Automatic Selection</title> |
| 856 |
<important> <title>Magics++</title>New to <productname>Magics++</productname> |
| 857 |
is a flexible set of differing resolution coastlines. The new mechanisms are explained below.</important> |
| 858 |
|
| 859 |
<para> <productname>Magics++</productname> incorporates a new set of high-resolution coastlines which were provided by |
| 860 |
http://www.naturalearthdata.com . By default, <productname>Magics</productname> will select an appropriate coastline |
| 861 |
file automatically, using the lowest resolution file that will give high |
| 862 |
quality output. This ensures high quality whilst improving speed and reducing |
| 863 |
the size of the output file. In the majority of cases this should be |
| 864 |
sufficient for most users' purposes. |
| 865 |
</para> |
| 866 |
</section> |
| 867 |
|
| 868 |
<section id="Specifying_a_Coastline_File"> |
| 869 |
<title>Specifying the coastline resolution</title> |
| 870 |
<para>The first parameter that can change which coastline file is used is |
| 871 |
<parameter>MAP_COASTLINE_RESOLUTION</parameter>. When set to <code>AUTOMATIC</code> |
| 872 |
(its default value), the coastline file will be chosen automatically as above. |
| 873 |
The possible alternatives are <code>LOW</code>, <code>MEDIUM</code> and <code>HIGH</code>. |
| 874 |
This behaviour can be overridden by manually specifying one of the existing coastline files in the <productname>Magics++</productname> |
| 875 |
share directory by setting the <parameter>MAP_COASTLINE_PATH</parameter> parameter. |
| 876 |
<!-- |
| 877 |
to one of the following:</para> |
| 878 |
<programlisting> |
| 879 |
CALL <function>PSETC</function> ('<parameter>MAP_COASTLINE_PATH</parameter>', 'coast_high.nc') |
| 880 |
CALL <function>PSETC</function> ('<parameter>MAP_COASTLINE_PATH</parameter>', 'coast_medium_high.nc') |
| 881 |
CALL <function>PSETC</function> ('<parameter>MAP_COASTLINE_PATH</parameter>', 'coast_medium.nc') |
| 882 |
CALL <function>PSETC</function> ('<parameter>MAP_COASTLINE_PATH</parameter>', 'coast_low.nc') |
| 883 |
CALL <function>PSETC</function> ('<parameter>MAP_COASTLINE_PATH</parameter>', 'coast_very_low.nc') |
| 884 |
CALL <function>PSETC</function> ('<parameter>MAP_COASTLINE_PATH</parameter>', 'coast_tiny.nc') |
| 885 |
</programlisting> |
| 886 |
<para> --> |
| 887 |
If you have a coastline file in another directory, you can specify |
| 888 |
a complete path to it in the <parameter>MAP_COASTLINE_PATH</parameter> parameter.</para> |
| 889 |
<para>Note that it is not generally recommended to use a high resolution coastline |
| 890 |
file with a large geographical area plot - the increase in quality will be hard to see |
| 891 |
and the increase in plotting time may be significant.</para> |
| 892 |
</section> |
| 893 |
|
| 894 |
<!-- |
| 895 |
<section id="Creating_a_Different_Resolution_Coastline_File"> |
| 896 |
<title>Creating a Different Resolution Coastline File</title> |
| 897 |
<para> If none of the existing files are quite right for you, you can run |
| 898 |
the <filename>CoastBuilder</filename> program to generate a new one. |
| 899 |
The following command line will produce a low-resolution coastline file |
| 900 |
called <filename>coast_0.2.nc</filename> from the original high-resolution |
| 901 |
data (<filename>coast.nc</filename>):</para> |
| 902 |
<programlisting> CoastBuilder -in $MAGPLUS_HOME/share/coast.nc -out coast_0.2.nc -t 0.2</programlisting> |
| 903 |
<para> You can now use this file by specifying its complete path to |
| 904 |
the <parameter>MAP_COASTLINE_PATH</parameter> parameter. This program works |
| 905 |
by removing points from the input file; no new points are created |
| 906 |
and none are moved. The <code>-t</code> parameter specifies an error |
| 907 |
threshold as a lat/long distance. The larger the value, the larger |
| 908 |
the acceptable error and therefore the more points that will be removed. |
| 909 |
</para> |
| 910 |
</section> |
| 911 |
--> |
| 912 |
|
| 913 |
<!-- |
| 914 |
<section id="Filtering_the_Coastlines_at_Runtime"> |
| 915 |
<title>Filtering the Coastlines at Run-time</title> |
| 916 |
<para> For the purpose of experimenting, it is possible to filter the coastlines |
| 917 |
during the running of your <productname>Magics</productname> program. This |
| 918 |
procedure uses the same filtering technique discussed briefly above. |
| 919 |
The following line of code specifies that a coastline is generated by |
| 920 |
filtering the original high-resolution coastline file with a threshold of 0.2:</para> |
| 921 |
<programlisting> CALL PSETR ('MAP_COASTLINE_SIMPLIFICATION_FACTOR', 0.2)</programlisting> |
| 922 |
<para> If you specify a <parameter>MAP_COASTLINE_PATH</parameter> then that data |
| 923 |
will be filtered using the algorithm.</para> |
| 924 |
</section> |
| 925 |
--> |
| 926 |
|
| 927 |
<section id="Land_and_Sea_Shading"> |
| 928 |
<title>Land and Sea Shading</title> |
| 929 |
|
| 930 |
<para><productname>Magics</productname> allows the shading of the land |
| 931 |
and sea in coastline plotting by means of two parameters |
| 932 |
<parameter>MAP_COASTLINE_LAND_SHADE</parameter> and |
| 933 |
<parameter>MAP_COASTLINE_SEA_SHADE</parameter>. The default value for |
| 934 |
both is '<code>OFF</code>'. If land/sea shading is required, either or |
| 935 |
both those parameters should be set to '<code>ON</code>' before |
| 936 |
<function>PCOAST</function> is called. By default, land will be shaded |
| 937 |
green and the sea blue. The user may change this by setting the |
| 938 |
parameters <parameter>MAP_COASTLINE_LAND_SHADE_COLOUR</parameter> and |
| 939 |
<parameter>MAP_COASTLINE_SEA_SHADE_COLOUR</parameter> to the desired |
| 940 |
colours. Land and sea shading can be turned on or off independently |
| 941 |
of each other.</para> |
| 942 |
|
| 943 |
<important id="Coastline_Outline_And_Shading"> <title>Magics++</title> |
| 944 |
Previous versions of <productname>Magics</productname> could not plot |
| 945 |
both the coast outline and shading with a single call to <function>PCOAST</function> - |
| 946 |
two calls were required. |
| 947 |
<productname>Magics++</productname> will plot both if shading is on. To achieve the |
| 948 |
effect of land or sea shading without the outlines visible, set the coastline colour |
| 949 |
to be the same as the land or sea shading. |
| 950 |
</important> |
| 951 |
|
| 952 |
</section> |
| 953 |
<section id="Political_boundaris"> |
| 954 |
<title>Political boundaries and rivers</title> |
| 955 |
<para><productname>Magics</productname> offers users to extend the display of coastlines |
| 956 |
with rivers and political boundaries. The data for these services are, as with the coastlines, |
| 957 |
taken from http://www.naturalearthdata.com . ECMWF is not responsible for the accuracy and content of the |
| 958 |
data sets and uses as they are provided by the owners. |
| 959 |
</para> |
| 960 |
</section> |
| 961 |
|
| 962 |
|
| 963 |
<section id="Gridline_Parameters"> |
| 964 |
<title>Gridline Parameters</title> |
| 965 |
|
| 966 |
<para>To change the default grid values, users could, for example, set |
| 967 |
<parameter>MAP_GRID_LATITUDE_REFERENCE</parameter> to <code>6.0</code> |
| 968 |
and <parameter>MAP_GRID_LATITUDE_INCREMENT</parameter> to |
| 969 |
<code>5.0</code>. This would result in the latitude lines being drawn on |
| 970 |
the map every 5 degrees using the 6 degree line as a reference, e.g. the |
| 971 |
lines drawn could be 1, 6, 11, 16 etc. The default values for these |
| 972 |
parameters are <code>0</code> and <code>10</code> respectively, which |
| 973 |
results in grid lines being drawn at 0, 10, 20, 30, 40 etc. The |
| 974 |
parameters <parameter>MAP_GRID_LONGITUDE_REFERENCE</parameter> and |
| 975 |
<parameter>MAP_GRID_LONGITUDE_INCREMENT</parameter> perform the same |
| 976 |
function for the map longitude.</para> |
| 977 |
|
| 978 |
<!-- |
| 979 |
<highlights> |
| 980 |
<para>Diagrams 9, 10, 11</para> |
| 981 |
</highlights> |
| 982 |
--> |
| 983 |
|
| 984 |
<para>The parameter <parameter>MAP_LABEL_LATITUDE_FREQUENCY</parameter> |
| 985 |
enables users to have control over the lines on which latitude labels |
| 986 |
appear. If this parameter is set to <code>4</code>, for example, then |
| 987 |
labels will be plotted on every fourth latitude line. The parameter |
| 988 |
<parameter>MAP_LABEL_LONGITUDE_FREQUENCY</parameter> performs the same |
| 989 |
function for the map longitude. Users may inhibit the plotting of grids |
| 990 |
and labels by setting both the parameters, |
| 991 |
<parameter>MAP_GRID</parameter> and <parameter>MAP_LABEL</parameter> to |
| 992 |
'<code>OFF</code>', the default for both being '<code>ON</code>'.</para> |
| 993 |
</section> |
| 994 |
|
| 995 |
<para>Very often, three action routines are required to plot a full map, |
| 996 |
e.g. <function>PCOAST</function>, <function>PCONT</function> and |
| 997 |
<function>PTEXT</function>. The first action routine to be called will set |
| 998 |
up the user's subpage, on which all subsequent plotting takes place. Users |
| 999 |
may call the action routines in any order, providing that the parameters |
| 1000 |
required have been previously set.</para> |
| 1001 |
|
| 1002 |
<para>It is essential that mapping parameters which affect the user's |
| 1003 |
subpage, i.e. those with the prefix <parameter>SUBPAGE_MAP</parameter>, be |
| 1004 |
set, if required, before the first action routine is called, e.g. |
| 1005 |
<parameter>SUBPAGE_LOWER_LEFT_LONGITUDE</parameter>, |
| 1006 |
<parameter>SUBPAGE_MAP_SCALE</parameter>.</para> |
| 1007 |
</section> |
| 1008 |
|
| 1009 |
|
| 1010 |
<xi:include href="../paramtables/pnew(SUPER_PAGE)_tables.xml" |
| 1011 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1012 |
|
| 1013 |
<xi:include href="../paramtables/pnew(PAGE)_tables.xml" |
| 1014 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1015 |
|
| 1016 |
<xi:include href="../paramtables/pnew(SUBPAGE)_tables.xml" |
| 1017 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1018 |
|
| 1019 |
<xi:include href="../paramtables/pcoast_tables.xml" |
| 1020 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1021 |
|
| 1022 |
|
| 1023 |
|
| 1024 |
<xi:include href="../paramtables/XmlSceneNode_page_magml_tables.xml" |
| 1025 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1026 |
|
| 1027 |
<xi:include href="../paramtables/XmlSceneNode_page_magml_flat_tables.xml" |
| 1028 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1029 |
|
| 1030 |
<xi:include href="../paramtables/XmlViewNode_map_magml_tables.xml" |
| 1031 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1032 |
|
| 1033 |
<xi:include href="../paramtables/XmlViewNode_map_magml_flat_tables.xml" |
| 1034 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1035 |
|
| 1036 |
<!-- |
| 1037 |
<xi:include href="../paramtables/XmlPage_magml_tables.xml" |
| 1038 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1039 |
|
| 1040 |
<xi:include href="../paramtables/XmlSubPage_magml_tables.xml" |
| 1041 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1042 |
--> |
| 1043 |
<xi:include href="../paramtables/Coastlines_coastlines_magml_tables.xml" |
| 1044 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1045 |
|
| 1046 |
<xi:include href="../paramtables/Coastlines_coastlines_magml_flat_tables.xml" |
| 1047 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1048 |
|
| 1049 |
<xi:include href="../paramtables/TaylorGrid_taylor_grid_magml_tables.xml" |
| 1050 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1051 |
|
| 1052 |
<!-- no need for flat taylor_grid tables as it is already a flat object |
| 1053 |
<xi:include href="../paramtables/TaylorGrid_taylor_grid_magml_flat_tables.xml" |
| 1054 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 1055 |
--> |
| 1056 |
|
| 1057 |
</chapter> |