# 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
`RasterSize`Two-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].

`LatitudeLimits`Two-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].
`LongitudeLimits`Two-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].
`ColumnsStartFrom`String 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'`.
`RowsStartFrom`String 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)```

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. 