# 地理网格编码概述
## 1. 简介
地理网格编码是将连续的地理空间划分为规则的网格单元，并为每个网格赋予唯一编码的技术。通过将空间对象（点、线、面、三维模型等）转换为网格编码，可以在网格空间中高效地管理和查询空间数据。
Yukon 的地理网格编码能力由 `yukon_geogridcoder` 扩展模块提供。此模块提供了地理网格类型的空间操作函数、空间关系判断函数，以及与 geometry 等数据类型的转换计算函数。
使用前请先确认是否已创建 `yukon_geogridcoder`扩展。
```sql
CREATE EXTENSION yukon_geogridcoder;
```
### 主要应用场景
- **高效空间查询**：Yukon中基于网格的空间过滤查询，是将 geometry 对象从地理空间转换到网格空间，落在相同网格的对象即为可能有交点的对象，将作为检索结果输出。在智慧城市、国土空间规划等应用中，需要同时检索多个专题图层（如建筑物、道路、地下管线、行政区划）在某一范围内的地物信息。将各图层对象统一转换为网格编码并建立索引，可实现一次查询快速关联所有图层，替代传统的逐图层空间过滤。
- **时空统计与分析**：在城市治理、物流调度等场景中，常以固定空间单元进行统计汇总。将地物或轨迹数据转换为网格编码后，可按网格单元快速聚合人口密度、设施分布、事件热度等指标，生成多级尺度的统计视图。
- **低空航线规划**：在城市低空物流、应急物资投运、电力设施巡检等应用中，飞行器需要在复杂城市三维环境中规避障碍物等。通过将障碍物空间离散化为三维网格编码，可在网格空间中直接搜索安全航线，替代复杂的三维几何实时求交计算。
---
## 2. 编码体系
在 Yukon `yukon_geogridcoder` 模块中，当前支持 GeoSOT 和北斗两种网格编码。两种编码体系之间可以使用 ``ST_GridConvert` 函数相互转换。
### 编码类型
#### GeoSOT
GeoSOT 是基于地球剖分模型的空间网格编码，支持二维和三维场景。GeoSOT 将地球表面空间进行递归四叉剖分，形成 1-32 级的层次网格体系，精度可达厘米级。数据类型为 `GeoSOTGrid` 或 `GeoGridCode`，编码格式如 `geosot;G001310322-230230`（15 级网格编码）。
#### 北斗网格
北斗网格位置码标准，支持二维和三维场景，适用于与北斗定位系统对接的业务需求，层级范围 1-10 级。数据类型为 `GeoGridCode`，编码格式如 `beidou;N050K0040010700`（4 级网格编码）。
### 索引
合理的索引策略能够显著加速网格编码的空间检索，避免大数据量场景下的全表扫描。`yukon_geogridcoder` 模块支持 **B-Tree** 和 **GIN** 两种索引类型，两者分别适用于不同的数据类型与查询模式。
| 索引类型 | 适用数据类型 | 支持的查询操作符 | 典型应用场景 | 创建语法 |
|----------|-----------|-----------------|-------------|----------|
| **B-Tree** | 单个网格编码值（`GeoSOTGrid`、`GeoGridCode`） | `=`、`ORDER BY` | 已知目标网格编码，精确匹配单条记录 | CREATE INDEX idx_btree_grid
ON sample_grid_table USING BTREE (grid);
|
| **GIN** | 网格编码数组（`GeoSOTGrid[]`、`GeoGridCode[]`） | `&&`（相交）、`@>`（包含）、`<@`（被包含） | 一个空间对象对应多个网格编码时，判断对象集合与目标网格是否存在交集 | CREATE INDEX idx_gin_grid
ON sample_grid_table USING GIN (grid);
|
> **选用建议：** 若数据列存储的是单个网格编码值，使用 B-Tree 索引；若列存储的是网格编码数组（如 `ST_AsGeoGridCode` 的返回结果），使用 GIN 索引。
### 坐标系
GeoSOT 和北斗网格编码均基于 **China2000（EPSG:4490）** 坐标系。待编码的空间对象若处于其他坐标系，需先转换至 EPSG:4490 再执行编码。
### 坐标值区间
不同网格支持的坐标值区间可能存在差异，具体取决于编码体系的设计和实现。请根据实际使用的编码体系参考相关文档确认坐标值区间限制。
---
## 3. 快速入门
### 简介
快速入门文档帮助用户快速理解 Yukon 地理网格编码的基本用法，包括建表、插入数据、计算网格编码、创建索引、查询。
更多网格函数见 [接口参考](../modular_api/geosot_api.md)。
### 语法说明
- 创建具有网格编码的表
```sql
CREATE TABLE t_gridcode (
id integer,
geom geometry, -- 几何对象
grid geogridcode[] -- 通用网格编码数组
);
```
- 插入几何数据
```sql
-- 插入点数据
INSERT INTO t_gridcode (id, geom)
VALUES (1, ST_GeomFromText('POINT(116.31522216796875 39.910277777777778)', 4490)),
(2, ST_GeomFromText('POINT(116.31522217796875 39.910277776777778)', 4490));
-- 插入面数据
INSERT INTO t_gridcode (id, geom)
VALUES (3, 'SRID=4490;POLYGON((116.31 39.90, 116.32 39.90, 116.32 39.91, 116.31 39.91, 116.31 39.90))'::geometry);
```
- 计算网格编码
```sql
-- 生成指定层级的 GeoSOT 网格编码
UPDATE t_gridcode
SET grid = ST_AsGeoGridCode(geom, 15, 'geosot');
-- 生成指定层级的北斗网格编码
UPDATE t_gridcode
SET grid = ST_AsGeoGridCode(geom, 4, 'beidou');
```
- 对网格码创建索引
```sql
-- 对网格编码数组列创建 GIN 索引
CREATE INDEX idx_gridcode_gin
ON t_gridcode USING GIN (grid);
```
- 查询
```sql
-- 与某个网格相交
SELECT id
FROM t_gridcode
WHERE grid && ARRAY['geosot;G001310322-230230'::geogridcode];
-- 网格编码转换为 WKT 几何对象
SELECT ST_AsText(ST_GeomFromGeoGridCode(unnest(grid)))
FROM t_gridcode
WHERE id = 1;
```
---