Documentation

geotiffwrite

Write GeoTIFF file

Syntax

geotiffwrite(filename,A,R)
geotiffwrite(filename,X,cmap,R)
geotiffwrite(...,Name,Value)

Description

geotiffwrite(filename,A,R) writes a georeferenced image or data grid, A, spatially referenced by R, into an output file, filename.

geotiffwrite(filename,X,cmap,R) writes the indexed image in X and its associated colormap, cmap, to filename. X is spatially referenced by R.

geotiffwrite(...,Name,Value) writes a georeferenced image or data grid with additional options that control various characteristics of the output file specified by one or more Name,Value pair arguments.

Input Arguments

collapse all

filename — Name and location of output filecharacter string

Name and location of output file, specified as a character string. If your filename includes an extension, it must be '.tif' or '.TIF'. The output file is a tiled GeoTIFF file if the input, A, is at least 160-by-160 in size. Otherwise, the output file is organized as rows-per-strip.

Data Types: char

A — Image dataM-by-N numeric array | M-by-N-by-P numeric array

Image data, specified as an M-by-N array (grayscale image or data grid) or M-by-N-by-P array (color or hyperspectral image, or data grid). The coordinates of A are geographic and in the 'WGS 84' coordinate system, unless you specify 'GeoKeyDirectoryTag' or 'CoordRefSysCode' and indicate a different coordinate system.

R — Spatial referencing informationraster reference object | referencing matrix | referencing vector

Spatial referencing information, specified as a raster reference object, referencing matrix, or referencing vector. If you are working with image coordinates in a projected coordinate system and R is a map raster reference object or a referencing matrix, specify 'GeoKeyDirectoryTag' or 'CoordRefSysCode' accordingly.

X — Indexed imagenumeric array

Indexed image data, specified as a numeric array.

cmap — Color mapM-by-3 array

Color map, specified as an M-by-3 array.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

The argument names are case insensitive.

'CoordRefSysCode'

Scalar, positive, integer-valued number that specifies the coordinate reference system code for the coordinates of the data. You can specify coordinates in either a geographic or a projected coordinate system, and you can use a string, such as 'EPSG:4326'. If you specify the coordinate system with a string, include the 'EPSG:' prefix. See References for a link to the GeoTiff Specification or the EPSG data files (pcs.csv and gcs.csv) for the code numbers.

If you specify both the 'GeoKeyDirectoryTag' and the 'CoordRefSysCode', the coordinate system code in the '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, you receive 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.

Default: 4326

'GeoKeyDirectoryTag'

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 field, GeoTIFFTags.GeoKeyDirectoryTag. If you set certain fields of the 'GeoKeyDirectoryTag' to inconsistent settings, you receive an error message.

The GTRasterTypeGeoKey field is ignored, if specified. The value for this GeoKey is derived from R. If you set certain fields of the 'GeoKeyDirectoryTag' to inconsistent settings, you receive an error message. For instance, if R is either a spatialref.GeoRasterReference object or a refvec and you specify a ProjectedCSTypeGeoKey field or you set the GTModelTypeGeoKey field to 1 (projected coordinate system), you receive an error. Likewise, if R is a spatialref.MapRasterReference object and you do not specify a ProjectedCSTypeGeoKey field or a 'CoordRefSysCode', or the GTModelTypeGeoKey field is set to 2 (geographic coordinate system), you receive an error message.

'RPCCoefficientTag'

map.geotiff.RPCCoefficientTag object that specifies values for the optional Rational Polynomial Coefficients (RPC) TIFF tag. For more information about these values, see map.geotiff.RPCCoefficientTag.

'TiffTags'

Structure that specifies values for the TIFF tags in the output file. 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

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

Class Support

The input array, A, can be any numeric class or logical. The indexed image, X, must be class uint8 or uint16. The colormap array, cmap, must be class double.

Examples

collapse all

Write Image from JPEG File to GeoTIFF File

Read JPEG image from file.

basename = 'boston_ovr';
imagefile = [basename '.jpg'];
RGB = imread(imagefile);

Derive world file name from image file name, read the world file, and construct a spatial referencing object.

worldfile = getworldfilename(imagefile);
R = worldfileread(worldfile, 'geographic', size(RGB));

Write image data and referencing data to GeoTIFF file.

filename = [basename '.tif'];
geotiffwrite(filename, RGB, R)

Construct an empty map axes and display the map.

figure
usamap(RGB, R)
geoshow(filename)

Write WMS Image to GeoTIFF File

Read data from WMS server.

nasaLayers = wmsfind('nasa', 'SearchField', 'serverurl');
layerName = 'bluemarbleng';
layer = refine(nasaLayers, layerName,  'SearchField', 'layername', ...
  'MatchType', 'exact');
[A, R] = wmsread(layer(1));

Write data to GeoTIFF file.

filename = [layerName '.tif'];
geotiffwrite(filename, A, R)

View data in file.

figure
worldmap world
geoshow(filename)

Write Concord Orthophotos to Single GeoTIFF File

Read the two adjacent orthophotos and combine them.

X_west = imread('concord_ortho_w.tif');
X_east = imread('concord_ortho_e.tif');
X = [X_west X_east];

