三维模型数据模块
=====================

yukon_geomodel 模块提供对空间三维模型数据的存储和管理。使用前数据库需创建 postgis 和 yukon_geomodel 扩展。
相关参考见：
:ref:`geomodelintroduce_label`、
:ref:`demo_regionextrude_label`。

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

GEOMODEL
~~~~~~~~~~~

三维模型几何对象类，其类型包括MESH、SURFACE、ANYTYPE。
支持客户端以二进制形式读写。

MODEL_ELEM
~~~~~~~~~~~

三维模型元素类，其类型包括EntitySkeleton（骨架）、EntityMaterial3D（材质）、EntityTexture（纹理）。
支持客户端以二进制形式读写。

.. warning::

GEOMODEL和MODEL_ELEM数据不能直接使用DDL命令操作，需通过数据库函数（如AddGeomodelColumn()、DropGeomodelColumn()）来完成数据的新增、删除等操作。


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

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
    返回：
        成功返回success,失败返回fail。

**示例**

.. code:: SQL

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

    -----------------
    success


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

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

**语法**

.. code:: SQL

    text DropGeomodelColumn(schema_name varchar, table_name varchar);

    参数：
        schema_name - 模式名称
        table_name - 表名
    返回：
        成功返回success,失败返回fail。

**示例**

.. code:: SQL

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

    -----------------
    success


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

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

**语法**

.. code:: SQL

    text DropGeomodelTable(varchar schema_name, varchar table_name);

    参数：
        schema_name - 模式名称
        table_name - 表名
    返回：
        成功返回success,失败返回fail。

**示例**

.. code:: SQL

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

    -----------------
    success


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

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

**语法**

.. code:: SQL

    text UpdateGeomodelSRID(varchar schema_name, varchar table_name, varchar column_name, integer srid);

    参数：
        schema_name - 模式名称
        table_name - 表名
        column_name - 列名
        srid - 指定的空间参考标识符
    返回：
        成功返回success,失败返回fail。

**示例**

.. code:: SQL

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

    -----------------
    success


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

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:: SQL

    geomodel ST_MakeGeomodel(model_elem objskeleton);

    参数：
        objskeleton - 骨架对象
    返回：
        返回 geomodel 对象。

**示例**

无


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

模型对象的名称转为 Hash 值，作为子表的 ID 唯一标识。

**语法**

.. code:: SQL

    int8 ST_MakeHashID(text elemname);

    参数：
        elemname - 模型对象的名称
    返回：
        返回 Hash 值。

**示例**

.. code:: SQL

    SELECT  ST_MakeHashID('material1');

    --------------------
    6152814707455701482


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

对 geomodel 列创建 GIST 索引。

**语法**

.. code:: SQL

    GIST(modelcol);

    参数：
        modelcol - geomodel 列名

**示例**

.. code:: SQL

    CREATE INDEX building_tree ON building USING GIST (modelcol);


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

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

获取 geomodel 列的类型，值域：MESH、SURFACE、ANYTYPE。

**语法**

.. code:: SQL

    text ST_GeoModelType(geomodel geog);

    参数：
        geog - geomodel对象
    返回：
        返回geomodel类型，值域：MESH、SURFACE、ANYTYPE。

**示例**

.. code:: SQL

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

    ---------------
    MESH
    

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

获取 geomodel 对象的包络盒。

**语法**

.. code:: SQL

    box3d ST_Boundary(geomodel geog);

    参数：
        geog - geomodel对象
    返回：
        返回 geomodel 对象的包络盒几何。

**示例**

.. code:: SQL

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


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

获取 geomodel 对象的包络盒。

**语法**

.. code:: SQL

    box3d ST_3DExtent(geomodel geog);

    参数：
        geog - geomodel对象
    返回：
        返回 geomodel 对象的包络盒几何。

**示例**

