geopointshape

R2026b

Point shape in geographic coordinates

Description

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

To represent a point or multipoint in planar coordinates, use a mappointshape object instead.

Creation

To create geopointshape objects, either:

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

• Use the geopointshape function (described here).

Syntax

shape = geopointshape(lat,lon)

shape = geopointshape(lat,lon,h)

shape = geopointshape(___,GeographicCRS=gcrs)

Description

shape = geopointshape(lat,lon) creates one or more 2-D points with the specified latitude and longitude coordinates. The sizes of lat, lon, and shape match.

shape = geopointshape(lat,lon,h) creates one or more 3-D points with the specified latitude, longitude, and height coordinates. (since R2026b)

shape = geopointshape(___,GeographicCRS=gcrs) specifies the geographic CRS for the points, in addition to any combination of input arguments from previous syntaxes. (since R2026b)

Input Arguments

lat — Latitude coordinates

numeric array | cell array of numeric arrays

Latitude 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 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 array in each cell of lat must match the size of the array in the corresponding cell of lon.

Data Types: double | cell

lon — Longitude coordinates

numeric array | cell array of numeric arrays

Longitude 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 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 array in each cell of lat must match the size of the array in the corresponding cell of lon.

Data Types: double | cell

h — Height coordinates

numeric array | cell array of numeric arrays

Since R2026b

Height 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 h must correspond to the NaN values in lat and lon.

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

Data Types: double | cell

gcrs — Geographic coordinate reference system

[] (default) | geocrs object

Geographic coordinate reference system (CRS), specified as a geocrs 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 geopointshape object, the value of NumPoints is 1 when the geopointshape object represents a single point and more than 1 when the object represents a multipoint.

For an array of geopointshape objects, the size of NumPoints matches the size of the array.

Data Types: double

Latitude — Latitude coordinates

array

Latitude coordinates, specified as an array.

• For a scalar geopointshape object, the size of Latitude matches the value of NumPoints.

• For an array of geopointshape objects, the size of Latitude matches the size of NumPoints. If the array contains multipoints, then accessing the Latitude property of the array is not supported. Instead, access the Latitude 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.

Latitude and Longitude must be the same size.

Data Types: double

Longitude — Longitude coordinates

array

Longitude coordinates, specified as an array.

• For a scalar geopointshape object, the size of Longitude matches the value of NumPoints.

• For an array of geopointshape objects, the size of Longitude matches the size of NumPoints. If the array contains multipoints, then accessing the Longitude property of the array is not supported. Instead, access the Longitude 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.

Latitude and Longitude must be the same size.

Data Types: double

Height — Height coordinates

array | []

Since R2026b

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

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

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

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

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

Height must be empty or be of the same size as Latitude and Longitude.

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: "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.

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

geoclip	Clip geographic shape to latitude-longitude 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 Geographic Points

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

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

ans = 
  13×1 geopointshape array with properties:

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

Display the locations on a road map by passing the geospatial table to the geoplot function.

figure
geoplot(GT,"o",MarkerFaceColor="#0072BD")
geobasemap streets

Create Geographic Points and Multipoints

Create an individual point as a geopointshape scalar. Specify the geographic CRS as the World Geodetic System of 1984, which has the EPSG code 4326.

gcrs = geocrs(4326);
point = geopointshape(39,-113,GeographicCRS=gcrs)

point = 
  geopointshape with properties:

               NumPoints: 1
                Latitude: 39
               Longitude: -113
                  Height: []
                Geometry: "point"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Create a multipoint as a geopointshape scalar.

multipoint = geopointshape({[38 -30 29]},{[-66 -31 42]}, ...
    GeographicCRS=gcrs)

multipoint = 
  geopointshape with properties:

               NumPoints: 3
                Latitude: [38 -30 29]
               Longitude: [-66 -31 42]
                  Height: []
                Geometry: "point"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Create three individual points as a 1-by-3 geopointshape vector.

pointVector = geopointshape([38 -20 29],[-66 -31 42], ...
    GeographicCRS=gcrs)

pointVector = 
  1×3 geopointshape array with properties:

               NumPoints: [1 1 1]
                Latitude: [38 -20 29]
               Longitude: [-66 -31 42]
                  Height: []
                Geometry: "point"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Create one individual point and one multipoint as a 1-by-2 geopointshape vector.

pointMultipoint = geopointshape({39,[38 -30 29]},{-113,[-66 -31 42]}, ...
    GeographicCRS=gcrs)

pointMultipoint = 
  1×2 geopointshape array with properties:

               NumPoints: [1 3]
                Geometry: "point"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Version History

Introduced in R2021b

R2026b: Specify geographic CRS

Specify the geographic CRS of a geopointshape object during creation by using the geocrs argument.

R2026b: Represent 3-D points

Use geopointshape objects to represent 3-D points. Create 3-D points from coordinate data by specifying latitude, longitude, and height coordinates. Query or set the height coordinates using the Height 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 Latitude and Longitude 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 Latitude and Longitude 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 geopointshape arrays when the input coordinates contain missing data. For example, you can now access the coordinates of a geopointshape 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.