Main Content

gtopo30

(To be removed) Read 30-arc-second global digital elevation data (GTOPO30)

gtopo30 will be removed in a future release. Use readgeoraster instead. For more information, see Compatibility Considerations.

Syntax

[Z,refvec] = gtopo30(tilename)
[Z,refvec] = gtopo30(tilename,samplefactor)
[Z,refvec] = gtopo30(tilename,samplefactor,latlim,lonlim)
[Z,refvec] = gtopo30(foldername, ...)

Description

[Z,refvec] = gtopo30(tilename) reads the GTOPO30 tile specified by tilename and returns the result as a regular data grid. tilename is a string scalar or character vector which does not include an extension and indicates a GTOPO30 tile in the current folder or on the MATLAB® path. If tilename is empty or omitted, a file browser will open for interactive selection of the GTOPO30 header file. The data is returned at full resolution with the latitude and longitude limits determined from the GTOPO30 tile. The data grid, Z, is returned as an array of elevations. Elevations are given in meters above mean sea level using WGS84 as a horizontal datum. refvec is the associated referencing vector.

[Z,refvec] = gtopo30(tilename,samplefactor) reads a subset of the elevation data from tilename. samplefactor is a scalar integer, which when equal to 1 reads the data at its full resolution. When samplefactor is an integer n greater than one, every nth point is read. If samplefactor is omitted or empty, it defaults to 1.

[Z,refvec] = gtopo30(tilename,samplefactor,latlim,lonlim) reads a subset of the elevation data from tilename using the latitude and longitude limits latlim and lonlim specified in degrees. latlim is a two-element vector of the form:

[southern_limit northern_limit]

Likewise, lonlim has the form:

[western_limit eastern_limit]

If latlim and lonlim are omitted, the coordinate limits are determined from the file. The latitude and longitude limits are snapped outward to define the smallest possible rectangular grid of GTOPO30 cells that fully encloses the area defined by the input limits. Any cells in this grid that fall outside the extent of the tile are filled with NaN.

[Z,refvec] = gtopo30(foldername, ...) is similar to the syntaxes above except that GTOPO30 data are read and concatenated from multiple tiles within a GTOPO30 CD-ROM or folder structure. The foldername input is a string scalar or character vector with the name of the folder which contains the GTOPO30 tile folders or GTOPO30 tiles. Within the tile folders are the uncompressed data files. The foldername for CD-ROMs distributed by the USGS is the device name of the CD-ROM drive. As with the case with a single tile, any cells in the grid specified by latlim and lonlim are NaN filled if they are not covered by a tile within foldername. samplefactor if omitted or empty defaults to 1. latlim if omitted or empty defaults to [-90 90]. lonlim if omitted or empty defaults to [-180 180].

Examples

collapse all

To run this example, you must download the GTOPO30 data set.

Extract and display full resolution data for the state of Massachusetts. Read the state line polygon boundary and calculate boundary limits.

Massachusetts = shaperead('usastatehi','UseGeoCoords',true, ...
  'Selector',{@(name) strcmpi(name,'Massachusetts'),'Name'});
latlim = [min(Massachusetts.Lat(:)) max(Massachusetts.Lat(:))];
lonlim = [min(Massachusetts.Lon(:)) max(Massachusetts.Lon(:))];

Read the GTOPO30 data at full resolution.

[Z,refvec] = gtopo30('W100N90',1,latlim,lonlim);

Display the data grid and overlay the state line boundary.

figure
ax = usamap(Z,refvec);
ax.SortMethod = 'ChildOrder';
geoshow(Z,refvec,'DisplayType','surface')
demcmap(Z)
geoshow(Massachusetts,'DisplayType','polygon',...
  'facecolor','none','edgecolor','y')

Topographic map showing the state boundary of Massachusetts

Version History

Introduced before R2006a

expand all

R2021b: Warns

Raster reading functions that return referencing vectors issue a warning that they will be removed in a future release, including gtopo30. Instead, use readgeoraster, which returns a raster reference object. Reference objects have several advantages over referencing vectors.

  • Unlike referencing vectors, reference objects have properties that document the size of the associated raster, its geographic limits, and the direction of its rows and columns. For examples of reference object properties, see GeographicCellsReference and GeographicPostingsReference.

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

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

  • Most functions that accept referencing vectors as input also accept reference objects.

This table shows some typical usages of gtopo30 and how to update your code to use readgeoraster instead. Unlike gtopo30, the readgeoraster function requires you to specify a file extension. For example, use [Z,R] = readgeoraster('W100N90.dem').

Will Be RemovedRecommended
[Z,refvec] = gtopo30(filename);
[Z,R] = readgeoraster(filename);
[Z,refvec] = gtopo30(filename,samplefactor);
[Z,R] = readgeoraster(filename);
[Z,R] = georesize(Z,R,1/samplefactor);
[Z,refvec] = gtopo30(filename,samplefactor,latlim,lonlim);
[Z,R] = readgeoraster(filename);
[Z,R] = geocrop(Z,R,latlim,lonlim);
[Z,R] = georesize(Z,R,1/scalefactor);

The readgeoraster function returns data using the native data type embedded in the file. Return a data using a different data type by specifying the 'OutputType' name-value pair. For example, use [Z,R] = readgeoraster(filename,'OutputType','double').

The readgeoraster function does not automatically replace missing data with NaN values. If your data set uses large negative numbers to indicate missing data, you can replace them with NaN values using the standardizeMissing function.

[Z,R] = readgeoraster('MtWashington-ft.grd');
info = georasterinfo('MtWashington-ft.grd');
m = info.MissingDataIndicator;
Z = standardizeMissing(Z,m);

Reading and merging multiple GTOPO30 tiles from a folder using the readgeoraster function is not supported. To read and merge multiple GTOPO30 tiles from a folder:

  1. Find the standard names of the GTOPO30 tiles required to cover a region by using the gtopo30s function.

  2. Read the individual tiles by using the readgeoraster function

  3. Starting in R2024a, merge the tiles by using the mergetiles function. Before R2024a, merge the tiles by using the workflow in Merge Spatially Referenced Raster Tiles.

Alternatively, you can read and merge multiple GTOPO30 tiles from a folder by using a custom datastore. For more information about using custom datastores to read and merge multiple tiles, see Merge Multiple Raster Tiles Using Datastore.