CLI 典型使用示例

以下示例覆盖远程场景交互和本地数据处理两大场景，演示 dimine CLI 的常见工作流。

前置条件

• 已安装 dimine-python-sdk
• 远程命令示例：Dimine 已启动并开启 WebSocket 服务
• 本地命令示例：已设置 DIMINE_HOME 环境变量

---

场景一：获取场景信息

从打开文件到获取图层再到获取几何体的完整工作流。

1. 查看当前打开的文件和图层树

$ dimine file-tree
{
  "file_count": 1,
  "files": [
    {
      "id": "f-20240527-001",
      "name": "矿山模型.dmf",
      "layers": [
        {"id": "l-001", "name": "地表"},
        {"id": "l-002", "name": "矿体"},
        {"id": "l-003", "name": "巷道"}
      ]
    }
  ]
}

2. 列出指定文件的所有图层

$ dimine layers --file-id f-20240527-001
{
  "file_id": "f-20240527-001",
  "layer_count": 3,
  "layers": [
    {"id": "l-001", "name": "地表"},
    {"id": "l-002", "name": "矿体"},
    {"id": "l-003", "name": "巷道"}
  ]
}

3. 获取图层中所有几何体

$ dimine geometry-list --file f-20240527-001 --layer l-002 --types shell
{
  "file_id": "f-20240527-001",
  "layer_id": "l-002",
  "entity_count": 2,
  "geometries": [
    {
      "id": "0-158",
      "file": "f-20240527-001",
      "layer": "l-002",
      "feature": "矿体1",
      "type": "shell",
      "color": [255, 128, 0],
      "properties": [...]
    }
  ]
}

---

场景二：实体选择与管道操作

利用管道将 get-selected 的输出直接传递给 hide 或 delete。

1. 获取当前选中的实体

$ dimine get-selected
{
  "total_count": 3,
  "page_size": 100,
  "page_num": 1,
  "count": 3,
  "entities": [
    {"id": "0-158", "file": "f-001", "layer": "l-002", "entity_type": "shell", "feature": "矿体1"},
    {"id": "0-159", "file": "f-001", "layer": "l-002", "entity_type": "shell", "feature": "矿体1"},
    {"id": "0-160", "file": "f-001", "layer": "l-003", "entity_type": "line", "feature": "巷道中线"}
  ]
}

2. 隐藏选中的实体

$ dimine get-selected | dimine hide --ids -
{
  "success": true,
  "message": "已成功隐藏 3 个实体"
}

3. 使用简写格式批量删除

$ dimine delete --ids f-001/0-158,f-001/0-159
{
  "success": true,
  "deleted_count": 2,
  "message": "已成功删除 2 个实体"
}

---

场景三：创建几何体

从 JSON 文件读取几何体定义并创建到 Dimine 场景中。

1. 准备几何体 JSON 文件

new_points.json：

[
  {
    "type": "point",
    "file": "f-20240527-001",
    "layer": "l-001",
    "feature": "勘探点",
    "geometry": {"point": [1000.5, 2000.3, 1250.0]},
    "color": [255, 0, 0]
  },
  {
    "type": "point",
    "file": "f-20240527-001",
    "layer": "l-001",
    "feature": "勘探点",
    "geometry": {"point": [1005.0, 2010.0, 1248.5]},
    "color": [255, 0, 0]
  }
]

2. 创建几何体

$ dimine geometry-create --geometries @new_points.json
{
  "success": true,
  "created_count": 2,
  "result": "...",
  "message": "已成功创建 2 个几何体"
}

3. 直接在命令行传入 JSON

$ dimine geometry-create --geometries '[{"type":"line","file":"f-001","layer":"l-003","feature":"巷道中线","geometry":{"points":[[0,0,0],[100,50,30]]},"color":[0,255,0]}]'

4. 从 GeoJSON 批量导入

GeoJSON 是最省事的批量入口——把测绘/其他软件导出的 FeatureCollection 直接丢进来即可，SDK 会转成 Dimine 内部格式。

orebody.geojson：

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {"file": "f-001", "layer": "l-002", "feature": "矿体1", "color": [255, 128, 0]},
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[0,0,0], [10,0,0], [10,10,0], [0,10,0], [0,0,0]]]
      }
    }
  ]
}

$ dimine geometry-create --geometries @orebody.geojson
{
  "success": true,
  "created_count": 1,
  "message": "已成功创建 1 个几何体"
}

