# 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
`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`StringIndicates 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'`.
`RowsStartFrom`StringIndicates 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)) ```

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.