distance

Distance between sites

Syntax

d = distance(site1,site2)

d = distance(site1,site2,path)

d = distance(___,Name=Value)

Description

d = distance(site1,site2) calculates the distance, in meters, between the specified sites. By default, the function calculates the Euclidean distance.

d = distance(site1,site2,path) calculates the distance using the specified path type, either the Euclidean path or the great circle path.

d = distance(___,Name=Value) specifies options using name-value arguments.

Examples

Calculate Distance Between Transmitter and Receiver Site

Create a transmitter site and a receiver site. Specify the locations using geographic coordinates.

tx = txsite(Name="MathWorks", ...
    Latitude=42.3001, ...
    Longitude=-71.3504);
rx = rxsite(Name="Fenway Park", ...
    Latitude=42.3467, ...
    Longitude=-71.0972);

Calculate the distance between the sites. The function returns the result in meters. By default, the function calculates the distance using a Euclidean path.

dme = distance(tx,rx)

dme = 2.1504e+04

Convert the distance to kilometers.

dkm = dme / 1000

dkm = 21.5037

Calculate Distance Using Great Circle Path

Create a transmitter site and a receiver site. Specify the locations using geographic coordinates.

tx = txsite(Name="MathWorks", ...
    Latitude=42.3001, ...
    Longitude=-71.3504);
rx = rxsite(Name="Fenway Park", ...
    Latitude=42.3467, ...
    Longitude=-71.0972);

Calculate the distance between the sites using a great circle path. The function returns the result in meters. Convert the distance from meters to kilometers.

dme = distance(tx,rx,"greatcircle");
dkm = dme / 1000

dkm = 21.4515

Input Arguments

site1, site2 — Transmitter or receiver site

txsite object | rxsite object

Transmitter or receiver site, specified as a txsite or rxsite object. Specify multiple sites using array inputs.

path — Measurement path type

"euclidean" (default) | "greatcircle"

Measurement path type, specified as one of the following:

• "euclidean" — Use the shortest path through space that connects the antenna center positions of the sites. The option is the default for both Cartesian and geographic sites.

• "greatcircle" — Use the shortest path on the surface of a spherical Earth that connects the geographic locations of the sites. This option requires the CoordinateSystem properties of the sites to be "geographic".

Data Types: char

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: d = distance(site1,site2,Map="myfile.stl") specifies the map as an STL file.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: d = distance(site1,site2,"Map","myfile.stl") specifies the map as an STL file.

Map — Map for visualization or surface data

siteviewer object | triangulation object | string scalar | character vector

Map for visualization or surface data, specified as a siteviewer object, a triangulation object, a string scalar, or a character vector. Valid and default values depend on the coordinate system.

Coordinate System	Valid Map Values	Default Map Value
"geographic"	A siteviewer object.a A terrain name, if the function is called with an output argument. Valid terrain names are: "none" — Terrain elevation is 0 everywhere. "gmted2010" — USGS GMTED2010 terrain data. This option requires an internet connection. The name of custom terrain data added using the addCustomTerrain function, specified using a string scalar or a character vector.	If the function is not called with an output, the current siteviewer object, or a new siteviewer object if none are open. By default, siteviewer objects use USGS GMTED2010 terrain data. If the function is called with an output, "gmted2010".
"cartesian"	"none" A siteviewer object. The name of a glTF™ file, specified using a string scalar or a character vector. The name of an STL file, specified using a string scalar or a character vector. A triangulation object.	"none"
a Alignment of boundaries and region labels are a presentation of the feature provided by the data vendors and do not imply endorsement by MathWorks®.

In most cases, if you specify this argument as a value other than a siteviewer or "none", then you must also specify an output argument.

Output Arguments

d — Distance between sites, in meters

M-by-N numeric array

Distance between the sites, in meters, returned as an M-by-N numeric array, where M is the number of sites in site2 and N is the number of sites in site1.

Version History

Introduced in R2019b