CLI 命令行工具

dimine 是 dimine-python-sdk 提供的命令行入口，无需编写 Python 脚本即可完成绝大部分远程场景交互和本地数据处理任务。

1. 安装与入口

安装 SDK 后，dimine 命令自动注册到系统 PATH：

pip install dimine-python-sdk

直接使用：

dimine --help

或使用 python -m 方式（适合虚拟环境未激活时）：

python -m dimine_python_sdk.cli --help

2. 全局选项

所有子命令均继承以下全局选项：

选项	说明	默认值
`--format {json,text}`	输出格式	`json`
`-h, --help`	显示帮助信息	-

示例：

dimine file-tree --format text
dimine entity-types --format text

3. 运行模式说明

CLI 子命令分为两大类，前置条件不同：

远程命令（需 Dimine 运行）

通过 WebSocket 与已启动的 Dimine 桌面应用通信。需满足：

Windows 操作系统
已设置 DIMINE_HOME 环境变量
Dimine 软件已启动并开启 WebSocket 服务（默认 ws://localhost:8000）

远程命令列表：entity-types, get-selected, select, delete, show, hide, exclusive-show, file-tree, file-save, file-open, file-close, file-create, file-visibility, layers, layer-create, layer-delete, layer-visibility, feature-list, feature-create, feature-update, feature-delete, geometry-list, geometry-create, geometry-update, geometry-upsert, camera-set, camera-screenshot, text-add

本地命令（仅需 `DIMINE_HOME`）

直接调用本地 C++ 扩展 DmPyBindInterface.pyd 进行数据处理，无需 Dimine GUI 运行。需满足：

Windows 操作系统
已设置 DIMINE_HOME 环境变量指向 Dimine 安装目录

本地命令列表：datatable-info, datatable-save, datatable-add-record, datatable-set, convert-file, laneway-section

混合命令

laneway-tunnel 默认在本地生成模型后自动导入到 Dimine，因此同时需要本地 SDK 和远程 SDK 可用；仅当指定 --no-import 时才是纯本地命令。

4. 命令分类详解

4.1 实体操作

`entity-types` — 列出实体类型枚举及中文名

dimine entity-types

`get-selected` — 获取当前选中实体

dimine get-selected [--page-size 100] [--page 1]

参数	说明	默认值
`--page-size`	每页返回数量	`100`
`--page`	页码	`1`

`select` — 选中/取消选中实体

dimine select <file_id> <entity_ids> [--mode {replace,add,remove}]

参数	说明
`file_id`	文件 ID
`entity_ids`	逗号分隔的实体 ID 列表，如 `entity_id1,entity_id2`
`--mode`	选择模式：`replace`（替换）、`add`（追加）、`remove`（移除）

`delete` — 删除实体

dimine delete --ids <entity_ids>

参数	说明
`--ids`	JSON 数组格式的实体列表，或 `file_id/entity_id` 逗号分隔格式，或 `-` 从 stdin 读取

`show` / `hide` / `exclusive-show` — 显示 / 隐藏 / 排他显示实体

dimine show --ids <entity_ids>
dimine hide --ids <entity_ids>
dimine exclusive-show --ids <entity_ids>

--ids 参数支持格式与 delete 一致。exclusive-show 会将指定实体以外的所有实体隐藏。

4.2 文件操作

`file-tree` — 获取打开文件及图层树

dimine file-tree

`file-save` — 导出文件到本地

dimine file-save --output <path> [--file-id <id>]

参数	说明
`--output`	保存/导出目标路径，需包含文件扩展名
`--file-id`	文件 ID，多个文件打开时必填

`file-open` — 打开文件到 Dimine 场景

dimine file-open --path <path>

`file-close` — 关闭 Dimine 中的文件

dimine file-close --file-id <id>

`file-create` — 在 Dimine 中创建新的空文件

dimine file-create --path <path>

`file-visibility` — 设置文件显示/隐藏状态

