# Spatial functions

These functions are used to specify 2D or 3D points in a Coordinate Reference System (CRS) and to calculate the geodesic distance between two points.

Functions:

The following graph is used for some of the examples below. ## 1. point.distance()

`point.distance()` returns a floating point number representing the geodesic distance between two points in the same Coordinate Reference System (CRS).

• If the points 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 points 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 points 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.

Syntax: `point.distance(point1, point2)`

Returns:

 A Float.

Arguments:

Name Description

`point1`

A point in either a geographic or cartesian coordinate system.

`point2`

A point in the same CRS as `point1`.

Considerations:

 `point.distance(null, null)`, `point.distance(null, point2)` and `point.distance(point1, null)` all return `null`. Attempting to use points with different Coordinate Reference Systems (such as WGS 84 2D and WGS 84 3D) will return `null`.
Query
``````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.

Table 1. Result
dist

`1.5`

Rows: 1

Query
``````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.

Table 2. Result
dist

`1269.9148706779097`

Rows: 1

Query
``````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.

Table 3. Result
travelDistance

`27842.0`

Rows: 1

Query
``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.

Table 4. Result
d

`<null>`

Rows: 1

## 2. point.withinBBox()

`point.withinBBox()` takes the following arguments:

• The point to check.

• The lower-left (south-west) point of a bounding box.

• The upper-right (or north-east) point of a bounding box.

The return value will be true if the provided point is contained in the bounding box (boundary included), otherwise the return value will be false.

Syntax: `point.withinBBox(point, lowerLeft, upperRight)`

Returns:

 A Boolean.

Arguments:

Name Description

`point`

A point in either a geographic or cartesian coordinate system.

`lowerLeft`

A point in the same CRS as 'point'.

`upperRight`

A point in the same CRS as 'point'.

Considerations:

 `point.withinBBox(p1, p2, p3)` will return `null` if any of the arguments evaluate to `null`. Attempting to use points with different Coordinate Reference Systems (such as WGS 84 2D and WGS 84 3D) will return `null`. `point.withinBBox` will handle crossing the 180th meridian in geographic coordinates. Switching the longitude of the `lowerLeft` and `upperRight` in geographic coordinates will switch the direction of the resulting bounding box. Switching the latitude of the `lowerLeft` and `upperRight` in geographic coordinates so that the former is north of the latter will result in an empty range.
Query
``````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.

Table 5. Result
result

`true`

Rows: 1

Query
``````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.

Table 6. Result
count(t)

`1`

Rows: 1

Query
``````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.

Table 7. Result
result

`true`

Rows: 1

Query
``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.

Table 8. Result
in

`<null>`

Rows: 1

## 3. point() - WGS 84 2D

`point({longitude | x, latitude | y [, crs][, srid]})` returns a 2D point in the WGS 84 CRS corresponding to the given coordinate values.

Syntax: `point({longitude | x, latitude | y [, crs][, srid]})`

Returns:

 A 2D point in WGS 84.

Arguments:

Name Description

`A single map consisting of the following:`

`longitude/x`

A numeric expression that represents the longitude/x value in decimal degrees

`latitude/y`

A numeric expression that represents the latitude/y value in decimal degrees

`crs`

The optional string 'WGS-84'

`srid`

The optional number 4326

Considerations:

 If any argument provided to `point()` is `null`, `null` will be returned. If the coordinates are specified using `latitude` and `longitude`, the `crs` or `srid` fields are optional and inferred to be `'WGS-84'` (srid=4326). If the coordinates are specified using `x` and `y`, then either the `crs` or `srid` field is required if a geographic CRS is desired.
Query
``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.

Table 9. Result
point

`point({x: 56.7, y: 12.78, crs: 'wgs-84'})`

Rows: 1

Query
``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`.

Table 10. Result
point

`point({x: 2.3, y: 4.5, crs: 'wgs-84'})`

Rows: 1

Query
``````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.

Table 11. Result
officePoint

`point({x: 12.994341, y: 55.611784, crs: 'wgs-84'})`

Rows: 1

Query
``RETURN point(null) AS p``

If `null` is provided as the argument, `null` is returned.

Table 12. Result
p

`<null>`

Rows: 1

## 4. point() - WGS 84 3D

`point({longitude | x, latitude | y, height | z, [, crs][, srid]})` returns a 3D point in the WGS 84 CRS corresponding to the given coordinate values.

Syntax: `point({longitude | x, latitude | y, height | z, [, crs][, srid]})`

Returns:

 A 3D point in WGS 84.

Arguments:

Name Description

`A single map consisting of the following:`

`longitude/x`

A numeric expression that represents the longitude/x value in decimal degrees

`latitude/y`

A numeric expression that represents the latitude/y value in decimal degrees

`height/z`

A numeric expression that represents the height/z value in meters

`crs`

The optional string 'WGS-84-3D'

`srid`

The optional number 4979

Considerations:

 If any argument provided to `point()` is `null`, `null` will be returned. If the `height/z` key and value is not provided, a 2D point in the WGS 84 CRS will be returned. If the coordinates are specified using `latitude` and `longitude`, the `crs` or `srid` fields are optional and inferred to be `'WGS-84-3D'` (srid=4979). If the coordinates are specified using `x` and `y`, then either the `crs` or `srid` field is required if a geographic CRS is desired.
Query
``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.

Table 13. Result
point

`point({x: 56.7, y: 12.78, z: 8.0, crs: 'wgs-84-3d'})`

Rows: 1

## 5. point() - Cartesian 2D

`point({x, y [, crs][, srid]})` returns a 2D point in the Cartesian CRS corresponding to the given coordinate values.

Syntax: `point({x, y [, crs][, srid]})`

Returns:

 A 2D point in Cartesian.

Arguments:

Name Description

`A single map consisting of the following:`

`x`

A numeric expression

`y`

A numeric expression

`crs`

The optional string 'cartesian'

`srid`

The optional number 7203

Considerations:

 If any argument provided to `point()` is `null`, `null` will be returned. The `crs` or `srid` fields are optional and default to the Cartesian CRS (which means `srid:7203`).
Query
``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.

Table 14. Result
point

`point({x: 2.3, y: 4.5, crs: 'cartesian'})`

Rows: 1

## 6. point() - Cartesian 3D

`point({x, y, z, [, crs][, srid]})` returns a 3D point in the Cartesian CRS corresponding to the given coordinate values.

Syntax: `point({x, y, z, [, crs][, srid]})`

Returns:

 A 3D point in Cartesian.

Arguments:

Name Description

`A single map consisting of the following:`

`x`

A numeric expression

`y`

A numeric expression

`z`

A numeric expression

`crs`

The optional string 'cartesian-3D'

`srid`

The optional number 9157

Considerations:

 If any argument provided to `point()` is `null`, `null` will be returned. If the `z` key and value is not provided, a 2D point in the Cartesian CRS will be returned. The `crs` or `srid` fields are optional and default to the 3D Cartesian CRS (which means `srid:9157`).
Query
``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.

Table 15. Result
point

`point({x: 2.3, y: 4.5, z: 2.0, crs: 'cartesian-3d'})`

Rows: 1