.. code:: SQL

    SELECT
    ST_3DExtent('0000000DECE3E242ECE3E2425299B1415299B141ACA5C24AC0A5C24A20030000019E359B197B5C5C40F43AB644F83236400000000000001440000000000000F03F000000000000F03F000000000000F03F0000000000000000000000000000000000000000000000000000000000002E40000000000040554000000000008050400000000000002E4000000000004055400000000000004C4000000000010000000000000000000000FFFFFFFF00000000010000005D4DEAF7FFFFEF3FDED00754553011BF3A6C21F0950F253F0000000000000000292689A4C22D113FFE8490EFFFFFEF3F45935EEF43462F3F00000000000000009F75D7491C1025BF7B4B4A74E9452FBFD262C9E9FFFFEF3F0000000000000000153DD156A8138B40735905F367BC92C05439F3226B934540000000000000F03F01000000200000004275696C64696E675F484B35315F42555F42425F3037345F4C4F44322D315F30010000005B0000004D544C5F443A5CCAFDBEDDCFEE5C4D6178D4B4CAFDBEDD5CB2A9B8E75C484B35315C4C4F44325C6D6170735C484B35315F42555F43435F3032302E6A706766666666666666665F66666666666666665F305F302E3030303030305F010000003A000000443A5CCAFDBEDDCFEE5C4D6178D4B4CAFDBEDD5CB2A9B8E75C484B35315C4C4F44325C6D6170735C484B35315F42555F43435F3032302E6A7067'::geomodel);
    
    ------------
    BOX3D(113.445159912109 22.1998634338379 6378198,113.445159912109 22.1998634338379 6378208)

ST_Extent
~~~~~~~~~~~~~~

获取 geomodel 对象的最小外接矩形。

**语法**

.. code:: SQL

    box2d ST_Extent(geomodel geog);

    参数：
        geog - geomodel对象
    返回：
        返回 geomodel 对象的最小外接矩形。

**示例**

.. code:: SQL

    SELECT
    ST_Extent('0000000DECE3E242ECE3E2425299B1415299B141ACA5C24AC0A5C24A20030000019E359B197B5C5C40F43AB644F83236400000000000001440000000000000F03F000000000000F03F000000000000F03F0000000000000000000000000000000000000000000000000000000000002E40000000000040554000000000008050400000000000002E4000000000004055400000000000004C4000000000010000000000000000000000FFFFFFFF00000000010000005D4DEAF7FFFFEF3FDED00754553011BF3A6C21F0950F253F0000000000000000292689A4C22D113FFE8490EFFFFFEF3F45935EEF43462F3F00000000000000009F75D7491C1025BF7B4B4A74E9452FBFD262C9E9FFFFEF3F0000000000000000153DD156A8138B40735905F367BC92C05439F3226B934540000000000000F03F01000000200000004275696C64696E675F484B35315F42555F42425F3037345F4C4F44322D315F30010000005B0000004D544C5F443A5CCAFDBEDDCFEE5C4D6178D4B4CAFDBEDD5CB2A9B8E75C484B35315C4C4F44325C6D6170735C484B35315F42555F43435F3032302E6A706766666666666666665F66666666666666665F305F302E3030303030305F010000003A000000443A5CCAFDBEDDCFEE5C4D6178D4B4CAFDBEDD5CB2A9B8E75C484B35315C4C4F44325C6D6170735C484B35315F42555F43435F3032302E6A7067'::geomodel);
    
    -----------
    BOX(113.445159912109 22.1998634338379,113.445159912109 22.1998634338379)


ST_SRID
~~~~~~~~~~~~

获得 geomodel 对象的空间参考标识码epsg code。

**语法**

.. code:: SQL

    integer ST_SRID(geomodel geog);

    参数：
        geog - geomodel对象
    返回：
        返回 geomodel 对象的空间参考标识码epsg code。

**示例**

.. code:: SQL

    SELECT ST_SRID('0010E60DC0E3E242CB'::geomodel);
    
    ------------
    4326


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

设置 geomodel 对象的空间参考标识码epsg code。

**语法**

.. code:: SQL

    geomodel ST_SetSRID(geom geomodel, srid integer);

    参数：
        geog - geomodel对象
        srid - epsg code，空间参考标识码
    返回：
        返回已设置指定空间参考系的 geomodel 对象。

**示例**

.. code:: SQL

    SELECT ST_SetSRID('0000000DC0E3E242CB'::geomodel, 4326);

    ------------------
    0010E60DC0E3E242CB


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

&&
~~~~~~~~~

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

**语法**

.. code:: SQL

    boolean Operator &&;
    
    返回：
        相交返回 true，不相交返回 false。

**示例**

.. code:: SQL

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