三维模型数据
============
格式说明参见知识库: :ref:`geomodelintroduce_label` 

使用范例参见范例集：:ref:`demo_regionextrude_label` 

yukon_geomodel模块提供对三维模型数据的存储和管理能力，使用前需要创建扩展：

.. code:: sql

       --- 创建postgis扩展， yukon_geomodel依赖于postgis。如果已创建，可忽略
       CREATE EXTENSION postgis;
       --- 创建 yukon_geomodel 扩展
       CREATE EXTENSION yukon_geomodel;


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

-  **GEOMODEL**\ ：MESH、SURFACE、ANYTYPE

支持客户端以二进制形式读写。

-  **MODEL_ELEM**

MODEL_ELEM
的子类包括骨架（EntitySkeleton）、材质（EntityMaterial3D）和纹理（EntityTexture）。

支持客户端以二进制形式读写。

.. warning::
    不能直接DDL操作，应通过数据库函数操作：AddGeomodelColumn、DropGeomodelColumn

.. note::
    本节示例中出现的geomodel相关二进制数据，是按geomodel的数据结构构造的。

管理函数
--------

AddGeoModelColumn
~~~~~~~~~~~~~~~~~

向指定的表格添加 geomodel 列，并自动创建子表。

**语法**

.. code:: SQL

    text AddGeoModelColumn(schema_name varchar, table_name varchar, column_name varchar, new_srid_in integer, _type varchar DEFAULT 'ANYTYPE');

**参数**

+-----------------+----------------------------------------+
| 参数名称        | 描述                                   |
+=================+========================================+
| schema\_name    | 模式名称                               |
+-----------------+----------------------------------------+
| table\_name     | 表名                                   |
+-----------------+----------------------------------------+
| column\_name    | 列名                                   |
+-----------------+----------------------------------------+
| new\_srid\_in   | 坐标系                                 |
+-----------------+----------------------------------------+
| \_type          | geomodel类型：ANYTYPE、MESH、SURFACE   |
+-----------------+----------------------------------------+

**示例**

.. code:: SQL

    SELECT AddGeoModelColumn('public','geomodel_test','geog',4326);

    addgeomodelcolumn| 
    -----------------+ 
    success 

DropGeomodelColumn
~~~~~~~~~~~~~~~~~~

删除指定表格的 geomodel 列，并删除子表。

**语法**

.. code:: SQL
    
    text DropGeomodelColumn(schema_name varchar, table_name varchar);

**参数**

+--------------------+----------+
| 参数名称           | 描述     |
+====================+==========+
| **schema\_name**   | 模式名   |
+--------------------+----------+
| **table\_name**    | 表名     |
+--------------------+----------+

**示例**

.. code:: SQL

    SELECT DropGeomodelColumn('public', 'geomodel_test');

DropGeomodelTable
~~~~~~~~~~~~~~~~~

删除带 geomodel 列的表及其子表。

**语法**

.. code:: SQL

    text DropGeomodelTable(varchar schema_name, varchar table_name);

**参数**

+--------------------+----------+
| 参数名称           | 描述     |
+====================+==========+
| **schema\_name**   | 模式名   |
+--------------------+----------+
| **table\_name**    | 表名     |
+--------------------+----------+

**示例**

.. code:: SQL

    SELECT DropGeomodelTable('public', 'geomodel_test');

UpdateGeomodelSRID
~~~~~~~~~~~~~~~~~~

更新 geomodel 列的 SRID，包括对象和元数据。

三个重载方法，可以指定/不指定catalog、schema名。

**语法**

.. code:: SQL
    
    text UpdateGeomodelSRID(varchar schema_name, varchar table_name, varchar column_name, integer srid);

**参数**

+--------------------+------------------------+
| 参数名称           | 描述                   |
+====================+========================+
| **schema\_name**   | 模式名                 |
+--------------------+------------------------+
| **table\_name**    | 表名                   |
+--------------------+------------------------+
| **column\_name**   | 列名                   |
+--------------------+------------------------+
| **srid**           | 指定的空间参考标识符   |
+--------------------+------------------------+

