Main Content

makerefmat

(Removed) Construct affine spatial-referencing matrix

collapse all in page

makerefmat has been removed. Create a raster reference object using the georefcells, georefpostings, georasterref, maprefcells, maprefpostings, or maprasterref function instead. For more information, see Version History.

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.

Version History

expand all

R2023b: Removed

Some functions that return referencing matrices have been removed, including the makerefmat function. Instead, create a geographic raster reference object by using the georefcells, georefpostings, or georasterref function, or a map raster reference object by using the maprefcells, maprefpostings, or maprasterref function. Reference objects have several advantages over referencing matrices.

  • Unlike referencing matrices, reference objects have properties that document the size of the associated raster, its limits, and the direction of its rows and columns. For more information about reference object properties, see the GeographicCellsReference and MapPostingsReference objects.

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

  • Most functions that accept referencing matrices as inputs also accept reference objects.

Depending on the makerefmat function syntax, there are different ways to update your code.

  • To specify the first data point of A and scalar values of dx and dy or dlon and dlat, use these replacement patterns. Use the georasterref function for geographic coordinates and the maprasterref function for planar map coordinates.

    RemovedRecommended
    R = makerefmat(x11,y11,dx,dy);
    		 
    W = [dx 0 x11; 0 dy y11];
R = maprasterref(W,size(A));
    R = makerefmat(lon11,lat11,dlon,dlat);
    		 
    W = [dlon 0 lon11; 0 dlat lat11];
R = georasterref(W,size(A));

  • To specify the first data point of A and vector values of dx and dy or dlon and dlat, use these replacement patterns. Use the georasterref function for geographic coordinates and the maprasterref function for planar map coordinates.

    RemovedRecommended
    R = makerefmat(x11,y11,dx,dy);
    		 
    W = [dx x11; dy y11];
R = maprasterref(W,size(A));
    R = makerefmat(lon11,lat11,dlon,dlat);
    		 
    W = [dlon lon11; dlat lat11];
R = georasterref(W,size(A));

  • To specify arguments such as the raster size or latitude and longitude limits, use this replacement pattern. Use the georefcells function for a raster of cells and the georefpostings function for a raster of regularly posted samples.

    RemovedRecommended
    R = makerefmat('RasterSize',size, ...
               'LatitudeLimits',latlim, ...
               'LongitudeLimits',lonlim);
    		 
    R = georefcells(latlim,lonlim,size);

You can also create a map raster reference object using the maprefcells or maprefpostings function. These functions are useful if you have information such as world limits or cell extents. Use the maprefcells function for a raster of cells and the maprefpostings function for a raster of regularly posted samples.

See Also

| | | | |