空间函数

空间函数用于在坐标参考系 (CRS) 中指定 2D 或 3D POINT 值，并计算两个 POINT 值之间的测地距离。

示例图

以下图用于以下示例。

要重新创建图，请对空的 Neo4j 数据库运行以下查询

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()

详细信息
语法	`point(input)`
描述	在笛卡尔坐标系或 WGS 84 地理坐标系中，给定两个或分别三个坐标值，返回一个 2D 或 3D 点对象。
参数	名称	类型	描述
	`输入`	`MAP`	笛卡尔 2D：`{ x :: FLOAT, y :: FLOAT, crs = "cartesian" :: STRING, srid = 7203 :: INTEGER }` 笛卡尔 3D：`{ x :: FLOAT, y :: FLOAT, z :: FLOAT, crs = "cartesian-3D" :: STRING, srid = 9157 :: INTEGER }` WGS 84 2D：`{ longitude \| x :: FLOAT latitude \| y :: FLOAT crs = "WGS-84-2D" :: STRING srid = 4326 :: INTEGER }` WGS 84 3D：`{ longitude \| x :: FLOAT, latitude \| y :: FLOAT, height \| z :: FLOAT, crs = "WGS-84-3D" :: STRING, srid = 4979 :: INTEGER }`
返回	`POINT`

注意事项
如果提供给 `point()` 的任何参数为 `null`，则将返回 `null`。
如果使用 `latitude` 和 `longitude` 指定坐标，则 `crs` 或 `srid` 字段是可选的，并推断为 `'WGS-84'` (`srid:4326`) 用于 2D 点或 `'WGS-84-3D'` (`srid:4979`) 用于 3D 点。
如果使用 `x` 和 `y` 指定坐标，则如果需要地理 CRS，则需要 `crs` 或 `srid` 字段。
如果没有提供 `height/z` 键和值，则将返回 2D `POINT`，位于 _WGS 84_ 或 _笛卡尔_ CRS 中，具体取决于使用的坐标系。
`crs` 或 `srid` 字段是可选的，默认值为 _笛卡尔_ CRS（这意味着 `srid:7203`）用于 2D 点或 _3D 笛卡尔_ CRS（这意味着 `srid:9157`）用于 3D 点。

示例 1. point() - WGS 84 2D

查询

RETURN point({longitude: 56.7, latitude: 12.78}) AS point

返回一个 2D POINT，其 longitude 为 56.7，latitude 为 12.78，位于 _WGS 84_ CRS 中。

结果
point
`point({srid:4326, x:56.7, y:12.78})`
行数：1

示例 2. point() - WGS 84 2D

查询

RETURN point({x: 2.3, y: 4.5, crs: 'WGS-84'}) AS point

x 和 y 坐标可以在 _WGS 84_ CRS 中使用，而不是分别使用 longitude 和 latitude，前提是 crs 设置为 'WGS-84'，或者 srid 设置为 4326。

结果
point
`point({srid:4326, x:2.3, y:4.5})`
行数：1

示例 3. point() - WGS 84 2D

查询

MATCH (p:Office)
RETURN point({longitude: p.longitude, latitude: p.latitude}) AS officePoint

返回一个 2D POINT，表示 _WGS 84_ CRS 中马尔默市坐标。

结果
officePoint
`point({srid:4326, x:12.994341, y:55.611784})`
行数：1

示例 4. point() - WGS 84 3D

查询

RETURN point({longitude: 56.7, latitude: 12.78, height: 8}) AS point

返回一个 3D POINT，其 longitude 为 56.7，latitude 为 12.78，高度为 8 米，位于 _WGS 84_ CRS 中。

结果
point
`point({srid:4979, x:56.7, y:12.78, z:8.0})`
行数：1

示例 5. point() - 笛卡尔 2D

查询

RETURN point({x: 2.3, y: 4.5}) AS point

返回一个 2D POINT，其 x 坐标为 2.3，y 坐标为 4.5，位于 _笛卡尔_ CRS 中。

结果
point
`point({srid:7203, x:2.3, y:4.5})`
行数：1

示例 6. point() - 笛卡尔 3D

查询

RETURN point({x: 2.3, y: 4.5, z: 2}) AS point

返回一个 3D POINT，其 x 坐标为 2.3，y 坐标为 4.5，z 坐标为 2，位于 _笛卡尔_ CRS 中。

