geopolyshape

Polygon in geographic coordinates

Since R2021b

Description

A geopolyshape object represents a polygon or multipolygon in geographic coordinates. A polygon is a region bounded by a closed curve and can include interior holes. A multipolygon is an individual polygon shape that includes multiple nonintersecting regions.

Polygons and multipolygons are useful for defining areas of interest (AOIs). For more information about AOIs, see Define Areas of Interest.

To represent a polygon or multipolygon in planar coordinates, use a mappolyshape object instead.

Creation

To create geopolyshape objects, either:

• Import polygon data in geographic coordinates as a geospatial table using the readgeotable function, and then query the Shape variable of the table.

• Create a quadrangular AOI by using the aoiquad function.

• Create an AOI of circles by using the aoicircle function.

• Use the geopolyshape function (described here).

Syntax

shape = geopolyshape(lat,lon)

Description

shape = geopolyshape(lat,lon) creates a geopolyshape object or array of geopolyshape objects with vertices at the specified latitude and longitude coordinates. The sizes of lat, lon, and the geopolyshape object array shape match.

The geopolyshape function assumes that lat and lon define polygons with valid topology. A polygon has valid topology when:

• Region interiors are to the right as you trace boundaries from vertex to vertex.

• The boundaries have no self-intersections.

In general, the outer boundaries of polygons with valid topology have vertices in clockwise order and the interior holes have vertices in counterclockwise order.

Input Arguments

lat — Latitude coordinates

numeric vector | cell array of numeric vectors

Latitude coordinates, specified as a numeric vector or a cell array of numeric vectors.

• Create a polygon by specifying a vector, such as [39 45 19 39].

• Create a polygon with holes or a multipolygon by specifying a vector and including breaks between the hole and region boundaries as NaN values, such as [37 46 31 20 37 NaN 45 49 35 32 45 NaN 35 40 42 35].

• Create an array of polygons and multipolygons by specifying a cell array of vectors, such as {[37 46 31 20 37],[45 49 35 32 45 NaN 35 40 42 35]}.

The NaN values in lat must correspond to the NaN values in lon.

The size of lat must match the size of lon. For cell arrays, the size of the vector in each cell of lat must match the size of the vector in the corresponding cell of lon.

Data Types: double | cell

lon — Longitude coordinates

numeric vector | cell array of numeric vectors

Longitude coordinates, specified as a numeric vector or a cell array of numeric vectors.

• Create a polygon by specifying a vector, such as [-113 -49 -100 -113].

• Create a polygon with holes or a multipolygon by specifying a vector and including breaks between the hole and region boundaries as NaN values, such as [69 90 105 79 69 NaN 6 52 43 14 6 NaN 18 32 22 18].

• Create an array of polygons and multipolygons by specifying a cell array of vectors, such as {[69 90 105 79 69],[6 52 43 14 6 NaN 18 32 22 18]}.

The NaN values in lat must correspond to the NaN values in lon.

The size of lat must match the size of lon. For cell arrays, the size of the vector in each cell of lat must match the size of the vector in the corresponding cell of lon.

Data Types: double | cell

Properties

NumRegions — Number of polygon regions

Read-only: array of nonnegative integers

This property is read-only.

Number of polygon regions, returned as an array of nonnegative integers. A region is a connected area such that any two points within the area can be connected by a path entirely within the area. Regions may contain holes.

For a geopolyshape scalar, the value of NumRegions is 1 when the geopolyshape object represents a single polygon and more than 1 when the object represents a multipolygon.

For a geopolyshape array, the size of NumRegions matches the size of the array.

Data Types: double

NumHoles — Number of holes

Read-only: array of nonnegative integers

This property is read-only.

Number of holes in the polygon or multipolygon, returned as an array of nonnegative integers.

For a geopolyshape array, the size of NumHoles matches the size of the array.

Data Types: double

Geometry — Geometric type

Read-only: "polygon" (default)

This property is read-only.

Geometric type, returned as "polygon".

Data Types: string

CoordinateSystemType — Coordinate system type

Read-only: "geographic" (default)

This property is read-only.

Coordinate system type, returned as "geographic".

Data Types: string

GeographicCRS — Geographic coordinate reference system

[] (default) | geocrs object

Geographic coordinate reference system (CRS), specified as a geocrs object. A geographic CRS consists of a datum (including its ellipsoid), prime meridian, and angular unit of measurement.

Object Functions

Visualize and Query

geoplot	Plot points, lines, and polygons on map
bounds	Bounds of shape in geographic or planar coordinates
isinterior	Query geographic or planar points in polygon
ismultipoint	Determine which array elements are multipoint shapes

Modify

geoclip	Clip geographic shape to latitude-longitude limits or polygon
buffer	Buffer shape in geographic or planar coordinates

Geometric Quantities

area	Area of polygon shape in geographic or planar coordinates
perimeter	Perimeter of polygon shape in geographic or planar coordinates

Boolean Operations

intersect	Intersection of shapes in geographic or planar coordinates
union	Union of shapes in geographic or planar coordinates
subtract	Difference of shapes in geographic or planar coordinates
xor	Exclusive OR of shapes in geographic or planar coordinates

Examples

Get Information About Imported Geographic Polygons

Import a shapefile containing worldwide land areas as a geospatial table. The shapefile represents the land areas using polygons.

GT = readgeotable("landareas.shp");

Create a subtable that contains the polygon representing Africa, Europe, and Asia. Get information about the polygon by querying the Shape variable of the table.

row = GT.Name == "Africa and Eurasia";
rowGT = GT(row,:);
rowGT.Shape

ans = 
  geopolyshape with properties:

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

Display the polygon on a world map.

worldmap([-45 80],[-25 195])
geoshow(rowGT)

Create Geographic Polygons and Multipolygons

Create an individual polygon with no holes as a geopolyshape scalar. Specify the geographic CRS as the World Geodetic System of 1984, which has the EPSG code 4326.

lat = [39 45 19 39];
lon = [-113 -49 -100 -113];
polyshp = geopolyshape(lat,lon);

g = geocrs(4326);
polyshp.GeographicCRS = g

polyshp = 
  geopolyshape with properties:

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

Create a multipolygon with two regions and one hole as a geopolyshape scalar.

lat = [37 46 31 20 37 NaN 45 49 35 32 45 NaN 35 40 42 35];
lon = [69 90 105 79 69 NaN 6 52 43 14 6 NaN 18 32 22 18];
multipolygon = geopolyshape(lat,lon);
multipolygon.GeographicCRS = g

multipolygon = 
  geopolyshape with properties:

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

Create two individual polygons as a 1-by-2 geopolyshape array. The second polygon contains a hole.

lat = {[37 46 31 20 37],[45 49 35 32 45 NaN 35 40 42 35]};
lon = {[69 90 105 79 69],[6 52 43 14 6 NaN 18 32 22 18]};
polyArray = geopolyshape(lat,lon);
polyArray.GeographicCRS = g

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

Version History

Introduced in R2021b