dimine file-visibility --file-id <id> --action {show,hide,exclusive_show}

参数	说明	默认值
`--file-id`	文件 ID	-
`--action`	操作类型：`show`（显示）、`hide`（隐藏）、`exclusive_show`（排他显示）	`show`

4.3 图层操作

`layers` — 列出图层

dimine layers [--file-id <id>]

不提供 --file-id 时，使用当前打开的第一个文件。

`layer-create` — 创建图层

dimine layer-create --name <name> [--file-id <id>]

`layer-delete` — 删除图层

dimine layer-delete --name <name> [--file-id <id>]

`layer-visibility` — 设置图层显示/隐藏状态

dimine layer-visibility --file-id <id> --layer-name <name> [--action {show,hide,exclusive_show}]

参数	说明	默认值
`--file-id`	文件 ID	-
`--layer-name`	图层名称	-
`--action`	操作类型：`show`（显示）、`hide`（隐藏）、`exclusive_show`（排他显示）	`show`

4.4 要素操作

`feature-list` — 列出要素定义

dimine feature-list [--file-id <id>]

`feature-create` — 创建要素定义

dimine feature-create --file-id <id> --name <name> --defines <json>

参数	说明
`--defines`	JSON 属性定义数组，如 `'[{"name":"field","type":"string"}]'`

`feature-update` — 更新要素定义

dimine feature-update --file-id <id> --name <name> --defines <json>

`feature-delete` — 删除要素定义

dimine feature-delete --file-id <id> --name <name>

4.5 几何体操作

`geometry-list` — 获取图层中的几何体

dimine geometry-list --file-id <id> [--layer-id <id>] [--entity-types <types>] [--features <names>] [--with-geometry]

参数	说明
`--file-id`	文件 ID（必填）
`--layer-id`	图层 ID，不提供则获取文件下所有图层的模型基础信息（不含几何数据）
`--entity-types`	逗号分隔的实体类型过滤，如 `point,line,shell`
`--features`	逗号分隔的要素名称过滤

`geometry-create` — 创建几何体

dimine geometry-create --geometries <json>

参数	说明
`--geometries`	JSON 几何体数组，支持 JSON 字符串、文件路径（`@path` 或 `.json`）或 stdin（`-`）

JSON 格式示例：

[
  {
    "type": "point",
    "file": "file-id",
    "layer": "layer-id",
    "feature": "要素名",
    "geometry": {"point": [10, 20, 30]},
    "color": [255, 0, 0]
  },
  {
    "type": "line",
    "file": "file-id",
    "layer": "layer-id",
    "feature": "要素名",
    "geometry": {"points": [[0,0,0], [10,10,10]]},
    "color": [0, 255, 0]
  }
]

`geometry-update` — 更新几何体

dimine geometry-update --geometries <json>

JSON 需包含 id 字段以定位要更新的实体。

`geometry-upsert` — 创建或更新几何体

dimine geometry-upsert --geometries <json>

根据 related 字段判断是创建还是更新。

4.6 相机与截图

`camera-set` — 设置相机视角

dimine camera-set --center-point <json> --normal-vector <json>

参数	说明
`--center-point`	相机中心点坐标 JSON 数组，如 `'[1.0, 2.0, 3.0]'`
`--normal-vector`	相机法向量 JSON 数组，如 `'[0.0, 0.0, 1.0]'`

`camera-screenshot` — 截图

dimine camera-screenshot

返回结果包含 image 字段，为生成的截图文件路径。

4.7 文字标注

`text-add` — 添加文字标注

支持单条模式（命令行参数）和批量模式（JSON 数组）。

单条模式：

dimine text-add --text "文字内容" --position [x,y,z] [--file <id>] [--layer <id>] [--color r,g,b] [--size <n>] [--feature <name>] [--normal [x,y,z]] [--rotate <deg>]

