Documentation

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, so that

 [x11 y11] = pix2map(R,1,1)

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. More abstractly, R is defined such that

[x11 + (col-1) * dx, y11 + (row-1) * dy] = pix2map(R, row, col)

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, for which

[x11 + ([row col]-1) * dx(:), y11 + ([row col]-1) * dy(:)] ... 

 = pix2map(R, row, col)

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. In this case,

[lat11,lon11] = pix2latlon(R,1,1),
[lat11+(row-1)*dlat,lon11+(col-1)*dlon] = pix2latlon(R,row,col)

for scalar dlat and dlon, and

[lat11+[row col]-1)*dlat,lon11+([row col]-1)*dlon] = ...
pix2latlon(R, row,col)

for vector dlat and dlon. Images or data grids aligned with latitude and longitude might already have referencing vectors. In this case you can use function refvec2mat to convert to a referencing matrix.

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].
ColumnsStartFromStringIndicates the column direction of the raster (south-to-north vs. north-to-south) in terms of the edge from which row indexing starts. The input string can have the value 'south' or 'north', can be shortened, and is 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'.
RowsStartFromStringIndicates the row direction of the raster (west-to-east vs. east-to-west) in terms of the edge from which column indexing starts. The input string can have the value 'west' or 'east', can be shortened, and is 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)

Create a referencing matrix for a global geoid grid.

% Add array 'geoid' to the workspace:
load geoid  

%'geoid' contains a model of the Earth's geoid sampled in 
% one-degree-by-one-degree cells. Each column of 'geoid'
% contains geoid heights in meters for 180 cells starting 
% at latitude -90 degrees and extending to +90 degrees, for 
% a given longitude. Each row contains geoid heights for 360 
% cells starting at longitude 0 and extending 360 degrees. 
geoidR = makerefmat('RasterSize', size(geoid), ...
   'Latlim', [-90 90], 'Lonlim', [0 360])

% At its most extreme, the geoid reaches a minimum of slightly 
% less than -100 meters. This minimum occurs in the Indian Ocean 
% at approximately 4.5 degrees latitude, 78.5 degrees longitude.
% Check the geoid height at its most extreme by using latlon2pix
% with the referencing matrix.
[row, col] = latlon2pix(geoidR, 4.5, 78.5)
geoid(round(row),round(col)) 

More About

expand 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.

Was this topic helpful?