refmatToGeoRasterReference

Convert referencing matrix to geographic raster reference object

Syntax

R = refmatToGeoRasterReference(refmat,rasterSize)

R = refmatToGeoRasterReference(refmat,rasterSize,rasterInterpretation)

R = refmatToGeoRasterReference(___,funcName)

R = refmatToGeoRasterReference(___,funcName,varName)

R = refmatToGeoRasterReference(___,funcName,varName,argIndex)

R = refmatToGeoRasterReference(Rin,rasterSize,___)

Description

Create Reference Object

R = refmatToGeoRasterReference(refmat,rasterSize) converts the referencing matrix refmat into a reference object for a raster of cells referenced to geographic coordinates, using the raster size rasterSize.

R = refmatToGeoRasterReference(refmat,rasterSize,rasterInterpretation) specifies the geometric nature of the raster. When the raster contains posting point samples referenced to geographic coordinates, specify rasterInterpretation as "postings". The default for rasterInterpretation is "cells", which specifies a raster of cells.

Note

Instead of converting a referencing matrix to a reference object, you can create a reference object directly.

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

• Create a reference object for a raster of posting points referenced to geographic coordinates by using the georefpostings function.

Validate Inputs

R = refmatToGeoRasterReference(___,funcName), when refmat or rasterSize is invalid, includes the specified function name in generated error identifiers. This syntax uses any combination of input arguments from previous syntaxes, and is useful when you want to both validate and convert a referencing matrix. For more information about validating inputs, see the validateattributes function.

R = refmatToGeoRasterReference(___,funcName,varName) includes the specified variable name in generated error messages.

R = refmatToGeoRasterReference(___,funcName,varName,argIndex) includes the position of the referencing matrix in generated error messages.

R = refmatToGeoRasterReference(Rin,rasterSize,___) verifies that the RasterSize property of the geographic raster reference object Rin matches rasterSize, and then returns Rin in R.

Examples

Convert Referencing Matrix to Geographic Raster Reference Object

Specify a sample referencing matrix and the size of a sample raster. Then, convert the referencing matrix to a geographic raster reference object.

refmat = [0 1; 1 0; -0.5 -90.5];
rasterSize = [180 360];
R = refmatToGeoRasterReference(refmat,rasterSize)

R = 
  GeographicCellsReference with properties:

             LatitudeLimits: [-90 90]
            LongitudeLimits: [0 360]
                 RasterSize: [180 360]
       RasterInterpretation: 'cells'
           ColumnsStartFrom: 'south'
              RowsStartFrom: 'west'
       CellExtentInLatitude: 1
      CellExtentInLongitude: 1
     RasterExtentInLatitude: 180
    RasterExtentInLongitude: 360
           XIntrinsicLimits: [0.5 360.5]
           YIntrinsicLimits: [0.5 180.5]
       CoordinateSystemType: 'geographic'
              GeographicCRS: []
                  AngleUnit: 'degree'

For comparison, create an equivalent reference object directly by using the georefcells function.

R2 = georefcells([-90 90],[0 360],rasterSize)

R2 = 
  GeographicCellsReference with properties:

             LatitudeLimits: [-90 90]
            LongitudeLimits: [0 360]
                 RasterSize: [180 360]
       RasterInterpretation: 'cells'
           ColumnsStartFrom: 'south'
              RowsStartFrom: 'west'
       CellExtentInLatitude: 1
      CellExtentInLongitude: 1
     RasterExtentInLatitude: 180
    RasterExtentInLongitude: 360
           XIntrinsicLimits: [0.5 360.5]
           YIntrinsicLimits: [0.5 180.5]
       CoordinateSystemType: 'geographic'
              GeographicCRS: []
                  AngleUnit: 'degree'

Input Arguments

refmat — Referencing matrix

3-by-2 matrix

Referencing matrix, specified as a 3-by-2 matrix. A referencing matrix defines a transformation that maps intrinsic coordinates to geographic coordinates.

Specify refmat so that $$\left[\begin{array}{cc}lon& lat\end{array}\right]=\left[\begin{array}{ccc}x& y& 1\end{array}\right]\cdot refmat$$, where x and y specify a location in intrinsic coordinates and lat and lon specify the same location in geographic coordinates.

When combined with rasterSize, the referencing matrix must create valid latitude and longitude limits. The columns and rows of the referencing matrix must align with meridians and parallels, respectively.

Data Types: double

rasterSize — Number of rows and columns

two-element vector

Number of rows and columns of the raster, specified as a two-element vector of the form [m n], where m is the number of rows and n is the number of columns.

For convenience, you can specify this argument as a vector with more than two elements, such as the size of an RGB image (m-by-n-by-3). The refmatToGeoRasterReference function uses only the first two elements of the size vector.

rasterInterpretation — Geometric nature of raster

"cells" (default) | "postings"

Geometric nature of the raster, specified as one of these options:

• "cells" — The raster is a grid of quadrangular cells. The boundary of the raster is made up of the outermost boundaries of the outermost cells.

• "postings" — The raster is a grid of posting point samples. The boundary of the raster is made up of sampling points along the edge of the raster.

For more information about cells and posting points, see Spatially Reference Imported Rasters.

The corresponding RasterInterpretation property of the reference object is read-only after you create the object.

Data Types: char | string

funcName — Name of function for validation

character vector | string scalar

Name of the function for validation, specified as a character vector or as a string scalar. If you specify an empty character vector, '', or the <missing> string, then the refmatToGeoRasterReference function ignores the funcName input.

Data Types: char | string

varName — Name of input variable

character vector | string scalar

Name of the input variable, specified as a character vector or a string scalar. If you specify an empty character vector, '', or the <missing> string, then the refmatToGeoRasterReference function ignores the varName input.

Data Types: char | string

argIndex — Position of input argument

positive integer

Position of the input argument, specified as a positive integer.

Data Types: double

Rin — Geographic raster reference object

GeographicCellsReference object | GeographicPostingsReference object

Geographic raster reference object, specified as a GeographicCellsReference or GeographicPostingsReference object.

If you specify both Rin and rasterInterpretation, the RasterInterpretion property of Rin must match the value of rasterInterpretation.

Output Arguments

R — Geographic raster reference object

GeographicCellsReference object | GeographicPostingsReference object

Geographic raster reference object, returned as a GeographicCellsReference or GeographicPostingsReference object. The value of R depends on the value of the rasterInterpretation argument.

rasterInterpretation	R
"cells"	GeographicCellsReference object
"postings"	GeographicPostingsReference object

Version History

Introduced in R2011a