Spatial functions
Spatial functions are used to specify 2D or 3D POINT
values in a Coordinate Reference System (CRS) and to calculate the geodesic distance between two POINT
values.
Example graph
The following graph is used for some of the examples below.
To recreate the graph, run the following query against an empty Neo4j database:
CREATE
(copenhagen:TrainStation {latitude: 55.672874, longitude: 12.564590, city: 'Copenhagen'}),
(malmo:Office {latitude: 55.611784, longitude: 12.994341, city: 'Malmö'}),
(copenhagen)-[:TRAVEL_ROUTE]->(malmo)
point()
Syntax |
|
||
Description |
Returns a 2D or 3D point object, given two or respectively three coordinate values in the Cartesian coordinate system or WGS 84 geographic coordinate system. |
||
Arguments |
Name |
Type |
Description |
|
|
Cartesian 2D: Cartesian 3D: WGS 84 2D: WGS 84 3D: |
|
Returns |
|
If any argument provided to |
If the coordinates are specified using |
If the coordinates are specified using |
If the |
The |
RETURN point({longitude: 56.7, latitude: 12.78}) AS point
A 2D POINT
with a longitude
of 56.7
and a latitude
of 12.78
in the WGS 84 CRS is returned.
point |
---|
|
Rows: 1 |
RETURN point({x: 2.3, y: 4.5, crs: 'WGS-84'}) AS point
x
and y
coordinates may be used in the WGS 84 CRS instead of longitude
and latitude
, respectively, providing crs
is set to 'WGS-84'
, or srid
is set to 4326
.
point |
---|
|
Rows: 1 |
MATCH (p:Office)
RETURN point({longitude: p.longitude, latitude: p.latitude}) AS officePoint
A 2D POINT
representing the coordinates of the city of Malmo in the WGS 84 CRS is returned.
officePoint |
---|
|
Rows: 1 |
RETURN point({longitude: 56.7, latitude: 12.78, height: 8}) AS point
A 3D POINT
with a longitude
of 56.7
, a latitude
of 12.78
and a height of 8
meters in the WGS 84 CRS is returned.
point |
---|
|
Rows: 1 |
RETURN point({x: 2.3, y: 4.5}) AS point
A 2D POINT
with an x
coordinate of 2.3
and a y
coordinate of 4.5
in the Cartesian CRS is returned.
point |
---|
|
Rows: 1 |
RETURN point({x: 2.3, y: 4.5, z: 2}) AS point
A 3D POINT
with an x
coordinate of 2.3
, a y
coordinate of 4.5
and a z
coordinate of 2
in the Cartesian CRS is returned.
point |
---|
|
Rows: 1 |
RETURN point(null) AS p
If null
is provided as the argument, null
is returned.
p |
---|
|
Rows: 1 |
point.distance()
Syntax |
|
||
Description |
Returns a |
||
Arguments |
Name |
Type |
Description |
|
|
A start point. |
|
|
|
An end point in the same CRS as the start point. |
|
Returns |
|
-
If the
POINT
values are in the Cartesian CRS (2D or 3D), then the units of the returned distance will be the same as the units of the points, calculated using Pythagoras' theorem. -
If the
POINT
values are in the WGS-84 CRS (2D), then the units of the returned distance will be meters, based on the haversine formula over a spherical Earth approximation. -
If the
POINT
values are in the WGS-84 CRS (3D), then the units of the returned distance will be meters.-
The distance is calculated in two steps.
-
First, a haversine formula over a spherical Earth is used, at the average height of the two points.
-
To account for the difference in height, Pythagoras' theorem is used, combining the previously calculated spherical distance with the height difference.
-
-
This formula works well for points close to the earth’s surface; for instance, it is well-suited for calculating the distance of an airplane flight. It is less suitable for greater heights, however, such as when calculating the distance between two satellites.
-
|
|
|
Attempting to use points with different Coordinate Reference Systems (such as WGS 84 2D and WGS 84 3D) will return |
WITH
point({x: 2.3, y: 4.5, crs: 'cartesian'}) AS p1,
point({x: 1.1, y: 5.4, crs: 'cartesian'}) AS p2
RETURN point.distance(p1,p2) AS dist
The distance between two 2D points in the Cartesian CRS is returned.
dist |
---|
|
Rows: 1 |
WITH
point({longitude: 12.78, latitude: 56.7, height: 100}) AS p1,
point({latitude: 56.71, longitude: 12.79, height: 100}) AS p2
RETURN point.distance(p1, p2) AS dist
The distance between two 3D points in the WGS 84 CRS is returned.
dist |
---|
|
Rows: 1 |
MATCH (t:TrainStation)-[:TRAVEL_ROUTE]->(o:Office)
WITH
point({longitude: t.longitude, latitude: t.latitude}) AS trainPoint,
point({longitude: o.longitude, latitude: o.latitude}) AS officePoint
RETURN round(point.distance(trainPoint, officePoint)) AS travelDistance
The distance between the train station in Copenhagen and the Neo4j office in Malmo is returned.
travelDistance |
---|
|
Rows: 1 |
RETURN point.distance(null, point({longitude: 56.7, latitude: 12.78})) AS d
If null
is provided as one or both of the arguments, null
is returned.
d |
---|
|
Rows: 1 |
point.withinBBox()
Syntax |
|
||
Description |
Returns true if the provided point is within the bounding box defined by the two provided points. |
||
Arguments |
Name |
Type |
Description |
|
|
A point to be confirmed in the bounding box. |
|
|
|
The lower left side point of the bounding box. |
|
|
|
The upper right side point of the bounding box. |
|
Returns |
|
|
Attempting to use |
|
Switching the longitude of the |
Switching the latitude of the |
WITH
point({x: 0, y: 0, crs: 'cartesian'}) AS lowerLeft,
point({x: 10, y: 10, crs: 'cartesian'}) AS upperRight
RETURN point.withinBBox(point({x: 5, y: 5, crs: 'cartesian'}), lowerLeft, upperRight) AS result
Checking if a point in Cartesian CRS is contained in the bounding box.
result |
---|
|
Rows: 1 |
WITH
point({longitude: 12.53, latitude: 55.66}) AS lowerLeft,
point({longitude: 12.614, latitude: 55.70}) AS upperRight
MATCH (t:TrainStation)
WHERE point.withinBBox(point({longitude: t.longitude, latitude: t.latitude}), lowerLeft, upperRight)
RETURN count(t)
Finds all train stations contained in a bounding box around Copenhagen.
count(t) |
---|
|
Rows: 1 |
WITH
point({longitude: 179, latitude: 55.66}) AS lowerLeft,
point({longitude: -179, latitude: 55.70}) AS upperRight
RETURN point.withinBBox(point({longitude: 180, latitude: 55.66}), lowerLeft, upperRight) AS result
A bounding box that crosses the 180th meridian.
result |
---|
|
Rows: 1 |
RETURN
point.withinBBox(
null,
point({longitude: 56.7, latitude: 12.78}),
point({longitude: 57.0, latitude: 13.0})
) AS in
If null
is provided as any of the arguments, null
is returned.
in |
---|
|
Rows: 1 |