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）

若确认 Dimine 未启动（调用远程命令时连不上），可用 dimine start 从 DIMINE_HOME 后台拉起（见 4.11）。

远程命令列表：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

应用启动命令

start 用于后台拉起 Dimine 主程序（在 DIMINE_HOME 下自动定位），仅需 Windows + DIMINE_HOME，不调用本地扩展、也无需 Dimine 已运行。

仅在确认 Dimine 确实没有运行时才可使用——该命令会先探测本机 Dimine 进程与远端 WebSocket 服务，任一命中即报错退出，不会重复启动实例。

混合命令

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> [--layer-name <name> ...] [--action {show,hide,exclusive_show}]

参数	说明	默认值
`--file-id`	文件 ID	-
`--layer-name`	图层名称，可重复指定以批量操作	-
`--action`	操作类型：`show`（显示）、`hide`（隐藏）、`exclusive_show`（排他显示，仅显示指定图层并隐藏其他所有图层）	`show`

# 批量隐藏同一文件下的多个图层
dimine layer-visibility --file-id f-20240527-001 --layer-name 矿体 --layer-name 巷道 --action hide

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-create / geometry-update / geometry-upsert）都支持两种模式：

批量模式：--geometries，接 JSON 数组、GeoJSON FeatureCollection、文件路径（@path / .json）或 stdin（-）
单个模式：扁平参数 --file --layer --feature --type --point / --points / --faces --color

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

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

参数	说明
`--file`	文件 ID 或文件名（必填）
`--layer`	图层 ID，不提供则获取文件下所有图层的模型基础信息（不含几何数据）
`--types`	逗号分隔的实体类型过滤，如 `point,line,polyline,shell`
`--features`	逗号分隔的要素名称过滤
`--with-geometry`	给出坐标数据所在的 dmf 文件路径（`geometry_file`）；不提供时只返回基础信息
`--inline-geometry`	与 `--with-geometry` 同用时把坐标读回来内联进输出；不提供时只输出 `geometry_file` 路径

坐标数据不再走 websocket：大模型坐标一次传输会撑爆通信、导致请求超时。因此 SDK 固定向 Dimine 下发 with_geometry=false，由 Dimine 把坐标落盘成一个临时 dmf 文件，响应只给出 geometry_file 路径。

默认（--with-geometry）CLI 不读那个 dmf，只输出路径与实体元信息，需要时自行按实体 id 去文件里取几何：

{
  "file_id": "新文件_0.dmf",
  "layer_id": "球体测试",
  "entity_count": 1,
  "geometry_file": "C:\\Users\\me\\AppData\\Local\\Temp\\TempDmfFile20260928173427.dmf",
  "geometries": [{"id": "0-3552", "type": "polyline", "...": "..."}]
}

需要旧的内联输出（stdout 里直接带坐标）时加 --inline-geometry，CLI 会把落盘文件读回来再输出。注意该文件里放的是整个图层的实体，可能比本次命中的更多，取坐标要按 id 匹配、不能按顺序对齐。

!!! warning "获取坐标必须指定 --layer" 坐标文件按图层产出，不给 --layer 时拿不到 geometry_file；此时结果里会带一个 notice 字段提示，而不是静默忽略 --with-geometry。

`geometry-create` — 创建几何体

# 批量模式
dimine geometry-create --geometries <json|@file.json|->

# 单个模式
dimine geometry-create --file <id> --layer <id> --feature <name> --type <type> \
                       [--point x,y,z | --points '[[x,y,z],...]' [--faces '[[0,1,2],...]']] \
                       [--color r,g,b]

参数	说明
`--geometries`	JSON 几何体数组或 GeoJSON FeatureCollection，支持 JSON 字符串、文件路径（`@path` 或 `.json`）或 stdin（`-`）
`--file` / `--layer` / `--feature`	单个模式的目标文件、图层、要素名
`--type`	`point` / `line` / `polyline` / `shell`（`polyline` 是 `line` 的别名）
`--point`	点坐标 `x,y,z`（`--type point`）
`--points`	点列表 JSON 数组（`--type line` / `polyline` / `shell`）
`--faces`	面片顶点索引 JSON 数组（`--type shell` 必需）
`--color`	颜色 `r,g,b`，默认 `255,255,255`

关于 line 与 polyline：Dimine 侧按顶点数校验实体类型——line 恰好接受 2 个顶点，多于 2 个顶点的折线必须是 polyline，否则创建/更新会报 The value of the key geometry has error!。SDK 会按顶点数自动判定，因此两种写法都能用；polyline 作为 line 的别名存在，便于按协议词表书写。

关于 shell 的面片：面片索引不可省略，且键名在传输层是 indexs（协议约定）。写原始 JSON 时 "faces" 与 "indexs" 两种键名都接受，SDK 统一转换。

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]
  },
  {
    "type": "shell",
    "file": "file-id",
    "layer": "layer-id",
    "feature": "要素名",
    "geometry": {
      "points": [[0,0,0], [10,0,0], [10,10,0]],
      "faces": [[0, 1, 2]]
    },
    "color": [0, 0, 255]
  }
]

也可直接给 GeoJSON FeatureCollection（Point / MultiPoint / LineString / MultiLineString / Polygon / MultiPolygon）：

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {"file": "file-id", "layer": "layer-id", "feature": "采场边界", "color": [0, 0, 255]},
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[0,0,0], [10,0,0], [10,10,0], [0,10,0], [0,0,0]]]
      }
    }
  ]
}

