/ 
Neo4j-Types-1.00
River stage one • 3 direct dependents • 5 total dependents
/ Neo4j::Types::Point

NAME

Neo4j::Types::Point - Represents a Neo4j spatial point value

VERSION

version 1.00

SYNOPSIS

$longitude  = $point->X;
$latitude   = $point->Y;
$height     = $point->Z;
$neo4j_srid = $point->srid;

@coords = ($x, $y, $z);
$point  = Neo4j::Types::Point->new( $neo4j_srid, @coords );

DESCRIPTION

Represents a spatial point value in Neo4j. Includes coordinates in two or three dimensions and a SRID that may define their semantics.

The SRID and thereby the coordinate semantics are defined by Neo4j. See "srid" for details.

This module makes no assumptions about its internal data structure. While default implementations for all methods are provided, inheritors are free to override these according to their needs. The default implementations assume the data is stored in an array reference whose order of elements matches that of Bolt PackStream for Point2D/Point3D.

Supported in Neo4j version 3.4 and above.

METHODS

Neo4j::Types::Point implements the following methods.

coordinates

@coordinates = $point->coordinates;
($x, $y, $z) = @coordinates;

Retrieve the point's coordinates as a list.

height

$value = $point->height;

Alias for Z().

latitude

$value = $point->latitude;

Alias for Y().

longitude

$value = $point->longitude;

Alias for X().

new

$point = Neo4j::Types::Point->new($neo4j_srid, @coordinates);

Creates a new Point instance with the specified value.

This method will fail if the SRID provided is not supported by Neo4j or if it requires a greater number of coordinates than provided.

srid

$neo4j_srid = $point->srid;

Retrieve an identifier for this point's spatial reference system. This SRID has no meaning outside the context of Neo4j; in particular, it is not an EPSG code.

To date, Neo4j has defined four SRIDs: 4326, 4979, 7203, and 9157. Every point retrieved from Neo4j is referred to a coordinate system identified by one of them.

Neo4j SRID 4326

Geographical ellipsoidal coordinates, referred to WGS84 (but spherically developed with distance() in Cypher). Axes: longitude (East), latitude (North). Units: decimal degrees. Neo4j moniker: wgs-84.

Neo4j SRID 4979

Geographical ellipsoidal coordinates, referred to WGS84 (but spherically developed with distance() in Cypher). Axes: longitude (East), latitude (North), height (Up). Units: decimal degrees; height in metres. The height is referred to the ellipsoid (which is not at sea level). Neo4j moniker: wgs-84-3d.

Neo4j SRID 7203

Coordinates in a two-dimensional Euclidian space (a plane). The geodetic datum, axis orientation and units are all undefined, but both axes must use the same unit. Neo4j moniker: cartesian.

Neo4j SRID 9157

Coordinates in a three-dimensional Euclidian space. The geodetic datum, axis orientation and units are all undefined, but all axes must use the same unit. Neo4j moniker: cartesian-3d.

The primary semantics of a Neo4j SRID can be easily determined by simple boolean expressions.

$is_geographic = $neo4j_srid == 4326 or $neo4j_srid == 4979;
$is_euclidian  = $neo4j_srid == 7203 or $neo4j_srid == 9157;
$is_2d         = $neo4j_srid == 4326 or $neo4j_srid == 7203;
$is_3d         = $neo4j_srid == 4979 or $neo4j_srid == 9157;

Note that Neo4j does not support geographic coordinates that are referred to any other geodetic datum than WGS84 (such as GCJ02, ETRS89, NAD27, or local datums), nor does it support geographic coordinates that are referred to an unknown datum. While it is technically possible to ignore Neo4j SRID semantics and just use other geographic coordinate reference systems anyway, you should be aware that this may create interoperability issues, particularly if more than a single client uses the Neo4j database.

Neo4j does not impose constraints on the datum of Euclidian coordinates, so using (for example) cartesian coordinates referred to WGS84 is possible. However, Neo4j does not offer a way to tag point values with the datum they actually use. Care should be taken not to mix different geodetic datums in the same database without considering the interoperability issues that this may cause, again particularly if more than a single client uses the Neo4j database.

X

$value = $point->X;

Retrieve the point's first ordinate, also known as the abscissa. Commonly used for the horizontal axis in an Euclidean plane or for the geographical longitude.

Y

$value = $point->Y;

Retrieve the point's second ordinate. Commonly used for the vertical axis in an Euclidean plane or for the geographical latitude.

Z

$value = $point->Z;

Retrieve the point's third ordinate. Commonly used for height.

For points in coordinate systems that have no more than two dimensions, this method returns an undefined value.

BUGS

The behaviour of the coordinates() method when called in scalar context has not yet been defined.

There are currently no methods named x(), y(), or z(). This is to avoid confusion with Perl's y/// operator.

SEE ALSO

AUTHOR

Arne Johannessen <ajnn@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2021 by Arne Johannessen.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)