aoiquad

Define quadrangular or rectangular area of interest

Since R2024b

Syntax

aoi = aoiquad(lat,lon)

aoi = aoiquad(lat,lon,gcrs)

aoi = aoiquad(x,y,pcrs)

aoi = aoiquad(GT)

aoi = aoiquad(shape)

aoi = aoiquad(R)

aoi = aoiquad(___,InterpolationMethod=method)

Description

Numeric Data

aoi = aoiquad(lat,lon) defines an area of interest (AOI) for the specified geographic coordinates by creating a quadrangle that bounds the coordinates. This syntax is also useful for defining an AOI from latitude-longitude limits.

aoi = aoiquad(lat,lon,gcrs) specifies the geographic coordinate reference system (CRS) for the coordinates.

aoi = aoiquad(x,y,pcrs) defines an AOI for the specified projected coordinates by creating a rectangle that bounds the coordinates. The pcrs argument specifies the projected CRS for the coordinates. This syntax is also useful for defining an AOI from xy-limits.

Geospatial Table and Shape Data

aoi = aoiquad(GT) defines an AOI for the shape objects in the specified geospatial table. The output is a quadrangle when the input is in geographic coordinates and a rectangle when the input is in projected coordinates.

aoi = aoiquad(shape) defines an AOI for the specified shape objects.

Raster Data

aoi = aoiquad(R) defines an AOI using the geographic or world limits stored in the specified raster reference object. The output is a quadrangle when the input is in geographic coordinates and a rectangle when the input is in projected coordinates.

Interpolation Method

aoi = aoiquad(___,InterpolationMethod=method) specifies the interpolation method to use when calculating the boundaries of the AOI, in addition to any combination of input arguments from the previous syntaxes. (since R2025a)

Examples

Define Quadrangular AOI from Latitude-Longitude Limits

Specify the latitude and longitude limits for a region surrounding the island of Kyushu, Japan. Specify the geographic CRS as the World Geodetic System of 1984, which has the EPSG code 4326.

latlim = [31 34];
lonlim = [129 132.5];
gcrs = geocrs(4326);

Create a quadrangular AOI from the limits. When you pass geographic coordinates to the aoiquad function, the function represents the AOI using a scalar polygon shape in geographic coordinates.

aoi = aoiquad(latlim,lonlim,gcrs)

aoi = 
  geopolyshape with properties:

              NumRegions: 1
                NumHoles: 0
                Geometry: "polygon"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

View satellite imagery for the region surrounding the AOI by plotting the AOI with no face or edge color.

geobasemap satellite
geoplot(aoi,FaceColor="none",EdgeColor="none")

Define Rectangular AOI from Projected Coordinates

Specify the projected coordinates for several places in Boston. Specify the projected CRS for the points as NAD83 / Massachusetts Mainland, which has the EPSG code 26986.

x = [234028 233569 235739 236266 234685 236536 234591 237114 235741 236548];
y = [900038 900190 901126 900974 901429 901901 901892 900670 900725 899587];
pcrs = projcrs(26986);

Create a rectangular AOI from the coordinates and the projected CRS. When you pass projected coordinates to the aoiquad function, the function represents the AOI using a scalar polygon shape in projected coordinates.

aoi = aoiquad(x,y,pcrs)

aoi = 
  mappolyshape with properties:

              NumRegions: 1
                NumHoles: 0
                Geometry: "polygon"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]

Display the AOI on a map.

geobasemap streets
geoplot(aoi)

Define Rectangular AOI from Geospatial Table

Read road data for an area in Concord, MA as a geospatial table. The table represents the roads using line shapes in projected coordinates.

GT = readgeotable("concord_roads.shp");
GT.Shape

ans=609×1 maplineshape array with properties:
                NumParts: [609×1 double]
                Geometry: "line"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]
      ⋮

Create a rectangular AOI from the shapes in the geospatial table. When you pass data in projected coordinates to the aoiquad function, the function represents the AOI using a scalar polygon shape in projected coordinates.

aoi = aoiquad(GT)

aoi = 
  mappolyshape with properties:

              NumRegions: 1
                NumHoles: 0
                Geometry: "polygon"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]

Display the road data and the boundary of the AOI on a map. Display the boundary of the AOI using a thick, dashed line.

geoplot(GT)
hold on
geoplot(aoi,LineWidth=2,LineStyle="--",FaceColor="none")

Define Quadrangular AOI from Geocoded Placename

Create a geospatial table by geocoding the states of Kansas and Oklahoma. The table represents the states using polygon shapes in geographic coordinates.

GT = geocode(["Kansas","Oklahoma"],"state");
GT.Shape

