空间网格编码
==============
空间网格编码模块，目前支持GeoSOT编码，参见知识库: :ref:`geosotintroduce_label` 。
使用范例参见范例集：:ref:`demogeosot1_label` ; :ref:`demogeosot2_label`

.. code:: sql

       --- 创建 yukon_geogridcoder 扩展
       CREATE EXTENSION yukon_geogridcoder;


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

-  **GeoSOTGrid**

    + 可作为列的数据类型；

    + 支持为 GeoSOTGrid 列创建B树索引；

    + 支持为 GeoSOTGrid 数组创建 GIN 索引(Generalized Inverted Index)。


对象操作
-------------------------

.. _stgetlevel:

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

获取网格对象的编码层级

**语法**

.. code:: 

   int ST_GetLevel(grid geosotgrid);

**参数**

======== ========
参数名称 描述
======== ========
grid     网格对象
======== ========

**示例**

.. code:: 

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

   st_getlevel
   -----------+
            15

.. _sthasz:

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

网格对象是否带Z方向编码

**语法**

.. code:: 

   bool ST_HasZ(grid geosotgrid);

**参数**

======== ========
参数名称 描述
======== ========
grid     网格对象
======== ========

**示例**

.. code:: 

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

   st_hasz
   -------+
   false  

网格编码计算
-------------

.. _stgeosotgrid:

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

获取geometry对象在指定层级所对应的网格编码

**语法**

.. code:: 

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

**参数**

======== ========
参数名称 描述
======== ========
geom     几何对象
level    编码等级
======== ========

**示例**

.. code:: 

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

   st_geosotgrid             |
   --------------------------+
   {074EACB000000000000F0000}|

文本转换
------------------

.. _stastext:

ST_AsText
~~~~~~~~~~~~~~~~~~~~~~~

将网格对象转换为标准规范的文本编码

**语法**

.. code:: 

   text ST_AsText(grid geosotgrid);

**参数**

======== ========
参数名称 描述
======== ========
grid     网格对象
======== ========

**示例**

.. code:: 

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

   st_astext        |
   -----------------+
   G001310322-230230|

.. _stgeosotgridfromtext:

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

将网格对象字符串转为geosotgrid对象数据类型

**语法**

.. code:: 

   geosotgrid ST_GeoSOTGridFromText(geosotgrid2d cstring);
   geosotgrid ST_GeoSOTGridFromText(geosotgrid2d cstring, geosotgrid_z cstring);

**参数**

============ =======================
参数名称     描述
============ =======================
geosotgrid2d 二维网格对象字符串
geosotgrid_z 三维网格Z方向编码字符串
============ =======================

**示例**

.. code:: 

   SELECT ST_GeoSOTGridFromText('G001310322-230230');

   st_geosotgridfromtext   |
   ------------------------+
   074EACB000000000000F0000|

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

   st_geosotgridfromtext           |
   --------------------------------+
   00B21A4984C0000000000104000F0001|

几何转换
------------------

.. _stgeomfromgeosotgrid:

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

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

**语法**

.. code:: 

   geometry ST_GeomFromGeoSOTGrid(grid geosotgrid);

   geometry[] ST_GeomFromGeoSOTGrid(gridarray geosotgrid[]);

**参数**

========= ============
参数名称  描述
========= ============
grid      网格对象
gridarray 网格对象数组
========= ============

**示例**

