巷道建模

井巷工程模块提供断面轮廓生成与三维巷道建模功能，基于本地 C++ 扩展 DmPyBindInterface 实现高性能计算，无需连接数采软件即可使用。

1. 断面轮廓生成

根据断面类型和尺寸参数，生成二维断面轮廓点列表。

import numpy as np
from dimine_python_sdk.lib.exploitation import Laneway, SectionParam

# 构造断面参数
section = SectionParam(
    type=0,          # 0=矩形拱
    width=2.0,       # 下宽度
    width_up=2.0,    # 上宽度
    wall_height=1.0, # 墙高
    wide_arch_ratio=3,
    offset_x=0.0,
    offset_y=0.0,
    point_count=20,  # 轮廓采集点数
)

# 获取断面轮廓（返回 numpy.ndarray）
contour = Laneway.get_section(section)
print(contour.shape)  # (N, 2) 或 (N, 3)

断面类型说明

type	断面类型
0	矩形拱
1	梯形拱
2	圆形拱
3	圆弧拱
4	三心拱
5	六边形拱
6	自定义断面

SectionParam 参数

参数名	类型	必填	默认值	约束	说明
type	int	是	—	0~6	断面类型
width	float	是	—	> 0	下宽度
width_up	float	否	0.0	—	上宽度
wall_height	float	否	0.0	—	墙高
wide_arch_ratio	int	否	2	>= 1	宽度/拱高比
offset_x	float	否	0.0	—	X 轴偏移
offset_y	float	否	0.0	—	Y 轴偏移
point_count	int	否	20	> 0	轮廓采集点数

注意：底层 JSON 接口使用旧拼写 wide_arch_raio。模型内部通过 alias 自动映射，用户代码中推荐写 wide_arch_ratio。

2. 巷道三维建模

根据断面参数和中心线集合，生成三维巷道模型，返回 List[TINGeometry] 三角网列表。每个 TINGeometry 包含 points（顶点坐标，shape=(N,3)）和 faces（三角面片索引，shape=(M,3)）。

from dimine_python_sdk.lib.exploitation import Laneway, LanewayParam, SectionParam
from dimine_python_sdk.models import TINGeometry

section = SectionParam(type=0, width=2.0, wall_height=1.0)

param = LanewayParam(
    section=section,
    polylines_set=[
        [[0.0, 0.0, 0.0], [10.0, 0.0, 0.0], [20.0, 5.0, 0.0]],
        [[5.0, 10.0, 0.0], [15.0, 10.0, 0.0]],
    ],
    close=True,        # 巷道尽头封口
    connectivity=False,# 交叉口不自动联通
    method=0,          # 0=整体连接
    bottom_contour=False,
)

models = Laneway.get_lane_way_model(param)
print(type(models))        # <class 'list'>
print(type(models[0]))     # <class 'TINGeometry'>
print(models[0].points.shape)  # (N, 3)
print(models[0].faces.shape)   # (M, 3)

支持 Line 对象作为中心线

polylines_set 除了接受三维顶点列表，还支持直接传入 dimine_python_sdk.models.types.Line 对象，模型会在验证阶段自动提取 Line.geometry 转换为列表。

import numpy as np
from dimine_python_sdk.models.types import Line
from dimine_python_sdk.lib.exploitation import LanewayParam, SectionParam

line1 = Line(geometry=np.array([[0.0, 0.0, 0.0], [10.0, 0.0, 0.0]], dtype=np.float32))
line2 = Line(geometry=np.array([[5.0, 10.0, 0.0], [15.0, 10.0, 0.0]], dtype=np.float32))

section = SectionParam(type=0, width=2.0)
param = LanewayParam(
    section=section,
    polylines_set=[line1, line2],  # 直接传入 Line 对象
)

Line 对象与纯列表可以混合使用： python polylines_set=[line1, [[0.0, 0.0, 0.0], [5.0, 5.0, 5.0]]]

LanewayParam 参数

参数名	类型	必填	默认值	约束	说明
section	SectionParam	是	—	—	断面参数
polylines_set	list[list[list[float]] | Line	否	[]	—	中心线集合
close	bool	否	True	—	巷道尽头是否封口
connectivity	bool	否	False	—	交叉口是否自动联通
method	int	否	0	0~2	0=整体连接 1=拐点分离 2=顶墙分离
bottom_contour	bool	否	False	—	是否为底部轮廓线（联通时用）

3. 异常处理

井巷工程模块定义了层次化异常，建议调用时捕获具体异常：

from dimine_python_sdk.lib.exploitation import (
    Laneway,
    LanewayError,
    SectionGenerateError,
    LanewayModelingError,
    SectionParam,
)

try:
    contour = Laneway.get_section(SectionParam(type=0, width=2.0))
except SectionGenerateError as e:
    print(f"断面生成失败: {e}")
except LanewayError as e:
    print(f"井巷工程错误: {e}")

异常继承关系：

RuntimeError
 └── LanewayError
      ├── SectionGenerateError  (断面生成失败)
      └── LanewayModelingError  (巷道建模失败)

4. 向后兼容

旧代码使用裸 dict 传递参数仍然可用，但会触发 DeprecationWarning，建议迁移到 Pydantic 模型：

import warnings

# 旧写法（仍可用，但会报警告）
with warnings.catch_warnings(record=True) as w:
    contour = Laneway.get_section({
        "type": 0,
        "width": 2.0,
        "wide_arch_raio": 3,  # 旧拼写也能兼容
    })

# 新写法（推荐）
contour = Laneway.get_section(SectionParam(type=0, width=2.0, wide_arch_ratio=3))

5. 完整示例

import numpy as np
from dimine_python_sdk.lib.exploitation import (
    Laneway,
    LanewayParam,
    SectionParam,
)
from dimine_python_sdk.models.types import Line


def main():
    # 1. 定义断面
    section = SectionParam(
        type=0,
        width=2.0,
        width_up=2.0,
        wall_height=1.0,
        wide_arch_ratio=3,
        point_count=20,
    )

    # 2. 获取断面轮廓
    contour = Laneway.get_section(section)
    print(f"断面轮廓点数: {len(contour)}")

    # 3. 定义中心线（混合使用 Line 对象和列表）
    center_line = Line(geometry=np.array([
        [0.0, 0.0, 0.0],
        [10.0, 0.0, 0.0],
        [20.0, 5.0, 0.0],
    ], dtype=np.float32))

    # 4. 巷道建模
    param = LanewayParam(
        section=section,
        polylines_set=[
            center_line,
            [[5.0, 10.0, 0.0], [15.0, 10.0, 0.0]],
        ],
        close=True,
        connectivity=False,
        method=0,
    )

    models = Laneway.get_lane_way_model(param)
    print(f"巷道模型数量: {len(models)}")
    print(f"三角网顶点数: {models[0].points.shape[0]}")
    print(f"三角网面片数: {models[0].faces.shape[0]}")


if __name__ == "__main__":
    main()