参数	说明	默认值
`--text`	文字内容（单条模式必填）	-
`--position`	文字位置，JSON 数组如 `'[x, y, z]'` 或 `x,y,z` 逗号分隔	-
`--file`	文件 ID（不提供则使用当前打开的第一个文件）	-
`--layer`	图层名称（不提供则使用第一个图层）	-
`--color`	颜色 `r,g,b`	`255,255,255`
`--size`	文字大小	`20`
`--feature`	所属要素名	`0`
`--normal`	法向量 JSON 数组 `[x, y, z]`	`[0, 0, 1]`
`--rotate`	旋转角度	`0`

批量模式：

dimine text-add --geometries <json>

参数	说明
`--geometries`	完整 JSON 数组，支持 JSON 字符串、`@文件路径` 或 `-` 从 stdin 读取

JSON 格式示例：

[
  {
    "file": "file-id",
    "layer": "layer-id",
    "text": "标注文字",
    "position": [10, 20, 30],
    "color": [255, 255, 0],
    "size": 24,
    "feature": "要素名",
    "normal": [0, 0, 1],
    "rotate": 0
  }
]

4.8 数据表（本地）

`datatable-info` — 加载并检查 `.dmd` 数据表文件

dimine datatable-info --file <path> [--column <name>] [--to-json]

参数	说明
`--file`	`.dmd` 数据表文件路径
`--column`	提取指定列的值
`--to-json`	同时输出全部记录数据

`datatable-save` — 保存 `.dmd` 数据表文件

dimine datatable-save --file <path>

`datatable-add-record` — 向 `.dmd` 数据表添加记录并保存

dimine datatable-add-record --file <path> --data <json>

参数	说明
`--data`	JSON 数组，每条为 `{"字段名": "值", ...}`

`datatable-set` — 设置 `.dmd` 数据表字段值并保存

dimine datatable-set --file <path> --data <json>

参数	说明
`--data`	JSON 数组 `[{"index": 0, "field": "字段名", "value": 值}, ...]`

4.9 文件转换（本地）

`convert-file` — 转换采矿文件格式

dimine convert-file --source <path> --target <path> [--overwrite <bool>]

参数	说明	默认值
`--source`	源文件路径	-
`--target`	目标文件路径（扩展名决定格式）	-
`--overwrite`	是否覆盖已存在的目标文件	`true`

支持格式：dmf ↔ dwg, dmf ↔ dtm（Surpac）, dmf ↔ STR（MicroMine）, dmf ↔ DAT（DataMine）, dmf ↔ mgis（MapGIS）

4.10 巷道建模（本地 + 可选导入）

`laneway-section` — 计算巷道断面轮廓点

dimine laneway-section --type <int> --width <float> [--height <float>] [--width-up <float>] [--wide-arch-ratio <int>] [--point-count <int>]

参数	说明	默认值
`--type`	断面类型：0=矩形拱, 1=梯形拱, 2=圆形拱, 3=圆弧拱, 4=三心拱, 5=六边形拱, 6=自定义	-
`--width`	巷道宽度（米）	-
`--height`	墙高（米），不提供则默认 `width * 0.8`	-
`--width-up`	上宽度（米）	`0.0`
`--wide-arch-ratio`	宽度/拱高比	`2`
`--point-count`	轮廓采集点数	`20`

`laneway-tunnel` — 生成巷道三维模型并导入 Dimine

dimine laneway-tunnel --type <int> --width <float> [--height <float>] [--center-lines <json>] [--width-up <float>] [--wide-arch-ratio <int>] [--point-count <int>] [--close] [--connectivity] [--method {0,1,2}] [--no-import]

