dimine-python-sdk 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

dimine_python_sdk/__init__.py

@@ -3,7 +3,7 @@ from pathlib import Path
 from .conn import ConnClient
 
 DOCS_PATH = Path(__file__).parent / "docs"
-__VERSION__ = "0.2.0"  # 由 build.bat 中的 generate_version.py 自动更新
+__VERSION__ = "0.2.2"  # 由 build.bat 中的 generate_version.py 自动更新
 
 
 __all__ = [

dimine_python_sdk/cli/commands/file.py

@@ -195,13 +195,13 @@ def register_commands(subparsers, format_parent) -> None:
     p.add_argument("--file-id", default=None, help="文件ID，多个文件打开时必填")
 
     p = subparsers.add_parser("file-open", parents=[format_parent], help="打开文件到 Dimine 场景")
-    p.add_argument("--path", required=True, help="要打开的 .dmf/.dwg/.dxf 等文件路径")
+    p.add_argument("--path", "--file", required=True, help="要打开的 .dmf/.dwg/.dxf 等文件路径")
 
     p = subparsers.add_parser("file-close", parents=[format_parent], help="关闭 Dimine 中的文件")
     p.add_argument("--file-id", required=True, help="要关闭的文件ID")
 
     p = subparsers.add_parser("file-create", parents=[format_parent], help="在 Dimine 中创建新的空文件")
-    p.add_argument("--path", required=True, help="新文件的路径")
+    p.add_argument("--path", "--file", required=True, help="新文件的路径")
 
     p = subparsers.add_parser("file-visibility", parents=[format_parent], help="设置文件显示/隐藏状态")
     p.add_argument("--file-id", required=True, help="文件ID")

dimine_python_sdk/cli/commands/geometry.py

@@ -202,6 +202,112 @@ def _build_single_geo_from_flat(file_id: str, layer_id: str, feature: str,
     return [obj]
 
 
+def _build_partial_geo_from_flat(entity_id: str, geo_type: str | None = None,
+                                  file_id: str | None = None, layer_id: str | None = None,
+                                  feature: str | None = None, point: str | None = None,
+                                  points: str | None = None, faces: str | None = None,
+                                  color: str | None = None) -> list:
+    """从扁平参数构建部分几何体对象（仅用于 update）。
+
+    与 _build_single_geo_from_flat 不同：
+    - 仅 entity_id 是必需的
+    - 未提供的字段设为 None/空，不会被发送到服务端
+    - geo_type 仅在提供几何数据时需要
+    """
+    from dimine_python_sdk.models.types import Line, Point, Shell
+
+    color_val = parse_color(color) if color else None
+
+    # 构建公共参数，只包含非 None 字段
+    common_kwargs = {"id": entity_id}
+    if file_id is not None:
+        common_kwargs["file"] = file_id
+    if layer_id is not None:
+        common_kwargs["layer"] = layer_id
+    if feature is not None:
+        common_kwargs["feature"] = feature
+    if color_val is not None:
+        common_kwargs["color"] = color_val
+
+    if geo_type == "point":
+        kwargs = dict(common_kwargs)
+        if point:
+            kwargs["geometry"] = parse_point3d(point)
+        obj = Point(**kwargs)
+    elif geo_type == "line":
+        kwargs = dict(common_kwargs)
+        if points:
+            kwargs["geometry"] = parse_points2d(points)
+        obj = Line(**kwargs)
+    elif geo_type == "shell":
+        kwargs = dict(common_kwargs)
+        if points:
+            pts = parse_points2d(points)
+            face_list = parse_points2d(faces) if faces else []
+            kwargs["geometry"] = {"points": pts, "faces": face_list}
+        obj = Shell(**kwargs)
+    elif geo_type is None:
+        # 无几何类型的纯属性更新（如只改 color）
+        obj = Shell(**common_kwargs)
+    else:
+        raise ValueError(f"无效的几何体类型 '{geo_type}'，可选: point/line/shell")
+
+    obj.related = True
+    return [obj]
+
+
+def _build_partial_geometry_objects(geometries: list) -> list:
+    """将 JSON 字典列表转换为部分几何体对象（仅用于 update）。
+
+    与 _build_geometry_objects 不同：
+    - 只设置字典中存在的字段，缺失字段不填默认值
+    - 每个字典必须包含 'id' 字段
+    """
+    from dimine_python_sdk.models.types import Line, Point, Shell
+
+    result = []
+    for g in geometries:
+        entity_id = g.get("id")
+        if not entity_id:
+            raise ValueError("update 模式下每个几何体必须提供 'id' 字段")
+
+        geo_type = g.get("type", "shell")
+        file_id = g.get("file")
+        layer_id = g.get("layer")
+        feature_name = g.get("feature")
+        color = g.get("color")
+        geometry = g.get("geometry", {})
+
+        kwargs = {
+            "id": entity_id,
+            "file": file_id,
+            "layer": layer_id,
+            "feature": feature_name,
+            "color": color,
+        }
+
+        if geo_type == "point":
+            if "geometry" in g and geometry:
+                pt = geometry.get("point", [0, 0, 0])
+                kwargs["geometry"] = pt
+            obj = Point(**kwargs)
+        elif geo_type == "line":
+            if "geometry" in g and geometry:
+                pts = geometry.get("points", [])
+                kwargs["geometry"] = pts
+            obj = Line(**kwargs)
+        else:
+            if "geometry" in g and geometry:
+                pts = geometry.get("points", [])
+                faces = geometry.get("faces", [])
+                kwargs["geometry"] = {"points": pts, "faces": faces}
+            obj = Shell(**kwargs)
+
+        obj.related = True
+        result.append(obj)
+    return result
+
+
 def cmd_geometry_get(fmt: str, file_id: str, layer_id: str | None,
                      entity_types: str | None = None, features: str | None = None,
                      with_geometry: bool = False) -> None:
@@ -332,8 +438,10 @@ def cmd_geometry_update(fmt: str, geometries: str | None = None,
     """更新现有几何体对象（需 Dimine 运行）。
 
     两种模式：
-    1. 扁平参数（单几何体）: --id --type --point/--points [--file --layer --feature --color]
+    1. 扁平参数（单几何体）: --id [--type --point/--points] [--file --layer --feature --color]
+       不传的字段保持服务端原值不变。
     2. JSON/文件/stdin（批量）: --geometries JSON/@file.json/-
+       字典中只包含需要更新的字段。
     """
     err = require_remote_sdk()
     if err:
@@ -344,21 +452,21 @@ def cmd_geometry_update(fmt: str, geometries: str | None = None,
             raw_geos = _read_geometries_input(geometries)
         except ValueError as e:
             output_error(str(e), fmt)
-    elif entity_id and geo_type and file_id and layer_id and feature:
+    elif entity_id:
         try:
-            raw_geos = _build_single_geo_from_flat(
+            raw_geos = _build_partial_geo_from_flat(
+                entity_id=entity_id, geo_type=geo_type,
                 file_id=file_id, layer_id=layer_id, feature=feature,
-                geo_type=geo_type, point=point, points=points, faces=faces, color=color,
-                entity_id=entity_id,
+                point=point, points=points, faces=faces, color=color,
             )
         except ValueError as e:
             output_error(str(e), fmt)
     else:
-        output_error("请提供 --geometries（批量）或 --id、--file、--layer、--feature、--type（单个更新）", fmt)
+        output_error("请提供 --geometries（批量）或 --id（单个更新）", fmt)
 
     if raw_geos and isinstance(raw_geos[0], dict):
         try:
-            geo_objects = _build_geometry_objects(raw_geos)
+            geo_objects = _build_partial_geometry_objects(raw_geos)
         except Exception as e:
             output_error(f"构建几何体对象失败: {e}", fmt)
     else:
@@ -391,7 +499,10 @@ def cmd_geometry_upsert(fmt: str, geometries: str | None = None,
 
     两种模式：
     1. 扁平参数（单几何体）: --file --layer --feature --type [--id] --point/--points [--color]
+       - 有 --id: 部分更新，不传的字段保持不变
+       - 无 --id: 新建几何体
     2. JSON/文件/stdin（批量）: --geometries JSON/@file.json/-
+       - 字典中含 "id" 则部分更新，不含则新建
     """
     err = require_remote_sdk()
     if err:
@@ -402,26 +513,39 @@ def cmd_geometry_upsert(fmt: str, geometries: str | None = None,
             raw_geos = _read_geometries_input(geometries)
         except ValueError as e:
             output_error(str(e), fmt)
+        # 按是否有 id 分离：有 id 的部分更新，无 id 的新建
+        update_dicts = [g for g in raw_geos if g.get("id")]
+        create_dicts = [g for g in raw_geos if not g.get("id")]
+        geo_objects = []
+        if update_dicts:
+            try:
+                geo_objects.extend(_build_partial_geometry_objects(update_dicts))
+            except Exception as e:
+                output_error(f"构建更新几何体对象失败: {e}", fmt)
+        if create_dicts:
+            try:
+                geo_objects.extend(_build_geometry_objects(create_dicts))
+            except Exception as e:
+                output_error(f"构建新建几何体对象失败: {e}", fmt)
     elif geo_type and file_id and layer_id and feature:
         try:
-            raw_geos = _build_single_geo_from_flat(
-                file_id=file_id, layer_id=layer_id, feature=feature,
-                geo_type=geo_type, point=point, points=points, faces=faces, color=color,
-                entity_id=entity_id,
-            )
+            if entity_id:
+                raw_geos = _build_partial_geo_from_flat(
+                    entity_id=entity_id, geo_type=geo_type,
+                    file_id=file_id, layer_id=layer_id, feature=feature,
+                    point=point, points=points, faces=faces, color=color,
+                )
+            else:
+                raw_geos = _build_single_geo_from_flat(
+                    file_id=file_id, layer_id=layer_id, feature=feature,
+                    geo_type=geo_type, point=point, points=points, faces=faces, color=color,
+                )
         except ValueError as e:
             output_error(str(e), fmt)
+        geo_objects = raw_geos
     else:
         output_error("请提供 --geometries（批量）或 --file、--layer、--feature、--type（单个）", fmt)
 
-    if raw_geos and isinstance(raw_geos[0], dict):
-        try:
-            geo_objects = _build_geometry_objects(raw_geos)
-        except Exception as e:
-            output_error(f"构建几何体对象失败: {e}", fmt)
-    else:
-        geo_objects = raw_geos
-
     async def _run():
         client = await get_client()
         result = await client.update_or_create_geometry(geo_objects)

dimine_python_sdk/conn/conn_client.py

@@ -163,7 +163,7 @@ class ConnClient(BaseConnClient):
             "layer": geom.layer,
             "feature": geom.feature or "0",
             "entity_type": geom.type,
-            "color": geom.color,
+            "color": geom.color if geom.color is not None else [0, 0, 0],
             "properties": [
                 {"name": prop.name, "value": prop.value}
                 for prop in geom.properties
@@ -350,18 +350,31 @@ class ConnClient(BaseConnClient):
         # 格式化模型数据
         formatted_geometries = []
         for geom in geometries:
-            formatted_geom = {
-                "id": geom.id,
-                "file": geom.file,
-                "layer": geom.layer,
-                "feature": geom.feature,
-                "entity_type": geom.type,
-                "geometry": geom.geometry.tolist() if geom.type!="shell" else {"indexs": geom.geometry.faces.tolist(), "points": geom.geometry.points.tolist()},
-                "color": geom.color,
-            }
+            formatted_geom: Dict[str, Any] = {"id": geom.id}
+            # 仅发送显式设置的非 None/空字段
+            if geom.file is not None:
+                formatted_geom["file"] = geom.file
+            if geom.layer is not None:
+                formatted_geom["layer"] = geom.layer
+            if geom.feature is not None:
+                formatted_geom["feature"] = geom.feature
+            if geom.type is not None:
+                formatted_geom["entity_type"] = geom.type
+            if geom.color is not None:
+                formatted_geom["color"] = geom.color
+            # geometry：仅当非空时发送
+            if geom.type == "shell" and geom.geometry is not None:
+                geo = geom.geometry
+                if geo.points is not None and len(geo.points) > 0:
+                    formatted_geom.setdefault("geometry", {})["points"] = geo.points.tolist()
+                if geo.faces is not None and len(geo.faces) > 0:
+                    formatted_geom.setdefault("geometry", {})["indexs"] = geo.faces.tolist()
+            elif geom.type in ("point", "line") and geom.geometry is not None and len(geom.geometry) > 0:
+                formatted_geom["geometry"] = geom.geometry.tolist()
 
             # 处理属性信息
-            formatted_geom["properties"] = [
+            if geom.properties:
+                formatted_geom["properties"] = [
                     {"name": prop.name, "value": prop.value}
                     for prop in geom.properties
                 ]

dimine_python_sdk/docs/examples/import_csv_to_drill_db.md

@@ -15,7 +15,7 @@ Dimine 需已启动并开启 WebSocket 服务（默认 `ws://localhost:8000`）
 ```python
 import asyncio
 import pandas as pd
-from dimine_python_sdk.lib.prospecting import DrillDBManager
+from dimine_python_sdk.lib.io import DmdFile
 from dimine_python_sdk.conn import open_client
 
 
@@ -23,9 +23,9 @@ async def import_and_open():
     # ------------------------------------------------------------------
     # 1. 从 CSV 导入并映射为中文标准列名
     # ------------------------------------------------------------------
-    db = DrillDBManager()
+    dmd = DmdFile()
 
-    db.collar = pd.read_csv("raw_collar.csv").rename(columns={
+    dmd.collar = pd.read_csv("raw_collar.csv").rename(columns={
         "HoleID": "工程号",
         "X": "横坐标",
         "Y": "纵坐标",
@@ -34,14 +34,14 @@ async def import_and_open():
         "Line": "勘探线",
     })
 
-    db.survey = pd.read_csv("raw_survey.csv").rename(columns={
+    dmd.survey = pd.read_csv("raw_survey.csv").rename(columns={
         "HoleID": "工程号",
         "Depth": "测斜深度",
         "Azimuth": "方位角",
         "Dip": "倾角",
     })
 
-    db.lithology = pd.read_csv("raw_lithology.csv").rename(columns={
+    dmd.lithology = pd.read_csv("raw_lithology.csv").rename(columns={
         "HoleID": "工程号",
         "From": "起始",
         "To": "结束",
@@ -49,7 +49,7 @@ async def import_and_open():
     })
 
     # 样品表可选；除标准列外可保留元素品位等非标准列
-    db.sample = pd.read_csv("raw_sample.csv").rename(columns={
+    dmd.sample = pd.read_csv("raw_sample.csv").rename(columns={
         "HoleID": "工程号",
         "SampleID": "样本编号",
         "From": "起始",
@@ -62,7 +62,7 @@ async def import_and_open():
     # 2. 保存为 .dmd 钻孔数据库
     # ------------------------------------------------------------------
     dmd_path = "C:/Projects/Mine/钻孔数据.dmd"
-    db.save(dmd_path)
+    dmd.save(dmd_path)
     print(f"已保存: {dmd_path}")
 
     # ------------------------------------------------------------------
@@ -77,6 +77,57 @@ if __name__ == "__main__":
     asyncio.run(import_and_open())
 ```
 
+## 导入扩展表
+
+除四大核心表外，还可以将分层表、地质编录表等自定义数据作为扩展表导入：
+
+```python
+import pandas as pd
+from dimine_python_sdk.lib.io import DmdFile
+from dimine_python_sdk.lib.native.models import NativeExtendTable
+
+dmd = DmdFile()
+
+# 设置核心表...
+dmd.collar = pd.read_csv("raw_collar.csv").rename(columns={...})
+dmd.survey = pd.read_csv("raw_survey.csv").rename(columns={...})
+dmd.lithology = pd.read_csv("raw_lithology.csv").rename(columns={...})
+
+# 方式一：使用 NativeExtendTable（推荐）
+ext_df = pd.read_csv("raw_stratigraphy.csv").rename(columns={
+    "HoleID": "工程号",
+    "From": "起始",
+    "To": "结束",
+    "LayerName": "分层名称",
+})
+
+dmd.extend_tables = [
+    NativeExtendTable(
+        df=ext_df,
+        dmt_filename="分层表.dmt",
+        hole_id_column="工程号",
+        from_column="起始",
+        to_column="结束",
+        display_title="分层表",
+    ),
+]
+
+# 方式二：使用 dict（向后兼容）
+dmd.extend_tables = [
+    {
+        "df": ext_df,
+        "dmt_filename": "分层表.dmt",
+        "hole_id_column": "工程号",
+        "from_column": "起始",
+        "to_column": "结束",
+        "display_title": "分层表",
+    },
+]
+
+# 保存（扩展表自动写入 _分层表.dmt 并在 .dmd 中记录引用）
+dmd.save("C:/Projects/Mine/钻孔数据.dmd")
+```
+
 ## 列名映射速查
 
 | 外部 CSV 列名 | 中文标准列名 | 对应表 |
@@ -94,6 +145,7 @@ if __name__ == "__main__":
 | `Rock` | `岩性编号` | 岩性表 |
 
 - 列名映射使用 `pandas.DataFrame.rename(columns=...)` 完成
-- DataFrame 列名必须包含[标准列名映射规范](../guides/db.md#标准列名映射规范)中对应表的必选标准列
+- DataFrame 列名必须包含[标准列名映射规范](../guides/lib/prospecting/drill_db.md#13-standard-column-mapping)中对应表的必选标准列
 - 元素品位等非标准列（如 `CU`、`AU`）无需映射，直接保留即可 — 它们会写入 `.dmt` 子表但不出现于 `.dmd` 引用
 - `.dmd` 文件与 `{stem}_collar.dmt` / `{stem}_survey.dmt` / `{stem}_lithology.dmt` 等子表文件保存在同一目录下
+- 扩展表的 `.dmt` 文件名由 `dmt_filename` 参数指定（如 `分层表.dmt`），保存时写入同一目录

dimine_python_sdk/docs/examples/lib_file_usage.md

@@ -73,14 +73,15 @@ with DmfFile("input.dmf") as dmf:
     # 新增图层
     layer = dmf.add_layer("计算结果")
 
-    # 插入点
-    layer.insert_point(np.array([100.0, 200.0, 300.0]), name="测点-1")
+    # 插入点（可指定颜色 color=[R, G, B]）
+    layer.insert_point(np.array([100.0, 200.0, 300.0]), name="测点-1", color=[255, 0, 0])
 
     # 插入直线
     layer.insert_line(
         np.array([0.0, 0.0, 0.0]),
         np.array([10.0, 0.0, 0.0]),
         name="中线",
+        color=[0, 255, 0],
     )
 
     # 插入多段线
@@ -92,6 +93,7 @@ with DmfFile("input.dmf") as dmf:
             [0, 10, 0],
         ]),
         name="轮廓线",
+        color=[0, 0, 255],
     )
 
     # 保存为新文件
@@ -120,7 +122,7 @@ faces = np.array([
 
 with DmfFile() as dmf:
     layer = dmf.add_layer("三角网")
-    layer.insert_shell(points, faces, name="坡面")
+    layer.insert_shell(points, faces, name="坡面", color=[128, 128, 128])
     dmf.save("shell_model.dmf")
 ```