MapCellsReference

Reference raster cells to map coordinates

Description

For a 2-D raster of cells, a MapCellsReference object describes the relationship between the intrinsic coordinate system for the raster and a planar coordinate system. The object associates each element of the raster with a location in planar coordinates.

A MapCellsReference object assumes that the raster is sampled regularly in the world xy-coordinates of the map system. The sample spacing from row to row does not need to equal the sample spacing from column to column.

The intrinsic and world coordinate systems have a rectilinear relationship when the axes of the intrinsic and world coordinate systems align. The coordinate systems have a affine relationship when the intrinsic axes are rotated with respect to the world axes. An affine relationship allows for rotation and skew.

This image illustrates a 8-by-10 raster of cells in planar coordinates. The raster cells have an extent of 1 meter in x and y, cover x values in the range [40,50] in meters, and cover y values in the range [20,28] in meters. The boundary of the raster of cells is made up of the outermost boundaries of the outermost cells.

To reference a raster of postings to planar map coordinates, use a MapPostingsReference object instead.

Creation

You can use these functions to create MapCellsReference objects:

• readgeoraster — Import a raster data file as an array and a reference object.

• maprefcells — Create a map raster reference object by specifying the x and y world limits of the raster and either the size of the raster or the extent of the cells.

• maprasterref — Convert a world file to a map raster reference object.

• refmatToMapRasterReference — Convert a referencing matrix to a map raster reference object.

Properties

XWorldLimits — Limits of raster in world x-coordinates

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

Limits of raster in world x-coordinates, specified as a two-element row vector of the form [xMin xMax].

The value of the ProjectedCRS property determines the length units for the raster. This code shows how to find the length units for a raster associated with the map cells reference object R.

R.ProjectedCRS.LengthUnit

Example: [207000 209000]

Data Types: double

YWorldLimits — Limits of raster in world y-coordinates

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

Limits of raster in world y-coordinates, specified as a two-element row vector of the form [yMin yMax].

The value of the ProjectedCRS property determines the length units for the raster. This code shows how to find the length units for a raster associated with the map cells reference object R.

R.ProjectedCRS.LengthUnit

Example: [911000 913000]

Data Types: double

RasterSize — Number of rows and columns of the raster or image associated with the referencing object

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

Number of rows and columns of the raster or image associated with the referencing object, specified as a two-element vector, [m n], where m represents the number of rows and n the number of columns.

For convenience, you can assign a size vector having more than two elements. This enables assignments like R.RasterSize = size(RGB), where RGB is m-by-n-by-3. In cases like this, the object stores only the first two elements of the size vector and ignores the higher (nonspatial) dimensions.

Example: [200 300]

Data Types: double

RasterInterpretation — Geometric nature of the raster

Read-only: 'cells' (default)

This property is read-only.

Geometric nature of the raster, specified as 'cells'. The value 'cells' indicates that the raster comprises a grid of quadrangular cells, and is bounded on all sides by cell edges. For an m-by-n raster, points with an intrinsic x-coordinate of 1 or n or an intrinsic x-coordinate of 1 or m fall within the raster, not on its edges.

Data Types: char

ColumnsStartFrom — Edge from which column indexing starts

'south' (default) | 'north'

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

Example: 'south'

Data Types: char

RowsStartFrom — Edge from which row indexing starts

'west' (default) | 'east'

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

Example: 'east'

Data Types: char

CellExtentInWorldX — Extent in world x-coordinates of individual cells

1 (default) | positive numeric scalar

Extent in world x-coordinates of individual cells, specified as a positive numeric scalar. Distance between the eastern and western limits of a single raster cell. The value is the same for all cells in the raster.

Example: 2.5

Data Types: double

CellExtentInWorldY — Extent in world y-coordinates of individual cells

1 (default) | positive numeric scalar

Extent in world y-coordinates of individual cells, specified as a positive numeric scalar. Distance between the northern and southern limits of a single raster cell. The value is the same for all cells in the raster.

Example: 2.5

Data Types: double

RasterExtentInWorldX — Extent of the full raster or image as measured in the world system in a direction parallel to its rows

Read-only: 2 (default) | positive numeric scalar

This property is read-only.

Extent of the full raster or image as measured in the world system in a direction parallel to its rows, specified as a positive numeric scalar. In the case of a rectilinear geometry, which is most typical, this is the horizontal direction (east-west).

Data Types: double

RasterExtentInWorldY — Extent of the full raster or image as measured in the world system in a direction parallel to its columns

Read-only: 2 (default) | positive numeric scalar

This property is read-only.

