modules.gisOperators 模块帮助

本章节包含 modules.gisOperators 包中常用「GIS 数据操作」模块的说明和示例，例如：

点/线/面等空间数据的基础几何处理
坐标与空间属性相关的小工具模块
多段线（剖面线）顶点表的创建与输出

ConvexHullCenter

模块简介与适用场景

ConvexHullCenter 用于计算一组点样本的 **凸包中心**（取凸包顶点的均值）。
当点数不足时会自动降级：
- 仅 1 个点：中心为该点
- 2 个点：中心为两点均值
- >= 3 个点：先求凸包，再对凸包顶点求均值
典型适用场景：
- 以一组测点/钻孔/构筑物坐标快速估计 “区域中心”，用于图件定位、视图缩放中心或后续空间分析的参考点；
- 从点集派生一个代表性位置（例如作为剖面/统计区域的中心点）。

端口说明

输入端口 - InputTable：点样本表（TableData）
输出端口 - OutputCenter：中心坐标（SingleResult，包含 2 个 UnitResult：X/Y 或经度/纬度）

快速上手示例：按 X/Y 坐标计算凸包中心

from gdisdk.dataclass.tables import TableData
from gdisdk.modules.gisOperators import ConvexHullCenter

# 列名建议使用默认约定：x_coordinate / y_coordinate
table = TableData(
    {
        "x_coordinate": [0.0, 1.0, 1.0, 0.0],
        "y_coordinate": [0.0, 0.0, 1.0, 1.0],
    },
    name="points",
    title="点样本",
)

mod = ConvexHullCenter(mname="HullCenter")
mod.by_xy = True
mod.InputTable = table
mod.execute()

print(mod.OutputCenter.data)

快速上手示例：按经纬度计算凸包中心

from gdisdk.dataclass.tables import TableData
from gdisdk.modules.gisOperators import ConvexHullCenter

table = TableData(
    {
        "longitude": [118.78, 118.80, 118.79],
        "latitude": [32.04, 32.05, 32.06],
    }
)

mod = ConvexHullCenter(mname="HullCenterLonLat")
mod.by_xy = False
mod.InputTable = table
mod.execute()

参数说明

ConvexHullCenter 参数一览
参数名	类型	默认值	说明
`by_xy`	`bool`	`True`	坐标来源选择：为 `True` 时从 `x_coordinate / y_coordinate` 计算；为 `False` 时从 `longitude / latitude` 计算。
`x_column`	`str \| None`	`None`	自定义 X 坐标列名/列标题（仅 `by_xy=True` 时生效）；为 `None` 时使用默认 `x_coordinate`。
`y_column`	`str \| None`	`None`	自定义 Y 坐标列名/列标题（仅 `by_xy=True` 时生效）；为 `None` 时使用默认 `y_coordinate`。
`longitude_column`	`str \| None`	`None`	自定义经度列名/列标题（仅 `by_xy=False` 时生效）；为 `None` 时使用默认 `longitude`。
`latitude_column`	`str \| None`	`None`	自定义纬度列名/列标题（仅 `by_xy=False` 时生效）；为 `None` 时使用默认 `latitude`。

Note

若 InputTable 为空（None 或空表），则 OutputCenter 输出 None。
输入表建议包含默认列名（x_coordinate/y_coordinate 或 longitude/latitude）。若你的表使用了字段元数据（title），也可以通过 “列标题” 等价访问这些字段（参见端口类型 (Port Type) 中的 TableData 说明）。
若你的点表列名并非默认约定，可用 x_column/y_column 或 longitude_column/latitude_column 指定实际列名（或列标题），避免你在上游模块中手动改列名。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.readers import CsvReader
from gdisdk.modules.gisOperators import ConvexHullCenter

pipe = PipeLine(app_name="HullCenterDemo", app_title="计算凸包中心示例")

read_csv = CsvReader("ReadPoints")
read_csv.file = "points.csv"  # 需包含 x_coordinate/y_coordinate 或 longitude/latitude
read_csv.encoding = "auto"

center = ConvexHullCenter("Center")
center.by_xy = True

links = read_csv.OutputTable >> center.InputTable
pipe.add_links(links)
pipe.run()

out = center.OutputCenter

更多信息

CreatePolyLines

模块简介与适用场景

CreatePolyLines 用于创建多段线顶点表（TableData），支持按 钻孔编号 或 坐标点 两种方式定义剖面线（define_poly_lines_by，详见「参数说明」）。
典型适用场景：
- 在生成地质剖面、地形切片等流程前，统一准备剖面线顶点数据；
- 将用户在 GDIM 界面配置的剖面线（钻孔序列或坐标点序列）转换为下游模块可消费的 InputPolyLines 表结构。
常见下游模块：GdimTerrainDataReader、SliceTerrain、ExportGeoSectionsByBores 等（均通过 InputPolyLines 接收本模块输出）。

端口说明

