-
Notifications
You must be signed in to change notification settings - Fork 7
Expand file tree
/
Copy pathmapug.html
More file actions
2472 lines (1960 loc) · 101 KB
/
Copy pathmapug.html
File metadata and controls
2472 lines (1960 loc) · 101 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" type="text/css" href="./doc/map.css">
<title>M_Map Users Guide</title>
</head>
<body >
<div class="row">
<div class="column left">
<a href="#1._M_Map_Logo" >
<img class="menu" src="./doc/mlogo.png" alt="" > </a>
<ul class="menu">
<li> <a href="./map.html">Introduction</a> </li>
<li> <a href="./map.html#gallery">Gallery</a></li>
<li> <a href="./map.html#download">Getting M_Map</a> </li>
<li> <a href="./map.html#relnotes">Release Notes</a></li>
<li> <a href="./mapug.html">Users Guide</a></li>
<li> <a href="./map.html#examples">Example Code<a></li>
<li> <a href="./map.html#Citation">Citation<a></li>
<li> <a href="./map.html#ack">Acknowledgements</a></li>
</ul>
<p class="menu"> Last changed 20/Mar/2019. Questions and comments to <a
href="mailto:rich@eos.ubc.ca">rich@eos.ubc.ca</a></p>
</div>
<div class="column right">
<a name="users"></a>
<h1> <a > M_Map: </a></h1>
<h2> Users Guide v1.4 </h2>
<hr>
<!-- Can check all these by using grep '-p"' mapug.html -->
<h2> <a name="ToC"> Table of Contents </a> </h2>
<p> (Note - a Chinese translation of an earlier version of this guide can be
<a href="http://bbs.06climate.com/forum.php?mod=viewthread&tid=42945&fromuid=904" >found here</a>)</p>
<ol class="menu">
<li> <a href="#p1">Getting started</a></li>
<li> <a href="#p2">Specifying projections</a></li>
<ol>
<li> <a href="#p2.1">Azimuthal projections</a></li>
<li> <a href="#p2.2">Cylindrical and Pseudo-cylindrical projections</a></li>
<li> <a href="#p2.3">Conic projections</a></li>
<li> <a href="#p2.4">Miscellaneous global projections</a></li>
<li> <a href="#p2.5">Yeah, but which projection should I use?</a></li>
<li> <a href="#p2.6">Map scales</a></li>
<li> <a href="#p2.7">Map coordinate systems - geographic and geomagnetic</a> </li>
</ol>
<li> <a href="#p3">Coastlines and Bathymetry</a></li>
<ol>
<li> <a href="#p3.1">Coastline options</a> </li>
<li> <a href="#p3.2">Topography/Bathymetry options</a></li>
</ol>
<li> <a href="#p4">Customizing the axes</a></li>
<ol>
<li> <a href="#p4.1">Grid lines and labels</a></li>
<li> <a href="#p4.2">Titles and x/ylabels</a></li>
<li> <a href="#p4.3">Legend Boxes</a></li>
<li> <a href="#p4.4">Scale bar</a></li>
</ol>
<li> <a href="#p5">Adding your own data</a></li>
<ol>
<li> <a href="#p5.1">Drawing lines, text,
arrows, patches, hatches, speckles, and contours</a> </li>
<li><a href="#p5.2">Drawing images and pcolor</a><img align="left" src="./doc/new.gif"> </li>
<li><a href="#p5.2b">Drawing shaded relief maps</a> </li>
<li> <a href="#p5.3">Drawing tracklines</a></li>
<li> <a href="#p5.4">Drawing range rings and geodesics</a></li>
<li> <a href="#p5.5">Converting longitude/latitude to projection coordinates</a></li>
<li> <a href="#p5.6">Converting projection to longitude/latitude coordinates </a></li>
<li> <a href="#p5.7">Computing distances between points</a></li>
<li> <a href="#p5.8">Annotation</a> </li>
<li> <a href="#p5.9">Colour and Colormaps</a><img align="left" src="./doc/new.gif"></li>
<li> <a href="#p5.10">Colourbars with Contourmaps</a></li>
</ol>
<li> <a href="#p6">More complex maps</a></li>
<li> <a href="#p7">Removing features from a map</a></li>
<li> <a href="#p8">Adding your own coastlines</a></li>
<ol>
<li> <a href="#p8.1">Reading and Handling coastline data</a></li>
<li> <a href="#p8.2">ESRI Shapefiles </li>
<li> <a href="#p8.2b" >Projection conversions </li>
<li> <a href="#p8.3">Coastline Extractor</a></li>
<li> <a href="#p8.4">DCW political boundaries</a></li>
<li> <a href="#p8.5"> Natural Earth political boundaries</li>
<li> <a href="#p8.6">GSHHS(G) high-resolution coastline database</a></li>
<ol>
<li> <a href="#p8.6.1">Installing GSHHS</a></li>
<li> <a href="#p8.6.2">Using GSHHS effectively</a></li>
</ol>
</ol>
<li> <a href="#p9">Adding your own topography/bathymetry</a></li>
<ol>
<li> <a href="#p9.1">Sandwell and Smith Bathymetry</a></li>
<li> <a href="#p9.2">TerrainBase 5-minute global bathymetry/topography </a></li>
<li> <a href="#p9.3"> ETOPO 2- and 1- minute global bathymetry/topography </a></li>
</ol>
<li> <a href="#p10">M_Map toolbox contents and description</a></li>
<li> <a href="#p11">Known Problems and Bugs</a></li>
<li> <a href="#p12">OCTAVE Compatibility Issues</a> <img align="left" src="./doc/new.gif"></li>
<li> <a href="#p13">Changes since last release</a> </li>
</ol>
<hr>
<h2> <a name="p1">1. Getting started </a> </h2>
<p> First, get all the files, either as a <a
href="http://www.eos.ubc.ca/%7Erich/m_map1.4.zip"> zip archive </a>or
a <a href="http://www.eos.ubc.ca/%7Erich/m_map1.4.tar.gz"> gzipped
tar-file </a>and unpack them. If you are unpacking the zip file MAKE
SURE YOU ALSO UNPACK SUBDIRECTORIES! Now, start up Matlab (version 5 or
higher). Make sure that the toolbox is in your path. This can be done
simply by <code>cd</code>'ing to the correct directory. </p>
<p> Alternatively, if you have unpacked them into directory <code>/users/rich/m_map</code>
(and <code>/users/rich/m_map/private</code>), then you can add this to
your search path: </p>
<pre>path(path,'/users/rich/m_map');<br></pre>
or
<pre>addpath /users/rich/m_map<br></pre>
<p>To follow along with this document, you would then use a Web-browser to
open <a href="./mapug.html"><code>file:/users/rich/m_map/map.html</code></a>,
that is, this HTML document.</p>
<p> Note: you may want to install M_Map as a toolbox accessible to all
users. To do this, unpack the files into <code>$MATLAB/toolbox/m_map</code>, add
that directory to the list defined in <code> $MATLAB/toolbox/local/pathdef.m</code>, and
update the cache file using </p>
<pre>
rehash toolboxcache
</pre>
<p> Instructions for installing an (optional) high-resolution
bathymetry database are given in <a href="#p9.3"> here</a>, and
instructions
for installing the (optional) high-resolution GSHHS coastline database
is given in <a href="#p8.6"> here</a>. However, we should first
check that the basic setup is OK. </p>
<p> To see an example map, try this: </p>
<pre>
m_proj('oblique mercator');
m_coast;
m_grid;
</pre>
<p>This is a line map of the Oregon/British Columbia coast, using an
Oblique Mercator projection (A few more complex maps can be generated
by running the demo function <code>m_demo</code>).</p>
<p> The first line initializes the projection. Defaults are set for the
different projection, so you can easily see what a specific projection
looks like, but all projections have a number of optional parameters as well.
To get the same map without using the defaults, you would use </p>
<pre>
m_proj('oblique mercator','longitudes',[-132 -125], ...
'latitudes',[56 40],'direction','vertical','aspect',.5);
</pre>
<p> The exact meanings of the various options is given in <a href="#p2">
Section 2</a>. However, notice that longitudes are specified using a <em>
signed </em> notation - East longitudes are positive, whereas West
longitudes are negative (Also note that a decimal degree notation
is used, so that a longitude of 120 30'W is specified as -120.5).</p>
<p> The second line draws a coastline, using the 1/4 degree database.
Coastlines with greater resolution can be drawn, using your own
database (see also <a href="#p8"> Section 8</a>). <code>m_coast</code>
can be called with various line parameters. For example,
<pre>
m_coast('linewidth',2,'color','r');
</pre>
<p> draws a thicker red coastline. Filled coastlines can also be drawn,
using the <code> 'patch' </code> option (followed by any of the usual
PATCH property/value pairs:</p>
<pre>
m_coast('patch',[.7 .7 .7],'edgecolor','none');
</pre>
<p> draws a coastline with a gray fill and no border.</p>
<p> The third line superimposes a grid. Although there are many
possible options that can be used to customize the appearance of the
grid, defaults can always be used (as in the example). These options
are discussed in <a href="#p4"> Section 4</a>. You can get a list of
the options using the GET syntax: <g>
<pre>
m_grid get
</pre>
<p> which acts somewhat like the <code> get(gca) </code> syntax for
regular plots.</p>
<p> Finally, suppose you want to show and label the location of, say, a
mooring at 129W, 48 30'N. </p>
<pre>
[X,Y]=m_ll2xy(-129,48.5);
line(X,Y,'marker','square','markersize',4,'color','r');
text(X,Y,' M5','vertical','top');
</pre>
<p> <code> m_ll2xy </code> (and its inverse <code>m_xy2ll</code>)
convert from longitude/latitude coordinates to those of the projection.
Various clipping options can also be specified in converting to
projection coordinates. If you are willing to accept default clipping
setting, you can use the
built-in functions <code> m_line </code> and <code> m_text </code>:
</p>
<pre>
m_line(-129,48.5,'marker','square','markersize',4,'color','r');
m_text(-129,48.5,' M5','vertical','top');
</pre>
<p> Finally (!), we may want to alter the grid details slightly. Note
that, a given map must only be initialized once. </p>
<pre>
clf
m_proj('oblique mercator'); % repeated here so cut-n-paste simplified
m_coast('patch',[.7 .7 .7],'edgecolor','none');
m_grid('xlabeldir','end','fontsize',10);
m_line(-129,48.5,'marker','square','markersize',4,'color','r');
m_text(-129,48.5,' M5','vertical','top');
</pre>
<img src="./doc/exobl2.png" align="middle" width=30%>
<hr>
<h2> <a name="p2"> 2. Specifying projections </a> </h2>
<p> In order to get a list of the current projections, </p>
<pre>
m_proj get
</pre>
<p> or</p>
<pre>m_proj('set');</pre>
<p>Which currently return the following list:</p>
<pre>
Available projections are:
Stereographic
Orthographic
Azimuthal Equal-area
Azimuthal Equidistant
Gnomonic
Satellite
Albers Equal-Area Conic
Lambert Conformal Conic
Mercator
Miller Cylindrical
Equidistant Cylindrical
Oblique Mercator
Transverse Mercator
Sinusoidal
Gall-Peters
Hammer-Aitoff
Mollweide
Robinson
UTM
</pre>
<p>If you want details about the possible options for any of these
projections, add its name to the above command, e.g. </p>
<pre>
m_proj('set','stereographic');
</pre>
<p>which returns</p>
<pre>
'Stereographic'
<,'lon<gitude>',center_long>
<,'lat<itude>', center_lat>
<,'rad<ius>', ( degrees | [longitude latitude] )>
<,'rec<tbox>', ( 'on' | 'off' )>
</pre>
<p>You can also get details about the current projection. For example, in
order to see what the default parameters are for the sinusoidal
projection, we first initialize it, and then use the <code> 'set' </code>
option:</p>
<pre>
m_proj('sinusoidal');
m_proj get
Current mapping parameters -
Projection: Sinusoidal (function: mp_tmerc)
longitudes: -90 30 (centered at -30)
latitudes: -65 65
Rectangular border: off
</pre>
<p>In order to initialize a projection, you usually specify some location
parameters that define the geometry of the projection (longitudinal
limits, central parallel, etc.), as well as parameters that define the
extent
of the map (whether it is in a rectangular axis, what the border points
are, etc.). These vary slightly from projection to projection.</p>
<p> Two useful properties for projections are (1) the ability the
preserve angles for differentially small regions, and (2) the ability
to preserve area. Projections satisfying the first condition are called
<em> conformal</em>, those satisfying the second are called <em>
equal-area</em>. No projection can be both. Many projections (especially global
projections) are neither, instead an attempt has been made to aesthetically balance
the errors in both conditions. </p>
<p> Note: Most projections are currently <em> spherical </em>
rather than ellipsoidal. UTM is an ellipsoidal projection, and both the lambert conformal
conic and albers equal-area conic can be specified with ellipses if desired. This
is sometime useful when you have data (e.g. from a GIS package) at scales of Canadian provinces
or US states, which are often mapped using one of these projections.
It is unlikely that using a spherical earth model will be a problem (or an advantage) in
normal usage. </p>
<p>Let's go through the list of available projections:</p>
<ol>
<h3><li> <a name="p2.1"> Azimuthal projections </a></li>
</h3>
<p> Azimuthal projections are those in which points on the
globe are projected onto a flat tangent plane. Maps using these
projections have the property that direction or azimuth from the center
point to all other points is shown correctly. Great circle routes
passing through the central point appear as straight lines (although
great circles not passing through the central point may appear curved).
These maps are usually drawn with circular boundaries. The following
parameters specify the center point of an azimuthal projection map: </p>
<pre>
<,'lon<gitude>',center_long>
<,'lat<itude>', center_lat>
</pre>
<p> Maps are aligned so that the specified longitude is vertical at
the map center, with its northern end at the top (but see option <code>rotangle</code>
below in order to rotate this orientation). Then the extent of the map
is defined by </p>
<pre>
<,'rad<ius>', ( degrees | [longitude latitude] )>
</pre>
<p> Either an angular
distance in degrees can be given (e.g. 90 for a hemisphere), or the
coordinates of a point on the boundary can be specified. Then,</p>
<pre>
<,'rec<tbox>', ( 'on' | 'off' | 'circle' )>
</pre>
<p> is used to specify the map boundary. The default is to enclose the map
in a circular boundary (chosen using either of the latter two options),
but a rectangular one can also be specified. However, rectangular maps
are usually better drawn using a cylindrical or conic projection of some sort.
Finally, </p>
<pre>
<,'rot<angle>', degrees CCW>
</pre>
<p> rotates the figure so that the central longitude
is not vertical. </p>
<p> THe azimuthal projections include:</p>
<ol>
<h4> <li>Stereographic </li></h4>
<p>The stereographic projection is conformal, but not
equal-area. This projection is often used for polar regions. </p>
<h4> <li>Orthographic </li></h4>
<p>This projection is neither equal-area nor conformal,
but resembles a perspective view of the globe. </p>
<img src="./doc/mlogo.png" align="middle" width=30%>
<h4> <li>Azimuthal Equal-Area </li></h4>
<p> Sometimes called the Lambert azimuthal equal-area
projection, this mapping is equal-area but not conformal. </p>
<img src="./doc/ex_ssmi2.png" align="middle" width=60%>
<h4> <li>Azimuthal Equidistant </li></h4>
<p>This projection is neither equal-area nor conformal,
but all distances and directions from the central point are true. </p>
<h4> <li> Gnomonic </li></h4>
<p>This projection is neither equal-area nor conformal,
but all straight lines on the map (not just those through the center)
are great circle routes. There is, however, a great degree of
distortion at the edges of the map, so maximum radii should be kept
fairly small - 20 or
30 degrees at most. </p>
<h4> <li> Satellite </a></li></h4>
<p>This is a perspective view of the earth, as seen by
a satellite at a specified altitude. Instead of specifying a <code>radius</code>
for the map, the viewpoint altitude is specified: </p>
<pre> <,'alt<itude>',altitude_fraction >
</pre>
<p>the numerical value assigned to this property
represents the height of the viewpoint in units of earth radii. For
example, a satellite in an orbit of radius 3 earth radii would have an
altitude of
2. </p>
</ol>
<h3> <li> <a name="p2.2"> Cylindrical and Pseudo-cylindrical Projections </a></li> </h3>
<p> Cylindrical projections are formed by projecting
points onto a plane wrapped around the globe, touching only along some
great circle. These are very useful projections for showing regions of great
lateral extent, and are also commonly used for global maps of
mid-latitude regions only. Also included here are two pseudo-cylindrical
projections, the sinusoidal and Gall-Peters, which have some similarities to the
cylindrical projections (see below). </p>
<p> These maps are usually drawn with rectangular
boundaries (with the exception of the sinusoidal and sometimes the
transverse mercator). </p>
<ol>
<h4><li> Mercator </li> </h4>
<p> This is a conformal map, based on a tangent cylinder
wrapped around the equator. Straight lines on this projection are rhumb
lines (i.e. the track followed by a course of constant bearing). The
following properties affect this projection: </a>
<pre> <,'lon<gitude>',( [min max] | center)> </pre>
<p>Either longitude limits can be set, or a central
longitude defined implying a global map. </p>
<pre> <,'lat<itude>', ( maxlat | [min max])> </pre>
<p> Latitude limits are most usually the same in
both N and S latitude, and can be specified with a single value, but
(if
desired) unequal limits can also be used. DO NOT USE MERCATOR FOR A MAP THAT DOES NOT CONTAIN THE EQUATOR!!!</a>
<h4> <li>Miller Cylindrical </li> </h4>
<p>This projection is neither equal-area nor conformal,
but "looks nice" for world maps. Properties are the same as for the
Mercator, above. </p>
<img src="./doc/exblueocean.png" align="middle" width=70%>
<h4> <li> Equidistant cylindrical </li> </h4>
<p> This projection is neither equal-area nor conformal.
It consists of equally-spaced latitude and longitude lines, and is very
often used for quick plotting of data. It is included here simply so
that such maps can take advantage of the grid generation routines. Also
known as the Plate Carree. Properties are the same as for the Mercator, above. </p>
<h4><li> Oblique Mercator </li> </h4>
<p>The oblique mercator arises when the great circle
of tangency is arbitrary. This is a useful projection for, e.g., long
coastlines or other awkwardly shaped or aligned regions. It is
conformal but not equal area. The following properties govern this
projection: </p>
<pre>
<,'lon<gitude>',[ G1 G2 ]>
<,'lat<itude>', [ L1 L2 ]>
</pre>
<p>Two points specify a great circle, and thus the
limits of this map (it is assumed that the region near the shortest of
the two arcs is desired). The 2 points (G1,L1) and (G2,L2) are thus at
the center of either the top/bottom or left/right sides of the map
(depending on the <code>'direction'</code> property). </p>
<pre>
<,'asp<ect>',value>
</pre>
<p> This specifies the size of the map in the direction
perpendicular to the great circle of tangency, as a proportion of the
length shown. An aspect ratio of 1 results in a square map, smaller
numbers result in skinnier maps. Aspect ratios >1 are possible, but not
recommended. </p>
<pre>
<,'dir<ection>',( 'horizontal' | 'vertical' ) </pre>
<p> This specifies whether the great circle of tangency
will be horizontal on the page (for making short wide maps), or
vertical (for tall thin maps). </p>
<img src="./doc/exobl2.png" align="middle" width=30%>
<p> <font color="red"> WARNING - at SOME times, for certain combinations of G1/G2 L1/L2 endpoints, the coastline mapping algorithms fail
because of a numerical instability affecting the mapping of points on the opposite side of the world - you can see weird lines
going across your map when you try to plot a coastline. The work-around for this is to alter the G1/G2 or L1/L2 slightly.
</font> </p>
<h4><li> Transverse Mercator </li> </h4>
<p> The Transverse Mercator is a special case of the
oblique mercator when the great circle of tangency lies along a
meridian of longitude, and is therefore conformal. It is often used for
large-scale maps and charts. The following properties govern this projection: </p>
<pre>
<,'lon<gitude>',[min max]>
<,'lat<itude>',[min max]>
</pre>
<p> These specify the limits of the map. </p>
<pre>
<,'clo<ngitude>',value>
</pre>
<p> Although it makes most sense in general
to specify the central meridian as the meridian of tangency (this is
the default), certain map classification systems (noteably UTM) use only a
fixed set of central longitudes, which may not be in the map center. </p>
<pre>
<,'rec<tbox>', ( 'on' | 'off' )>
</pre>
<p>The map limits can either be based on
latitude/longitude (the default), or the map boundaries can form an
exact rectangle. The difference is small for large-scale maps. Note: Although this
projection is similar to the Universal Transverse Mercator (UTM) projection, the
latter is actually ellipsoidal in nature. </p>
<h4><li> Universal Transverse Mercator (UTM) </li> </h4>
<p>UTM maps are needed only for high-quality maps of
small regions of the globe (less than a few degrees in longitude). This
is an ellipsoidal projection. Options are similar to those of the
Transverse Mercator, with the addition of </p>
<pre>
<,'zon<e>', value 1-60>
<,'hem<isphere>',value 0=N,1=S>
</pre>
<p> These are computed automatically if not specified.
The ellipsoid defaults to <code>'normal'</code>, a spherical earth of
radius 1 unit, but other options can also be chosen using the following
property: </p>
<pre>
<,'ell<ipsoid>', ellipsoid>
</pre>
<p> For a list of available ellipsoids try <code>m_proj('set','utm')</code>.</p>
<p> The big difference between UTM and all the
other projections is that for ellipsoids other than <code>'normal'</code>
the projection coordinates are in meters, so-called "easting" and "northing". To take full
advantage of this it is often useful to call <code>m_proj</code> with <code>'rectbox'</code>
set to <code>'on'</code> and not to use the long/lat grid generated
by <code>m_grid</code> (since the regular matlab grid will be in units
of meters). </p>
<img src="./doc/extrack1.png" align="middle" width=50%>
<h4><li> Sinusoidal </li> </h4>
<p>This projection is usually called
"pseudo-cylindrical" since parallels of latitude appear as straight
lines, similar to their appearance in cylindrical projections tangent
to the equator. However, meridians curve together in this projection in
a sinusoidal way (hence the name), making this map equal-area. </p>
<h4><li> Gall-Peters </li></h4>
<p>Parallels of latitude and meridians both appear as
straight lines, but the vertical scale is distorted so that area is
preserved. This is useful for tropical areas, but the distortion in
polar areas is extreme. </p>
</ol>
<h3> <li> <a name="p2.3"> Conic Projections </li> </h3>
<p>Conic projections result from projecting onto a cone
wrapped around the sphere. The vertex of the cone lies on the
rotational axis of the sphere. The cone is either tangent at a single
latitude, or can intersect the sphere at two separated latitudes. It is
a useful projection for mid-latitude areas of large east-west extent.
The following properties affect these projections: </p>
<pre>
<,'lon<gitude>',[min max]>
<,'lat<itude>',[min max]>
</pre>
<p> These specify the limits of the map. </p>
<pre>
<,'clo<ngitude>',value>
</pre>
<p> The central longitude appears as a vertical on the
page. The default value is the mean longitude, although it may be set
to any value (even one outside the limits). </p>
<pre>
<,'par<allels>',[lat1 lat2]>
</pre>
<p>The standard parallels can be specified. Either one or
two parallels can be given: </p>
<pre>
<,'rec<tbox>', ( 'on' | 'off' )>
</pre>
<p>The default is a parallels at 1/3 and 2/3 of the latitudinal range. </p>
<p>The map limits can either be based on
latitude/longitude (the default), or the map boundaries can form an
exact rectangle which contain the given limits. Unless the region being mapped is small, it
is best to leave this <code> 'off' </code>. </p>
<p>The default is to use a spherical earth model for the mapping transformations. However, ellipsoidal coordinates can
also be specified. This tends to be useful only for doing coordinate transformations (e.g., if a particular
gridded database in in this kind of projection, and you want to find lat/long data), since
the difference would be impossible to see by eye on a plot.
The particular ellipsoid used can be chosen using the following
property: </p>
<pre>
<,'ell<ipsoid>', ellipsoid>
</pre>
<p> For a list of available ellipsoids try <code>m_proj('set','albers')</code>.
<p> Finally, if you just want to use <code>M_Map</code> as an engine to transform
between projected coordinates in some database and lat/long, it is useful to be able to explicitly specify the origin of the coordinate
system that was originally used (origins are sometimes set at the lower boundary of a projection so that all Y values are positive). This can be done be setting:
<pre>
<,'ori<gin>', [long lat]>
</pre>
<p>But note that "false eastings" and "false northings" are not handled by <code>m_proj</code>, instead you must
correct for them explicitly using </p>
<pre>
[long,lat]=m_xy2ll(x-false_easting,y-false_northing);
</pre>
<p> if you are trying to do this.</p>
<ol>
<h4><li> Albers Equal-Area Conic </li> </h4>
<p>This projection is equal-area, but not conformal </p>
<h4><li> Lambert Conformal Conic </li></h4>
<p>This projection is conformal, but not equal-area. </a>
<img src="./doc/exmodis.png" align="middle" width=70%>
</ol>
<h3> <li> <a name="p2.4"> Miscellaneous global projections </a> </li> </h3>
<p> There are a number of projections which don't really
fit into any of the above categories. Mostly these are global
projections (i.e. they show the whole world), and they have been
designed to be "pleasing to the eye". I'm not sure what use they are in
general, but they make
nice logos! </p>
<ol>
<h4><li> Hammer-Aitoff </li> </h4>
<p>An equal-area projection with curved meridians and
parallels. </p>
<img src="./doc/exrring.png" align="middle" width=60%>
<h4><li> Mollweide </li> </h4>
<p> Also called the Elliptical or Homolographic
Equal-Area Projection. Parallels are straight (and parallel) in this
projection.</p>
<p> Note that <a href="./map.html#e4">example 4</a> shows a rather
sophisticated use for viewing the oceans, designed to reduce distortion. </p>
<img src="./doc/exsinus.png" align="middle" width=60%>
<p>A more standard map
can be made using</p>
<pre>
m_proj('mollweide');
m_coast('patch','r');
m_grid('xaxislocation','middle');
</pre>
<h4><li> Robinson</li> </h4>
<p> Not equal-area OR conformal, but supposedly "pleasing to the eye".
<img src="./doc/exstepjet.png" align="middle" width=60%>
</ol>
<h3> <li> <a name="p2.5"> Yeah, but which projection should I use?</a></li> </h3>
<p>Well, it depends really on how large an area you are
mapping. Usually, maps of the whole world are Mercator, although often
the Miller Cylindrical projection looks better because it doesn't
emphasize the polar areas as much. Another choice is the Hammer-Aitoff
or Mollweide (which has meridians curving together near the poles).
Both are equal-area. It's probably not a good idea to use these
projections for maps that don't have the equator somewhere near the
middle. The Robinson projection is not equal-area or conformal, but was the choice of National Geographic (for a while, anyway),
and also appears in the IPCC reports.</p>
<p> If you are plotting something with a large
north/south extent, but not very wide (say, North and South America, or
the North
and South Atlantic), then the Sinusoidal or Mollweide projections will
look pretty good. Another choice is the Transverse Mercator, although
that
is usually used only for very large-scale maps (i.e., ones covering a very small area). </p>
<p>For smaller areas within one hemisphere or other
(say, Australia, the United States, the Mediterranean, the North
Atlantic) you might pick a conic projection. The differences between
the two available conic projections are subtle, and if you don't know
much about projections it probably won't make much difference which one
you use. </p>
<p> If you get smaller than that, it doesn't matter a
whole lot which projection you use. One projection I find useful in
many cases is the Oblique Mercator, since you can align it along a long
(but narrow) coastal area. If map limits along lines of
longitude/latitude are OK, use a Transverse Mercator or Conic
Projection. The UTM projection is also useful if you want to make a grid in meters, since the
projection coordinates (i.e., "eastings and northings") are in meters. </p>
<p> Polar areas are traditionally mapped using a
Stereographic projection, since everyone seems to think it looks nice to have a
"bullseye" pattern of latitude lines (the fact that lines of longitude come together at the poles also makes them
an almost irresistable destination for polar scientists and explorers). </p>
<p> If you want to get a quick idea of what any
projection looks like, it is simple to do so - default parameters for all functions are set for
a "typical" usage. For example, to see a stereographic map, try: </p>
<pre>
m_proj('stereographic'); % Example for stereographic projection
m_coast;
m_grid;
</pre>
<h3><li> <a name="p2.6">Map scales</a> </li></h3>
<p>M_Map usually scales the map so that it fits exactly
within the current axes. If you just want a nice picture (which is
mostly the case) then this is exactly what you need. On the other hand,
sometimes you want to print things out at some exact scale (i.e. if you
really much prefer sitting at your desk with a ruler and a piece of
paper trying to figure out how far apart Bangkok and Tokyo are). Use
the <code>m_scale</code> primitive for this - for a 1:250000 map, call
</p>
<pre>
m_scale(250000);
</pre>
<p>after you have drawn everything (Be careful - a
1:250000 map of the world is a lot bigger than 8.5"x11" sheet of
paper). </p>
<p>This option is usually only useful for
large-scale maps, i.e. maps of very small areas). </p>
<p>If you wish to know the current scale, calling <code>m_scale</code>
without any parameters will calculate and return that value. </p>
<p> To return to the default scaling call <code>m_scale('auto')</code>. </p>
<p>(PS - If you do want to find distances from Bangkok
to anywhere, plot an azimuthal equidistant projection of the world
centered on Bangkok (13 44'N, 100 30'E), and choose a fairly small
scale, like 1:200,000,000). Another option would be to use range rings, see <a
href="./map.html#e11">example 11</a>.</p>
<h3> <li> <a name="p2.7">Map coordinate systems - geographic and geomagnetic.</a></li> </h3>
<p> Latitude/Longitude is the
usual coordinate system for maps. In some cases UTM coords are also
used, but these are really just a simple transformation based on the
location of the equator and certain lines of longitude. On the other
hand, there are occasions when a coordinate system based on some other
set of axes is useful. For example, in space
physics data is often projected in coordinates based on the magnetic
poles. M_Map has a limited capability to deal with data in these other
coordinate systems. <code>m_coord</code> allows you to change the coordinate system from
geographic to geomagnetic. The following code gives you the idea - grids and boxes
are shown in the two different coordinate systems:
</p>
<pre>
lat=[25*ones(1,100) 50*ones(1,100) 25]; % Outline of a box
lon=[-99:0 0:-1:-99 -99];
subplot(121);
m_coord('IGRF2000-geomagnetic'); % Treat all lat/longs as geomagnetic
m_proj('stereographic');
m_coast('patch',[.5 1 .5],'edgecolor','none');
m_grid;
m_line(lon,lat,'color','r','linewi',3); % "lat/ln" assumed geomagnetic on the geomagnetic map
m_coord('geographic'); % Switch to assuming geographic
m_line(lon,lat,'color','b','linewi',3'); % Now they are treated as geographic
subplot(122);
m_coord('geographic'); % Define all in geographic
m_proj('stereographic');
m_coast('patch',[.5 1 .5],'edgecolor','none');
m_grid;
m_line(lon,lat,'color','b','linewi',3);
m_coord('IGRF2000-geomagnetic'); % Now assume that values are in geomagnetic
m_line(lon,lat,'color','r','linewi',3);
</pre>
<!-- print -dpng exMAG -->
<img src="./doc/exMAG.png" align="middle" width=80%>
<p> Note that this option is not
used very much, hence is not fully supported. In particular, filled
coastlines may not work properly. </p>
</ol>
<hr>
<h2> <a name="p3"> 3. Coastlines and Bathymetry </a> </h2>
<p> M_Map includes two fairly simple databases for coastlines and
global elevation data. Highly-detailed databases are not included in
this release because they are a) extremely large and b) extremely
time-consuming to
process (loops are inherently involved). If more detailed maps are
required, <a href="#p8"> section 8 </a> and <a href="#p9"> section 9 </a>
give instructions on how to add some freely-available high-resolution
datasets.
<ol>
<h2> <a name="p3.1"> <li> Coastline options </li></a> </h2>
<p> M_Map includes a 1/4 degree resolution coastline database. This
is suitable for maps covering large portions of the globe, but is
noticeably coarse for many large-scale applications. The M_Map
database is accessed using the <code> m_coast </code> function.
Coastlines can be drawn as simple lines,
using </p>
<pre>
m_coast('line', ...optional line arguments );
</pre>
<p>or</p>
<pre>
m_coast( optional line arguments );
</pre>
<p>where the optional arguments are all the standard arguments for
specifying line style, width, color, etc. Coastlines can also be drawn
as filled
patches using</p>
<pre>
m_coast('patch', ...optional patch arguments );
</pre>
<p>where the optional trailing arguments are the standard patch
properties. For example,</p>
<pre>
m_coast('patch',[.7 .7 .7],'edgecolor','g');
</pre>
<p> draws gray land, outlined in green. When patches are being drawn, lakes
and inland seas are given the axes background colour.</p>
<p> Many older (ocean) maps are created with speckled land
boundaries, which looks
very nice in black and white. You can get a speckled boundary with </p>
<pre>
m_coast('speckle', ....optional m_hatch arguments);
</pre>
<p> which calls <code>m_hatch</code>. This only looks nice if there aren't
too many
very tiny islands and/or lakes in the image (see <a
href="./map.html#12._Speckle">Example 13</a>).</p>
<p> Note that line coastlines are usually drawn rather rapidly.
Filled coastlines take considerably more time to generate (because map limits
are not necessarily rectangular, clipping must be accomplished in m-files). </p>
<h2> <a name="p3.2"> <li> Topography/Bathymetry options </li>
</a> </h2>
<p> M_Map can access a 1-degree resolution global elevation database
(actually, this database is is included in the Matlab distribution,
used by <code>$MATLAB/toolbox/matlab/demos/earthmap.m</code>). A
contour map of elevations at default levels can be drawn using </p>
<pre>m_elev;<br></pre>
Different levels can also be specified:
<pre>m_elev('contour',LEVELS, optional contour arguments);<br></pre>
For example, if you want all the contours to be dark blue, use:
<pre>m_elev('contour',LEVELS,'edgecolor','b');<br></pre>
Filled contours are also possible:
<pre>m_elev('contourf',LEVELS, optional contourf arguments);<br></pre>
Finally, if you want to simply extract the elevation data for your own
purposes,
<pre>[Z,LONG,LAT]=m_elev([LONG_MIN LONG_MAX LAT_MIN LAT_MAX]);<br></pre>
returns rectangular matrices for depths <code>Z</code> at locations <code>LONG,LAT</code>.
</ol>
<hr>
<h2> <a name="p4"> 4. Customizing axes </a> </h2>
<ol>
<h3> <li><a name="p4.1"> Grid lines and labels </a></li> </h3>
<p>In order to get the perfect grid, you may want to
experiment with different grid options. Two functions are useful here,
<code>m_grid</code> which draws a grid, and <code>m_ungrid</code> which erases the current grid
(but leaves all coastlines and user-specified data alone). Try </p>
<pre>
m_proj('Lambert');
m_coast;
m_grid;
</pre>
<p>to get a Lambert conic projection of North America.
Now try </p>
<pre>
m_ungrid
</pre>
<p>The coastline is still there, but the grid has
disappeared and the axes shows raw X/Y projection coordinates. Now, try
this: </p>
<pre>
m_grid('xtick',10,'tickdir','out','yaxislocation','right','fontsize',7);
</pre>
<p>The various options that can be changed include: </p>
<pre>
'box',( 'on' | 'off' | 'fancy' )
</pre>
<p>which specifies whether or not an outline box is drawn.
Three types of outline boxes are available: <code>'on'</code>, the
default, is a a simple line. Two types of fancy outline boxes are
available. If <code>'tickdir'</code> is <code>'in'</code>, then
alternating black and white patches are made (see </a><a
href="./map.html#e2">example 2</a>). If <code>'tickdir'</code> is
set to <code>'out'</code>, then a more complex line pattern is drawn
(see <a href="./map.html#e6">example 6</a>). Fancy boxes are in
general only available for maps bounded by lat/long limits (i.e. not
for azimuthal projections), but if this option is chosen
inappropriately a warning message is issued.</p>
<p>The number/location of ticks on the longitude grid is given by </p>
<pre>
'xtick',( num | [value1 value2 ...])
</pre>
<p>If a single
number is specified, grid lines/values are drawn for approximately that
number of equally-spaced locations (the number is only approximate
because the M_GRID attempts to find "nice" intervals, i.e. it rounds to
even increments). Exact locations can be specified by using a vector of
location values. There is an analogous <code> 'ytick' </code>
property.</p>
<p> Special labels can be specified using </p>
<pre>
'xticklabels',[label1;label2 ...]
</pre>
<p> Labels can either be numerical values
(which are then formatted by M_GRID), or string values which are used
without change. There is an analogous <code> 'yticklabels' </code>
property. </p>