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 with a format such as GeoTIFF, Esri Binary Grid, GRIB, or DTED. The output argument R contains spatial referencing information for the array. For a full list of supported formats, see Supported Formats.

[A,R] = readgeoraster(___,Name=Value) specifies options using one or more name-value 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.

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

Read Band from GRIB File

Since R2023b

GRIB files often store data using multiple bands. If you do not know which bands to read, you can query the metadata stored in the GRIB file.

Read and display a band of data from a GRIB file. The file contains sea ice concentrations for multiple years [1][2], and each band of the file corresponds to a different year.

Get information about the GRIB file by creating a RasterInfo object. Get the metadata by accessing the Metadata property of the RasterInfo object.

info = georasterinfo("seaice.grib");
metadata = info.Metadata;

RasterInfo objects store GRIB metadata using a table, where each row of the table corresponds to a band of data in the file. Find the band that contains data for the year 2016.

yrs = year(metadata.ReferenceTime);
band = find(yrs == 2016);

Read data from the band by using the readgeoraster function. Convert the concentrations to percentages.

[A,R] = readgeoraster("seaice.grib",Bands=band);
A = A * 100;

Display the data as a surface on an axesm-based map. Change the colormap and add a labeled color bar.

figure
worldmap(A,R)
mlabel off
plabel off
geoshow(A,R,DisplayType="surface")

colormap abyss
c = colorbar;
c.Label.String = "Sea ice concentration (%)";

[1] Hersbach, H., B. Bell, P. Berrisford, G. Biavati, A. Horányi, J. Muñoz Sabater, J. Nicolas, et al. "ERA5 Hourly Data on Single Levels from 1940 to Present." Copernicus Climate Change Service (C3S) Climate Data Store (CDS), 2023. Accessed May 22, 2023. https://doi.org/10.24381/cds.adbb2d47.

[2] Neither the European Commission nor ECMWF is responsible for any use that may be made of the Copernicus information or data it contains.

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.

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.

Example: [A,R] = readgeoraster(filename,OutputType="double",Bands=1:2) specifies the data value for A and the bands to read.

OutputType — Data type for A

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

Data type for A, specified as a character vector or string scalar containing one of these values: "native", "single", "double", "int8" (since R2024b), "int16", "int32", "int64" (since R2024b), "uint8", "uint16", "uint32", "uint64" (since R2024b), or "logical".

The default for OutputType is "native". For most formats, "native" returns A using the native data type embedded in the file. For GRIB files, "native" returns A using the double data type.

Using a data type other than "native" can result in a loss of precision.

Data Types: char | string

Bands — Bands to read

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

Bands to read, specified as "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.

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.

StandardizeMissing — Standardize missing data

true or 1 (default) | false or 0

Since R2025a

Standardize missing data, specified as a numeric or logical 1 (true) or 0 (false).

• true — When the file specifies a missing data indicator, and the function creates A using the single or double data type, replace values that match the missing data indicator with NaN values. For more information about missing data indicators, see the MissingDataIndicator property of the RasterInfo object.

• false — Do not replace values that match the missing data indicator.

Before R2025a: When A is of type single or double, you can replace missing data by using the georasterinfo and standardizeMissing functions.

[A,R] = readgeoraster(filename,OutputType="double");
info = georasterinfo(filename);
m = info.MissingDataIndicator;
A = standardizeMissing(A,m);

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.

For most formats, the default data type of A matches the native data type embedded in filename. For GRIB files, the default data type of A is double. Specify a data type using the OutputType name-value argument.

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

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

The readgeoraster and georasterinfo functions support these file formats.

• GeoTIFF (.tif or .tiff)

• Esri Binary Grid (.adf)

• Esri ASCII Grid (.asc or .grd)

• Esri GridFloat (.flt)

• GRIB (.grb, .grib, .grib2) (since R2023b)

• DTED (.dt0, .dt1, or .dt2)

• SDTS (.DDF)

• USGS DEM (.dem)

• SRTM Height (.hgt)

• Vertical Mapper Numeric Grid (.grd)

• Vertical Mapper Classified Grid (.grc)

• ER Mapper ERS (.ers)

• ENVI (.dat)

• ERDAS IMAGINE (.img)

• Geospatially referenced JPEG 2000 (.jp2) (since R2023b)

The extension of a file does not always indicate its file format. If you do not know the format of your file, ask your data provider. In some cases, you can read files in supported formats when they have no extensions or have extensions other than the ones listed.

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

• 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

R2025a: Automatically standardize missing data

Raster data sets sometimes indicate missing data values using a large number called a missing data indicator. When the readgeoraster function creates A using the single or double data type, the function replaces values that match the missing data indicator with NaN values. In previous releases, the function did not replace the missing data.

As a result of this change, you might need to update your code.

• In cases where you find and replace the missing data by using the georasterinfo and standardizeMissing functions, removing the code is optional. To update your code, remove uses of the georasterinfo and standardizeMissing functions. This table shows an optional replacement strategy.

  Original Code	Updated Code
  [A,R] = readgeoraster(filename,OutputType="double"); info = georasterinfo(filename); m = info.MissingDataIndicator; A = standardizeMissing(A,m);	[A,R] = readgeoraster(filename,OutputType="double");

• In cases where you find and replace the missing data by using functions such as min or max, you must update your code. Otherwise, your code might overwrite valid data. To update your code, remove the calculations that find and replace the missing data. This table shows some common code patterns and replacement strategies.

  Original Code	Updated Code
  [A,R] = readgeoraster(filename,OutputType="double"); m = min(A,[],"all"); A(A == m) = NaN;	[A,R] = readgeoraster(filename,OutputType="double");
  [A,R] = readgeoraster(filename,OutputType="double"); m = max(A,[],"all"); A = standardizeMissing(A,m);	[A,R] = readgeoraster(filename,OutputType="double");

You can prevent readgeoraster from replacing the missing data by specifying the StandardizeMissing name-value argument as false.

R2024b: Read compressed GRIB files

The readgeoraster function can read GRIB files that use Consultative Committee for Space Data Systems (CCSDS) compression, as defined by CCSDS recommended standard 121.0-B-3.

R2024b: Read data using int8, int64, and uint64 data types

The readgeoraster function supports the int8, int64, and uint64 data types.

R2023b: Read data from GRIB files

The readgeoraster function can read data from files in GRIB format (.grb, .grib, .grib2).

R2023b: Read geospatial data from JPEG 2000 files

The readgeoraster function can read geospatial data from files in JPEG 2000 format (.jp2).

R2023b: Improved performance when reading data with multiple bands

The readgeoraster function shows improved performance when reading data with multiple bands.

For example, this code creates a GeoTIFF file with 225 bands and then reads the file using the readgeoraster function. The code that reads the file is about 55 times faster than in the previous release.

function timingTest
    % Create a GeoTIFF file
    A1 = ones(180,360,225,"uint8");
    R1 = georefcells([-90 90],[-180 180],size(A1));
    geotiffwrite("mytif.tif",A1,R1)

    tic
    [A2,R2] = readgeoraster("mytif.tif");
    toc

    delete mytif.tif
end

The approximate execution times are:

• R2023b: 0.062 s

• R2023a: 3.43 s

This code was timed on a Windows^® 10 Intel^® Xeon^® CPU W-2133 @ 3.6 GHz test system, by calling the function timingTest.

R2021b: Read SRTM Height data

The readgeoraster function can read SRTM Height data files with extension .hgt.

R2021a: Read data in Vertical Mapper Grid formats

The readgeoraster function can read data in the Vertical Mapper Numeric Grid and Vertical Mapper Classified Grid formats.