Main Content

maptrims

(Removed) Trim regular data grid to latitude-longitude quadrangle

maptrims has been removed. Use the geocrop function instead. For more information, see Compatibility Considerations.

Syntax

[Z_trimmed] = maptrims(Z,R,latlim,lonlim)
[Z_trimmed] = maptrims(Z,R,latlim,lonlim,cellDensity)
[Z_trimmed, R_trimmed] = maptrims(...)

Description

[Z_trimmed] = maptrims(Z,R,latlim,lonlim) trims a regular data grid Z to the region specified by latlim and lonlim. By default, the output grid Z_trimmed has the same sample size as the input. R can be a geographic raster reference object, a referencing vector, or a referencing matrix. If R is a geographic raster reference object, its RasterSize property must be consistent with size(Z) and its RasterInterpretation must be 'cells'.

If R is a referencing vector, it must be a 1-by-3 vector with elements:

[cells/degree northern_latitude_limit western_longitude_limit]
If R is a referencing matrix, it must be 3-by-2 and transform raster row and column indices to/from geographic coordinates according to:
[lon lat] = [row col 1] * R
If R is a referencing matrix, it must define a (non-rotational, non-skewed) relationship in which each column of the data grid falls along a meridian and each row falls along a parallel. latlim and lonlim are two-element vectors, defining the latitude and longitude limits, respectively. The latlim vector has the form:

[southern_limit northern_limit]

Likewise, the lonlim vector has the form:

[western_limit eastern_limit]

When an individual value in latlim or lonlim corresponds to a parallel or meridian that runs precisely along cell boundaries, the output grid will extend all the way to that limit. But if a limiting parallel or meridian cuts through a column or row of input cells, then the limit will be adjusted inward. In other words, the requested limits will be truncated as necessary to avoid partial cells.

[Z_trimmed] = maptrims(Z,R,latlim,lonlim,cellDensity) uses the scalar cellDensity to reduce the size of the output. If R is a referencing vector, then R(1) must be evenly divisible by cellDensity. If R is a referencing matrix, then the inverse of each element in the first two rows (containing "deltaLat" and "deltaLon") must be evenly divisible by cellDensity.

[Z_trimmed, R_trimmed] = maptrims(...) returns a referencing vector, matrix, or object for the trimmed data grid. If R is a referencing vector, then R_trimmed is a referencing vector. If R is a referencing matrix, then R_trimmed is a referencing matrix. If R is a geographic raster reference object, then R_trimmed is either a geographic raster reference object (when Z_trimmed is non-empty) or [] (when Z_trimmed is empty).

Examples

Load elevation raster data and a geographic cells reference object. Then, trim the data to the specified latitude and longitude limits.

load topo60c
[subgrid,subR] = maptrims(topo60c,topo60cR,...
                              [80.25 85.3],[165.2 170.7])
subgrid =
       -2826       -2810       -2802       -2793
       -2915       -2913       -2905       -2884
       -3192       -3186       -3165       -3122
       -3399       -3324       -3273       -3214

subR = 

  GeographicCellsReference with properties:

             LatitudeLimits: [81 85]
            LongitudeLimits: [166 170]
                 RasterSize: [4 4]
       RasterInterpretation: 'cells'
           ColumnsStartFrom: 'south'
              RowsStartFrom: 'west'
       CellExtentInLatitude: 1
      CellExtentInLongitude: 1
     RasterExtentInLatitude: 4
    RasterExtentInLongitude: 4
           XIntrinsicLimits: [0.5 4.5]
           YIntrinsicLimits: [0.5 4.5]
       CoordinateSystemType: 'geographic'
                  AngleUnit: 'degree'

The upper left corner of the grid might differ slightly from that of the requested region. The maptrims function uses the corner coordinates of the first cell inside the limits.

Version History

Introduced before R2006a

expand all

R2023b: Removed

Some functions that accept referencing vectors or referencing matrices as input have been removed, including the maptrims function. Use a geographic reference object and the geocrop function instead. Reference objects have several advantages over referencing vectors and matrices.

  • Unlike referencing vectors and matrices, reference objects have properties that document the size of the associated raster, its geographic limits, and the direction of its rows and columns. For more information about reference object properties, see the GeographicCellsReference and GeographicPostingsReference objects.

  • Manipulate the limits of geographic rasters associated with reference objects using the geocrop function.

  • Manipulate the size and resolution of geographic rasters associated with reference objects using the georesize function.

To update your code, first create a reference object for either a raster of cells using the georefcells function or a raster of regularly posted samples using the georefpostings function. Alternatively, convert from a referencing vector or a referencing matrix to a reference object using the refvecToGeoRasterReference or refmatToGeoRasterReference function, respectively.

Then, replace instances of the maptrims function with the geocrop function using these patterns.

RemovedRecommended
[B,RB] = maptrims(A,R,latlim,lonlim);
[B,RB] = geocrop(A,R,latlim,lonlim)
[B,RB] = maptrims(A,R,latlim,lonlim,cellDensity);
[B,RB] = geocrop(A,R,latlim,lonlim)
latscale = cellDensity * RB.CellExtentInLatitude;
lonscale = cellDensity * RB.CellExtentInLongitude;
[B,RB] = georesize(B,RB,latscale,lonscale,'nearest');

The limits of the reference object returned by the geocrop function may be larger than the limits returned by the maptrims function.