ans=2×1 geopolyshape array with properties:
              NumRegions: [2×1 double]
                NumHoles: [2×1 double]
                Geometry: "polygon"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Create a quadrangular AOI from the shapes in the geospatial table. When you pass data in geographic coordinates to the aoiquad function, the function represents the AOI using a scalar polygon shape in geographic coordinates.

aoi = aoiquad(GT)

aoi = 
  geopolyshape with properties:

              NumRegions: 1
                NumHoles: 0
                Geometry: "polygon"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Display the states and the boundary of the AOI on a map. Display the boundary of the AOI using a thick, dashed line.

geobasemap colorterrain
geoplot(GT)
hold on
geoplot(aoi,LineWidth=2,LineStyle="--",FaceColor="none")

Define Quadrangular AOI from Shape Object

Read the geographic coordinates of European capitals into the workspace. Create a point shape object from the coordinates. Specify the geographic CRS as the World Geodetic System of 1984, which has the EPSG code 4326.

[lat,lon] = readvars("european_capitals.txt");
shape = geopointshape(lat,lon);
shape.GeographicCRS = geocrs(4326);

Create a quadrangular AOI from the shapes. When you pass data in geographic coordinates to the aoiquad function, the function represents the AOI using a scalar polygon shape in geographic coordinates.

aoi = aoiquad(shape);

Create a map using the latitude and longitude limits of the AOI. Note that, to maintain the aspect ratio of the map, the geolimits function typically uses wider limits than the limits you specify.

[latlim,lonlim] = bounds(aoi);
geolimits(latlim,lonlim)

Define Quadrangular AOI From Raster Data

Get the AOI for a raster data file. Then, display the AOI on a map. Displaying the AOI for a raster data file enables you to view the footprint of the file.

Get information about a raster data file by creating a RasterInfo object. Extract the raster reference from the object. The raster reference indicates that the raster is a grid of rectangular cells referenced to projected xy-coordinates.

info = georasterinfo("MountDartmouth-ft.grd");
R = info.RasterReference

R = 
  MapCellsReference with properties:

            XWorldLimits: [300390 310770]
            YWorldLimits: [4902150 4916340]
              RasterSize: [473 346]
    RasterInterpretation: 'cells'
        ColumnsStartFrom: 'north'
           RowsStartFrom: 'west'
      CellExtentInWorldX: 30
      CellExtentInWorldY: 30
    RasterExtentInWorldX: 10380
    RasterExtentInWorldY: 14190
        XIntrinsicLimits: [0.5 346.5]
        YIntrinsicLimits: [0.5 473.5]
      TransformationType: 'rectilinear'
    CoordinateSystemType: 'planar'
            ProjectedCRS: [1×1 projcrs]

Create a rectangular AOI from the raster reference. When you pass data in projected coordinates to the aoiquad function, the function represents the AOI using a scalar polygon shape in projected coordinates.

aoi = aoiquad(R)

aoi = 
  mappolyshape with properties:

              NumRegions: 1
                NumHoles: 0
                Geometry: "polygon"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]

Note that the bounds of the AOI match the XWorldLimits and YWorldLimits properties of the raster reference.

[xlimits,ylimits] = bounds(aoi);
isequal(xlimits,R.XWorldLimits) && isequal(ylimits,R.YWorldLimits)

ans = logical
   1

Display the AOI on a map. The AOI represents the footprint of the raster data file.

geobasemap topographic
geoplot(aoi)

Specify Interpolation Method for Quadrangular AOI

Since R2025a

By default, the aoiquad function creates AOIs with boundaries that follow linear paths. Create an AOI with boundaries that follow great-circle or geodesic paths by using the InterpolationMethod name-value argument.

Create a geospatial table by geocoding the cities of Denver, Colorado and Paris, France. The table represents the cities using point shapes in geographic coordinates.

cities = readgeotable("worldcities.shp");
GT = geocode(["Denver","Paris"],cities)

GT=2×2 table
             Shape               Name  
    _______________________    ________

    (39.6888°N, 104.9425°W)    "Denver"
    (48.8708°N,   2.4131°E)    "Paris" 

Create a quadrangular AOI from the shapes in the geospatial table. Calculate AOI boundaries that follow geodesic paths by specifying the InterpolationMethod name-value argument as "great-circle".

aoi = aoiquad(GT,InterpolationMethod="great-circle");

Find points along a geodesic track from Denver to Paris by using the interpm function.

lat = GT.Shape.Latitude;
lon = GT.Shape.Longitude;
[lattrk,lontrk] = interpm(lat,lon,0.5,"gc");

Display the AOI and the geodesic track on a map.

figure
geoplot(aoi)
hold on
geoplot(lattrk,lontrk)

Export Quadrangular AOI to Shapefile

Export the footprint of a raster data file to a shapefile.

Get information about a DTED file by creating a RasterInfo object. Create an AOI from the raster reference that is stored in the RasterInfo object.

