maprasterref

Construct map raster reference object

collapse all in page

Use the maprefcells function or the maprefpostings function instead, except when constructing a raster reference object from a world file matrix.

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 regular raster of cells in planar map coordinates using the specified world file matrix W and raster size rasterSize.

R = maprasterref(W,rasterSize,rasterInterpretation), where rasterInterpretation is 'postings', specifies that the raster contains regularly posted samples in planar map coordinates. The default for rasterInterpretation is 'cells', which specifies a regular raster of cells.

R = maprasterref(Name,Value) accepts a list of name-value pairs that are used to assign selected properties when initializing a map raster reference object.

Input Arguments

collapse all

World file matrix, specified as a 2-by-3 numeric array. Each of the six elements in W matches one of the lines in a world file that defines the transformation in raster referencing object R.

Data Types: double

Number of rows (m) and columns (n) of the raster or image associated with the referencing object, specified as a two-element vector [m n]. For convenience, you may assign a size vector having more than two elements to RasterSize. This flexibility enables assignments like R.RasterSize = size(RGB), for example, where RGB is m-by-n-by-3. However, in such cases, only the first two elements of the size vector are actually stored. The higher (non-spatial) dimensions are ignored

Controls handling of raster edges. The rasterInterpretation input is optional, and can equal either 'cells' or 'postings'.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

You can include any of the following properties, overriding their default values as needed. Alternatively, you may omit any or all properties when constructing your map raster reference object. Then, you can customize the result by resetting properties from this list one at a time. This name-value syntax always results in an object with a 'rectilinear' TransformationType. If your image is rotated with respect to the world coordinate axes, you need an object with a TransformationType of 'affine'. Alternately, you can provide an appropriate world file matrix as input, as shown in the third syntax. You cannot do it by resetting properties of an existing rectilinear map raster reference object.

'XLimWorld'

Limits of raster in world x

Two-element row vector of the form [xMin xMax].

Default: [0.5 2.5]

'YLimWorld'

Limits of raster in world y

Two-element row vector of the form [yMin yMax].

Default: [0.5 2.5]

'RasterSize'

Two-element vector [M N] specifying the number of rows (M) and columns (N) of the raster or image associated with the referencing object. For convenience, you may assign a size vector having more than two elements to RasterSize. This flexibility enables assignments like R.RasterSize = size(RGB), for example, where RGB is M-by-N-by-3. However, in such cases, only the first two elements of the size vector are actually stored. The higher (non-spatial) dimensions are ignored.

Default: [2 2]

'RasterInterpretation'

Controls handling of raster edges, specified as either 'cells' or 'postings'.

Default: 'cells'

'ColumnsStartFrom'

Edge where column indexing starts, specified as either 'south' or 'north'.

Default: 'south'

'RowsStartFrom'

Edge from which row indexing starts, specified as either 'west' or 'east'.

Default: 'west'

Output Arguments

collapse all

Map raster, specified as a MapCellsReference or MapPostingsReference object.

Examples

collapse all

Open Live Script

Construct a referencing object for an 1000-by-2000 image with square, half-meter pixels referenced to a planar map coordinate system (the "world" system). The X-limits in the world system are 207000 and 208000. The Y-limits are 912500 and 913000. The image follows the popular convention in which world X increases from column to column and world Y decreases from row to row.

R = maprasterref('RasterSize', [1000 2000], ...
          'YWorldLimits', [912500 913000], 'ColumnsStartFrom','north', ...
          'XWorldLimits', [207000 208000])
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: []
Open Live Script

Create a default raster reference object.

R = maprasterref
R = 
  MapCellsReference with properties:

            XWorldLimits: [0.5 2.5]
            YWorldLimits: [0.5 2.5]
              RasterSize: [2 2]
    RasterInterpretation: 'cells'
        ColumnsStartFrom: 'south'
           RowsStartFrom: 'west'
      CellExtentInWorldX: 1
      CellExtentInWorldY: 1
    RasterExtentInWorldX: 2
    RasterExtentInWorldY: 2
        XIntrinsicLimits: [0.5 2.5]
        YIntrinsicLimits: [0.5 2.5]
      TransformationType: 'rectilinear'
    CoordinateSystemType: 'planar'
            ProjectedCRS: []

Set fields in the raster reference object.

R.XWorldLimits = [207000 208000];
R.YWorldLimits = [912500 913000];
R.ColumnsStartFrom = 'north';
R.RasterSize = [1000 2000]
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: []
Open Live Script

Create a world file matrix.

W = [0.5   0.0   207000.25; ...
     0.0  -0.5   912999.75];

Specify the size of the image.

rasterSize = [1000 2000];

Create the map raster reference object.

R = maprasterref(W, rasterSize)
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: []

See Also

Functions

Objects

Mapping Toolbox Documentation

Support