**示例**

.. code:: SQL

    SELECT UpdateGeomodelSRID('public', 'geomodel_test','geog',4326);

操作函数 
---------

ST_GeoModelType
~~~~~~~~~~~~~~~~

获取 geomodel 列的类型。包括：mesh、surface、anytype

**语法**

.. code:: SQL
    
    text ST_GeoModelType(geomodel geog);

**参数**

+------------+----------------+
| 参数名称   | 描述           |
+============+================+
| **geog**   | geomodel对象   |
+------------+----------------+

**示例**

.. code:: SQL

    select  ST_GeoModelType('01000000180000003131395F303030303030303038373244364531305F47656F3B0000005B505F5A303130303233372E6A70677C716B31366A7A31312E6A70675F4166666666666666665F4466666666666666665F53305F504633432D315D00000040BF1357C00000008028094F40000000E0BE14294000000080EF385AC000000080DCEF4E400000000000002440000000000000F03F0000000000000000000000000000000000000000000000000000000000000000000000000000F03F0000000000000000000000000000000000000000000000000000000000000000000000000000F03F0000000000000000000000000000000000000000000000000000000000000000000000000000F03F0700000003000500000000007CC7D1C2E47E7742F7A54841FA9DB8C244497842F7A54841FA9DB8C24449784211113141FA9DB8C244497842000020417CC7D1C2E47E77420000204105000000000066AB80BCEAF77F3F0000008066AB80BCEAF77F3F0000008066AB80BCEAF77F3F0000008066AB80BCEAF77F3F0000008066AB80BCEAF77F3F0000008000000000020000000200050000000000324E1340B5D46A3F40208ABEB5D46A3F40208ABE6357C53E40208ABE9AF4023A324E13409AF4023A0200050000000000EC73043D8F9B463F71F5B73D8F9B463F71F5B73DDC54483F71F5B73D3C94493FEC73043D3C94493F0100000009000000000000000104000000000001000200000002000300000003000400010000003B0000005B505F5A303130303233372E6A70677C716B31366A7A31312E6A70675F4166666666666666665F4466666666666666665F53305F504633432D315D'::geomodel);

    st_geomodeltype| 
    ---------------+ 
    MESH 

ST_Boundary
~~~~~~~~~~~~

获取 geomodel 对象的包围盒。

**语法**

.. code:: SQL
    
    box3d  ST_Boundary(geomodel geog);

**参数**

+------------+----------------+
| 参数名称   | 描述           |
+============+================+
| **geog**   | geomodel对象   |
+------------+----------------+

**示例** 

.. code:: SQL

    SELECT
    ST_BOUNDARY('0000000DECE3E242ECE3E2425299B1415299B141ACA5C24AC0A5C24A20030000019E359B197B5C5C40F43AB644F83236400000000000001440000000000000F03F000000000000F03F000000000000F03F0000000000000000000000000000000000000000000000000000000000002E40000000000040554000000000008050400000000000002E4000000000004055400000000000004C4000000000010000000000000000000000FFFFFFFF00000000010000005D4DEAF7FFFFEF3FDED00754553011BF3A6C21F0950F253F0000000000000000292689A4C22D113FFE8490EFFFFFEF3F45935EEF43462F3F00000000000000009F75D7491C1025BF7B4B4A74E9452FBFD262C9E9FFFFEF3F0000000000000000153DD156A8138B40735905F367BC92C05439F3226B934540000000000000F03F01000000200000004275696C64696E675F484B35315F42555F42425F3037345F4C4F44322D315F30010000005B0000004D544C5F443A5CCAFDBEDDCFEE5C4D6178D4B4CAFDBEDD5CB2A9B8E75C484B35315C4C4F44325C6D6170735C484B35315F42555F43435F3032302E6A706766666666666666665F66666666666666665F305F302E3030303030305F010000003A000000443A5CCAFDBEDDCFEE5C4D6178D4B4CAFDBEDD5CB2A9B8E75C484B35315C4C4F44325C6D6170735C484B35315F42555F43435F3032302E6A7067'::geomodel);
    
    st_boundary |
    ------------------------------------------------------------------------------------------+
    BOX3D(113.445159912109 22.1998634338379 6378198,113.445159912109 22.1998634338379 6378208)

