addCustomTerrain

R2026b

Add custom terrain data

Syntax

addCustomTerrain(terrainName,files)

addCustomTerrain(___,Name=Value)

Description

addCustomTerrain(terrainName,files) adds the terrain data specified with a user-defined terrainName and files. You can use this function to add custom terrain data in Site Viewer and other RF propagation functions. You can access the custom terrain data in the current and future sessions of MATLAB^® until you call removeCustomTerrain.

Note

In Antenna Toolbox™, addCustomTerrain function converts terrain elevation data from orthometric to ellipsoidal for visualization and when performing Euclidean distance or angle calculations between locations for example for free space path loss.

addCustomTerrain(___,Name=Value) specifies options using one or more name-value arguments in addition to the input arguments in the previous syntax. For example, specify the location to write the terrain data by using the WriteLocation argument.

Examples

Site Viewer Maps Using Custom Terrain

Add terrain for a region around Boulder, Colorado. The DTED file is from the SRTM Void Filled data set, available from the US Geological Survey. Name the terrain "southboulder".

dtedfile = "n39_w106_3arc_v2.dt1";
attribution = "SRTM 3 arc-second resolution. Data available from the US Geological Survey.";
addCustomTerrain("southboulder",dtedfile,Attribution=attribution)

Create a Site Viewer. Specify the terrain by name, using the Terrain argument of the siteviewer function.

viewer = siteviewer(Terrain="southboulder");

Display a site within the region that is covered by the terrain data.

mtzion = txsite(Name="Mount Zion", ...
    Latitude=39.74356,Longitude=-105.24193, ...
    AntennaHeight=30);
show(mtzion)

Create a coverage map of the area within 20 km of the transmitter site.

coverage(mtzion,MaxRange=20000,SignalStrengths=-100:-5)

Close the viewer and remove the custom terrain.

close(viewer)
removeCustomTerrain("southboulder")

Input Arguments

terrainName — User-defined identifier for terrain data

string scalar | character vector

User-defined identifier for terrain data, specified as a string scalar or a character vector.

Data Types: char | string

files — Names of DTED files to read

string scalar | character vector | string vector | cell array of character vectors

Names of DTED files to read, specified as a string scalar, a character vector, a string vector, or a cell array of character vectors.

• To add custom terrain from one DTED file, specify files as a string scalar or a character vector.

• To add custom terrain from multiple DTED files, specify files as a string vector or a cell array of character vectors. If you specify multiple files that do not cover a complete rectangular geographic region, you must set the FillMissing name-value argument to true.

The way you specify each file depends on the location of the file.

• If the file is in your current folder or in a folder on the MATLAB path, then specify the name of the file, such as "myFile.dt1".

• If the file is not in the current folder or in a folder on the MATLAB path, then specify the full or relative path name, such as "C:\myfolder\myFile.dt1" or "dataDir\myFile.dt1".

The horizontal datum code of each DTED file must be "WGS84". The vertical datum code of each DTED file must be "E96", "MSL", or "W84". You can query the datum codes of a DTED file by using the georasterinfo (Mapping Toolbox) function. This code stores the horizontal datum code in hDatum and the vertical datum code in vDatum.

info = georasterinfo("n39_w106_3arc_v2.dt1");
hDatum = info.Metadata.DTED_HorizontalDatum;
vDatum = info.Metadata.DTED_VerticalDatum;

Data Types: char | string | cell

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: addCustomTerrain(terrainName,files,Attribution="My attribution") specifies the attribution for the custom terrain.

NameExistsRule — Behavior when terrain name already exists

"overwrite" (default) | "preserve" | "error"

Since R2026b

Behavior when the terrain name already exists, specified as one of these options. The function applies this behavior when terrainName matches the name of a custom terrain already in the list.

• "overwrite" — Overwrite the existing terrain data. This option is useful when you want to change the terrain data that terrainName represents.

• "preserve" — Preserve the existing terrain data and do not add the new terrain data. This option is useful when you want to avoid overwriting terrain that already exists.

• "error" — Issue an error.

The addCustomTerrain function compares terrainName with the names of existing custom terrains. The comparison is case-insensitive. The function does not compare the data associated with the names.

When terrainName does not match the name of an existing custom terrain, the function adds new terrain, regardless of the value of NameExistsRule.

Attribution — Attribution of custom terrain data

character vector | string scalar

Attribution of custom terrain data, specified as a character vector or a string scalar. The attribution is displayed on the Site Viewer map. By default, the value is empty.

Data Types: char | string

FillMissing — Fill data of missing files with value 0

false (default) | true

Fill data of missing files with value 0, specified as true or false. Missing file values are required to complete a rectangular geographic region with the input files.

Data Types: logical

WriteLocation — Name of folder to write extracted terrain files to

character vector | string scalar

Name of folder to write extracted terrain files to, specified as a character vector or a string scalar. The folder must exist and have write permissions. By default, addCustomTerrain writes extracted terrain files to a temporary folder that it generates using the tempname function.

Data Types: char | string

Tips

• You can find and download DTED files by using EarthExplorer, a data portal provided by the US Geological Survey (USGS). From the list of data sets, search for DTED files by selecting Digital Elevation, SRTM, and then SRTM 1 Arc-Second Global and SRTM Void Filled.

Version History

Introduced in R2019b

R2026b: Control overwrite behavior when terrain name already exists

Control the overwrite behavior of the addCustomTerrain function by using the NameExistsRule name-value argument. When you specify the name of a custom terrain that already exists, the NameExistsRule argument determines whether the function overwrites the terrain data, preserves the existing terrain data, or issues an error.

R2026b: addCustomTerrain overwrites existing terrain data by default

By default, when you specify the name of a custom terrain that already exists, the addCustomTerrain function overwrites the existing terrain data. In previous releases, the function issues an error. Starting in R2026b, you can issue an error by specifying the NameExistsRule name-value argument as "error".