geotiffwrite

Write GeoTIFF file

Syntax

geotiffwrite(filename,A,R)

geotiffwrite(filename,X,cmap,R)

geotiffwrite(___,Name=Value)

Description

geotiffwrite(filename,A,R) writes the georeferenced image or data grid A, with raster reference R, to the file filename.

geotiffwrite(filename,X,cmap,R) writes the indexed image X, with colormap cmap and raster reference R, to filename.

geotiffwrite(___,Name=Value) specifies options using one or more name-value arguments.

Examples

Write Image from JPEG File to GeoTIFF File

Read a JPEG image of Boston [1] into the workspace as an array.

jpgFilename = "boston_ovr.jpg";
RGB = imread(jpgFilename);

The image is referenced by a world file. Derive the name of the world file from the name of the image file. Then, read the world file into the workspace as a raster reference object.

worldfile = getworldfilename(jpgFilename);
R = worldfileread(worldfile,"geographic",size(RGB));

Write the image and the reference object to a GeoTIFF file.

tifFilename = "boston_ovr.tif";
geotiffwrite(tifFilename,RGB,R)

Read the GeoTIFF file into the workspace as an array and a reference object. Display the image on a map.

[RGB2,R2] = readgeoraster(tifFilename);

figure
geoimage(RGB2,R2)
geobasemap none

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

Convert Classic TIFF to Tiled BigTIFF

Convert a georeferenced classic TIFF file to a tiled BigTIFF file by extracting information from the classic TIFF file. First, import a classic TIFF image of Boston and a map cells reference object. Get metadata from the file using geotiffinfo.

infilename = "boston.tif";
[A,R] = readgeoraster(infilename);
info = geotiffinfo(infilename);

Specify tags to include in the tiled BigTIFF file. To do this, extract the GeoKey directory tag from the metadata. Then, create tags specifying the length and width of the tiles.

geoTags = info.GeoTIFFTags.GeoKeyDirectoryTag;
tiffTags = struct(TileLength=1024,TileWidth=1024);

Write the data to a new GeoTIFF file. Specify the file format as BigTIFF using the TiffType argument. Include tags by specifying the GeoKeyDirectoryTag and TiffTags arguments.

outfilename = "boston_bigtiff.tif";
geotiffwrite(outfilename,A,R,TiffType="bigtiff", ...
    GeoKeyDirectoryTag=geoTags,TiffTags=tiffTags)

Verify you have written the BigTIFF file by reading the file and querying the tags.

biginfo = geotiffinfo(outfilename);
biginfo.GeoTIFFTags.GeoKeyDirectoryTag

ans = struct with fields:
        GTModelTypeGeoKey: 1
       GTRasterTypeGeoKey: 1
    ProjectedCSTypeGeoKey: 26986
        PCSCitationGeoKey: 'State Plane Zone 2001 NAD = 83'
    ProjLinearUnitsGeoKey: 9003

t = Tiff(outfilename);
getTag(t,"TileLength")

ans = 1024

getTag(t,"TileWidth")

ans = 1024

close(t)

Write WMS Data to GeoTIFF File

Search the WMS Database for a Blue Marble layer from EOX::Maps. For more information about EOX::Maps, see EOX::Maps.

layer = wmsfind("tiles.maps.eox.at",SearchFields="serverurl");
layer = refine(layer,"bluemarble",MatchType="exact");

Read the layer into the workspace as an array and a raster reference object.

[A,R] = wmsread(layer);

Write the data to a GeoTIFF file.

geotiffwrite("bluemarble.tif",A,R)

Read the GeoTIFF file into the workspace as an array and a reference object. Display the image on a map.

figure
newmap
geoimage(A,R)

Add an attribution to the map using a text box annotation.

annotation("textbox",[0.52 0.05 0.47 0.1],EdgeColor="none", ...
    String="Blue Marble © NASA's Earth Observatory", ...
    VerticalAlignment="middle")

Write Merged Image to GeoTIFF File

Read two adjacent orthophotos. Create reference objects for the orthophotos by reading their world files.

X_west = imread("concord_ortho_w.tif");
X_east = imread("concord_ortho_e.tif");

R_west = worldfileread("concord_ortho_w.tfw","planar",size(X_west));
R_east = worldfileread("concord_ortho_e.tfw","planar",size(X_east));

Merge the orthophotos.

[X,R] = mergetiles(X_west,R_west,X_east,R_east);

Write the merged image to a GeoTIFF file. Use the code number 26986, which indicates the NAD83 / Massachusetts Mainland projected coordinate reference system (CRS).

