mapprofile

Interpolate between waypoints on terrain

Syntax

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon)

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon,units)

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon,units,trackmethod)

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon,units,trackmethod,interpmethod)

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon,ellipsoid)

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon,ellipsoid,trackmethod)

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon,ellipsoid,trackmethod,interpmethod)

mapprofile(___)

[___] = mapprofile

Description

Use Unit Sphere and Get Range in Degrees

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon) interpolates intermediate points between the waypoints specified by lat and lon. You must specify the elevation data Z and spatial reference R for the terrain. For each intermediate point, the function returns the interpolated terrain height in zq, the distance from the first waypoint (the range) in distq, the latitude in latq, and the longitude in lonq.

Specify Range Units

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon,units) specifies the units units for distq. The function calculates surface distances using the default radius of the Earth (equivalent to 6371 kilometers).

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon,units,trackmethod) additionally specifies whether intermediate points are along great circles or rhumb lines.

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon,units,trackmethod,interpmethod) additionally specifies the interpolation method.

Specify Reference Ellipsoid

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon,ellipsoid) specifies the reference ellipsoid for the coordinates. This syntax returns distq using the units of the semimajor axis of the reference ellipsoid.

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon,ellipsoid,trackmethod) additionally specifies whether intermediate points are along great circle tracks or rhumb line tracks.

[zq,distq,latq,lonq] = mapprofile(Z,R,lat,lon,ellipsoid,trackmethod,interpmethod) additionally specifies the interpolation method.

Display and Interactively Select Coordinates

mapprofile(___) displays an elevation profile of the intermediate points in a new figure on an axesm-based map.

[___] = mapprofile enables you to interactively select waypoints on the current axesm-based map. If the current object on the map is a regular data grid, then the function uses the z-coordinate data (the ZData property) as the terrain elevation data. Otherwise, the function uses z-coordinate data from the first regular data grid it finds on the map. If the grid does not have z-coordinate data, then the function uses the color data (the CData property), instead. To finish selecting points, press Enter.

Examples

Compute Elevation Profile Along Track

Load elevation data and a geographic cells reference object for the Korean peninsula. Compute the elevation profile between two points in the region, specifying the units for the range (distq) as kilometers. By default, the mapprofile function uses bilinear interpolation along a great circle track.

load korea5c

lat = [40.5 30.7];
lon = [121.5 133.5];
[zq,distq,latq,lonq] = mapprofile(korea5c,korea5cR,lat,lon,"km");

Plot the track over a satellite basemap.

figure
geolimits(korea5cR.LatitudeLimits,korea5cR.LongitudeLimits)
hold on
geoplot(latq,lonq,"w",LineWidth=2)
geobasemap satellite

Display the elevation profile on a Cartesian plot.

figure
plot(distq,zq)
xlabel("Range (kilometers)")
ylabel("Elevation (meters)")

Specify Track Method and Interpolation Method

Load world topography data into the workspace as an array and a geographic raster reference object. Calculate an elevation profile for the great circle track between San Francisco and New York City, using nearest neighbor interpolation.

load topo60c

lat = [37.77 40.71];
lon = [-122.41 -74.01];
[zqgc,distqgc,latqgc,lonqgc] = mapprofile(topo60c,topo60cR,lat,lon,"km","gc","nearest");

Calculate an elevation profile for the rhumb line track between the same cities, using bicubic interpolation.

[zqrh,distqrh,latqrh,lonqrh] = mapprofile(topo60c,topo60cR,lat,lon,"km","rh","bicubic");

Display both tracks on a map. Use magenta for the great circle track and blue for the rhumb line track.

figure
geoplot(latqgc,lonqgc,"m",LineWidth=1.5)
hold on
geoplot(latqrh,lonqrh,"b",LineWidth=1.5)
geobasemap topographic

Display both elevation profiles on a Cartesian plot.

figure
plot(distqgc,zqgc,"m")
hold on
plot(distqrh,zqrh,"b")
xlabel("Range (kilometers)")
ylabel("Elevation (meters)")

Display 3-D Elevation Profile on Map

Load terrain elevation data for the Korean peninsula into the workspace as an array and a geographic cells reference object. Specify the coordinates of four waypoints.

load korea5c
lat = [43 43 41 38];
lon = [116 120 126 128];

Display the elevation profile on a map by omitting the output arguments. When you specify more than two waypoints, the function displays the result in 3-D.

mapprofile(korea5c,korea5cR,lat,lon)

Add coastlines and city locations to the map.

load coastlines
plotm(coastlat,coastlon)
geoshow("worldcities.shp","Marker",".","Color","r")

Input Arguments

Z — Elevation data grid

m-by-n array

Elevation data grid, specified as an m-by-n array.

Data Types: single | double

R — Spatial reference for Z

GeographicCellsReference object | GeographicPostingsReference object

Spatial reference for Z, specified as a GeographicCellsReference or GeographicPostingsReference object. The RasterSize property of R must be consistent with size(Z).

lat — Latitude coordinates of waypoints

vector

Latitude coordinates of the waypoints, in degrees, specified as a vector. You can separate sets of waypoints into line sequences using NaN values. The NaN values in lat must correspond to the NaN values in lon.

The size of lat must match the size of lon.

Data Types: single | double

lon — Longitude coordinates of waypoints