ST_Extent
~~~~~~~~~~

聚合函数，获取 geomodel 列的矩形范围。

**语法**

.. code:: SQL

    box2d  ST_Extent(geomodel geog);

**参数**

+------------+----------------+
| 参数名称   | 描述           |
+============+================+
| **geog**   | geomodel对象   |
+------------+----------------+

**示例**

.. code:: SQL
    
    select
    ST_Extent('0000000DECE3E242ECE3E2425299B1415299B141ACA5C24AC0A5C24A20030000019E359B197B5C5C40F43AB644F83236400000000000001440000000000000F03F000000000000F03F000000000000F03F0000000000000000000000000000000000000000000000000000000000002E40000000000040554000000000008050400000000000002E4000000000004055400000000000004C4000000000010000000000000000000000FFFFFFFF00000000010000005D4DEAF7FFFFEF3FDED00754553011BF3A6C21F0950F253F0000000000000000292689A4C22D113FFE8490EFFFFFEF3F45935EEF43462F3F00000000000000009F75D7491C1025BF7B4B4A74E9452FBFD262C9E9FFFFEF3F0000000000000000153DD156A8138B40735905F367BC92C05439F3226B934540000000000000F03F01000000200000004275696C64696E675F484B35315F42555F42425F3037345F4C4F44322D315F30010000005B0000004D544C5F443A5CCAFDBEDDCFEE5C4D6178D4B4CAFDBEDD5CB2A9B8E75C484B35315C4C4F44325C6D6170735C484B35315F42555F43435F3032302E6A706766666666666666665F66666666666666665F305F302E3030303030305F010000003A000000443A5CCAFDBEDDCFEE5C4D6178D4B4CAFDBEDD5CB2A9B8E75C484B35315C4C4F44325C6D6170735C484B35315F42555F43435F3032302E6A7067'::geomodel);

    st_extent |
    ------------------------------------------------------------------------+
    BOX(113.445159912109 22.1998634338379,113.445159912109 22.1998634338379)|

ST_3DExtent
~~~~~~~~~~~~

聚合函数，获取 geomodel 列的包围盒。

**语法**

.. code:: SQL

    box3d  ST_3DExtent(geomodel geog);
    
**参数**

+------------+----------------+
| 参数名称   | 描述           |
+============+================+
| **geog**   | geomodel对象   |
+------------+----------------+

**示例**

.. code:: SQL
    
    select
    ST_3DExtent('0000000DECE3E242ECE3E2425299B1415299B141ACA5C24AC0A5C24A20030000019E359B197B5C5C40F43AB644F83236400000000000001440000000000000F03F000000000000F03F000000000000F03F0000000000000000000000000000000000000000000000000000000000002E40000000000040554000000000008050400000000000002E4000000000004055400000000000004C4000000000010000000000000000000000FFFFFFFF00000000010000005D4DEAF7FFFFEF3FDED00754553011BF3A6C21F0950F253F0000000000000000292689A4C22D113FFE8490EFFFFFEF3F45935EEF43462F3F00000000000000009F75D7491C1025BF7B4B4A74E9452FBFD262C9E9FFFFEF3F0000000000000000153DD156A8138B40735905F367BC92C05439F3226B934540000000000000F03F01000000200000004275696C64696E675F484B35315F42555F42425F3037345F4C4F44322D315F30010000005B0000004D544C5F443A5CCAFDBEDDCFEE5C4D6178D4B4CAFDBEDD5CB2A9B8E75C484B35315C4C4F44325C6D6170735C484B35315F42555F43435F3032302E6A706766666666666666665F66666666666666665F305F302E3030303030305F010000003A000000443A5CCAFDBEDDCFEE5C4D6178D4B4CAFDBEDD5CB2A9B8E75C484B35315C4C4F44325C6D6170735C484B35315F42555F43435F3032302E6A7067'::geomodel);

    st_3dextent |
    ------------------------------------------------------------------------------------------+
    BOX3D(113.445159912109 22.1998634338379 6378198,113.445159912109 22.1998634338379 6378208)|

