# maprasterref

(Not recommended) Create map raster reference object

The `maprasterref` function is not recommended, except when creating a raster reference object from a world file matrix. To specify options using name-value arguments, use the `maprefcells` or `maprefpostings` function instead. For more information, see Compatibility Considerations.

## Syntax

``R = maprasterref(W,rasterSize)``
``R = maprasterref(W,rasterSize,rasterInterpretation)``
``R = maprasterref(Name,Value)``

## Description

example

````R = maprasterref(W,rasterSize)` creates a reference object for a raster of cells referenced to planar coordinates using the world file matrix `W` and raster size `rasterSize`.```
````R = maprasterref(W,rasterSize,rasterInterpretation)` specifies the geometric nature of the raster. When the raster contains posting point samples referenced to planar coordinates, specify `rasterInterpretation` as `"postings"`. The default for `rasterInterpretation` is `"cells"`, which specifies a raster of cells.```
````R = maprasterref(Name,Value)` specifies options using name-value arguments.```

## Examples

collapse all

Create a reference object for a raster of cells with size 1000-by-2000, cell xy-extents of 0.5 linear units, world x-limits of [207000, 208000] linear units, and world y-limits of [912500, 913000] linear units. Orient the raster using a convention typical for imagery, where image rows run from west to east and image columns run from north to south.

Specify the world file matrix using these values:

ValueExplanation
`0.5`The rows of the raster start from the west and each cell is 0.5 linear units wide.
`207000.25`World x-coordinate of the first cell center.
`-0.5`The rows of the raster start from the north and each cell is 0.5 linear units tall.
`912999.75`World y-coordinate of the first cell center.

`W = [0.5 0 207000.25; 0 -0.5 912999.75];`

Create the reference object.

`R = maprasterref(W,[1000 2000],"cells")`
```R = MapCellsReference with properties: XWorldLimits: [207000 208000] YWorldLimits: [912500 913000] RasterSize: [1000 2000] RasterInterpretation: 'cells' ColumnsStartFrom: 'north' RowsStartFrom: 'west' CellExtentInWorldX: 1/2 CellExtentInWorldY: 1/2 RasterExtentInWorldX: 1000 RasterExtentInWorldY: 500 XIntrinsicLimits: [0.5 2000.5] YIntrinsicLimits: [0.5 1000.5] TransformationType: 'rectilinear' CoordinateSystemType: 'planar' ProjectedCRS: []```

## Input Arguments

collapse all

World file matrix, specified as a 2-by-3 numeric array. A world file matrix defines a transformation that maps intrinsic coordinates to world coordinates.

The form of `W` depends on whether the intrinsic and world axes have a rectilinear relationship, where the intrinsic and world axes align, or an affine relationship, where the intrinsic axes are rotated with respect to the world axes.

When the relationship is rectilinear, specify `W` using the form `[xspacing 0 x; 0 yspacing y]`, where

• `xspacing` determines the `RowsStartFrom` and the `CellExtentInWorldX` or `SampleSpacingInWorldX` properties of `R`.

• When `xspacing` is positive, `RowsStartFrom` is `'west'`. When `xspacing` is negative, `RowsStartFrom` is `'east'`.

• `CellExtentInWorldX` or `SampleSpacingInWorldX` is `abs(xspacing)`.

• `yspacing` determines the `ColumnsStartFrom` and the `CellExtentInWorldY` or `SampleSpacingInWorldY` properties of `R`.

• When `yspacing` is positive, `ColumnsStartFrom` is `'south'`. When `yspacing` is negative, `ColumnsStartFrom` is `'north'`.

• `CellExtentInWorldY` or `SampleSpacingInWorldY` is `abs(yspacing)`.

• `x` and `y` are the world xy-coordinates of the first cell center or posting point. For a spatially referenced raster `A`, the first cell center or posting point is the spatial location associated with `A(1,1,:)`.

When the relationship is affine, specify `W` so that $\left[\begin{array}{c}{x}_{w}\\ {y}_{w}\end{array}\right]=W\cdot \left[\begin{array}{c}{x}_{i}-1\\ {y}_{i}-1\\ 1\end{array}\right]$, where (xi, yi) is a location in intrinsic coordinates and (xw, yw) is the same location in world coordinates.

Number of rows and columns of the raster, specified as a two-element vector of the form [`m` `n`], where `m` is the number of rows and `n` is the number of columns.

For convenience, you can specify this argument as a vector with more than two elements, such as the size of an RGB image (m-by-n-by-3). The `maprasterref` function uses only the first two elements of the size vector.

Geometric nature of the raster, specified as one of these options:

• `"cells"` — The raster is a grid of quadrangular cells. The boundary of the raster is made up of the outermost boundaries of the outermost cells.

• `"postings"` — The raster is a grid of posting point samples. The boundary of the raster is made up of sampling points along the edge of the raster.

The corresponding property of the reference object, `RasterInterpretation`, is read-only after you create the object.

### Name-Value Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Example: ```maprasterref("XWorldLimits",[207000 208000],"YWorldLimits",[912500 913000])``` creates a map cells reference object with x-values in the range [207000, 208000] linear units and y-values in the range [912500, 913000] linear units.

x-limits in world coordinates of the rectangle that bounds the georeferenced raster, specified as a two-element vector of the form ```[xMin xMax]```.

y-limits in world coordinates of the rectangle that bounds the georeferenced raster, specified as a two-element vector of the form ```[yMin yMax]```.

Number of rows and columns of the raster, specified as a two-element vector [`m` `n`], where `m` is the number of rows and `n` is the number of columns.

For convenience, you can specify `RasterSize` as a vector with more than two elements, such as the size of an RGB image (m-by-n-by-3). The `maprasterref` function uses only the first two elements of the size vector.

Geometric nature of the raster, specified as one of these options:

• `"cells"` — The raster is a grid of quadrangular cells. The boundary of the raster is made up of the outermost boundaries of the outermost cells.

• `"postings"` — The raster is a grid of posting point samples. The boundary of the raster is made up of sampling points along the edge of the raster.

The corresponding property of the raster reference object is read-only after you create the object.

Data Types: `char` | `string`

Edge from which column indexing starts, specified as `"south"` or `"north"`.

Data Types: `char` | `string`

Edge from which row indexing starts, specified as `"west"` or `"east"`.

Data Types: `char` | `string`

## Output Arguments

collapse all

Map raster reference object, returned as a `MapCellsReference` or `MapPostingsReference` object. The value of `R` depends on the value of the `rasterInterpretation` argument or `RasterInterpretation` name-value argument.

`rasterInterpretation` or `RasterInterpretation``R`
`"cells"``MapCellsReference` object
`"postings"``MapPostingsReference` object

## Tips

• When you create a reference object by using the ```R = maprasterref(Name,Value)``` syntax, the function assumes the raster has a rectilinear relationship between the intrinsic and world systems and sets the read-only property `TransformationType` to `'rectilinear'`. If your raster is rotated with respect to the world system, set the `TransformationType` property to `'affine'` by specifying a world matrix or by using the `maprefcells` or `maprefpostings` function instead.

## Version History

Introduced in R2011a

expand all

Not recommended starting in R2015b