# 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.```

example

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

example

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

## Examples

collapse all

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 ```

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

collapse all

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

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 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 SystemValid map valuesDefault map value
`"geographic"`
• The current `siteviewer` object or a new `siteviewer` object if none are open

• `"gmted2010"`, if the function is called with an output

`"cartesian"`
• `"none"`

• A `siteviewer` object

• The name of a glTF™ file

• The name of an STL file

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

Data Types: `char` | `string`

## Output Arguments

collapse all

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