ST_SRID
~~~~~~~~

获得 geomodel 对象的空间参考标识符

**语法**

.. code:: SQL
    
    integer ST_SRID(geomodel geog);

**参数**

+------------+----------------+
| 参数名称   | 描述           |
+============+================+
| **geog**   | geomodel对象   |
+------------+----------------+

**示例**

.. code:: SQL
    
    SELECT ST_SRID('0010E60DC0E3E242CB'::geomodel);
    st_srid|
    -------+ 
    4326   |

ST_SetSRID
~~~~~~~~~~~

设置 geomodel 对象的空间参考标识符

**语法**

.. code:: SQL

    geomodel ST_SetSRID(geom geomodel, srid integer);

**参数**

+------------+------------------------+
| 参数名称   | 描述                   |
+============+========================+
| **geog**   | geomodel对象           |
+------------+------------------------+
| **srid**   | 指定的空间参考标识符   |
+------------+------------------------+

**示例**

.. code:: SQL
    
    SELECT ST_SetSRID('0000000DC0E3E242CB'::geomodel, 4326);
    st_setsrid | 
    ------------------+ 
    0010E60DC0E3E242CB|

构造函数
--------

ST_MakeSkeletonFromTIN
~~~~~~~~~~~~~~~~~~~~~~~

从TIN对象构建模型的骨架

**语法**

.. code:: SQL

    model_elem ST_MakeSkeletonFromTIN(geometry geom,text skeleton_name,text material_name);

**参数**

+----------------------+---------------------------+
| 参数名称             | 描述                      |
+======================+===========================+
| **geom**             | geometry 对象，TIN 类型   |
+----------------------+---------------------------+
| **skeleton\_name**   | 设置骨架的名字            |
+----------------------+---------------------------+
| **material\_name**   | 设置骨架上挂接的材质名    |
+----------------------+---------------------------+

ST_MakeDefaultMaterial
~~~~~~~~~~~~~~~~~~~~~~~

构造一个默认的材质对象

**语法**

.. code:: SQL

    model_elem ST_MakeDefaultMaterial(text material_name);

**参数**

+----------------------+--------------------------+
| 参数名称             | 描述                     |
+======================+==========================+
| **material\_name**   | 设置骨架上挂接的材质名   |
+----------------------+--------------------------+

ST_MakeGeomodel
~~~~~~~~~~~~~~~~

从骨架对象构造 geomodel 对象

.. code:: text

    geomodel ST_MakeGeomodel(model_elem objskeleton);

**参数**

+-------------------+------------+
| 参数名称          | 描述       |
+===================+============+
| **objskeleton**   | 骨架对象   |
+-------------------+------------+

ST_MakeHashID
~~~~~~~~~~~~~~

名字转 Hash 值，作为子表的ID列值

.. code:: SQL

    int8 ST_MakeHashID(text elemname);

**参数**

+----------------+--------------------------+
| 参数名称       | 描述                     |
+================+==========================+
| **elemname**   | model\_elem 对象的名字   |
+----------------+--------------------------+

**示例**

.. code:: SQL

    SELECT  ST_MakeHashID('material1');

    -- 输出
    6152814707455701482

空间索引
--------

可以对 geomodel 列创建 GiST 索引

**示例**

.. code:: SQL
    
    -- 其中 modelcol 是表的 geomodel 列   
    CREATE INDEX building_tree ON building USING GIST ( modelcol );

操作符
------

&&
~~~~~

判断 geomodel 对象和 geometry 对象是否相交

**语法**

.. code:: SQL
    
    boolean Operator &&;

**示例**

.. code:: SQL

    select '0000000DC0E3E242CB'::geomodel && st_makepoint(1, 1);
    column  | 
    --------+ 
    false   |