readgeoraster
Syntax
Description
[
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 A
,R
] = readgeoraster(filename
)R
contains spatial referencing information for the array. For a full list of supported
formats, see Supported Formats.
[
specifies options using one or more name-value arguments.A
,R
] = readgeoraster(___,Name,Value
)
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.
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);
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. Replace missing data with NaN
values by using the standardizeMissing
function. Then, convert the concentrations to percentages.
[A,R] = readgeoraster("seaice.grib",Bands=band);
m = info.MissingDataIndicator;
A = standardizeMissing(A,m);
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.
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 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.
Example: 'OutputType','double'
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.
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'
– ReturnsR
as a raster reference object determined by the contents of the file.'geographic'
– ReturnsR
as a geographic cells or postings reference object.'planar'
– ReturnsR
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.
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, thenR
is aGeographicCellsReference
object orGeographicPostingsReference
object.If the data in
filename
is referenced to a projected coordinate system, thenR
is aMapCellsReference
object orMapPostingsReference
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
ordouble
, such as thegeoshow
function for displaying surfaces. To use the output ofreadgeoraster
with these functions, specify the output type as'single'
or'double'
using theOutputType
name-value argument.Regardless of the file format, the array returned by
readgeoraster
has columns starting from north and theColumnsStartFrom
property of the reference object has a value of'north'
.
Version History
Introduced in R2020aR2024b: 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.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)