aoicircle

Define circular area of interest

Since R2024b

collapse all in page

Syntax

aoi = aoicircle(lat,lon,radius)
aoi = aoicircle(lat,lon,radius,gcrs)
aoi = aoicircle(x,y,radius,pcrs)
aoi = aoicircle(GT,radius)
aoi = aoicircle(shape,radius)

Description

Numeric Data

aoi = aoicircle(lat,lon,radius) defines an area of interest (AOI) by creating circles with the specified radius that are centered at the specified geographic coordinates.

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

example

aoi = aoicircle(x,y,radius,pcrs) uses the specified projected coordinates as the center points. The pcrs argument specifies the projected CRS for the coordinates.

example

Geospatial Table and Shape Data

aoi = aoicircle(GT,radius) uses the point shape objects within the specified geospatial table as the center points.

example

aoi = aoicircle(shape,radius) uses the specified point shape objects as the center points.

example

Examples

collapse all

Open Live Script

Read the geographic coordinates of European capitals into the workspace. Specify the geographic CRS as the World Geodetic System of 1984, which has the EPSG code 4326.

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

Create an AOI of circles from the geographic coordinates. Specify the radius of each circle as 2 degrees. When you pass geographic coordinates to the aoicircle function, the function represents the AOI using a scalar polygon shape in geographic coordinates.

aoi = aoicircle(lat,lon,2,gcrs)
aoi = 
  geopolyshape with properties:

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

Display the AOI and the capitals on a map. 

geobasemap topographic
geoplot(aoi)
hold on
geoplot(lat,lon,"k.",MarkerSize=10)

Open Live Script

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 = [236266 235743 234685 232989 236536 234591 235741 237114 235741 236548];
y = [900974 900355 901429 901884 901901 901892 900663 900670 900725 899587];
pcrs = projcrs(26986);

When you pass projected coordinates to the aoicircle function, you must specify the radius of each circle using the length unit of the projected CRS. Find the length unit. The result indicates that you must specify radius in meters. 

pcrs.LengthUnit
ans = 
"meter"

Create an AOI of circles. Specify the circle centers using the projected coordinates, and specify the radius of each circle as 200 meters. When you pass projected coordinates to the aoicircle function, the function represents the AOI using a scalar polygon shape in projected coordinates.

aoi = aoicircle(x,y,200,pcrs)
aoi = 
  mappolyshape with properties:

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

Display the AOI on a map. 

geobasemap streets
geoplot(aoi)

Figure contains an axes object with type geoaxes. The geoaxes object contains an object of type polygon.

Open Live Script

Create a geospatial table by geocoding several Australian cities. The table represents the cities using point shapes in geographic coordinates. 

cities = ["Adelaide","Melbourne","Canberra","Sydney","Brisbane"];
GT = geocode(cities,"city");
GT.Shape
ans = 
  5×1 geopointshape array with properties:

               NumPoints: [5×1 double]
                Latitude: [5×1 double]
               Longitude: [5×1 double]
                Geometry: "point"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Create an AOI of circles from the shapes in the geospatial table. Specify the radius of each circle as 3 degrees. When you pass data in geographic coordinates to the aoicircle function, the function represents the AOI using a scalar polygon shape in geographic coordinates. 

aoi = aoicircle(GT,3)
aoi = 
  geopolyshape with properties:

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

Display the AOI and the cities on a map. 

geoplot(aoi)
hold on
geoplot(GT,"k.",MarkerSize=20)

Open Live Script

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 = [236266 235743 234685 232989 236536 234591 235741 237114 235741 236548];
y = [900974 900355 901429 901884 901901 901892 900663 900670 900725 899587];
pcrs = projcrs(26986);

Create a point shape object from the coordinates and projected CRS. 

shape = mappointshape(x,y);
shape.ProjectedCRS = pcrs;

When you pass projected coordinates to the aoicircle function, you must specify the radius of each circle using the length unit of the projected CRS. Find the length unit. The result indicates that you must specify the radius in meters. 

pcrs.LengthUnit
ans = 
"meter"

Create an AOI of circles from the point shape. Specify the radius of each circle as 300 meters. When you pass data in projected coordinates to the aoicircle function, the function represents the AOI using a scalar polygon shape in projected coordinates.

aoi = aoicircle(shape,300)
aoi = 
  mappolyshape with properties:

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

Display the AOI and the places on a map. 

geoplot(aoi)
hold on
geobasemap topographic
geoplot(shape,".k",MarkerSize=10)

Figure contains an axes object with type geoaxes. The geoaxes object contains 2 objects of type polygon, point.

Open Live Script

Create a point shape in geographic coordinates that represents Paris, France. Specify the geographic CRS as the World Geodetic System of 1984, which has the EPSG code 4326.

shape = geopointshape(48.86,2.35);
shape.GeographicCRS = geocrs(4326);

Create an AOI from the point shape. Specify the radius as 0.5 degrees. 

aoi = aoicircle(shape,0.5);

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 = "parisAOI.shp";
shapewrite(aoiGT,filename)

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

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

Input Arguments

collapse all

Latitudes of the center points in degrees, specified as a numeric array with elements in the range [–90, 90]. The sizes of lat and lon must match.

Longitudes of the center points in degrees, specified as a numeric array. The sizes of lat and lon must match.

Radius of the circles, specified as a numeric scalar.

The units you use to specify radius and the way the function interprets radius depends on the type of coordinates you use to specify the center points of the circles.

Type of CoordinatesUnitsInterpretation
Geographic coordinates

Specify radius using degrees. The value you specify must be less than or equal to 90.

radius is a spherical distance along a great circle or geodesic path.

Projected coordinates

Specify radius using the length unit of the projected CRS associated with the coordinates. To find the length unit, get the projcrs object that is associated with the coordinates. Then, query the LengthUnit property of the projcrs object.

For example, for a mappointshape object shp, the length unit is shp.ProjectedCRS.LengthUnit.

radius is a linear distance along the Cartesian plane.

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

x-coordinates of the center points, specified as a numeric array. The sizes of x and y must match.

The units for x depend on the length unit of pcrs. You can find the length unit by querying the LengthUnit property of the projcrs object, pcrs.

y-coordinates of the center points, specified as a numeric array. The sizes of x and y must match.

The units for y depend on the length unit of pcrs. You can find the length unit by querying the LengthUnit property of the projcrs object, pcrs.

Projected CRS of the coordinates, specified as a projcrs object.

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 aoicircle function requires the Shape variable to contain only geopointshape or only mappointshape objects. The ProjectedCRS property of mappointshape objects must not be empty.

Point shapes, specified as one of these options:

  • An array of geopointshape objects — Point shapes in geographic coordinates.

  • An array of mappointshape objects — Point shapes in projected coordinates. The ProjectedCRS property of the objects must not be empty.

You can also specify this argument as a scalar point shape object.

Output Arguments

collapse all

AOI composed of circles, 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.

When you specify multiple center points, the AOI can contain multiple parts.

More About

collapse all

Version History

Introduced in R2024b

See Also

Functions

Objects

Topics