支持的 GeoJSON 几何类型：Point / MultiPoint → 点，LineString / MultiLineString → 线，Polygon / MultiPolygon → 体。Multi* 类型会展开成多个几何体。

注意：GeoJSON 的 Polygon 里没有 faces 的位置，也不需要——SDK 对线性环做扇形三角化，并自动去掉线性环首尾重复的收尾点。只有写原始 JSON 格式时才需要自己给 faces（或协议名 indexs）。

5. 单个模式（无需拼 JSON）

# 点
$ dimine geometry-create --file f-001 --layer l-001 --feature 勘探点 --type point --point 1000.5,2000.3,1250.0

# 多段折线（≥3 点；--type line 亦可，SDK 按顶点数自动判定）
$ dimine geometry-create --file f-001 --layer l-003 --feature 巷道中线 --type polyline \
    --points '[[0,0,0],[100,50,30],[200,60,40]]' --color 0,255,0

# 体：--faces 必需，缺失会在本地报错而不是发出去换回一句晦涩的服务端错误
$ dimine geometry-create --file f-001 --layer l-002 --feature 采场 --type shell \
    --points '[[0,0,0],[10,0,0],[10,10,0]]' --faces '[[0,1,2]]'

---

场景四：图层与文件可见性控制

通过 layer-visibility 和 file-visibility 命令直接控制图层或文件的显隐状态。

1. 排他显示指定图层

$ dimine layer-visibility --file-id f-20240527-001 --layer-name 矿体 --action exclusive_show
{
  "success": true,
  "layer_count": 1,
  "message": "已成功排他显示图层 矿体"
}

2. 隐藏指定图层

$ dimine layer-visibility --file-id f-20240527-001 --layer-name 巷道 --action hide
{
  "success": true,
  "layer_count": 1,
  "message": "已成功隐藏图层 巷道"
}

3. 批量操作同一文件下的多个图层

--layer-name 可重复指定，一次批量操作多个图层。

$ dimine layer-visibility --file-id f-20240527-001 --layer-name 矿体 --layer-name 巷道 --action exclusive_show
{
  "success": true,
  "layer_count": 2,
  "message": "已成功排他显示图层 矿体、巷道"
}

4. 隐藏整个文件的所有图层

$ dimine file-visibility --file-id f-20240527-001 --action hide
{
  "success": true,
  "message": "已成功隐藏文件 f-20240527-001"
}

---

场景五：相机设置与截图

调整相机视角并截取 Dimine 场景图片。

1. 设置相机视角

$ dimine camera-set --center-point '[1000.0, 2000.0, 500.0]' --normal-vector '[0.0, 0.0, 1.0]'
{
  "success": true,
  "center_point": [1000.0, 2000.0, 500.0],
  "normal_vector": [0.0, 0.0, 1.0],
  "message": "相机视角已设置"
}

2. 截图

$ dimine camera-screenshot
{
  "success": true,
  "image": "D:/Temp/screenshot.png",
}

---

场景六：巷道建模并导入 Dimine

在 Dimine 中选中巷道中心线，生成立体巷道模型并自动导入。

1. 在 Dimine 中选中中心线

手动选中一条代表巷道中心线的多段线。

2. 生成巷道模型并导入（默认行为）

$ dimine laneway-tunnel --type 0 --width 4.5 --height 3.8 --close --connectivity
{
  "success": true,
  "section_type": 0,
  "width": 4.5,
  "wall_height": 3.8,
  "center_line_points": 12,
  "total_faces": 420,
  "total_vertices": 380,
  "imported": {
    "status": "ok",
    "file": "矿山模型.dmf",
    "layer": "巷道",
    "feature": "巷道",
    "entity_count": 1
  }
}

3. 仅生成本地模型，不导入 Dimine

$ dimine laneway-tunnel --type 0 --width 4.5 --height 3.8 --close --no-import
{
  "success": true,
  "section_type": 0,
  "width": 4.5,
  "wall_height": 3.8,
  "center_line_points": 12,
  "total_faces": 420,
  "total_vertices": 380,
  "imported": false
}

4. 使用自定义中心线（不依赖 Dimine 选中）

$ dimine laneway-tunnel --type 4 --width 5.0 --center-lines '[[0,0,100],[50,0,100],[100,50,100]]' --method 1

如果不提供 --center-lines，CLI 会自动尝试从 Dimine 当前选中的线段获取；如果 Dimine 未运行且未提供 --center-lines，命令会报错。

---

场景七：数据表批处理

对 .dmd 数据表文件进行批量增删改查。

1. 查看数据表结构

