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.

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

    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:
    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,
    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). Try
    to get a Lambert conic projection of North America. Now try
    The coastline is still there, but the grid has disappeared and the axes shows raw X/Y projectioncoordinates. Now, try this:
    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.


    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.

    'linewidth', value
    'linestyle', ( linespec | 'none' )

    Specify various line/text properties for the grid and its labels.

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

  • Legend Boxes
  • A legend box can be added to the map using m_legend. Only someof the functionality of legend is currently included. The legendbox can be dragged and dropped using the mouse button.

    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 plot, 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_plot(LONG,LAT,...line properties) % draw a line on a map (erase current plot)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:

    Again, these functions will return handles to graphics objects, allowing (for example) the drawing oflabelled contours:

    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)

    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

  • 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


    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.


    No clipping is performed. This is sometimes useful for debugging purposes.


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


    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:
    There are no options.

  • Computing distances between points
  • Geodesic distances on a spherical earth can be computed between pairs ofwither geographic (long/lat) or map (X/Y) coordinates using the functionsm_lldist and m_xydist. For example,
    DIST=m_lldist([20 30],[44 45])
    computes the distance from 20E, 44N to 30E, 45N. Alternatively, if you want to compute the distance between two points selected by the mouse:
    will return that distance.Because of the inaccuracies implicit in a spherical earth approximation thetrue geodesic distances may differ by 1% or so from the computed distances.

    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:

    1. Go to ftp://ftp.ngdc.noaa.gov/MGG/shorelines/ .
    2. Get and uncompress any or all of the files gshhs_c.b.gz, gshhs_l.b.gz, gshhs_i.b.gz and/or gshhs_h.b.gzin aconvenient directory. One useful place is in m_map/private.
    3. If the database files are not in subdirectory m_map/private ,you must edit the FILNAME settings in m_gshhs_c.m,m_gshhs_l.m, m_gshhs_i.m, m_gshhs_h.m and/or m_gshhs_f.mto 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.
    A Mapping package for Matlab (2024)
    Top Articles
    Latest Posts
    Article information

    Author: Pres. Lawanda Wiegand

    Last Updated:

    Views: 6138

    Rating: 4 / 5 (71 voted)

    Reviews: 94% of readers found this page helpful

    Author information

    Name: Pres. Lawanda Wiegand

    Birthday: 1993-01-10

    Address: Suite 391 6963 Ullrich Shore, Bellefort, WI 01350-7893

    Phone: +6806610432415

    Job: Dynamic Manufacturing Assistant

    Hobby: amateur radio, Taekwondo, Wood carving, Parkour, Skateboarding, Running, Rafting

    Introduction: My name is Pres. Lawanda Wiegand, I am a inquisitive, helpful, glamorous, cheerful, open, clever, innocent person who loves writing and wants to share my knowledge and understanding with you.