参数	说明	默认值
`--type`	断面类型编号	-
`--width`	巷道宽度（米）	-
`--height`	墙高（米）	`width * 0.8`
`--center-lines`	中心线 JSON 数组，如 `'[[x1,y1,z1],[x2,y2,z2],...]'`；不指定则自动获取当前选中的线段	从选中获取
`--width-up`	上宽度（米）	`0.0`
`--wide-arch-ratio`	宽度/拱高比	`2`
`--point-count`	轮廓采集点数	`20`
`--close`	巷道尽头是否封口	`false`
`--connectivity`	交叉口是否自动联通	`false`
`--method`	建模方法：0=整体连接, 1=拐点分离, 2=顶墙分离	`0`
`--no-import`	仅生成本地模型，不导入到 Dimine	`false`

5. JSON 参数输入技巧

CLI 中大量命令需要 JSON 参数。由于 Windows CMD 对双引号的特殊处理，推荐以下输入方式：

5.1 外层单引号包裹（推荐）

在 Windows CMD 中，用单引号包裹整个 JSON，保护内部双引号：

dimine delete --ids '[{"id":"0-158","file":"file-1"}]'

CLI 内部会自动去掉外层单引号并解析 JSON。

5.2 从文件读取（`@path` 或 `.json`）

将 JSON 保存到文件，通过 @ 前缀或 .json 扩展名引用：

dimine geometry-create --geometries @geometries.json
dimine geometry-create --geometries ./data/geos.json

5.3 从 stdin 读取（`-`）

通过管道从 stdin 传入 JSON：

cat entities.json | dimine delete --ids -
dimine get-selected | dimine hide --ids -

注意：get-selected 的完整 JSON 输出会被自动提取 entities 字段。

5.4 常见错误修复

CLI 内部 parse_json_arg 会自动修复以下常见格式错误：

外层单引号包裹
\" 转义（LLM 在 Windows 上生成的常见错误）
单引号代替双引号（如 [{'id':'0-158'}]）

如果仍解析失败，请确保使用标准双引号 JSON。

6. 输出格式对比

`json` 格式（默认）

$ dimine file-tree --format json
{
  "file_count": 1,
  "files": [
    {
      "id": "file-1",
      "name": "test.dmf",
      "layers": [
        {"id": "layer-1", "name": "图层1"}
      ]
    }
  ]
}

结构化、机器可读
支持管道传递到下游命令（dimine get-selected | dimine hide --ids -）
错误输出到 stderr，格式为 {"success": false, "error": "..."}

`text` 格式

$ dimine file-tree --format text
file_count: 1
files:
  -
    id: file-1
    name: test.dmf
    layers:
      -
        id: layer-1
        name: 图层1

人类可读，适合直接查看
字典递归打印为缩进文本
错误输出到 stderr，格式为 Error: ...

7. 实体 ID 格式说明

--ids 参数支持三种实体引用格式：

JSON 数组：'[{"id":"0-158","file":"file-1"}]'
简写格式：file-1/0-158,file-1/0-159（逗号分隔的 file_id/entity_id）
管道输入：dimine get-selected | dimine hide --ids -

简写格式在快速操作单个文件下的多个实体时最为方便。

CLI 命令行工具

1. 安装与入口

2. 全局选项

3. 运行模式说明

远程命令（需 Dimine 运行）

本地命令（仅需 DIMINE_HOME）

混合命令

4. 命令分类详解

4.1 实体操作

entity-types — 列出实体类型枚举及中文名

get-selected — 获取当前选中实体

select — 选中/取消选中实体

delete — 删除实体

show / hide / exclusive-show — 显示 / 隐藏 / 排他显示实体

4.2 文件操作

file-tree — 获取打开文件及图层树

file-save — 导出文件到本地

file-open — 打开文件到 Dimine 场景

file-close — 关闭 Dimine 中的文件

file-create — 在 Dimine 中创建新的空文件

file-visibility — 设置文件显示/隐藏状态

4.3 图层操作

layers — 列出图层

layer-create — 创建图层

layer-delete — 删除图层

layer-visibility — 设置图层显示/隐藏状态

4.4 要素操作

feature-list — 列出要素定义

feature-create — 创建要素定义

feature-update — 更新要素定义

feature-delete — 删除要素定义