结果
point
`point({srid:9157, x:2.3, y:4.5, z:2.0})`
行数：1

示例 7. point() - null

查询

RETURN point(null) AS p

如果提供 null 作为参数，则返回 null。

结果
p
`<null>`
行数：1

point.distance()

详细信息
语法	`point.distance(from, to)`
描述	返回一个 `FLOAT`，表示同一 CRS 中任意两点之间的距离。如果点位于 WGS 84 CRS 中，则该函数返回测地距离（即地球曲面上的最短路径）。如果点位于笛卡尔 CRS 中，则该函数返回欧几里德距离（即平面空间中最短的直线距离）。
参数	名称	类型	描述
	`from`	`POINT`	起点。
	`to`	`POINT`	与起点位于同一 CRS 中的终点。
返回	`FLOAT`

如果 POINT 值位于 _笛卡尔_ CRS（2D 或 3D）中，则返回的距离单位将与点的单位相同，使用勾股定理计算。
如果 POINT 值位于 _WGS-84_ CRS（2D）中，则返回的距离单位将为米，基于球形地球近似上的半正矢公式。
如果 POINT 值位于 _WGS-84_ CRS（3D）中，则返回的距离单位将为米。
- 距离计算分两步进行。
  - 首先，使用半正矢公式在球形地球上进行计算，以两点平均高度为基准。
  - 为了考虑高度差异，使用勾股定理，将先前计算的球面距离与高度差相结合。
- 此公式适用于靠近地球表面的点；例如，它非常适合计算飞机航线的距离。然而，对于更大的高度，它就不太合适了，例如，计算两颗卫星之间的距离时。

注意事项
`point.distance(null, null)` 返回 `null`。
`point.distance(null, to)` 返回 `null`。
`point.distance(from, null)` 返回 `null`。
尝试使用不同坐标参考系统（例如 WGS 84 2D 和 WGS 84 3D）的点将返回 `null`。

示例 8. point.distance()

查询

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

返回笛卡尔 CRS 中两个二维点之间的距离。

结果
dist
`1.5`
行数：1

示例 9. point.distance()

查询

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

返回WGS 84 CRS 中两个三维点之间的距离。

结果
dist
`1269.9148706779097`
行数：1

示例 10. point.distance()

查询

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

返回哥本哈根火车站和马尔默 Neo4j 办公室之间的距离。

结果
travelDistance
`27842.0`
行数：1

示例 11. point.distance()

查询

RETURN point.distance(null, point({longitude: 56.7, latitude: 12.78})) AS d

如果提供一个或两个参数为 null，则返回 null。

结果
d
`null`
行数：1

point.withinBBox()

详细信息
语法	`point.withinBBox(point, lowerLeft, upperRight)`
描述	如果提供的点位于由两个提供的点定义的边界框内，则返回 true。
参数	名称	类型	描述
	`point`	`POINT`	要确认在边界框中的点。
	`lowerLeft`	`POINT`	边界框的左下角点。
	`upperRight`	`POINT`	边界框的右上角点。
返回	`布尔值`

注意事项
如果任何参数计算为 `null`，则 `point.withinBBox(point, lowerLeft, upperRight)` 将返回 `null`。
尝试使用不同坐标参考系统（例如 WGS 84 2D 和 WGS 84 3D）的`POINT` 值将返回 `null`。
`point.withinBBox` 将处理地理坐标中跨越 180 度经线的跨度。
在地理坐标中切换 `lowerLeft` 和 `upperRight` 的经度将切换结果边界框的方向。
在地理坐标中切换 `lowerLeft` 和 `upperRight` 的纬度，使前者位于后者的北部，将导致空范围。

示例 12. point.withinBBox()

查询

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

检查笛卡尔 CRS 中的点是否包含在边界框中。

结果
result
`true`
行数：1

示例 13. point.withinBBox()

查询

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)

查找包含在哥本哈根周围边界框中的所有火车站。

结果
count(t)
`1`
行数：1

示例 14. point.withinBBox()

查询

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

跨越 180 度经线的边界框。

结果
result
`true`
行数：1

示例 15. point.withinBBox()

查询

RETURN
  point.withinBBox(
    null,
    point({longitude: 56.7, latitude: 12.78}),
    point({longitude: 57.0, latitude: 13.0})
  ) AS in

如果提供任何参数为 null，则返回 null。

结果
in
`null`
行数：1