A Mapping package for Matlab (2024)

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_coastcan 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.

m_coast('line', ...optional line arguments );

m_coast( optional line arguments );

m_coast('patch', ...optional patch arguments );

m_coast('patch',[.7 .7 .7],'edgecolor','g');

m_elev;

m_elev('contour',LEVELS, optional contour arguments);

m_elev('contour',LEVELS,'edgecolor','b');

m_elev('contourf',LEVELS, optional contourf arguments);

[Z,LONG,LAT]=m_elev([LONG_MIN LONG_MAX LAT_MIN LAT_MAX]);

m_proj('Lambert');m_coast;m_grid;

m_ungrid

m_grid('xtick',10,'tickdir','out','yaxislocation','right','fontsize',7);

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'); 

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 track

or

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!

m_gshhs_h('patch',[.5 .5 .5]);

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.