空间网格编码
==============

yukon_geogridcoder 模块提供空间网格编码的相关操作，目前支持 GeoSOT 编码。使用前数据库需创建 yukon_geogridcoder 扩展。
相关参考见：
:ref:`geosotintroduce_label`、
:ref:`demogeosot1_label`、
:ref:`demogeosot2_label`。


数据类型
--------

GeoSOTGrid
~~~~~~~~~~~~

空间网格编码数据类型。
支持为 GeoSOTGrid 列创建 B树索引，支持为 GeoSOTGrid 数组创建 GIN 索引（Generalized Inverted Index）。


网格构造
-------------

ST_GeoSOTGrid
~~~~~~~~~~~~~~

获取 geometry 对象的网格编码，默认获取对象的最小外包网格编码，也可设置指定层级，获取对象指定层级的空间网格编码。

**语法**

.. code:: 

   geosotgrid[] ST_GeoSOTGrid (geom geometry, int level);
   geosotgrid[] ST_GeoSOTGrid (geom geometry);

   参数：
      geometry - 几何对象
      level - 网格编码层级
   返回：
      空间对象的空间网格编码。

**示例**

.. code:: SQL

   SELECT ST_GeoSOTGrid(st_geomfromtext('POINT(116.315  39.91027777777778)', 4490), 15);

   --------------------------
   {074EACB000000000000F0000}


ST_GeoSOTGridAgg
~~~~~~~~~~~~~~~~

获取 geometry 对象在指定层级范围内的网格编码。

**语法**

.. code:: 

   geosotgrid[] ST_GeoSOTGridAgg(geom geometry, int level_max, int level_min);

   参数：
      geometry - 几何对象
      level_max - 最大编码层级
      level_min - 最小编码层级
   返回：
      空间对象的空间网格编码。

**示例**

.. code:: SQL

   SELECT ST_GeoSOTGridAgg('srid=4490;polygon((0.1 0.1, 0.2 0.2, 0.3 0.1, 0.1 0.1))'::geometry, 11, 9);

   --------------------------
   {0000000000000000000B0000,0000040000000000000B0000}


ST_GeoSOTGridZ
~~~~~~~~~~~~~~

返回 z 方向上指定层级的网格编号，用海拔基准面开始向上的第 N 层网格来表示。

**语法**

.. code:: 

   int ST_GeoSOTGridZ(float8 altitude, int level);

   参数：
      altitude - 海拔高度
      level - 网格编码层级
   返回：
      z 方向上的网格编号。

**示例**

.. code:: SQL

   SELECT ST_GeoSOTGridZ(9300, 15);

   ----------
   5


ST_Aggregate
~~~~~~~~~~~~~~~~

通过精细层网格编码聚合粗糙层网格编码。

**语法**

.. code:: 

   geosotgrid ST_Aggregate(geosotgrid grid, int level);
   geosotgrid[] ST_Aggregate(geosotgrid[] gridarray,int level);

   参数：
      grid - 网格编码
      gridarray - 网格编码数组
      level - 网格编码层级
   返回：
      空间对象的空间网格编码。

**示例**

.. code:: SQL

   SELECT ST_Aggregate('074EA000000000000A0A0000'::geosotgrid, 9);

   --------------------------
   074E80000000000009090000


网格访问
-------------

ST_GetLevel
~~~~~~~~~~~~~~~~~~~~

获取网格对象的编码层级。

**语法**

.. code:: 

   int ST_GetLevel(grid geosotgrid);

   参数：
      geosotgrid - 网格对象
   返回：
      网格编码层级。

**示例**

.. code:: SQL

   SELECT ST_GetLevel('0000040000000000000B0000');

   --------------------------
   11


ST_GetLevelExtremum
~~~~~~~~~~~~~~~~~~~~

获取网格编码数组的编码层级范围。

**语法**

.. code:: 

   int[] ST_GetLevelextremum(geosotgrid[] gridarray);
      
   参数：
      gridarray - 网格编码数组
   返回：
      网格编码层级范围,{最小层级level_min，最大层级level_max}

**示例**

.. code:: SQL

   SELECT ST_GetLevelextremum(array['074526EEF400000013130000','07452C4701C0000013150000'::geosotgrid]);

   --------------------------
   {19,21}


ST_HasZ
~~~~~~~~~~~~

网格编码是否含Z方向。

**语法**

.. code:: 

   bool ST_HasZ(geosotgrid grid);
      
   参数：
      grid - 网格对象
   返回：
      网格编码含z方向返回true，不含z方向返回false。

**示例**

.. code:: SQL

   SELECT ST_HasZ(unnest(ST_GeoSOTGrid(st_geomfromtext('POINT(116.315 39.91027777777778)', 4490), 15)));

   --------------------------
   false


ST_AltitudeFromGeoSOTGridZ
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

