First, get all the files, either as a zip archive or a gzipped tar-file and unpack them. Now, start up Matlab (version 5 or higher). Makesure that the toolbox is in your path. This can be done simply by cd
'ing to the correct directory.
Alternatively,if you have unpacked them intodirectory /users/rich/m_map
(and /users/rich/m_map/private
),then you can add this to your search path:
(Note: you may want to install M_Map as a toolbox accessible to allusers. To do this, unpack the files into $MATLAB/toolbox/m_map, andadd that directory to the list defined in $MATLAB/toolbox/local/pathdef.m).
Instructions for installing the (optional) high-resolution bathymetry database are givenin Section 9 , and instructions for installing the (optional)high-resolution GSHHS coastline database is given in Section 10 .However, we should first check that the basic setup is OK.
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 numberof optional parameters as well. To get the same map without using the defaults, you would use
The second line draws a coastline, using the 1/4 degree database. Coastlines with greaterresolution can be drawn, using your own database (see also Section 7 ). m_coast
can be called with various line parameters. For example,
The third line superimposes a grid. Although there are many possible options that can be used tocustomize the appearance of the grid, defaults can always be used (as in the example). These options are discussed in Section 4 . You can get a list of the optionsusing the GET syntax:
Finally, suppose you want to show and label the location of, say, a mooring at 129W, 48 30'N.
m_ll2xy
(and its inverse m_xy2ll
) convert from longitude/latitude coordinates to those of theprojection. Various clipping options can also be specified in converting to projectioncoordinates. If you are willing to accept default clipping setting, you canuse the built-in functions m_line
and m_text
:
Finally (!), we may want to alter the grid details slightly. Note that, a given mapmust only be initialized once.
Two useful properties for projections are (1) the ability the preserve angles for differentiallysmall regions, and (2) the ability to preserve area. Projections satisfying the first conditionare called conformal , those satisfying the second are called equal-area .No projection can be both. Many projections (especially global projections) are neither, insteadan attempt has been made to aesthetically balance the errors in both conditions.
Note: All projections (except UTM) are currently spherical rather than ellipsoidal. It is unlikelythat this will be a problem in normal usage.
M_Map includes two fairly simple databases for coastlines and global elevation data.Highly-detailed databases are not included in this release because theyare a) extremely large and b) extremelytime-consuming to process (loops are inherently involved). If more detailed mapsare required, section 9 and section 10 give instructions on how to add some freely-available high-resolution datasets.Read section 7 and section 8 if youwant to add your own coastline/bathymetry data.
Coastline options
M_Map includes a 1/4 degree resolution coastline database. This is suitable for mapscovering large portions of the globe, but is noticeably coarse for many large-scaleapplications. Users not satisfied with their regional map are directed to section 7 and/or section 10 for more information on creating and using high-resolutioncoastlines.The M_Map database is accessed using the m_coast
function. Coastlinescan be drawn as simple lines, using
m_coast('line', ...optional line arguments );or
m_coast( optional line arguments );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
m_coast('patch', ...optional patch arguments );where the optional trailing arguments are the standard patch properties. For example,
m_coast('patch',[.7 .7 .7],'edgecolor','g');draws gray land, outlined in green. When patches are being drawn, lakes and inland seas are given the axes background colour.
Note that line coastlines are usually drawn rather rapidly. Filled coastlines take considerablymore time to generate (because map limits are not necessarily rectangular, clipping mustbe accomplished in m-files).
Topography/Bathymetry options
M_Map can access a 1-degree resolution global elevation database (actually, this database isis included in the Matlab distribution, used by of $MATLAB/toolbox/matlab/demos/earthmap.m
).A contour map of elevations at default levels can be drawn using
m_elev;Different levels can also be specified:
m_elev('contour',LEVELS, optional contour arguments);For example, if you want all the contours to be dark blue, use:
m_elev('contour',LEVELS,'edgecolor','b');Filled contours are also possible:
m_elev('contourf',LEVELS, optional contourf arguments);Finally, if you want to simply extract the elevation data for your own purposes,
[Z,LONG,LAT]=m_elev([LONG_MIN LONG_MAX LAT_MIN LAT_MAX]);returns rectangular matrices for depths Z at locations LONG,LAT.
Grid lines and labels
In order to get the perfect grid, you may want to experiment with different grid options. Twofunctions are useful here, M_GRID which draws a grid, and M_UNGRID which erases the currentgrid (but leaves all coastlines and user-specified data alone). Trym_proj('Lambert');m_coast;m_grid;to get a Lambert conic projection of North America. Now try
m_ungridThe coastline is still there, but the grid has disappeared and the axes shows raw X/Y projectioncoordinates. Now, try this:
m_grid('xtick',10,'tickdir','out','yaxislocation','right','fontsize',7);The various options that can be changed are:
'box',( 'on' | 'off' | 'fancy' )
This specifies whether or not an outline box is drawn. Three types of outlineboxes are available: 'on'
, the default, is a a simple line. Twotypes of fancy outline boxes are available. If 'tickdir'
is 'in'
,then alternating black and white patches are made (see example 2).If 'tickdir'
is set to 'out'
, then a more complex line patternis drawn (see example 6).Fancy boxes are in general only available for maps boundedby lat/long limits (i.e. not for azimuthal projections), but if this option ischosen inappropriately a warning message is issued. 'xtick',( num | [value1 value2 ...])
This specifies the number/location of the longitude grid. If a single number is specified,grid lines/values are drawn for approximately that number of equally-spaced locations (thenumber is only approximate because the M_GRID attempts to find "nice" intervals, i.e. itrounds to even increments). Exact locations can be specified by using a vector oflocation values. There is an analagous 'ytick'
property. 'xticklabels',[label1;label2 ...]
Special labels can be specified. Labels can either be numerical values (which are then formattedby M_GRID), or string values which are used without change. There is an analagous 'yticklabels'
property 'xlabeldir', ( 'middle' | 'end' )
Longitude labels are either middled onto the ends of their prespective grid lines (and drawnperpendicular to those lines), or are drawn extending outwards fro the ends of those lines.There is an analagous 'ylabeldir'
property. 'ticklen',value
Specifies the length of tickmarks (as a fraction of plot width) 'tickdir',( 'in' | 'out' )
Specifies whether tickmarks point inwards or outwards. If 'box'
isset to 'fancy'
, this specifies the form of the fancy outline box. 'color',colorspec
'linewidth', value
'linestyle', ( linespec | 'none' )
'fontsize',value
'fontname',name
Specify various line/text properties for the grid and its labels.'linewidth', value
'linestyle', ( linespec | 'none' )
'fontsize',value
'fontname',name
'XaxisLocation',( 'bottom' | 'middle' | 'top' )
Specifies where the X-axis will be drawn, either at the bottom (southermost) end, atthe top (northernmost) end, or in the middle. 'YaxisLocation',( 'left' | 'middle' | 'right' )
Specifies where the Y-axis will be drawn, either at the left (westernmostmost) end, atthe right (easternmost) end, or in the middle. Titles and x/ylabels
Titles and x/ylabels can be added to maps using the title
and x/ylabel
functions in the usual way (this is a change from v1.0 in whichthe 'visible' property hadto be explicitly set to 'on'; this is now done within m_grid).The purpose of this package is to allow you to map your own data! Once a suitablegrid and (possibly) a coastline have been chosen, you can add your own lines, text,or contour plots using built-in M_Map drawing functions which handle the conversion fromlongitude/latitude coordinates to projection coordinates. These drawing functions arevery similar to the standard Matlab plotting functions, and are described in the next section.
Sometimes you may want to convert between longitude/latitude and projection coordinateswithout immediately plotting the data. This might happen if you want to interactivelyselect points using ginput
, or if you want to draw labels tied to aspecific point on the screen rather than a particular longitude/latitude. Projectionconversion routines are described in sections 5.2 and5.3. Once raw longitude/latitude coordinates are converted intoprojection coordinates, standard Matlab plotting functions can be used.
Maps are drawn to fit within the boundaries of the plot axes. Thus their scaleis somewhat arbitrary. If you are interested in making a map to a given scale, e.g. 1:200000 or something like that, you can do so by using them_scale
primitive, see section 2.6 .The data units are the projection coordinates, which are distances expressedas a fraction of earth radii. To get a map "distance" between two points,use the Cartesian distance between the points in the projection coordinatesystem and multiply by your favourite value for the earth's radius, usuallyaround 6370 km (exception - the UTM projection uses coordinates of northing andeasting in meters, so no conversion is necessary).
Caution: One problem that sometimes occurs is that data does not appear on the plot due toambiguities in longitude values. For example, if plot longitude limits are [-180 180],a point with a longitude of, say, 200, may not appear in cylindrical and conic projections. This is not a bug. Handling the clipping in "wrapped around" curves requiresadding points (rather than just moving them) and is therefore incompatible withvarious other requirements (such as keeping input and output matrices the same sizein the conversion routines described below).
Drawing lines, text, arrows, patches and contours
For most purposes you do not need to know what the projection coordinates actuallyare - you just want to plot something at a specified longitude/latitude. Most of the time you when you want to plot something on a map you want to do soby specifying longitude/latitude coordinates, instead of the usual X/Y locations. To do so in M_Map, replace calls to line, text, quiver, patch,contour, and contourf
with M_Map equivalents that recognizelontgitude/latitude coordinates by prepending "m_" to the function name. For example,m_line(LONG,LAT,...line properties) % draw a line on a mapm_quiver(LONG,LAT,U,V,S) % A quiver plotm_text(LONG,LAT,'string') % Textm_patch(LONG,LAT,..patch properties) % Patches.Each of these functions will handle the coordinate conversion internally, and will return a vector of handles to the graphic objects if desired. Theonly difference between these functions and the standard Matlab functions is that the first twoarguments MUST be longitude and latitude.
One caveat applies to m_patch
. For compatibility reasons this uses thesame code that applies to coastline filling. Coastlines come either as either "islands"or "lakes", and M_Map keeps track of the difference by assuming curves are oriented so thatthe filled area ("land") is always on the right as we go around the curve. This isslightly different than the convention used in patch
which always fillsthe inside. Keeping track of this difference is relatively straightforward in a Cartesiansystem, but not so easy in spherical coordinates. In the absence of other informationm_patch
tries to do the right thing, but (especially when the patchintersects a map boundary) it can get confused. If a patch isn't filling correctly,try reversing the order of points using flipud
or fliplr
.
Data gridded in longitude and latitude can also be contoured:
m_contour(LONG,LAT,VALUES)m_contourf(LONG,LAT,VALUES)Again, these functions will return handles to graphics objects, allowing (for example) the drawing oflabelled contours:
[cs,h]=m_contour(LONG,LAT,VALUES)clabel(cs,h,'fontsize',6);
Fancy arrows (i.e. with width, head shape, and colour specifications) can be generated using m_vec.m
. See the on-line help for more details about the use of m_vec
.
Drawing tracklines
It is sometimes useful to annotate lines representing the time-varying location ofa ship, aircraft, or satellite with time and date annotations. This can be doneusing m_track
. m_proj('UTM','long',[-72 -68],'lat',[40 44]);m_gshhs_i('color','k');m_grid('box','fancy','tickdir','out');% fake up a tracklinelons=[-71:.1:-67];lats=60*cos((lons+115)*pi/180);dates=datenum(1997,10,23,15,1:41,zeros(1,41));m_track(lons,lats,dates,'ticks',0,'times',4,'dates',8,... 'clip','off','color','r','orient','upright');
![A Mapping package for Matlab (1) A Mapping package for Matlab (1)](https://i0.wp.com/www.eoas.ubc.ca/track1.gif)
See the on-line help for more details about the use of
m_track
, andthe different options for setting fontsize, tick spacing, date formats, etc.While fiddling with the various parameters, it is often handy to be able to erasethe plotted tracks without erasing the coastline and grid. This can be done using
m_ungrid trackor
m_ungrid('track')
Drawing range rings
One nifty thing that is sometimes useful is the ability to draw circles at a given rangeor ranges from a specific location. This can be done using m_range_ring
,which has 3 required calling parameters: LONG, LAT, RANGE, followed by any number of(optional) line specification property/value pairs. Example 11illustrates how to use m_range_ring
. Converting longitude/latitude to projection coordinates
If you want to use projection coordinates (perhaps you want to compute map areas, ordistances, or you want to make a legend in the upper left corner), the following command converts longitude/latitude coordinates to projection coordinates. [X,Y]=m_ll2xy(LONG,LAT, ...optional clipping arguments )where LONG, LAT, X, and Y are matrices of the same size. Projection coordinates areequal to true distances near the center of the map, and are expressed as fractionsof an earth radius. To get a distance, multiply by the radius of the earth (about6370km). The exception is the UTM projection which provides coordinates of northingand easting in meters.
The possible clipping arguments are
'clip','on'
This is the default. Columns of LONG and LAT are assumed to form lines, and these are clippedto the map limits. The first point outside the map is therefore moved to the map edge,and all other points are converted the NaN. 'clip','off'
No clipping is performed. This is sometimes useful for debugging purposes. 'clip','point'
Points are tested against the map limits. Those outside the limits are converted to NaN,those inside are converted to projection coordinates. No points are moved. This optionis useful for point data (such as station locations). 'clip','patch'
Points are tested against the map limits. Those outside the limits changed into a point exactlyon the limits. Those inside are converted to projection coordinates. This optionmay be useful when trying to draw patches, however it probably won't work well. Converting projection coordinates to longitude/latitude
Conversion from projection coordinates to longitude/latitude is straightforward:[LONG,LAT]=m_xy2ll(X,Y)There are no options.
For ideas on how to make more complex plots, see the Examples.These plots are also included in the function m_demo
.
Once a given map includes several elements a certain amount of fiddling is usually necessaryto satisfy the natural human urge to give the image a certain aesthetic quality. If the imageincludes complicated coastlines which take a long time to draw (e.g. those discussed below) than clearing the figure andredrawing soon becomes tedious. The m_ungrid
command introduced above can be usedto selectively remove parts of the figure. For example:
m_ungrid
can recognize and delete specific elements by searching the 'tag'
property of all plot elements, which is set by the variousdifferent M_Map routines.
If you are interested in a particular area and want a higher-resolution coastline thanthat used by m_coast
, the best procedure is to
A number of global and regional topography databases are available at NCAR . Several areavailable for free from their ftp site.
As long as the data is stored in a mat-file as a rectangular matrix in longitude/latitude,then m_contour
or m_contourf
can be used to plotthat data.
For many purposes the elevation database accessed by M_Map provides adequateresolution. However, there are also many cases when more detail is desired. I have not included a higher-resolution database becauseit would greatly increase the size of the package. However, v1.2 includes m-filesto access and plot a popular global 5-minute bathymetry/topography database,after a few minutes of work.
This section provides instructions on how to download TerrainBase, and convertit from a 56Mb ASCII file to a 18Mb binary file using m_tba2b.m
. Itis then straightforward to access and plot bathymetry from this file using m_tbase.m
, which is in every way functionally identical to m_elev
(see Section 3.2).
TerrainBase is also available on CDrom, and is alsocommonly stored in netcdf (or other) binary format somewhere on many academic networks. Ifyou modify m_tbase.m
to access data from one of thesesources, let me know!
Installing GSHHS
When drawing maps there is always a tradeoff between the execution time of thegenerating program and the resolution of the resulting map. Included in M_Mapis a 1/4 degree coastline database which can be used to generate very fast maps,with adequate resolution for many purposes.
However, it is often desirable to be able to make detailed maps of limited geographicareas. For this purpose a higher-resolution coastline database is necessary.I have not included such a database in M_Map because it would greatly increasethe size of the package. However, I have included m-files to access and usea popular high-resolution database called GSHHS
As distributed, GSHHS consists of a hierarchical set of databases at differentresolutions. The lowest or "crude" resolution is not as good as the M_Mapdatabase, although it contains many more inland lakes. The "high" resolutionconsists of points about 200m apart. There isalso an even finer "full" resolution. You can install part or all of thedatabase (depending on how much disk space you have available). The "full" resolution occupies 90Mb of disk space, and successively coarser resolutions are smaller by about 1/4.Thus "high" resolution occupies 21Mb, "intermediate" uses 6Mb, and "low" uses 1.1Mb (onereason for not always using "high" resolution is that the entire 90Mb database must be readand processed each call, which may take some time).
How to install GSHHS:
- Go to ftp://ftp.ngdc.noaa.gov/MGG/shorelines/ .
- Get and uncompress any or all of the files
gshhs_c.b.gz, gshhs_l.b.gz, gshhs_i.b.gz
and/orgshhs_h.b.gz
in aconvenient directory. One useful place is inm_map/private
. - If the database files are not in subdirectory
m_map/private
,you must edit theFILNAME
settings inm_gshhs_c.m,m_gshhs_l.m, m_gshhs_i.m, m_gshhs_h.m
and/orm_gshhs_f.m
to point to the appropriate files.
Using GSHHS effectively
The simplest calling mechanism is identical to that for m_coast
( Section 3 ). For example, to draw a gray-filled high-resolution coastline,m_gshhs_h('patch',[.5 .5 .5]);is sufficient. However, execution times may be very, very long, as the entiredatabase must be searched and processed. I would not recommend trying to draw worldmaps with the intermediate or high-resolution coastlines! There are two ways to speed this up.The first is merely to use a lower-resolution database, with fewer points.The second is useful ifyou are going to be repeatedly drawinga map (because, for example, it's the base figure for your work). Inthis case I recommendthat you save an intermediate processed (generally smaller) file as follows:
m_proj ... % set up projection parameters% This command does not draw anything - it merely processes the % high-resolution database using the current projection parameters % to generate a smaller coastline file called "gumby"m_gshhs_h('save','gumby');% Now we can draw a few maps of the same area much more quicklyfigure(1);m_usercoast('gumby','patch','r');m_grid;figure(2);m_usercoast('gumby','linewidth',2,'color','b');m_grid('tickdir','out','yaxisloc','left');etc.