mapprofile

Interpolate between waypoints on regular data grid

Syntax

[zi,ri,lat,lon] = mapprofile
[zi,ri,lat,lon] = mapprofile(Z,R,lat,lon)
[zi,ri,lat,lon] = mapprofile(Z,R,lat,lon,units)
[zi,ri,lat,lon] = mapprofile(Z,R,lat,lon,ellipsoid)
[zi,ri,lat,lon] = mapprofile(___,'trackmethod','interpmethod')


Description

mapprofile plots a profile of values between waypoints on a displayed regular data grid. mapprofile uses the current object if it is a regular data grid, or the first regular data grid found on the current axes. The grid's zdata is used for the profile. The color data is used in the absence of zdata. The result is displayed in a new figure.

[zi,ri,lat,lon] = mapprofile returns the values of the profile without displaying them. The output zi contains interpolated values along great circles between the waypoints. ri is a vector of associated distances from the first waypoint in units of degrees of arc along the surface. lat and lon are the corresponding latitudes and longitudes.

[zi,ri,lat,lon] = mapprofile(Z,R,lat,lon) accepts as input a regular data grid and waypoint vectors. No displayed grid is required. Sets of waypoints may be separated by NaNs into line sequences. The output ranges are measured from the first waypoint within a sequence. R is a geographic raster reference object. The RasterSize property of R must be consistent with size(Z).

[zi,ri,lat,lon] = mapprofile(Z,R,lat,lon,units) specifies the units of the output ranges along the profile. Valid range units inputs are any distance value recognized by unitsratio. Surface distances are computed using the default radius of the earth. If omitted, 'degrees' are assumed.

[zi,ri,lat,lon] = mapprofile(Z,R,lat,lon,ellipsoid) uses the provided ellipsoid definition in computing the range along the profile. ellipsoid is a referenceSphere, referenceEllipsoid, or oblateSpheroid object, or a vector of the form [semimajor_axis eccentricity]. The output range is reported in the same distance units as the semimajor axes of the ellipsoid. If you do not specify ellipsoid and R has a nonempty GeographicCRS property, then mapprofile uses the ellipsoid contained in the Spheroid property of the geocrs object in the GeographicCRS property of R. Otherwise, mapprofile uses the unit sphere.

[zi,ri,lat,lon] = mapprofile(___,'trackmethod','interpmethod') control the interpolation methods used. Valid track methods are 'gc' for great circle tracks between waypoints, and 'rh' for rhumb lines. Valid methods for interpolation within the matrix are 'bilinear' for linear interpolation, 'bicubic' for cubic interpolation, and 'nearest' for nearest neighbor interpolation. If omitted, 'gc' and 'bilinear' are assumed.

Examples

Interpolate Between Waypoints

Load elevation raster data and a geographic cells reference object for the Korean peninsula. Specify an elevation profile. Then, plot the profile along with coastline and city marker data. When you select more than two waypoints, the automatically generated figure displays the result in 3-D.

load korea5c
plat = [ 43  43  41  38];
plon = [116 120 126 128];
mapprofile(korea5c,korea5cR,plat,plon)
load coastlines
plotm(coastlat,coastlon)
geoshow('worldcities.shp','Marker','.','Color', 'red')

Interactively Select Waypoints

This example shows the relative sizes of the mountains compared to the depths of the sea.

First, load elevation raster data and a geographic cells reference object for the Korean peninsula. Create a map with appropriate limits and display the data as a surface. Then, interactively pick waypoints by calling mapprofile without input arguments. Select the two waypoints, one in the upper-left corner and one in the lower-right corner, by clicking your mouse. Press Enter after you select the last point.

load korea5c
worldmap(korea5c,korea5cR)
meshm(korea5c,korea5cR)
demcmap(korea5c)
[zi,ri,lat,lon] = mapprofile;

When you call mapprofile using output arguments, the results do not display in a new figure. Instead, use the results in further calculations or display the results yourself. For this example, convert ranges and elevations to kilometers and display them in a new figure. Set the vertical exaggeration factor to 50. Otherwise, the changes in elevation would be almost too small to see.

