makerefmat

Construct affine spatial-referencing matrix

Syntax

R = makerefmat(x11, y11, dx, dy)
R = makerefmat(lon11, lat11, dlon, dlat)
R = makerefmat(param1, val1, param2, val2, ...)

Description

R = makerefmat(x11, y11, dx, dy), with scalars dx and dy, constructs a referencing matrix that aligns image or data grid rows to map x and columns to map y. Scalars x11 and y11 specify the map location of the center of the first (1,1) pixel in the image or the first element of the data grid.

dx is the difference in x (or longitude) between pixels in successive columns, and dy is the difference in y (or latitude) between pixels in successive rows.

Pixels cover squares on the map when abs(dx) = abs(dy). To achieve the most typical kind of alignment, where x increases from column to column and y decreases from row to row, make dx positive and dy negative. In order to specify such an alignment along with square pixels, make dx positive and make dy equal to -dx:

 R = makerefmat(x11, y11, dx, -dx)

R = makerefmat(x11, y11, dx, dy), with two-element vectors dx and dy, constructs the most general possible kind of referencing matrix.

In this general case, each pixel can become a parallelogram on the map, with neither edge necessarily aligned to map x or y. The vector [dx(1) dy(1)] is the difference in map location between a pixel in one row and its neighbor in the preceding row. Likewise, [dx(2) dy(2)] is the difference in map location between a pixel in one column and its neighbor in the preceding column.

To specify pixels that are rectangular or square (but possibly rotated), choose dx and dy such that prod(dx) + prod(dy) = 0. To specify square (but possibly rotated) pixels, choose dx and dy such that the 2-by-2 matrix [dx(:) dy(:)] is a scalar multiple of an orthogonal matrix (that is, its two eigenvalues are real, nonzero, and equal in absolute value). This amounts to either rotation, a mirror image, or a combination of both. Note that for scalars dx and dy,

R = makerefmat(x11, y11, [0 dx], [dy 0])

is equivalent to

R = makerefmat(x11, y11, dx, dy)

R = makerefmat(lon11, lat11, dlon, dlat), with longitude preceding latitude, constructs a referencing matrix for use with geographic coordinates.

R = makerefmat(param1, val1, param2, val2, ...) uses parameter name-value pairs to construct a referencing matrix for an image or raster grid that is referenced to and aligned with a geographic coordinate system. There can be no rotation or skew: each column must fall along a meridian, and each row must fall along a parallel. Each parameter name must be specified exactly as shown, including case.

Parameter NameData TypeValue
RasterSizeTwo-element size vector [M N]

The number of rows (M) and columns (N) of the raster or image to be used with the referencing matrix.

With 'RasterSize', you may also provide a size vector having more than two elements. This enables usage such as:

R = makerefmat('RasterSize', ...
   size(RGB), ...)
where RGB is M-by-N-by-3. However, in cases like this, only the first two elements of the size vector will actually be used. The higher (non-spatial) dimensions will be ignored. The default value is [1 1].

LatitudeLimitsTwo-element row vector of the form: [southern_limit, northern_limit], in units of degrees.The limits in latitude of the geographic quadrangle bounding the georeferenced raster. The default value is [0 1].
LongitudeLimitsTwo-element row vector of the form: [western_limit, eastern_limit], in units of degrees. The limits in longitude of the geographic quadrangle bounding the georeferenced raster. The elements of the 'LongitudeLimits' vector must be ascending in value. In other words, the limits must be unwrapped. The default value is [0 1].
ColumnsStartFromString scalar or character vectorIndicates the column direction of the raster (south-to-north vs. north-to-south) in terms of the edge from which row indexing starts. Values are 'south' or 'north' and they can be shortened, and are case-insensitive. In a typical terrain grid, row indexing starts at southern edge. In images, row indexing starts at northern edge. The default value is 'south'.
RowsStartFromString scalar or character vectorIndicates the row direction of the raster (west-to-east vs. east-to-west) in terms of the edge from which column indexing starts. Values are: 'west' or 'east' and they can be shortened, and are case-insensitive. Rows almost always run from west to east. The default value is 'west'.

Examples

Create a referencing matrix for an image with square, four-meter pixels and with its upper left corner (in a map coordinate system) at x = 207000 meters, y = 913000 meters. The image follows the typical orientation: x increasing from column to column and y decreasing from row to row.

x11 = 207002;  % Two meters east of the upper left corner
y11 = 912998;  % Two meters south of the upper left corner
dx =  4;
dy = -4;
R = makerefmat(x11, y11, dx, dy)

More About

collapse all

Spatial Referencing Matrix

A spatial referencing matrix R ties the row and column subscripts of an image or regular data grid to 2-D map coordinates or to geographic coordinates (longitude and geodetic latitude). R is a 3-by-2 affine transformation matrix. R either transforms pixel subscripts (row, column) to/from map coordinates (x,y) according to

[x y] = [row col 1] * R

or transforms pixel subscripts to/from geographic coordinates according to

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

To construct a referencing matrix for use with geographic coordinates, use longitude in place of X and latitude in place of Y, as shown in the R = makerefmat(X11, Y11, dx, dy) syntax. This is one of the few places where longitude precedes latitude in a function call.