GeoJSON 的 Polygon 不需要 faces——SDK 会对线性环做扇形三角化，并自动去掉线性环首尾重复的收尾点。GeoJSON 里没有地方写面片索引，这是它与原始 JSON 格式的关键区别。

发送前校验：SDK 会在本地校验每条几何体（类型是否合法、坐标是否齐全、shell 是否有面片），一次性报出所有问题及其下标，不会让一条坏数据把整批发到服务端后只换回一句 The value of the key geometry has error!。

`geometry-update` — 更新几何体

dimine geometry-update --geometries <json>
dimine geometry-update --id <实体ID> --file <id> --layer <id> --feature <name> --type <type> [--color r,g,b]

批量模式下 JSON 需包含 id 字段以定位要更新的实体。可选的只有几何数据：不带 --point / --points / --faces 时该实体的几何保持不变，只更新传入的属性（如颜色）。

注意：--file、--layer、--feature、--type 在更新时都要传。服务端对更新请求是按位置读取这些键的，缺任一个会分别报 Failed to retrieve memory file[]! / Message json has not layer key! / Message json has not feature key! / Message json has not entity_type key!。因此 geometry-update --id <id> --color ... 这种"只改颜色"的最简写法不可用，必须补齐上述字段。

更新是整条替换语义：传了 --points/--faces 就整体覆盖该实体的几何，未传则几何原样保留。

不带几何更新时必须给出实体的准确类型。服务端会校验 entity_type 与库中已有实体完全一致，而 SDK 只有在传了几何时才能按顶点数推断。因此： - 更新折线（polyline）实体且不带 --points 时，必须写 --type polyline；写 --type line 会被服务端拒绝（entity type is not match） - 带几何更新时 --type 只需 line/polyline 之一即可，SDK 一律按顶点数判定

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

dimine geometry-upsert --geometries <json>
dimine geometry-upsert --file <id> --layer <id> --feature <name> --type <type> [--id <实体ID>] ...

批量模式下，字典中含 id 的做部分更新，不含 id 的新建。related 字段由 SDK 按 id 是否存在设置，无需手工指定。

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 ↔ dm（DataMine）, dmf → mgis（MapGIS，仅单向）, dmd → dmg（钻孔数据库）

MapGIS 仅支持作为目标格式，mgis → dmf 当前不可用。 dmf → mgis 的产物是文件夹（如 新文件2/，内含 .WL/.WT），而非 新文件2.mgis 文件；JSON 输出中的 output_path 为真实产物路径，output_is_directory 标识是否为文件夹。

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`

4.11 应用启动（本地进程）

`start` — 后台启动 Dimine

定位 DIMINE_HOME 下的 Dimine 主程序并在后台分离启动，作为执行 file-tree、file-open 等远程命令的前置步骤。

前置条件：仅当确认 Dimine 确实没有运行时才可使用。 调用其他远程命令发现连不上 Dimine（连接被拒绝 / 超时）时，才应该用本命令拉起实例。命令会先做两重探测确认： 1. 本机是否已有 Dimine 进程（按 Dimine*.exe 前缀匹配，Dimine.exe、Dimine_ai.exe 等变体名都会被识别）； 2. 远端服务 ws://127.0.0.1:8000 是否可连接。

只要任一命中，就认定 Dimine 已在运行，直接报错退出（success=false），既不会启动新实例，也不会结束任何旧进程。如需重启请先在 Dimine 中退出。

dimine start                        # 默认等远端 WebSocket 就绪最多 8s
dimine start --wait 30              # 把“等 UAC 应答 + 等远端就绪”整体预算调为 30s
dimine start --wait 0               # 不等待就绪也不设预算：启动后立即返回
dimine start --home <path>          # 手动指定 Dimine 安装目录（默认取 DIMINE_HOME）

参数	说明	默认值
`--home`	Dimine 安装目录（应含主程序 exe）	`DIMINE_HOME` 环境变量
`--wait`	启动总预算秒数：提权启动时等 UAC 应答 + 之后等远端服务（`ws://127.0.0.1:8000`）就绪，合计不超过该值	`8`（`0`=不等待就绪且不设预算）

输出（json）示例：

{
  "success": true,
  "pid": 12648,
  "pids": [12648],
  "dimine_home": "E:\\数采软件\\x64\\x64",
  "exe": "E:\\数采软件\\x64\\x64\\Dimine.exe",
  "wait_seconds": 8,
  "remote_ready": true,
  "waited_seconds": 2.1,
  "message": "已后台启动 Dimine: ...（pid=12648），远端服务 ws://127.0.0.1:8000 已在 2.1s 内就绪"
}

若主程序要求管理员权限而当前终端未提权（启动报 WinError 740）：自动触发一次 UAC 提权启动。请在弹出的 UAC 窗口选择「是」；若在 --wait 预算内一直未应答，命令报错退出（该次未决提权随之取消）。
提权成功但新进程 pid 未被探测到时：message 提示为「已触发 UAC 提权启动」，pid 为 null（提权进程由系统独立创建，需经任务列表二次探测）。
remote_ready=false（就绪在预算内未完成）：命令仍返回 success=true，可加大 --wait 重试。
中途可按 Ctrl+C 中止等待。

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 — 删除要素定义