tifFilename = "concord_ortho.tif";
coordRefSysCode = 26986;
geotiffwrite(tifFilename,X,R,CoordRefSysCode=coordRefSysCode);

Read the GeoTIFF file into the workspace as an array and a reference object. Set up a new map using the projected CRS that is stored in the reference object. Then, display the image on the map.

[X2,R2] = readgeoraster(tifFilename);

figure
pcrs = R2.ProjectedCRS;
newmap(pcrs)
geoimage(X2,R2)

Write Subset of GeoTIFF File to New GeoTIFF File

Read a GeoTIFF image of Boston [1] into the workspace as an array and a raster reference object.

[A,RA] = readgeoraster("boston.tif");

Crop the data to the xy-limits specified by xlimits and ylimits.

xlimits = [764318 767678];
ylimits = [2951122 2954482];
[B,RB] = mapcrop(A,RA,xlimits,ylimits);

Read information about the GeoTIFF image into the workspace as a structure array. Extract the GeoKey directory tag from the structure array.

info = geotiffinfo("boston.tif");
key = info.GeoTIFFTags.GeoKeyDirectoryTag;

Write the cropped data and GeoKey directory tag to a new GeoTIFF file.

geotiffwrite("boston_subimage.tif",B,RB,GeoKeyDirectoryTag=key)

Read the new GeoTIFF file into the workspace as an array and a reference object. Set up a new map using the projected CRS that is stored in the reference object. Then, display the image on the map.

[B2,RB2] = readgeoraster("boston_subimage.tif");

figure
pcrs = RB2.ProjectedCRS;
newmap(pcrs)
geoimage(B2,RB2)

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

Write Elevation Data to GeoTIFF File

Write elevation data for an area around South Boulder Peak in Colorado to a GeoTIFF file.

Read the elevation data [1] into the workspace as a matrix and a raster reference object.

[Z,R] = readgeoraster("n39_w106_3arc_v2.dt1");

Specify a GeoKey directory tag for the GeoTIFF file using a structure array. For a list of keys that you can specify, see Key ID Summary in the GeoTIFF specification.

• Indicate that the data uses geographic coordinates by specifying the GTModelTypeGeoKey field as 2.

• Indicate that the data is a grid of posting point samples (rather than a grid of cells) by specifying the GTRasterTypeGeoKey field as 2.

• Indicate the geographic CRS for the data by specifying the GeographicTypeGeoKey field as 4326.

key.GTModelTypeGeoKey = 2;
key.GTRasterTypeGeoKey = 2;
key.GeographicTypeGeoKey = 4326;

Write the data and the GeoKey directory tag to a file.

filename = "southboulder.tif";
geotiffwrite(filename,Z,R,GeoKeyDirectoryTag=key)

Read the GeoTIFF file into the workspace as a matrix and a reference object. Then, display the data on a map. Apply a colormap that is appropriate for elevation data.

[Z2,R2] = readgeoraster(filename);

figure
geopcolor(Z2,R2)
demcmap(Z2)
geobasemap none

[1] The elevation data used in this example is from the US Geological Survey.

Write TIFF File Containing RPC Metadata

Create a sample TIFF file with RPC metadata. To do this, create an array of zeros and an associated reference object.

A = zeros(180,360);
latlim = [-90 90];
lonlim = [-180 180];
RA = georefcells(latlim,lonlim,size(A));

Then, create an RPCCoefficientTag metadata object and set some fields with typical values. The RPCCoefficientTag object represents RPC metadata in a readable form.

rpctag = map.geotiff.RPCCoefficientTag;
rpctag.LineOffset = 1;
rpctag.SampleOffset = 1;
rpctag.LineScale = 2;
rpctag.SampleScale = 2;
rpctag.GeodeticHeightScale = 500;

Write the image, the associated referencing object, and the RPCCoefficientTag object to a file.

geotiffwrite("myfile.tif",A,RA,RPCCoefficientTag=rpctag)

Write Raw RPC Coefficient Metadata to GeoTIFF File

This example shows how to write RPC coefficient metadata to a TIFF file. In a real workflow, you would create the RPC coefficient metadata according to the TIFF extension specification. This example does not show the specifics of how to create valid RPC metadata. To simulate raw RPC metadata, the example creates a sample TIFF file with RPC metadata and then uses imfinfo to read this RPC metadata in raw, unprocessed form from the file. The example then writes this raw RPC metadata to a file using the geotiffwrite function.

Create Raw RPC Coefficient Metadata

