mappointshape

R2026b

Point shape in planar coordinates

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)

shape = mappointshape(x,y,z)

shape = mappointshape(___,ProjectedCRS=pcrs)

Description

shape = mappointshape(x,y) creates one or more 2-D points with the specified xy-coordinates. The sizes of x, y, and shape match.

shape = mappointshape(x,y,z) creates one or more 3-D points with the specified xyz-coordinates. (since R2026b)

shape = mappointshape(___,ProjectedCRS=pcrs) specifies the projected CRS for the points, in addition to any combination of input arguments from previous syntaxes. (since R2026b)

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

z — z-coordinates

numeric array | cell array of numeric arrays

Since R2026b

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

• Create a 3-D point by specifying a scalar, such as 100.

• Create a 3-D multipoint by specifying an array within a cell, such as {[100 200 300]}.

• Create an array of 3-D points by specifying an array, such as [100 200 300].

• Create an array of 3-D points and multipoints by specifying a cell array of numeric arrays, such as {100,[200 300 400]}.

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

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

Data Types: double | cell

pcrs — Projected coordinate reference system

[] (default) | projcrs object

Projected coordinate reference system (CRS), specified as a projcrs object.

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 scalar mappointshape object, 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 an array of mappointshape objects, 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 scalar mappointshape object, the size of X matches the value of NumPoints.

• For an array of mappointshape objects, the size of X matches the size of NumPoints. If the array contains 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 the 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 scalar mappointshape object, the size of Y matches the value of NumPoints.

• For an array of mappointshape objects, the size of Y matches the size of NumPoints. If the array contains 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 the 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

Z — z-coordinates

array | []

Since R2026b

z-coordinates, specified as an array or an empty array ([]).

• For a scalar mappointshape object that represents a 3-D point, the size of Z matches the value of NumPoints.

• For an array of mappointshape objects that represent 3-D points, the size of Z matches the size of NumPoints. If the array contains multipoints, then accessing the Z property of the array is not supported. Instead, access the Z property of individual objects within the array. You can determine whether the array contains multipoints by using the ismultipoint function.

• For mappointshape objects that represent 2-D points, the value of Z is an empty array.

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

Z must be empty or be of the same size as X and Y.

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.

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]
                       Z: []
                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.

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

point = 
  mappointshape with properties:

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

Create a multipoint as a mappointshape scalar.

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

multipoint = 
  mappointshape with properties:

               NumPoints: 3
                       X: [-66 -31 42]
                       Y: [38 -30 29]
                       Z: []
                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], ...
    ProjectedCRS=pcrs)

pointVector = 
  1×3 mappointshape array with properties:

               NumPoints: [1 1 1]
                       X: [-66 -31 42]
                       Y: [38 -30 29]
                       Z: []
                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]}, ...
    ProjectedCRS=pcrs)

pointMultipoint = 
  1×2 mappointshape array with properties:

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

Version History

Introduced in R2021b

R2026b: Specify projected CRS

Specify the projected CRS of a mappointshape object during creation by using the pcrs argument.

R2026b: Represent 3-D points

Use mappointshape objects to represent 3-D points. Create 3-D points from coordinate data by specifying xyz-coordinates. Query or set the z-coordinates using the Z property.

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.