maprasterref

R2026b

(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 Version History.

Syntax

R = maprasterref(W,rasterSize)

R = maprasterref(W,rasterSize,rasterInterpretation)

R = maprasterref(Name=Value)

Description

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 properties of the reference object using one or more name-value arguments.

Examples

Create Map Reference Object from World File Matrix

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:

Value	Explanation
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 columns 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

W — World file matrix

2-by-3 numeric array

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 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 (x_i, y_i) is a location in intrinsic coordinates and (x_w, y_w) is the same location in world coordinates.

rasterSize — Number of rows and columns

two-element vector

Number of rows and columns in 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.

rasterInterpretation — Geometric nature of raster

"cells" (default) | "postings"

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.

For more information about cells and posting points, see Reference Raster Data Using Geographic or World Limits.

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.

Example: R = 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.

XWorldLimits — x-limits, in world coordinates

[0.5 2.5] (default) | two-element vector

x-limits of the rectangle that bounds the raster, in world coordinates, specified as a two-element vector of the form [xmin xmax], where xmax is greater than xmin.

YWorldLimits — y-limits, in world coordinates

[0.5 2.5] (default) | two-element vector

y-limits of the rectangle that bounds the raster, in world coordinates, specified as a two-element vector of the form [ymin ymax], where ymax is greater than ymin.

RasterSize — Number of rows and columns

[2 2] (default) | two-element vector of positive integers

Number of rows and columns in 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 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.

RasterInterpretation — Geometric nature of raster

"cells" (default) | "postings"

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.

For more information about cells and posting points, see Reference Raster Data Using Geographic or World Limits.

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

ColumnsStartFrom — Edge from which column indexing starts

"south" (default) | "north"

Edge from which column indexing starts, specified as one of these options:

• "south" — Column indexing starts from south.

• "north" — Column indexing starts from north.

RowsStartFrom — Edge from which row indexing starts

"west" (default) | "east"

Edge from which row indexing starts, specified as one of these options:

• "west" — Row indexing starts from west.

• "east" — Row indexing starts from east.

ProjectedCRS — Projected coordinate reference system

[] (default) | projcrs object

Projected coordinate reference system (CRS), specified as a projcrs object.

Output Arguments

R — Map raster reference object

MapCellsReference object | MapPostingsReference object

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

Version History

Introduced in R2011a

R2026b: Specify projected CRS using name-value argument

Specify the projected CRS of the raster reference object during creation by using the ProjectedCRS name-value argument.

R2015b: maprasterref is not recommended

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

• Create a reference object for a grid of rectangular cells referenced to world xy-coordinates by using the maprefcells function.

• Create a reference object for a grid of posting point samples referenced to world coordinates by using the maprefpostings function.