Main Content

geopolyshape

Polygon in geographic coordinates

Since R2021b

expand all in page

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.

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.

  • Use the geopolyshape function (described here).

Syntax

shape = geopolyshape(lat,lon)

Description

example

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

expand all

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

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

expand all

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

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

This property is read-only.

Geometric type, returned as "polygon".

Data Types: string

This property is read-only.

Coordinate system type, returned as "geographic".

Data Types: string

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

geoplotPlot points, lines, and polygons on map
geoclipClip geographic shape to latitude-longitude limits
isinteriorQuery geographic or planar points in polygon
ismultipointDetermine which array elements are multipoint shapes

Examples

collapse all

Open Live Script

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: [1x1 geocrs]

Display the polygon on a world map.

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

Open Live Script

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: [1x1 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: [1x1 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 object
  1x2 geopolyshape array with properties:

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

Version History

Introduced in R2021b

See Also

Functions

Objects

Topics