$ dimine datatable-info --file "D:/Data/sample.dmd"
{
  "file": "D:/Data/sample.dmd",
  "field_count": 5,
  "record_count": 128,
  "fields": ["ID", "名称", "品位", "厚度", "深度"]
}

2. 查看某一列的值

$ dimine datatable-info --file "D:/Data/sample.dmd" --column 品位
{
  "column": "品位",
  "count": 128,
  "values": [0.52, 1.23, 0.89, ...]
}

3. 批量添加记录

$ dimine datatable-add-record --file "D:/Data/sample.dmd" --data '[{"ID": 129, "名称": "ZK-129", "品位": 2.15, "厚度": 5.2, "深度": 320.0}]'
{
  "success": true,
  "file": "D:/Data/sample.dmd",
  "added_count": 1,
  "total_records": 129,
  "message": "已添加 1 条记录并保存"
}

4. 批量修改字段值

$ dimine datatable-set --file "D:/Data/sample.dmd" --data '[{"index": 0, "field": "品位", "value": 0.55}, {"index": 1, "field": "品位", "value": 1.30}]'
{
  "success": true,
  "file": "D:/Data/sample.dmd",
  "updated_count": 2,
  "total_records": 129,
  "message": "已更新 2 个字段并保存"
}

---

场景八：场景全文检索

按正则表达式检索当前场景中已打开的文件、图层、要素和实体，适合先按关键字定位内容，再配合 dimine select / dimine get-selected 做后续选中与查询。文字标注属于实体的一部分，检索实体时一并命中。

1. 按名称检索图层

--keyword 始终按正则表达式处理，因此可以一次匹配多种形态。

$ dimine scene-search --keyword '^\d+水平$'
{
  "success": true,
  "keyword": "^\\d+水平$",
  "total_count": 21,
  "counts": {
    "layer": 21
  },
  "results": [
    {
      "related": false,
      "type": "layer",
      "file": "E:\\Data\\地下矿山整体系统.dmf",
      "layer": "435水平"
    },
    {
      "related": false,
      "type": "layer",
      "file": "E:\\Data\\地下矿山整体系统.dmf",
      "layer": "450水平"
    }
  ]
}

counts 是各类型的命中数汇总，results 按 文件 → 图层 → 要素 → 实体 的顺序排列。

2. 限定检索范围

--scope 支持逗号分隔，可选 file、layer、feature、entity（默认检索全部）。

$ dimine scene-search --keyword '0' --scope entity
{
  "success": true,
  "keyword": "0",
  "total_count": 3,
  "counts": {
    "entity": 3
  },
  "results": [
    {
      "related": false,
      "type": "entity",
      "file": "E:\\Data\\地下矿山整体系统.dmf",
      "layer": "530水平",
      "feature": "0",
      "id": "0-10"
    }
  ]
}

命中实体返回的 id 是实体句柄，可直接用于选中。

3. 检索结果直接用于选中

$ dimine select "E:\Data\地下矿山整体系统.dmf" 0-10 --mode replace

检索 → 选中的完整链路也可以直接用 SDK 串联：

import asyncio
from dimine_python_sdk.conn import open_client

async def main():
    async with open_client() as client:
        result = await client.search_scene("0", scope=["entity"])
        for hit in result.results:
            print(hit.type, hit.id, hit.layer)
        # 命中结果直接用于选中，id 为实体句柄
        hit = result.results[0]
        await client.select_geometry([{"id": hit.id, "file": hit.file}], mode="replace")

asyncio.run(main())

4. 其它可选参数

# 只检索指定文件
$ dimine scene-search --keyword '.*cu.*' --files "地下矿山整体系统.dmf"

# 区分大小写（默认不区分）
$ dimine scene-search --keyword 'Cu' --case-sensitive

# 文本格式输出，便于肉眼查看
$ dimine scene-search --keyword '水平' --scope layer --format text

注意：scope 中不含 text，文字标注随 entity 一起检索。

---

提示与技巧

1. 管道链式操作：dimine get-selected | dimine hide --ids - 是最常用的快捷操作。
2. 文件路径：支持相对路径、绝对路径（Windows D:\\ 或 D:/ 均可），以及用户目录 ~/。
3. JSON 参数大体积时：优先使用 @path 文件引用，避免命令行长度限制。
4. Windows CMD 单引号：JSON 参数外层用单引号包裹，CLI 内部会自动去除并解析。
5. 错误排查：远程命令失败时先检查 dimine file-tree 是否能正常返回，确认 Dimine 已启动且 WebSocket 服务正常。