To simulate raw RPC metadata, create a simple test file and write some RPC metadata to the file. For this test file, create a toy image and a referencing object associated with the image.

myimage = zeros(180,360);
latlim = [-90 90];
lonlim = [-180 180];
R = georefcells(latlim,lonlim,size(myimage));

Create an RPCCoefficientTag metadata object and set some of the fields. The toolbox uses the RPCCoefficientTag object to represent RPC metadata in human readable form.

rpctag = map.geotiff.RPCCoefficientTag;
rpctag.LineOffset = 1;
rpctag.SampleOffset = 1;
rpctag.LineScale = 2;
rpctag.SampleScale = 2;
rpctag.GeodeticHeightScale = 500;

Write the image, the associated referencing object, and the RPCCoefficientTag object to a file.

geotiffwrite("myfile.tif",myimage,R,RPCCoefficientTag=rpctag)

Read Raw RPC Coefficient Metadata

Read the RPC coefficient metadata from the test file using the imfinfo function. When it encounters unfamiliar metadata, imfinfo returns the data, unprocessed, in the UnknownTags field. Note that the UnknownTags field contains an array of 92 doubles. This is the raw RPC coefficient metadata, read from the file in unprocessed form.

info = imfinfo("myfile.tif");
info.UnknownTags

ans = struct with fields:
        ID: 50844
    Offset: 10680
     Value: [-1 -1 1 1 0 0 0 2 2 1 1 500 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]

Write Raw RPC Metadata to a File

Write the raw RPC metadata to a file. First, extract the RPC coefficient metadata from the info structure.

value = info.UnknownTags.Value;

Then, construct an RPCCoefficientTag object, passing the raw RPC metadata (array of 92 doubles) as an argument.

rpcdata = map.geotiff.RPCCoefficientTag(value) 