输入端口 - InputMultiProfile1D：钻孔剖面数据（MultiProfile1D）；当 define_poly_lines_by="bores" 时 必须连接，用于按钻孔编号查找 x_coord、y_coord、top。
输出端口 - OutputPolyLines：多段线顶点表（TableData）。列包括 name、x_coordinate、y_coordinate；基于钻孔时额外包含 z_coordinate``（孔口标高）与 ``bore_number；基于坐标点时若输入含 z_coordinate 则输出保留该列。

快速上手示例：基于钻孔编号创建剖面线

from gdisdk.modules.gisOperators import CreatePolyLines

# poly_lines 可由 GDIM 前端以 list[dict] 形式传入；此处演示等价的列表写法
poly_lines = [
    {"name": "剖面1", "bore_number": "ZK1"},
    {"name": "剖面1", "bore_number": "ZK2"},
    {"name": "剖面1", "bore_number": "ZK3"},
]

mod = CreatePolyLines(mname="CreateSectionLines")
mod.define_poly_lines_by = "bores"
mod.poly_lines = poly_lines
mod.InputMultiProfile1D = your_multi_profile_1d  # 来自 ConvertToMultiProfile1D 等上游模块

mod.execute()
out = mod.OutputPolyLines.data

快速上手示例：基于坐标点创建剖面线

import pandas as pd

from gdisdk.modules.gisOperators import CreatePolyLines

poly_lines = pd.DataFrame(
    {
        "name": ["剖面A", "剖面A", "剖面B", "剖面B"],
        "x_coordinate": [100.0, 150.0, 200.0, 260.0],
        "y_coordinate": [50.0, 80.0, 60.0, 90.0],
    }
)

mod = CreatePolyLines(mname="CreateLinesByPoints")
mod.define_poly_lines_by = "points"
mod.poly_lines = poly_lines

mod.execute()
out = mod.OutputPolyLines.data

参数说明

CreatePolyLines 参数一览
参数名	类型	默认值	说明
`bores`	`MultiProfile1D \| None`	`None`	构造时可直接赋给 `InputMultiProfile1D`；`define_poly_lines_by="bores"` 时须在执行前提供有效钻孔数据。
`define_poly_lines_by`	`Literal["bores", "points"]`	`"bores"`	多段线定义方式：`"bores"` 按钻孔编号；`"points"` 按坐标点。对应界面选项「基于钻孔」/「基于坐标点」。
`poly_lines`	`pd.DataFrame \| list[dict] \| None`	`None`	多段线顶点，一行一个点。前端通常以 `list[dict]` 传入；模块内部会规范化为 `DataFrame`。

Note

若 poly_lines 为 None 或空，则 OutputPolyLines 输出 None。
同一条多段线（相同 name）至少须包含 2 个顶点，否则抛出 ValueError。
define_poly_lines_by="bores" 时：poly_lines 须含非空 name、bore_number；InputMultiProfile1D.profiles_table 不能为空；钻孔编号须在 profiles_table["pnum"] 中存在。
define_poly_lines_by="points" 时：poly_lines 须含非空 name、x_coordinate、y_coordinate；若任意行提供了 z_coordinate，则所有行的 z_coordinate 均不能为空。
输出表结构遵循 PolyLinesTable 约定，便于 SliceTerrain、ExportGeoSectionsByBores 等模块直接解析。

在 pipeline 中的使用方式

from gdisdk.pipeline.pipeline import PipeLine
from gdisdk.modules.converters import ConvertToMultiProfile1D
from gdisdk.modules.gisOperators import CreatePolyLines
from gdisdk.modules.geoDataProcess import ExportGeoSectionsByBores, SliceTerrain
from gdisdk.modules.readers import GdimTableReader, GdimTerrainDataReader

pipe = PipeLine(app_name="SectionLinesDemo", app_title="创建剖面线示例")

reader = GdimTableReader("ReadTables")
convert_bores = ConvertToMultiProfile1D("ConvertBores")
create_lines = CreatePolyLines("CreatePolyLines")
terrain_reader = GdimTerrainDataReader("TerrainReader")
terrain_reader.query_mode = "nearest_line"
slice_terrain = SliceTerrain("SliceTerrain")
export_sections = ExportGeoSectionsByBores("ExportSections")

links = (
    reader.OutputTables >> convert_bores.InputTables
    | convert_bores.OutputMultiProfile1D >> create_lines.InputMultiProfile1D
    | create_lines.OutputPolyLines >> terrain_reader.InputPolyLines
    | create_lines.OutputPolyLines >> slice_terrain.InputPolyLines
    | create_lines.OutputPolyLines >> export_sections.InputPolyLines
)
pipe.add_links(links)

# 将剖面线配置暴露为 pipeline 属性，供 GDIM 界面编辑
pipe.add_attribute(
    attr_name="define_poly_lines_by",
    module_name="CreatePolyLines",
    param_name="define_poly_lines_by",
    attr_title="剖面线定义方式",
)
pipe.add_attribute(
    attr_name="poly_lines",
    module_name="CreatePolyLines",
    param_name="poly_lines",
    attr_title="剖面线",
)

pipe.run()

更多信息

API 参考 - modules 包
完整类定义与参数说明（gisOperators）
多段线表结构约定
地质数据处理中的 SliceTerrain``（``InputPolyLines 下游）