mappointshape

Point shape in planar coordinates

Since R2021b

Description

A mappointshape object represents a point or multipoint in planar coordinates. A multipoint is an individual point shape that contains a set of point locations.

To represent a point or multipoint in geographic coordinates, use a geopointshape object instead.

Creation

To create mappointshape objects, either:

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

• Use the mappointshape function (described here).

Syntax

shape = mappointshape(x,y)

Description

shape = mappointshape(x,y) creates a mappointshape object or array of mappointshape objects with the specified x- and y-coordinates. The sizes of x, y, and the mappointshape object array shape match.

Input Arguments

x — x-coordinates

numeric array | cell array of numeric arrays

x-coordinates, specified as a numeric array or a cell array of numeric arrays.

• Create a point by specifying a scalar, such as 39.

• Create a multipoint by specifying an array within a cell, such as {[38 -30 29]}.

• Create an array of points by specifying an array, such as [38 -30 29].

• Create an array of points and multipoints by specifying a cell array of numeric arrays, such as {39,[38 -30 29]}.

Create placeholders for points with missing data by including NaN values. The NaN values in x must correspond to the NaN values in y.

The size of x must match the size of y. For cell arrays, the size of the array in each cell of x must match the size of the array in the corresponding cell of y.

Data Types: double | cell

y — y-coordinates

numeric array | cell array of numeric arrays

y-coordinates, specified as a numeric array or a cell array of numeric arrays.

• Create a point by specifying a scalar, such as -113.

• Create a multipoint by specifying an array within a cell, such as {[-66 -31 42]}.

• Create an array of points by specifying an array, such as [-66 -31 42].

• Create an array of points and multipoints by specifying a cell array of numeric arrays, such as {-113,[-66 -31 42]}.

Create placeholders for points with missing data by including NaN values. The NaN values in x must correspond to the NaN values in y.

The size of x must match the size of y. For cell arrays, the size of the array in each cell of x must match the size of the array in the corresponding cell of y.

Data Types: double | cell

Properties

NumPoints — Number of points

Read-only: array of nonnegative integers

This property is read-only.

Number of points, returned as an array of nonnegative integers.

For a mappointshape scalar, the value of NumPoints is 1 when the mappointshape object represents a single point and more than 1 when the object represents a multipoint.

For a mappointshape array, the size of NumPoints matches the size of the array.

Data Types: double

X — x-coordinates

array

x-coordinates, specified as an array.

For a mappointshape scalar, the size of X matches the value of NumPoints.

For a mappointshape array, the size of X matches the size of NumPoints. If the array contains mappointshape objects with multipoints, then accessing the X property of the array is not supported. Instead, access the X property of individual objects within the array. You can determine whether a mappointshape array contains multipoints by using the ismultipoint function.

This property is read-only for arrays when any element of NumPoints is greater than 1.

X and Y must be the same size.

Data Types: double

Y — y-coordinates

array

y-coordinates, specified as an array.

For a mappointshape scalar, the size of Y matches the value of NumPoints.

For a mappointshape array, the size of Y matches the size of NumPoints. If the array contains mappointshape objects with multipoints, then accessing the Y property of the array is not supported. Instead, access the Y property of individual objects within the array. You can determine whether a mappointshape array contains multipoints by using the ismultipoint function.

This property is read-only for arrays when any element of NumPoints is greater than 1.

X and Y must be the same size.

Data Types: double

Geometry — Geometric type

Read-only: "point" (default)

This property is read-only.

Geometric type, returned as "point".

Data Types: string

CoordinateSystemType — Coordinate system type

Read-only: "planar" (default)

This property is read-only.

Coordinate system type, returned as "planar".

Data Types: string

ProjectedCRS — Projected coordinate reference system

[] (default) | projcrs object

Projected coordinate reference system (CRS), specified as a projcrs object. A projected CRS consists of a geographic CRS and several parameters that are used to transform coordinates to and from the geographic CRS.

Object Functions

Visualize and Query

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

Modify

mapclip	Clip planar shape to xy-limits or polygon
buffer	Buffer 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 Planar Points

Import a shapefile containing the coordinates of locations in Boston as a geospatial table. The shapefile represents the locations using points. Get information about the points by querying the Shape variable of the table.

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

ans = 
  13×1 mappointshape array with properties:

               NumPoints: [13×1 double]
                       X: [13×1 double]
                       Y: [13×1 double]
                Geometry: "point"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]

Display the locations using black plus signs on a road map.

geoplot(GT,"+k")
geobasemap streets

Create Planar Points and Multipoints

Create an individual point as a mappointshape scalar. Specify the projected CRS as World Equidistant Cylindrical, which has the EPSG authority code 4087.

point = mappointshape(-113,39);
p = projcrs(4087);
point.ProjectedCRS = p

point = 
  mappointshape with properties:

               NumPoints: 1
                       X: -113
                       Y: 39
                Geometry: "point"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]

Create a multipoint as a mappointshape scalar.

multipoint = mappointshape({[-66 -31 42]},{[38 -30 29]});
multipoint.ProjectedCRS = p

multipoint = 
  mappointshape with properties:

               NumPoints: 3
                       X: [-66 -31 42]
                       Y: [38 -30 29]
                Geometry: "point"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]

Create three individual points as a 1-by-3 mappointshape array.

pointVector = mappointshape([-66 -31 42],[38 -30 29]);
pointVector.ProjectedCRS = p

pointVector = 
  1×3 mappointshape array with properties:

               NumPoints: [1 1 1]
                       X: [-66 -31 42]
                       Y: [38 -30 29]
                Geometry: "point"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]

Create one individual point and one multipoint as a 1-by-2 mappointshape array.

pointMultipoint = mappointshape({-113,[-66 -31 42]},{39, [38 -30 29]});
pointMultipoint.ProjectedCRS = p

pointMultipoint = 
  1×2 mappointshape array with properties:

               NumPoints: [1 3]
                Geometry: "point"
    CoordinateSystemType: "planar"
            ProjectedCRS: [1×1 projcrs]

Version History

Introduced in R2021b

R2022a: Points with missing coordinate data have some changed property values

When a point shape has missing coordinate data, its NumPoints property has a value of 0 and its X and Y properties each have a value of NaN.

• When you create a point by specifying both coordinates as NaN values, its NumPoints property has a value of 0. In the previous release, the property had a value of 1.

• When a point has no coordinate data, its X and Y properties each have a value of NaN. In the previous release, the properties were each empty double values.

These changes make it easier to create and access the properties of mappointshape arrays when the input coordinates contain missing data. For example, you can now access the coordinates of a mappointshape array when the array contains a combination of points with coordinate data (NumPoints is 1) and without coordinate data (NumPoints is 0). In the previous release, MATLAB^® issued an error.