The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Neo4j-Types-2.00
River stage one • 2 direct dependents • 2 total dependents
1 ++
/ Neo4j::Types::Point

NAME

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

VERSION

version 2.00

SYNOPSIS

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

DESCRIPTION

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

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

The coordinate reference systems of spatial points in Neo4j are currently severely constrained. There is no way to tag points with the CRS they actually use, and for geographic coordinates (lat/lon), only a single, subtly non-standard CRS is even supported. This deviates from common OGC standards for geospatial databases. Prudence suggests to expect future changes in Neo4j. Such changes would likely necessitate breaking changes to this module. For uses that don't require the spatial functions that Neo4j offers, it might be best to eschew the point type completely and store coordinate tuples as a simple list in the Neo4j database instead.

Supported in Neo4j version 3.4 and above.

METHODS

Neo4j::Types::Point specifies the following methods. Additionally, a new() method is currently available as a backwards compatibility alias for new() in "Point" in Neo4j::Types::Generic.

coordinates

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

Retrieve the point's coordinates as a list.

In scalar context, return the number of coordinates for this point (2 for points in two-dimensional coordinate systems, 3 for three-dimensional systems).

 $dimensions = scalar $point->coordinates;

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.

SEE ALSO

AUTHOR

Arne Johannessen <ajnn@cpan.org>

If you contact me by email, please make sure you include the word "Perl" in your subject header to help beat the spam filters.

COPYRIGHT AND LICENSE

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

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0 or (at your option) the same terms as the Perl 5 programming language system itself.