空间函数

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

示例图

下方的图表用于下文中的部分示例。

Example graph connecting a train station node to an office node via a travel route relationship

要重新创建该图，请在空的 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)

描述

返回一个 2D 或 3D 点对象，该对象由笛卡尔坐标系或 WGS 84 地理坐标系中的两个或三个坐标值给定。

参数

名称

类型

描述

input

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 字段是可选的，对于 2D 点默认为 'WGS-84' (srid:4326)，对于 3D 点默认为 'WGS-84-3D' (srid:4979)。

如果使用 x 和 y 指定坐标，若需要地理 CRS，则必须提供 crs 或 srid 字段。

如果未提供 height/z 键和值，将根据所使用的坐标系统，返回一个 WGS 84 或 笛卡尔 CRS 下的 2D POINT。

crs 或 srid 字段是可选的，对于 2D 点，默认值为 笛卡尔 CRS（即 srid:7203）；对于 3D 点，默认值为 3D 笛卡尔 CRS（即 srid:9157）。
示例 1. point() - WGS 84 2D
查询
RETURN point({longitude: 56.7, latitude: 12.78}) AS point

返回一个 WGS 84 CRS 下的 2D POINT，其 longitude 为 56.7，latitude 为 12.78。

结果
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

如果 crs 设置为 'WGS-84'，或者 srid 设置为 4326，则可以在 WGS 84 CRS 中使用 x 和 y 坐标代替 longitude 和 latitude。

结果
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

返回一个表示马尔默市坐标的 WGS 84 CRS 下的 2D POINT。

结果
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

返回一个 WGS 84 CRS 下的 3D POINT，其 longitude 为 56.7，latitude 为 12.78，高度为 8 米。

结果
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

返回一个 笛卡尔 CRS 下的 2D POINT，其 x 坐标为 2.3，y 坐标为 4.5。

结果
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

返回一个 笛卡尔 CRS 下的 3D POINT，其 x 坐标为 2.3，y 坐标为 4.5，z 坐标为 2。

结果
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。如果这些点位于 WGS 84 坐标系中，该函数返回测地距离（即地球弯曲表面上的最短路径）。如果这些点位于笛卡尔坐标系中，该函数返回欧几里得距离（即平坦平面空间中的最短直线距离）。

参数

名称

类型

描述

从 (from)

POINT

起始点。

转换为

POINT

与起始点在同一 CRS 下的结束点。

返回

FLOAT

  • 如果 POINT 值处于 笛卡尔 CRS（2D 或 3D）中，则返回距离的单位将与点坐标的单位相同，并通过勾股定理计算得出。

  • 如果 POINT 值处于 WGS-84 CRS（2D）中，则返回距离的单位将为米，基于球面地球近似的半正矢公式（haversine formula）计算得出。

  • 如果 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 中两个 2D 点之间的距离。

结果
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 中两个 3D 点之间的距离。

结果
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

边界框的右上角点。

返回

布尔值 (BOOLEAN)
注意事项

如果任何参数的计算结果为 null，point.withinBBox(point, lowerLeft, upperRight) 将返回 null。

尝试使用不同坐标参考系统的 POINT 值（例如 WGS 84 2D 和 WGS 84 3D）将返回 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 中的点是否包含在边界框内。

结果
结果

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 度经线的边界框。

结果
结果

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