rpcdata = 
  RPCCoefficientTag with properties:

                BiasErrorInMeters: -1
              RandomErrorInMeters: -1
                       LineOffset: 1
                     SampleOffset: 1
           GeodeticLatitudeOffset: 0
          GeodeticLongitudeOffset: 0
             GeodeticHeightOffset: 0
                        LineScale: 2
                      SampleScale: 2
            GeodeticLatitudeScale: 1
           GeodeticLongitudeScale: 1
              GeodeticHeightScale: 500
        LineNumeratorCoefficients: [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
      LineDenominatorCoefficients: [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
      SampleNumeratorCoefficients: [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
    SampleDenominatorCoefficients: [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]

Pass the RPCCoefficientTag object to the geotiffwrite function and write the RPC metadata to a file.

geotiffwrite("myfile2.tif",myimage,R,RPCCoefficientTag=rpcdata)

To verify that the data was written to the file, read the RPC metadata from the TIFF file using geotiffinfo. Compare the returned RPC metadata with the metadata written to the test file.

ginfo = geotiffinfo("myfile2.tif");
ginfo.GeoTIFFTags.RPCCoefficientTag

ans = 
  RPCCoefficientTag with properties:

                BiasErrorInMeters: -1
              RandomErrorInMeters: -1
                       LineOffset: 1
                     SampleOffset: 1
           GeodeticLatitudeOffset: 0
          GeodeticLongitudeOffset: 0
             GeodeticHeightOffset: 0
                        LineScale: 2
                      SampleScale: 2
            GeodeticLatitudeScale: 1
           GeodeticLongitudeScale: 1
              GeodeticHeightScale: 500
        LineNumeratorCoefficients: [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
      LineDenominatorCoefficients: [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
      SampleNumeratorCoefficients: [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
    SampleDenominatorCoefficients: [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]

Input Arguments

filename — Name and location of output file

character vector | string scalar

Name and location of output file, specified as a string scalar or character vector. If filename includes an extension, it must be .tif or .TIF. If the size of the input A is at least 160-by-160, then the output file is a tiled GeoTIFF file. Otherwise, geotiffwrite organizes the output file as rows-per-strip.

Data Types: char | string

A — Georeferenced image or data grid

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

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

• An M-by-N numeric matrix representing a grayscale image or data grid

• An M-by-N-by-P numeric array representing a color image, multispectral image, hyperspectral image, or data grid

The coordinates of A are geographic and in the WGS 84 coordinate system, unless you indicate a different coordinate system by specifying the GeoKeyDirectoryTag or CoordRefSysCode argument.

Data Types: double | single | uint8 | uint16 | uint32 | int8 | int16 | int32 | logical

R — Raster reference for A or X

GeographicCellsReference object | GeographicPostingsReference object | MapCellsReference object | MapPostingsReference object

Raster reference for A or X, specified as a GeographicCellsReference, GeographicPostingsReference, MapCellsReference, or MapPostingsReference object.

If you are working with image coordinates in a projected coordinate system and R is a map raster reference object, specify the GeoKeyDirectoryTag or CoordRefSysCode argument accordingly.

The geotiffwrite function does not use information contained in the GeographicCRS property of geographic raster reference objects or the ProjectedCRS property of map raster reference objects.

X — Indexed image

M-by-N numeric matrix

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

Data Types: uint8 | uint16

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.

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: geotiffwrite(filename,A,R,CoordRefSysCode=26986) specifies a coordinate reference system code for the coordinates.

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

Example: geotiffwrite(filename,A,R,"CoordRefSysCode",26986) specifies a coordinate reference system code for the coordinates.

CoordRefSysCode — Coordinate reference system code

4326 (default) | positive integer | string scalar | character vector

Coordinate reference system code for the coordinates of the data, specified as a positive integer, a string scalar, or a character vector. You can specify coordinates in either a geographic or a projected coordinate system. If you specify the coordinate system with a string scalar or character vector, include the "EPSG:" prefix. To find code numbers, see the EPSG registry or the GeoTIFF specification in the Tips section.

If you specify both the GeoKeyDirectoryTag and the CoordRefSysCode arguments, the coordinate system code in CoordRefSysCode takes precedence over the coordinate system key found in the GeoKeyDirectoryTag. If one value specifies a geographic coordinate system and the other value specifies a projected coordinate system, the function issues an error.

If you do not specify a value for this argument, the default value is 4326, indicating that the coordinates are geographic and in the WGS 84 geographic coordinate system.

Example: 26986

Example: "EPSG:26986"

GeoKeyDirectoryTag — GeoKey directory tag

structure

GeoKey directory tag, specified as a structure that specifies the GeoTIFF coordinate reference system and meta-information. The structure contains field names that match the GeoKey names in the GeoTIFF specification. The field names are case insensitive. The structure can be obtained from the GeoTIFF information structure, returned by geotiffinfo, in the GeoTIFFTags.GeoKeyDirectoryTag field.

If you specify the GTRasterTypeGeoKey field, geotiffwrite ignores it. The value for this GeoKey is derived from R. If you set certain fields of the GeoKeyDirectoryTag to inconsistent settings, the function issues an error. For example, if R is a geographic raster reference object and you specify a ProjectedCSTypeGeoKey field or set the GTModelTypeGeoKey field to 1 (projected coordinate system), the function issues an error. Likewise, if R is a map raster reference object and you do not specify a ProjectedCSTypeGeoKey field or a CoordRefSysCode, or the GTModelTypeGeoKey field is set to 2 (geographic coordinate system), the function issues an error.

RPCCoefficientTag — Rational Polynomial Coefficients (RPC) tag

RPCCoefficientTag object

Values for the optional RPC TIFF tag, specified as an RPCCoefficientTag object.

TiffTags — TIFF tags

structure

Values for the TIFF tags in the output file, specified as a structure. The field names of the structure match the TIFF tag names supported by the Tiff class. The field names are case insensitive.

You cannot set most TIFF tags using the structure input.

TiffTags Exceptions

BitsPerSample	SubFileType	GeoAsciiParamsTag
SampleFormat	SubIFD	GeoDoubleParamsTag
SamplesPerPixel	TileByteCounts	GeoKeyDirectoryTag
StripByteCounts	TileOffsets	ModelPixelScaleTag
StripOffsets	ImageLength	ModelTiepointTag
ColorMap	ImageWidth	ModelTransformationTag

The function sets several TIFF tags. The field names corresponding to the TIFF tag, their corresponding field values set by the function, their permissible values (if different from the Tiff class), and their data type are noted in the following table.

Automatic TIFF Tags

Field Name	Description
Compression	Type of image compression. The default is 'PackBits'. Other permissible values are 'LZW', 'Deflate', and 'none'. Numeric values, Tiff.Compression.LZW, Tiff.Compression.PackBits, Tiff.Compression.Deflate, or Tiff.Compression.None can also be used.
PhotometricInterpretation	Type of photometric interpretation. The field name can be shortened to Photometric. The value is set based on the input image characteristic, using the following algorithm: If A is [M-by-N-by-3] and is class type uint8 or uint16, then the value is 'RGB'. For all other sizes and data types, the value is 'MinIsBlack'. If the X, CMAP syntax is supplied, the value is 'Palette'. If the value is set to 'RGB' and A is not [M-by-N-by-3], an error is issued. Permissible values are 'MinIsBlack', 'RGB', 'Palette', 'Separated'. The numeric values, Tiff.Photometric.MinIsBlack, Tiff.Photometric.RGB, Tiff.Photometric.Palette, Tiff.Photometric.Separated can also be used.
Software	Software maker of the file. The value is set to the value 'MATLAB, Mapping Toolbox, The MathWorks, Inc.'. To remove the value, set the tag to the empty string or character vector ('').
RowsPerStrip	A scalar positive integer-valued number specifying the desired rows per strip in the output file. If the size of A is less than [160-by-160], geotiffwrite sets RowsPerStrip to 1. If you specify RowsPerStrip and TileWidth, with or without TileLength, geotiffwrite issues an error.
TileWidth	A scalar positive integer-valued number and a multiple of 16 specifying the width of the tiles. TileWidth is set if the size of A is greater than [160-by-160]. If so, the value is such that a maximum of [10-by-10] tiles are created. If you specify both RowsPerStrip and TileWidth, geotiffwrite issues an error.
TileLength	A scalar positive integer-valued number and a multiple of 16 specifying the length of the tiles. TileLength is set if the size of A is greater than [160-by-160]. If so, the value is such that a maximum of [10-by-10] tiles are created. If you specify both RowsPerStrip and TileLength, geotiffwrite issues an error.

TiffType — Type of TIFF file

"classictiff" (default) | "bigtiff"

Type of TIFF file, specified as "classictiff" or "bigtiff". The "classictiff" option creates a Classic TIFF file. The "bigtiff" option creates a BigTIFF file. In BigTIFF format, files can be larger than 4 GB.

While using the "bigtiff" format enables you to create files larger than 4 GB, the data you want to write must fit in memory.

Tips

• If you are working with image coordinates in a projected coordinate system and R is a map raster reference object, set the GeoKeyDirectoryTag or CoordRefSysCode argument, accordingly.

• You can find values for the CoordRefSysCode and GeoKeyDirectoryTag arguments by checking the GeoTIFF specification.

  • For a list of CoordRefSysCode values that you can specify for geographic coordinate systems, see Geographic CS Type Codes in the GeoTIFF specification.

  • For a list of CoordRefSysCode values that you can specify for projected coordinate systems, see Projected CS Type Codes in the GeoTIFF specification.

  • For a list of keys that you can specify using the GeoKeyDirectoryTag argument, see Key ID Summary in the GeoTIFF specification.

Version History

Introduced before R2006a

R2024b: geotiffwrite does not accept referencing vectors or referencing matrices as input

The geotiffwrite function does not accept referencing vectors or referencing matrices as input. Use a geographic raster reference object (specified as a GeographicCellsReference or GeographicPostingsReference object) or a map raster reference object (specified as a MapCellsReference or MapPostingsReference object) as input instead. Reference objects have several advantages over referencing vectors and referencing matrices.

• Unlike referencing vectors and referencing matrices, reference objects have properties that document the size of the associated raster, its limits, and the direction of its rows and columns.

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

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

Depending on whether the referencing vector or referencing matrix is in geographic or planar coordinates, there are different ways to update your code.

Geographic Coordinates

If the referencing vector or referencing matrix is in geographic coordinates, create a geographic reference object.

• Create a geographic reference object for a raster of cells by using the georefcells function.

• Create a geographic reference object for a raster of regularly posted samples by using the georefpostings function.

• Convert from a referencing vector to a geographic reference object by using the refvecToGeoRasterReference function.

• Convert from a referencing matrix to a geographic reference object by using the refmatToGeoRasterReference function.

Once you have created a reference object, replace uses of the referencing vector or referencing matrix in your code with the reference object.

Planar Map Coordinates

If the referencing vector or referencing matrix is in planar map coordinates, create a map reference object.

• Create a map reference object for a raster of cells by using the maprefcells function.

• Create a map reference object or for a raster of regularly posted samples by using the maprefpostings function.

• Convert from a referencing matrix to a map reference object by using the refmatToMapRasterReference function.

Once you have created a reference object, replace uses of the referencing vector or referencing matrix in your code with the reference object.

R2018a: Export data containing more than 4 GB in BigTIFF format​

Specify the format of the GeoTIFF file to write as either classic TIFF or BigTIFF by using the TiffType name-value argument. The BigTIFF format enables you to create files that exceed 4 GB in size.