readgeoraster

Read geospatial raster data file

Syntax

[A,R] = readgeoraster(filename)

[A,R] = readgeoraster(___,Name,Value)

[___,cmap] = readgeoraster(___)

Description

[A,R] = readgeoraster(filename) creates an array by reading geographic or projected raster data from a file. The output argument R contains spatial referencing information for the array. Supported file formats include Esri Binary Grid, Esri GridFloat, GeoTIFF, and DTED. For a full list of supported formats, see Supported Formats and Extensions.

[A,R] = readgeoraster(___,Name,Value) specifies options using one or more Name,Value pair arguments.

[___,cmap] = readgeoraster(___) also returns the colormap of A.

Examples

Read and Display GeoTIFF Image

Read a GeoTIFF image of Boston as an array and a map cells reference object. The array is of size 2881-by-4481-by-3 and specifies the red, green, and blue components of the image. Display the image using the mapshow function.

[A,R] = readgeoraster('boston.tif');
mapshow(A,R)

The data used in this example includes material copyrighted by GeoEye, all rights reserved.

Read and Display Land Cover Classification

Read and display a land cover classification of Oahu, Hawaii.

First, read the land cover data as an array, a map cells reference object, and a colormap. The elements of A index into the colormap. Each row of the colormap specifies the red, green, and blue components of a single color. Then, display the land cover data.

[A,R,cmap] = readgeoraster('oahu_landcover.img');
mapshow(A,cmap,R)

The data used in this example is courtesy of the National Oceanic and Atmospheric Administration (NOAA).

Read and Display Elevation Data

Read and display elevation data for an area around South Boulder Peak in Colorado.

First, read the elevation data as an array and a geographic postings reference object. To display the data as a surface, the geoshow function requires data of type double or single. In this case, preserve precision by specifying the output type as 'double'.

[A,R] = readgeoraster('n39_w106_3arc_v2.dt1','OutputType','double');

Create a map. First, create map axes by specifying the latitude and longitude limits of the data. Then, display the data as a surface using the geoshow function. Apply a colormap appropriate for elevation data using the demcmap function.

latlim = R.LatitudeLimits;
lonlim = R.LongitudeLimits;
usamap(latlim,lonlim)
geoshow(A,R,'DisplayType','surface')
demcmap(A)

The elevation data used in this example is courtesy of the US Geological Survey.

Replace Missing Data with NaN Values

Raster data sets sometimes indicate missing data values using a large negative number. Import raster data, find the missing data indicator, and then replace missing data with NaN values.

Import raster data and a reference object using the readgeoraster function. Find the missing data indicator using the georasterinfo function.

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

m = -32766

Verify the raster data contains missing data using the ismember function. The ismember function returns logical 1 (true) if the raster contains the missing data indicator.

ismember(m,A)

ans = logical
   1

Replace the missing data with NaN values using the standardizeMissing function.

A = standardizeMissing(A,m);

Input Arguments

filename — Name of file to read

character vector | string scalar

Name of the file to read, specified as a character vector or string scalar. The form of filename depends on the location of your 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.dem'.

• 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.tif' or 'dataDir\myFile.dat'.

For a list of supported file formats, see Supported Formats and Extensions.

Data Types: char | string

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.

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

Example: 'OutputType','double','Bands',1:2

OutputType — Data type for A

'native' (default) | 'single' | 'double' | 'int32' | ...

Data type for A, specified as the comma-separated pair consisting of 'OutputType' and a character vector or string scalar containing one of these values: 'native', 'single', 'double', 'int16', 'int32', 'int64', 'uint8', 'uint16', 'uint32', 'uint64', or 'logical'.

The default for 'OutputType' is 'native', which returns A using the native data type embedded in filename. Using a data type other than 'native' may result in a loss of precision.

Example: 'OutputType','double'

Data Types: char | string

Bands — Bands to read

'all' (default) | positive integer | vector of positive integers