vector

Longitude coordinates of the waypoints, in degrees, specified as a vector. You can separate sets of waypoints into line sequences using NaN values. The NaN values in lon must correspond to the NaN values in lat.

The size of lat must match the size of lon.

Data Types: single | double

units — Units for distq

"degrees" (default) | "degree" | "deg" | "kilometer" | "kilometers" | "km" | ...

Units for distq, specified as one of these options:

• These angular units.

  Value	Unit Name
  "degree", "degrees", "deg"	Degrees
  "radian", "radians", "rad"	Radians

• Any length unit supported by the validateLengthUnit function.

  Value	Unit Name
  "m", "meter", "meters", "metre", "metres"	Meters
  "cm", "centimeter", "centimeters", "centimetre", "centimetres"	Centimeters
  "mm", "millimeter", "millimeters", "millimetre", "millimetres"	Millimeters
  "micron", "microns"	Microns
  "km", "kilometer", "kilometers", "kilometre", "kilometers"	Kilometers
  "nm", "naut mi", "nautical mile", "nautical miles"	Nautical miles
  "ft", "international ft", "foot", "international foot", "feet", "international feet"	Feet
  "in", "inch", "inches"	Inches
  "yd", "yds", "yard", "yards"	Yards
  "mi", "mile", "miles", "international mile", "international miles"	Miles
  "sf", "survey ft", "US survey ft", "U.S. survey ft", "survey foot", "US survey foot", "U.S. survey foot", "survey feet", "US survey feet", "U.S. survey feet"	U.S. survey feet
  "sm", "survey mile", "survey miles", "statute mile", "statute miles", "US survey mile", "US survey miles", "U.S. survey mile(s)", "U.S. survey miles"	U.S. survey miles (statute miles)
  "Clarke's foot", "Clarkes foot"	Clarke's feet
  "German legal metre", "German legal meter"	German legal metres
  "Indian foot"	Indian feet

This argument is case insensitive.

Data Types: char | string

ellipsoid — Reference ellipsoid

[1 0] (default) | referenceSphere object | referenceEllipsoid object | oblateSpheroid object | two-element numeric vector

Reference ellipsoid, specified as a referenceSphere object, a referenceEllipsoid object, an oblateSpheroid object, or a two-element vector of the form [semimajor_axis eccentricity], where semimajor_axis is the length of the semimajor axis and eccentricity is the eccentricity. The values semimajor_axis and eccentricity must be of data type double.

The default value of [1 0] represents the unit sphere.

When you specify the ellipsoid argument, the mapprofile function returns distq in the units of the semimajor axis of the reference ellipsoid.

If you do not specify the ellipsoid argument and R contains a geocrs object in its GeographicCRS property, then the mapprofile function uses the ellipsoid contained in the geocrs object. For example, given a reference object R, the function uses R.GeographicCRS.Spheroid.

trackmethod — Track method

"gc" (default) | "rh"

Track method, specified as one of these options:

• "rh" — Find track points along rhumb line paths.

• "gc" — For spheres, find track points along great circle paths. For ellipsoids, find track points along geodesic paths.

Data Types: char | string

interpmethod — Interpolation method

"bilinear" (default) | "bicubic" | "nearest"

Interpolation method, specified as one of these options:

• "bilinear" — Use linear interpolation.

• "bicubic" — Use cubic interpolation.

• "nearest" — Use nearest neighbor interpolation.

Data Types: char | string

Output Arguments

zq — Terrain heights of intermediate points

numeric vector

Terrain heights of the intermediate points, returned as a numeric vector. The function calculates the terrain heights using the same units as Z.

The number of intermediate points depends on the density of the terrain elevation data. When you increase the density of the data, the mapprofile function returns more intermediate points.

The sizes of zq, distq, latq, and lonq match.

distq — Range

numeric vector

Range, returned as a numeric vector. For each intermediate point, the range is the distance from the first point to the intermediate point. If you separate the input waypoints into sequences using NaN values, then the function calculates the distance of each intermediate waypoint from the first waypoint in the corresponding sequence.

By default, the units for distq are degrees. You can specify the units for distq using the units or ellipsoid argument.

The number of intermediate points depends on the density of the terrain elevation data. When you increase the density of the data, the mapprofile function returns more intermediate points.

The sizes of zq, distq, latq, and lonq match.

latq — Latitudes of intermediate points

numeric vector

Latitudes of the intermediate points, in degrees, returned as a numeric vector.

The number of intermediate points depends on the density of the terrain elevation data. When you increase the density of the data, the mapprofile function returns more intermediate points.

The sizes of zq, distq, latq, and lonq match.

lonq — Longitudes of intermediate point

numeric vector

Longitudes of the intermediate points, in degrees, returned as a numeric vector.

The number of intermediate points depends on the density of the terrain elevation data. When you increase the density of the data, the mapprofile function returns more intermediate points.

The sizes of zq, distq, latq, and lonq match.

Version History

Introduced before R2006a

R2024b: mapprofile does not accept referencing vectors or referencing matrices as input

The mapprofile function does not accept referencing vectors or referencing matrices as input. 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.

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

When you specify a referencing vector or referencing matrix as input, the mapprofile function issues a warning that it will not accept referencing vectors or referencing matrices as input in a future release.

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.