Construct referencing objects for the orthophotos and for their combination.

R_west = worldfileread('concord_ortho_w.tfw', 'planar', size(X_west));
R_east = worldfileread('concord_ortho_e.tfw', 'planar', size(X_east));
R = R_west;
R.XLimWorld = [R_west.XLimWorld(1) R_east.XLimWorld(2)];
R.RasterSize = size(X);

Write the combined image to a GeoTIFF file. Use the code number, 26986, indicating the PCS_NAD83_Massachusetts Projected Coordinate System.

coordRefSysCode = 26986;
filename = 'concord_ortho.tif';
geotiffwrite(filename, X, R, 'CoordRefSysCode', coordRefSysCode);

Display the map.

figure
mapshow(filename)

Write Subset of GeoTIFF File to New GeoTIFF File

Read GeoTIFF file.

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

Specify subset of data that you want to write.

m = size(A,1);
n = 1024;
firstrow = m-n+1;
lastrow = m;
firstcol = 1;
lastcol = n;
subImage = A(firstrow:lastrow, firstcol:lastcol, :);
xi = [firstcol - .5, lastcol + .5];
yi = [firstrow - .5, lastrow + .5];
[xlimits, ylimits] = intrinsicToWorld(R, xi, yi);
subR = R;
subR.RasterSize = size(subImage);
subR.XLimWorld = sort(xlimits);
subR.YLimWorld = sort(ylimits);
info = geotiffinfo('boston.tif');

Write subset to file.

filename = 'boston_subimage.tif';
geotiffwrite(filename, subImage, subR,  ...
       'GeoKeyDirectoryTag', info.GeoTIFFTags.GeoKeyDirectoryTag);
figure
mapshow(filename);

Write SDTS DEM terrain data to GeoTIFF File

This example shows how to write the Mount Washington SDTS DEM terrain data to GeoTIFF. The data are referenced to Universal Transverse Mercator (UTM), Zone 19, in the North American Datum of 1927. This corresponds to the GeoTIFF PCS_NAD27_UTM_zone_19N code number 26719. Set the raster interpretation to 'postings' because the data is USGS DEM. This corresponds to the GeoTIFF raster type PixelIsPoint.

Read SDTS DEM data.

[Z, refmat] = sdtsdemread('9129CATD.ddf');
R = refmatToMapRasterReference(refmat, size(Z), 'postings');
key.GTModelTypeGeoKey  = 1;  % Projected Coordinate System (PCS)
key.GTRasterTypeGeoKey = 2;  % PixelIsPoint
key.ProjectedCSTypeGeoKey = 26719;
filename = '9129.tif';
geotiffwrite(filename, Z, R, 'GeoKeyDirectoryTag', key);

Plot the outline of the state of New Hampshire in UTM.

S = shaperead('usastatelo', 'UseGeoCoords', true, 'Selector',...
    {@(name) any(strcmp(name,{'New Hampshire'})), 'Name'});
proj = geotiffinfo(filename);
[x, y] = projfwd(proj, [S.Lat], [S.Lon]);
figure
mapshow(x,y)

Display the GeoTIFF DEM file.

hold on
h = mapshow(filename, 'DisplayType', 'surface');
demcmap(get(h,'ZData'))

Read and Write TIFF File Containing RPC Metadata

This example shows how to read a file containing RPC metadata, modify the file, and then write the file, including the RPC metadata in the new file. To illustrate this process, the example first creates a sample TIFF file containing RPC Metadata.

Create a Sample TIFF File with RPC Metadata

Create a sample test TIFF file containing RPC metadata. 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 fields with typical values. 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 RPCCoefficentTag object to a file.

geotiffwrite('myfile',myimage,R,'RPCCoefficientTag',rpctag)

Read the Metadata and Image Data from the Sample TIFF File

Read the metadata and the image data from the test file. geotiffinfo returns the RPC metadata in the GeoTIFFTags field of the structure returned.

info = geotiffinfo('myfile');
[imagedata, R] = geotiffread('myfile');

Write Modified Image Data and RPC Metadata to File

First modify the image data read from the file. For example, set all the zero-valued pixels to 1 in the image.

imagedata(imagedata==0)= 1;

Write the modified image to a file, along with the RPC metadata from the original file.

geotiffwrite('myfile2',imagedata,R,...
    'RPCCoefficientTag',info.GeoTIFFTags.RPCCoefficientTag)

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 Coefficent 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 RPCCoefficentTag object to a file.

geotiffwrite('myfile',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 how 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 = 

        ID: 50844
    Offset: 10672
     Value: [1x92 double]

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',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');
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]

More About

expand all

Tips

  • If you are working with image coordinates in a projected coordinate system and R is a map raster reference object or a referencing matrix, set the 'GeoKeyDirectoryTag' or 'CoordRefSysCode' argument, accordingly. See Name-Value Pair Arguments for more information.

References

Check the GeoTIFF specification for values of the following parameters:

The 'CoordRefSysCode' values may also be obtained from the EPSG data files (pcs.csv and gcs.csv) in the folder:

matlabroot/toolbox/map/mapproj/projdata/epsg_csv

Introduced before R2006a

Was this topic helpful?