返回 Z 方向指定层级下第 N 个网格对应的海拔高度，单位米。

**语法**

.. code:: 

   float ST_AltitudeFromGeoSOTGridZ(int4 z_num,int level);
      
   参数：
      z_num - Z方向上的第几个网格
      level - 网格编码层级
   返回：
      海拔高度。

**示例**

.. code:: SQL

   SELECT ST_AltitudeFromGeoSOTGridZ(5, 15);

   --------------------------
   9203.23364591971


转换函数
-------------

ST_AsText
~~~~~~~~~~

将网格编码转换为标准规范的文本字符串。

**语法**

.. code:: 

   text ST_AsText(geosotgrid grid);
      
   参数：
      grid - 网格对象
   返回：
      网格编码的文本字符串

**示例**

.. code:: SQL

   SELECT ST_AsText('074EACB000000000000F0000'::geosotgrid);

   --------------------------
   G001310322-230230


ST_GeoSOTGridFromText
~~~~~~~~~~~~~~~~~~~~~~

将网格编码文本字符串转为 geosotgrid 类型的网格编码。

**语法**

.. code:: 

   geosotgrid ST_GeoSOTGridFromText(cstring geosotgrid2d);
   geosotgrid ST_GeoSOTGridFromText(cstring geosotgrid2d, cstring geosotgrid_z);
      
   参数：
      geosotgrid2d - 二维网格编码字符串
      geosotgrid_z - 三维网格编码Z方向字符串
   返回：
      geosotgrid 类型的网格编码。

**示例**

.. code:: SQL

   SELECT ST_GeoSOTGridFromText('G001310322-230230', '101');

   --------------------------
   00B21A4984C0000000000104000F0001


ST_GeomFromGeoSOTGrid
~~~~~~~~~~~~~~~~~~~~~~

返回网格对象的几何信息，二维网格返回POLYGON，三维网格返回POLYHEDRALSURFACE Z

**语法**

.. code:: 

   geometry ST_GeomFromGeoSOTGrid(geosotgrid grid);
   geometry[] ST_GeomFromGeoSOTGrid(geosotgrid[] gridarray);
      
   参数：
      grid - 网格编码
      gridarray - 网格编码数组
   返回：
      geosotgrid 类型的网格编码

**示例**

.. code:: SQL

   SELECT ST_ASTEXT(ST_GeomFromGeoSOTGrid('074EACB000000000000F0000'::geosotgrid));

   --------------------------
   POLYGON (116.3 39.9, 116.3 39.916666666666664, 116.31666666666666 39.916666666666664, 116.31666666666666 39.9, 116.3 39.9)


操作符
-----------

&&
~~~~~~~~~~

网格编码相交计算，此操作符不仅可对同一层级的网格编码计算是否相交，对多个不同层级的网格编码同样可以计算相交关系。

**语法**

.. code:: 

    boolean &&(geosotgrid[] gridsA,geosotgrid[] gridsB);
    
    参数：
      gridsA - 网格编码数组A
      gridsB - 网格编码数组B
    返回：
      存在相交则返回 true，不存在相交则返回 false。

**示例**

.. code:: SQL

   SELECT ST_GeoSOTGrid(ST_MAKEENVELOPE(1, 1, 2, 2, 4490), 15) && ST_GeoSOTGrid(ST_MAKEENVELOPE(1.5, 1.5, 2.5, 2.5, 4490), 15);
 
   -------------
   true


@>
~~~~~~~~~~~~~

网格编码包含关系计算。

**语法**

.. code::

    boolean @>(geosotgrid[] gridsA,geosotgrid[] gridsB);
    
    参数：
      gridsA - 网格编码数组A
      gridsB - 网格编码数组B
    返回：
      若包含则返回 true，不包含相交则返回 false。

**示例**

.. code:: SQL

   SELECT ST_GeoSOTGrid(ST_MAKEENVELOPE(1, 1, 2, 2, 4490), 15) @> ST_GeoSOTGrid(ST_MAKEENVELOPE(1.2, 1.2, 1.8, 1.8, 4490), 15);
 
   -------------
   true


@<
~~~~~~~~~~~~~~

网格编码被包含关系计算。

**语法**

.. code:: 

    boolean @<(geosotgrid[] gridsA,geosotgrid[] gridsB);
    
    参数：
      gridsA - 网格编码数组A
      gridsB - 网格编码数组B
    返回：
      若被包含则返回 true，不被包含则返回 false。

**示例**

.. code:: SQL
   
   SELECT ST_GeoSOTGrid(ST_MAKEENVELOPE(1.5, 1.5, 2, 2, 4490), 15) <@ ST_GeoSOTGrid(ST_MAKEENVELOPE(1, 1, 2, 2, 4490), 15);
 
   -------------
   true