geotiffread

(Not recommended) Read GeoTIFF file

geotiffread is not recommended, except when reading a GeoTIFF file from a URL or when reading multiple images from the same file. In other situations, use readgeoraster instead. For more information, see Version History.

Syntax

[A,R] = geotiffread(filename)

[X,cmap,R] = geotiffread(filename)

[A,refmat,bbox] = geotiffread(filename)

[X,cmap,refmat,bbox] = geotiffread(filename)

[___] = geotiffread(url)

[___] = geotiffread(___,idx)

Description

[A,R] = geotiffread(filename) reads a georeferenced grayscale, RGB, or multispectral image or data grid from the GeoTIFF file specified by filename into A and creates a spatial referencing object, R.

[X,cmap,R] = geotiffread(filename) reads an indexed image into X and the associated colormap into cmap, and creates a spatial referencing object, R.

[A,refmat,bbox] = geotiffread(filename) reads a georeferenced grayscale, RGB, or multispectral image or data grid into A, the corresponding referencing matrix into refmat, and the bounding box into bbox.

[X,cmap,refmat,bbox] = geotiffread(filename) reads an indexed image into X, the associated colormap into cmap, the referencing matrix into refmat, and the bounding box into bbox. The referencing matrix must be unambiguously defined by the GeoTIFF file, otherwise it and the bounding box are returned empty.

[___] = geotiffread(url) reads the GeoTIFF image from a URL.

[___] = geotiffread(___,idx) reads one image from a multi-image GeoTIFF file or URL.

Examples

Read and Display Image from GeoTIFF File

Read a GeoTIFF file into the workspace as an array and a map cells reference object.

[boston,R] = geotiffread("boston.tif");

Display the image using the mapshow function.

figure
mapshow(boston,R)
axis image off

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

Input Arguments

filename — Name of GeoTIFF file

character vector | string scalar

Name of the GeoTIFF file, specified as a string scalar or character vector. Include the folder name in filename or place the file in the current folder or in a folder on the MATLAB^® path. If the named file includes the extension .TIF or .TIFF (either upper- or lowercase), you can omit the extension from filename.

idx — Index of image in GeoTIFF file

1 (default) | positive integer

Index of image in GeoTIFF file, specified as a positive integer. For example, if idx is 3, geotiffread reads the third image in the file. By default, idx indexes to the first image in the file.

url — Internet URL

character vector | scalar string

Internet URL, specified as a string scalar or character vector. The URL must include the protocol type (e.g., "https://").

Output Arguments

A — Georeferenced image or data grid

M-by-N numeric matrix | M-by-N-by-P numeric array

Georeferenced image or data grid, returned as one of the following:

• An M-by-N numeric matrix when the file contains a grayscale image or data grid

• An M-by-N-by-P numeric array when the file contains a color image, multispectral image, hyperspectral image, or data grid

The class of A depends on the storage class of the pixel data in the file, which is related to the BitsPerSample property as returned by the imfinfo function.

R — Spatial referencing object

geographic raster reference object | map raster reference object

Spatial referencing object, returned as one of the following.

• A geographic raster reference object of type GeographicCellsReference or GeographicPostingsReference. This object is returned when the image or data grid is referenced to a geographic coordinate system.

• A map raster reference object of type MapCellsReference or MapPostingsReference. This object is returned when the image or data grid is referenced to a projected coordinate system.

X — Indexed image

M-by-N numeric matrix

Indexed image, returned as an M-by-N numeric matrix.

cmap — Color map

c-by-3 numeric matrix

Color map associated with indexed image X, specified as an c-by-3 numeric matrix. There are c colors in the color map, each represented by a red, green, and blue pixel value. Colormap values are rescaled into the range [0,1].

refmat — Referencing matrix

3-by-2 numeric matrix | []

Referencing matrix, returned as 3-by-2 numeric matrix that transforms raster row and column indices to or from geographic coordinates according to:

[lon lat] = [row col 1] * refmat

refmat defines a (non-rotational, non-skewed) relationship in which each column of the data grid falls along a meridian and each row falls along a parallel. refmat must be unambiguously defined by the GeoTIFF file, otherwise it and the bounding box, bbox, are returned empty.

Data Types: double

bbox — Bounding box

2-by-2 numeric matrix | []

Bounding box, returned as a 2-by-2 numeric matrix that specifies the minimum (row 1) and maximum (row 2) values for each dimension of the image data in the GeoTIFF file. bbox is returned empty if refmat is ambiguously defined by the GeoTIFF file.

Data Types: double

Tips

• geotiffread imports pixel data using the TIFF-reading capabilities of the MATLAB function imread and likewise shares any limitations of imread. Consult the imread documentation for information on TIFF image support.

Version History

Introduced before R2006a

R2020a: geotiffread is not recommended

geotiffread is not recommended, except when reading a GeoTIFF file from a URL or when reading multiple images from the same file. In other situations, use readgeoraster instead. There are no plans to remove geotiffread.

Unlike geotiffread, which returns a referencing matrix in some cases, the readgeoraster function returns a raster reference object. Reference objects have several advantages over referencing matrices.

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

• You can manipulate the limits of rasters associated with reference objects using the geocrop or mapcrop functions.

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

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

Not Recommended	Recommended
[A,R] = geotiffread(filename);	[A,R] = readgeoraster(filename);
[X,cmap,R] = geotiffread(filename);	[X,R,cmap] = readgeoraster(filename);
[A,refmat,bbox] = geotiffread(filename);	[A,R] = readgeoraster(filename); xlimits = R.XWorldLimits; ylimits = R.YWorldLimits; bbox = [xlimits' ylimits'];