figure
plot(deg2km(ri),zi/1000)
daspect([ 1 1/50 1 ]);
xlabel 'Range (km)'
ylabel 'Elevation (km)'

The profile you get depends on the transect locations you pick.

Specify Units and Interpolation Method

You can compute values along a path without reference to an existing figure by providing a regular data grid and vectors of waypoint coordinates. Optional arguments allow control over the units of the range output and interpolation methods between waypoints and data grid elements.

Show what land and ocean areas lie under a great circle track from Frankfurt to Seattle:

cities = shaperead('worldcities.shp', 'UseGeoCoords', true);
Seattle = strcmp('Seattle', {cities(:).Name});
Frankfurt = strcmp('Frankfurt', {cities(:).Name});
lat = [cities(Seattle).Lat cities(Frankfurt).Lat];
lon = [cities(Seattle).Lon cities(Frankfurt).Lon];
load topo60c
[valp,rp,latp,lonp] = ...
   mapprofile(topo60c,topo60cR, ...
   lat,lon,'km','gc','nearest');
figure
worldmap([40 80],[-135 20])
land = shaperead('landareas.shp', 'UseGeoCoords', true);
faceColors = makesymbolspec('Polygon',...
   {'INDEX', [1 numel(land)], 'FaceColor', ...
   polcmap(numel(land))});
geoshow(land,'SymbolSpec',faceColors)
plotm(latp,lonp,'r')
plotm(lat,lon,'ro')
axis off

Compute Elevation Profile Along Straight Line

Load elevation data and a geographic cells reference object for the Korean peninsula. View the region on geographic axes using a satellite basemap.

load korea5c
figure
geolimits(korea5cR.LatitudeLimits,korea5cR.LongitudeLimits)
geobasemap('satellite')

Define endpoints for a straight-line transect through the region. Compute the elevation profile by using the mapprofile function. By default, the mapprofile function uses bilinear interpolation along a great circle track.

plat = [40.5 30.7];
plon = [121.5 133.5];
[z,rng,lat,lon] = mapprofile(korea5c,korea5cR,plat,plon);

Preserve the limits by using hold on. Plot the transect on the geographic axes.

hold on
geoplot(lat,lon,'w','LineWidth',2)

Plot the transect range and elevation on Cartesian axes.

figure
plot(rng,z,'r')

Version History

Introduced before R2006a

R2022b: mapprofile will not accept referencing vectors or referencing matrices as input

The mapprofile function will not accept referencing vectors or referencing matrices as input in a future release. Use a geographic raster reference object, specified as a GeographicCellsReference or GeographicPostingsReference object, as input instead. Reference objects have several advantages over referencing vectors and referencing matrices.

• Unlike referencing vectors and referencing matrices, reference objects have properties that document the size of the associated raster, its geographic limits, and the direction of its rows and columns.

• You can manipulate the limits of geographic rasters associated with reference objects using the geocrop function.

• You can manipulate the size and resolution of geographic rasters associated with reference objects using the georesize function.

To update your code, create a geographic reference object.

• Create a geographic reference object for a raster of cells by using the georefcells function.

• Create a geographic reference object for a raster of regularly posted samples by using the georefpostings function.

• Convert from a referencing vector to a geographic reference object by using the refvecToGeoRasterReference function.

• Convert from a referencing matrix to a geographic reference object by using the refmatToGeoRasterReference function.

Once you have created a reference object, replace uses of the referencing vector or referencing matrix in your code with the reference object.

R2020b: mapprofile uses reference ellipsoid information in raster reference objects

When you specify R as a geographic raster reference object, the mapprofile function uses the reference ellipsoid within the object. To find the reference ellipsoid for a geographic raster reference object, R, first get its geographic coordinate reference system as a geocrs object. Then, query the Spheroid property of the geocrs object.

g = R.GeographicCRS;
g.Spheroid

To use mapprofile with a different ellipsoid, specify the ellipsoid argument.