Extent of the full raster or image as measured in the world system in a direction parallel to its columns, specified as a positive numeric scalar. In the case of a rectilinear geometry, which is most typical, this is the vertical direction (north-south).

Data Types: double

XIntrinsicLimits — Raster limits in intrinsic x-coordinates

Read-only: [0.5 2.5] (default) | two-element row vector of positive integers

This property is read-only.

Raster limits in intrinsic x-coordinates, specified as a two-element row vector of positive integers, [xMin xMax]. For an m-by-n raster, XIntrinsicLimits equals [0.5, m+0.5], because the RasterInterpretation is 'cells'.

Data Types: double

YIntrinsicLimits — Raster limits in intrinsic y-coordinates

Read-only: [0.5 2.5] (default) | two-element row vector of positive integers

This property is read-only.

Raster limits in intrinsic y-coordinates, specified as a two-element row vector of positive integers, [yMin yMax]. For an m-by-n raster, YIntrinsicLimits equals [0.5, m+0.5], because the RasterInterpretation is 'cells'.

Data Types: double

TransformationType — Type of geometric relationship between intrinsic and world systems

Read-only: 'rectilinear' (default) | 'affine'

This property is read-only.

Type of geometric relationship between the intrinsic coordinate system and the world coordinate system, specified as either 'rectilinear' or 'affine'. Its value is 'rectilinear' when world x depends only on intrinsic x and vice versa, and world y depends only on intrinsic y and vice versa. When the value is 'rectilinear', the image displays without rotation in the world system, although it might be flipped. Otherwise, the value is 'affine'.

Data Types: char

CoordinateSystemType — Type of coordinate system to which the image or raster is referenced

Read-only: 'planar' (default)

This property is read-only.

Type of coordinate system to which the image or raster is referenced, specified as 'planar'.

Data Types: char

ProjectedCRS — Projected coordinate reference system

[] (default) | projcrs object

Projected coordinate reference system (CRS), specified as a projcrs object. A projected CRS consists of a geographic CRS and several parameters that are used to transform coordinates to and from the geographic CRS.

The value of ProjectedCRS determines the length units for the raster. To find the length units, query the LengthUnit property of the projcrs object.

Object Functions

contains	Determine if geographic or map raster contains points
cropToBlock	Crop raster reference object to row and column limits of raster
firstCornerX	Return world x-coordinate of map raster index (1,1)
firstCornerY	Return world y-coordinate of map raster index (1,1)
intrinsicToWorld	Transform intrinsic to planar world coordinates
sizesMatch	Determine if geographic or map raster object and image or raster are size-compatible
worldFileMatrix	Return world file parameters for transformation
worldGrid	World coordinates of raster elements
worldToDiscrete	Convert planar world coordinates to discrete subscripts
worldToIntrinsic	Transform planar world to intrinsic coordinates

Examples

Display Planar Raster with Regularly Spaced Cell Centers

Import a land cover classification of Oahu, Hawaii as an array, a MapCellsReference object, and a colormap by using the readgeoraster function.

[Z,R,cmap] = readgeoraster('oahu_landcover.img');

View the properties of the MapCellsReference object.

R

R = 
  MapCellsReference with properties:

            XWorldLimits: [569857 645907]
            YWorldLimits: [2345284 2405884]
              RasterSize: [2020 2535]
    RasterInterpretation: 'cells'
        ColumnsStartFrom: 'north'
           RowsStartFrom: 'west'
      CellExtentInWorldX: 30
      CellExtentInWorldY: 30
    RasterExtentInWorldX: 76050
    RasterExtentInWorldY: 60600
        XIntrinsicLimits: [0.5 2535.5]
        YIntrinsicLimits: [0.5 2020.5]
      TransformationType: 'rectilinear'
    CoordinateSystemType: 'planar'
            ProjectedCRS: [1×1 projcrs]

Display the land cover classification on a map.

mapshow(Z,cmap,R)

More About

Intrinsic Coordinate System

An intrinsic coordinate system is a 2-D Cartesian coordinate system where:

• The x-axis is parallel to the rows of the raster. From column to column, the value of x increases by 1. At the center of a cell, the value of x has an integer value that is equal to the column index.

• The y-axis is parallel to the columns of the raster. From row to row, the value of y increases by 1. At the center of a cell, the value of y has an integer value equal to the row index.

Coordinates in an intrinsic coordinate system can correspond to the indices of the raster. For example, when column indexing starts from the north edge of the raster and row indexing starts from the west edge of the raster, the intrinsic coordinates x = 3.0, y = 5.0 correspond to the center point of the cell in row 5 and column 3.

Version History

Introduced in R2013b