Bands to read, specified as the comma-separated pair consisting of 'Bands' and 'all', a positive integer, or a vector of positive integers. For example, if you specify the value 3, readgeoraster reads the third band in the file. Bands are returned in the specified order.

The default for 'Bands' is 'all', where readgeoraster reads all bands in the file.

Example: 'Bands',3

CoordinateSystemType — Coordinate system type for R

'auto' (default) | 'geographic' | 'planar'

Coordinate system type for R, specified as one of these values:

• 'auto' – Returns R as a raster reference object determined by the contents of the file.

• 'geographic' – Returns R as a geographic cells or postings reference object.

• 'planar' – Returns R as a map cells or postings reference object.

Specify the coordinate system type when your data does not contain projection information.

Example: 'CoordinateSystemType','geographic'

Output Arguments

A — Georeferenced image or data grid

numeric array

Georeferenced image or data grid, returned as an M-by-N or M-by-N-by-P numeric array.

By default, the data type of A matches the native data type embedded in filename. Specify a data type using the 'OutputType' name-value pair.

Regardless of how the data is encoded, the first row of A represents the northernmost data, and the last row of A represents the southernmost data.

R — Spatial reference

GeographicCellsReference object | GeographicPostingsReference object | MapCellsReference object | MapPostingsReference object

Spatial reference for A, returned as a GeographicCellsReference object, GeographicPostingsReference object, MapCellsReference object, or MapPostingsReference object. The value of R depends on the data in filename:

• If the data in filename is referenced to a geographic coordinate system, then R is a GeographicCellsReference object or GeographicPostingsReference object.

• If the data in filename is referenced to a projected coordinate system, then R is a MapCellsReference object or MapPostingsReference object.

If the file does not contain enough information to determine whether the data is projected or geographic, then R is a MapCellsReference or MapPostingsReference object. If a file contains no valid spatial reference information, then R is empty. You can specify the spatial reference as 'geographic' or 'planar' using the 'CoordinateSystemType' name-value pair.

cmap — Colormap

n-by-3 matrix

Colormap associated with an indexed image, returned as a n-by-3 numeric matrix with values in the range [0,1]. Each row of cmap is a three-element RGB triplet that specifies the red, green, and blue components of a single color in the colormap. The value of cmap is empty unless A is an indexed image.

More About

Supported Formats and Extensions

The readgeoraster and georasterinfo functions support these file formats and extensions. In some cases, you can read supported file formats using extensions other than the ones listed.

File Format	Extension
GeoTIFF	.tif or .tiff
Esri Binary Grid	.adf
Esri ASCII Grid	.asc or .grd
Esri GridFloat	.flt
DTED	.dt0, .dt1, or .dt2
SDTS	.DDF
USGS DEM	.dem
ER Mapper ERS	.ers
ENVI	.dat
ERDAS IMAGINE	.img
Vertical Mapper Numeric Grid	.grd
Vertical Mapper Classified Grid	.grc
SRTM Height	.hgt

Some file formats consist of a data file and multiple supporting files. For example, Esri GridFloat files may have supporting header files (.hdr). When you read a data file with supporting files using readgeoraster or georasterinfo, specify the extension of the data file.

File formats may be referred to using different names. For example, the Esri GridFloat format may also be referred to as Esri .hdr Labelled or ITT ESRI .hdr RAW Raster. The Esri Binary Grid format may also be referred to as ArcGrid Binary, Esri ArcGIS Binary Grid, or Esri ArcInfo Grid.

Tips

• Some functions require input arguments of type single or double, such as the geoshow function for displaying surfaces. To use the output of readgeoraster with these functions, specify the output type as 'single' or 'double' using the 'OutputType' name-value pair.

• Regardless of the file format, the array returned by readgeoraster has columns starting from north and the ColumnsStartFrom property of the reference object has a value of 'north'.

Version History

Introduced in R2020a