.. code:: 

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

   st_geomfromgeosotgrid																	
   ----------------------------------------------------------------------------------------+
   POLYGON ((116.3 39.9, 116.3 39.916666666666664, 116.31666666666666 39.916666666666664, 116.31666666666666 39.9, 116.3 39.9))												   |

   SELECT ST_GeomFromGeoSOTGrid('00B21A4984C0000000000104000F0001'::geosotgrid);

   st_geomfromgeosotgrid                                                                   
   ----------------------------------------------------------------------------------------+
   SRID=4490;SRID=4490;POLYHEDRALSURFACE Z (((116.3 39.9 9203.23364591971, 116.3 39.916666666666664 9203.23364591971, 116.31666666666666 39.916666666666664 9203.23364591971, 116.31666666666666 39.9 9203.23364591971, 116.3 39.9 9203.23364591971)), ((116.3 39.9 11045.473321879283, 116.31666666666666 39.9 11045.473321879283, 116.31666666666666 39.916666666666664 11045.473321879283, 116.3 39.916666666666664 11045.473321879283, 116.3 39.9 11045.473321879283)), ((116.3 39.9 9203.23364591971, 116.3 39.9 11045.473321879283, 116.3 39.916666666666664 11045.473321879283, 116.3 39.916666666666664 9203.23364591971, 116.3 39.9 9203.23364591971)), ((116.31666666666666 39.9 9203.23364591971, 116.31666666666666 39.916666666666664 9203.23364591971, 116.31666666666666 39.916666666666664 11045.473321879283, 116.31666666666666 39.9 11045.473321879283, 116.31666666666666 39.9 9203.23364591971)), ((116.3 39.9 9203.23364591971, 116.31666666666666 39.9 9203.23364591971, 116.31666666666666 39.9 11045.473321879283, 116.3 39.9 11045.473321879283, 116.3 39.9 9203.23364591971)), ((116.3 39.916666666666664 9203.23364591971, 116.3 39.916666666666664 11045.473321879283, 116.31666666666666 39.916666666666664 11045.473321879283, 116.31666666666666 39.916666666666664 9203.23364591971, 116.3 39.916666666666664 9203.23364591971)))

.. code:: 

   SELECT unnest(ST_GeomFromGeoSOTGrid(ST_GeoSOTGrid(st_makeenvelope(116.31, 39.91, 116.32, 39.92, 4490), 15)));

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

   POLYGON ((116.31666666666666 39.9, 116.31666666666666 39.916666666666664, 116.33333333333333 39.916666666666664, 116.33333333333333 39.9, 116.31666666666666 39.9))

   POLYGON ((116.3 39.916666666666664, 116.3 39.93333333333333, 116.31666666666666 39.93333333333333, 116.31666666666666 39.916666666666664, 116.3 39.916666666666664)) 

   POLYGON ((116.31666666666666 39.916666666666664, 116.31666666666666 39.93333333333333, 116.33333333333333 39.93333333333333, 116.33333333333333 39.916666666666664, 116.31666666666666 39.916666666666664))	


层级转换
-------------

.. _stdegenerate:

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

从精细层网格对象构造粗糙层

**语法**

.. code:: 

   geosotgrid ST_Aggregate(grid geosotgrid, level int);

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

**参数**

========= ============
参数名称  描述
========= ============
grid      网格对象
gridarray 网格对象数组
level     层级
========= ============

**示例**

.. code:: 

   SELECT ST_GeomFromGeoSOTGrid(ST_Aggregate(unnest(ST_GeoSOTGrid(st_geomfromtext('POINT(116.315 39.91027777777778)', 4490), 10)), 9));

   st_geomfromgeosotgrid                             
   --------------------------------------------------+
   POLYGON ((116 39, 116 40, 117 40, 117 39, 116 39))

高度编码
---------------

.. _stgeosotgridz:

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

返回高度方向所属的第N个网格

**语法**

.. code:: 

   int ST_GeoSOTGridZ(altitude float8, level int);

**参数**

======== ========
参数名称 描述
======== ========
altitude 海拔高度
level    层级
======== ========

**示例**

.. code:: 

   SELECT ST_GeoSOTGridZ(9300, 15);

   st_geosotgridz
   --------------+
                5

.. _staltitudefromgeosotgridz:

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

返回Z方向第N个格子在指定层级时的高度值

**语法**

.. code:: 

   float ST_AltitudeFromGeoSOTGridZ(z_num int4, level int);

**参数**

======== =================
参数名称 描述
======== =================
z_num    Z方向上第几个格子
level    格子所在的层级
======== =================

**示例**

.. code:: 

   SELECT ST_AltitudeFromGeoSOTGridZ(5, 15);

   st_altitudefromgeosotgridz
   --------------------------+
             9203.23364591971