info = georasterinfo("n40_w106_3arc_v2.dt1");
R = info.RasterReference;
aoi = aoiquad(R);

Create a geospatial table from the AOI. Then, export the geospatial table to a shapefile by using the shapewrite function.

aoiGT = table(aoi,VariableName="Shape");
filename = "n40_w106_footprint.shp";
shapewrite(aoiGT,filename)

Read the shapefile into the workspace, and view the AOI.

GT = readgeotable(filename);
geobasemap topographic
geoplot(GT)

Input Arguments

lat — Latitude coordinates in degrees

numeric array with elements in range [–90, 90]

Latitude coordinates in degrees, specified as a numeric array with elements in the range [–90, 90]. This argument is also useful for specifying latitude limits.

The sizes of lat and lon must match. If lat and lon are scalar, then the function creates the AOI by calculating a small buffer around the point.

lon — Longitude coordinates in degrees

numeric array

Longitude coordinates in degrees, specified as a numeric array. This argument is also useful for specifying longitude limits.

The sizes of lat and lon must match. If lat and lon are scalar, then the function creates the AOI by calculating a small buffer around the point.

gcrs — Geographic CRS of latitude and longitude coordinates

geocrs object

Geographic CRS of the latitude and longitude coordinates, specified as a geocrs object.

x — x-coordinates

numeric array

x-coordinates, specified as a numeric array. This argument is also useful for specifying x-limits.

The sizes of x and y must match. If x and y are scalar, then the function creates the AOI by calculating a small buffer around the point.

y — y-coordinates

numeric array

y-coordinates, specified as a numeric array. This argument is also useful for specifying y-limits.

The sizes of x and y must match. If x and y are scalar, then the function creates the AOI by calculating a small buffer around the point.

pcrs — Projected CRS for xy-coordinates

projcrs object

Projected CRS for the xy-coordinates, specified as a projcrs object.

GT — Geospatial table

geospatial table

Geospatial table. A geospatial table is a table or timetable object with a Shape variable that contains point, line, or polygon shapes. For more information about geospatial tables, see Create Geospatial Tables.

The ProjectedCRS properties of mappointshape, maplineshape, and mappolyshape objects within the Shape variable must not be empty.

shape — Point, line, or polygon shapes

vector of geopointshape, geolineshape, or geopolyshape objects | vector of mappointshape, maplineshape, or mappolyshape objects

Point, line, or polygon shapes, specified as one of these options:

• A vector of geopointshape, geolineshape, or geopolyshape objects — Point, line, or polygon shapes in geographic coordinates.

• A vector of mappointshape, maplineshape, or mappolyshape objects — Point, line, or polygon shapes in projected coordinates. The ProjectedCRS properties of the shapes must not be empty.

For each option, you can include a combination of point, line, and polygon shapes. You can also specify this argument as a scalar point, line, or polygon shape.

R — Raster reference

array of GeographicCellsReference objects | array of GeographicPostingsReference objects | array of MapCellsReference objects | array of MapPostingsReference objects

Raster reference, specified one of these options:

• An array of GeographicCellsReference objects — Raster reference for a grid of quadrangular cells in geographic coordinates.

• An array of GeographicPostingsReference objects — Raster reference for a grid of posting point samples in geographic coordinates.

• An array of MapCellsReference objects — Raster reference for a grid of quadrangular cells in projected coordinates.

• An array of MapPostingsReference objects — Raster reference for a grid of posting point samples in projected coordinates.

You can also specify this argument as a scalar object.

The ProjectedCRS properties of MapCellsReference and MapPostingsReference objects must not be empty.

method — Interpolation method

"linear" (default) | "great-circle"

Since R2025a

Interpolation method to use when calculating the boundary of the AOI, specified as one of these options:

• "linear" — Create the boundary of the AOI by interpolating points along a linear path.

• "great-circle" — Create the boundary of the AOI by interpolating points along a great-circle or geodesic path. To use this interpolation method, you must specify data in geographic coordinates.

Data Types: char | string

Output Arguments

aoi — Quadrangular or rectangular AOI

scalar geopolyshape object | scalar mappolyshape object

Quadrangular or rectangular AOI, returned as one of these options:

• A scalar geopolyshape object, when you specify the input using geographic coordinates.

• A scalar mappolyshape object, when you specify the input using projected coordinates.

More About

Area of Interest

An area of interest (AOI) defines a focus area for geospatial analysis and visualization. Mapping Toolbox™ represents AOIs using polygon shape objects. A scalar geopolyshape object represents an AOI in geographic coordinates, and a scalar mappolyshape object represents an AOI in projected coordinates.

Version History

Introduced in R2024b

R2025a: Create AOIs with boundaries that follow great-circle paths

Create an AOI with boundaries that follow great-circle or geodesic paths by specifying the InterpolationMethod name-value argument.