sunvpy-docs/docs/content/21-tian-jia-dui-xiang-zuo-biao-dian.md

本文档详细说明如何为新建的地理对象添加坐标点，这是地理对象编辑流程中的核心步骤。通过坐标点的添加，可以构建点、线、面等不同类型的几何对象，为后续的保存和数据库存储奠定基础。

## 方法概述

`addNewObjPoint` 方法用于向当前新建的地理对象添加一个空间坐标点。该方法属于 `GeoEditMixin` 混合类，通过 `SSProcessManager` 实例调用。它支持三维坐标输入，并可设置点的类型和名称属性。

**方法签名**:
```python
addNewObjPoint(x: float, y: float, z: float, type: int, name: str) -> bool
```

**参数说明**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| x | float | 点的 X 坐标值 |
| y | float | 点的 Y 坐标值 |
| z | float | 点的 Z 坐标值（高程） |
| type | int | 点的类型，使用 PointInfoEnum 点信息枚举的二进制位存储 |
| name | str | 点的名称标识 |

**返回值**:
- `True`: 添加成功
- `False`: 添加失败（通常是因为当前没有新建对象）

Sources: [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L417-L434)

## 工作流程

添加坐标点的操作必须建立在已创建地理对象的基础上。完整的工作流程包括对象创建、坐标点添加、对象保存等步骤。

```mermaid
flowchart TD
    A[开始] --> B[创建地理对象<br/>createNewObjByCode]
    B --> C[是否创建成功?]
    C -->|否| D[返回错误]
    C -->|是| E[添加第一个坐标点<br/>addNewObjPoint]
    E --> F[需要添加更多点?]
    F -->|是| G[添加后续坐标点<br/>addNewObjPoint]
    G --> F
    F -->|否| H[添加到选择集<br/>addNewObjToSelObjList]
    H --> I[添加到保存列表<br/>addNewObjToSaveObjList]
    I --> J[保存到数据库<br/>saveBufferObjToDatabase]
    J --> K[结束]
```

Sources: [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L417-L464)

## 使用场景

根据几何对象类型的不同，添加坐标点的行为有所差异：

| 对象类型 | 所需点数 | 点的顺序要求 | 典型应用 |
|----------|---------|-------------|---------|
| 点对象 | 1个 | 无 | 地标点、测量控制点 |
| 线对象 | ≥2个 | 需按路径顺序 | 道路中心线、管线 |
| 面对象 | ≥3个 | 按顺时针或逆时针闭合 | 建筑物轮廓、地块边界 |
| 注记对象 | 1个（定位点） | 无 | 文字标注位置 |

Sources: [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L35-L51)

## 代码示例

### 示例 1: 创建点对象并添加坐标

```python
# 创建点对象（代码 1001 表示某种特定类型的点）
obj, geo = SSProcess.createNewObjByCode(1001)
if obj and geo:
    # 添加唯一坐标点
    success = SSProcess.addNewObjPoint(
        x=123456.789,
        y=3456789.012,
        z=45.5,
        type=ATTR_NORMAL_POINT,
        name="控制点P1"
    )
    if success:
        # 添加到选择集和保存列表
        SSProcess.addNewObjToSelObjList()
        SSProcess.addNewObjToSaveObjList()
        SSProcess.saveBufferObjToDatabase()
```

Sources: [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L417-L434)

### 示例 2: 创建线对象并添加多个坐标点

```python
# 创建线对象（代码 2001 表示道路中心线）
obj, geo = SSProcess.createNewObjByCode(2001)
if obj and geo:
    # 添加路径上的坐标点
    points = [
        (123456.789, 3456789.012, 45.5, "起点"),
        (123460.789, 3456793.012, 45.3, "中间点1"),
        (123470.789, 3456803.012, 45.1, "中间点2"),
        (123480.789, 3456813.012, 45.0, "终点")
    ]
    
    for x, y, z, name in points:
        SSProcess.addNewObjPoint(x, y, z, ATTR_NORMAL_LINE, name)
    
    # 保存对象
    SSProcess.addNewObjToSelObjList()
    SSProcess.addNewObjToSaveObjList()
    SSProcess.saveBufferObjToDatabase()
```

Sources: [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L417-L434)

### 示例 3: 创建面对象并形成闭合多边形

```python
# 创建面对象（代码 3001 表示建筑物）
obj, geo = SSProcess.createNewObjByCode(3001)
if obj and geo:
    # 按顺时针顺序添加顶点形成闭合多边形
    corners = [
        (123456.789, 3456789.012, 45.5, "西北角"),
        (123466.789, 3456789.012, 45.5, "东北角"),
        (123466.789, 3456799.012, 45.5, "东南角"),
        (123456.789, 3456799.012, 45.5, "西南角")
    ]
    
    for x, y, z, name in corners:
        SSProcess.addNewObjPoint(x, y, z, ATTR_NORMAL_POLY, name)
    
    # 保存对象
    SSProcess.addNewObjToSelObjList()
    SSProcess.addNewObjToSaveObjList()
    SSProcess.saveBufferObjToDatabase()
```

Sources: [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L417-L434)

## 点类型枚举

`type` 参数使用二进制位存储的点信息枚举值，常用的枚举常量包括：

| 枚举常量 | 值 | 说明 |
|---------|---|------|
| ATTR_NORMAL_POINT | 普通点类型 | 一般点对象 |
| ATTR_CTR_POINT | 控制点类型 | 测量控制点 |
| ATTR_LAND_HEIGHT | 陆地高程点 | 高程注记点 |
| ATTR_WATER_HEIGHT | 水位高程点 | 水位注记点 |
| ATTR_FORMULA_HEIGHT | 计算高程点 | 通过计算得到的高程点 |
| ATTR_NAME_POINT | 名称点 | 地名标识点 |
| ATTR_NORMAL_LINE | 普通线型 | 一般线段 |
| ATTR_PHYSI_LINE | 自然界线 | 自然地理界线 |
| ATTR_EQUAL_VALUE_LINE | 等值线 | 等高线、等深线 |
| ATTR_NORMAL_POLY | 普通面 | 一般多边形 |
| ATTR_AUTO_POLY | 自动生成面 | 程序自动生成的面 |

Sources: [PySSMath.py](PySSMath.py#L630-L660)

## 注意事项

### 前置条件检查

在调用 `addNewObjPoint` 之前，必须确保已经成功创建了地理对象：

```python
# 检查当前新建对象是否存在
if SSProcess.curNewObj[0] is not None and SSProcess.curNewObj[1] is not None:
    # 可以安全添加坐标点
    success = SSProcess.addNewObjPoint(x, y, z, type, name)
else:
    print("错误：请先创建地理对象！")
```

Sources: [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L417-L424)

### 坐标系统

- 坐标值应与当前地图的坐标系统一致
- X 和 Y 坐标通常表示平面位置
- Z 坐标表示高程，对于二维数据可设置为 0 或默认值

### 对象类型适配

添加坐标点的数量和顺序必须与对象类型匹配：
- **点对象**：只添加一个点
- **线对象**：至少添加两个点，按路径顺序
- **面对象**：至少添加三个点，形成闭合多边形
- **注记对象**：只添加一个定位点

### 保存机制

添加的坐标点暂存在内存中，必须通过以下步骤才能持久化到数据库：

```python
# 1. 添加到脚本选择集（可选，用于后续查询）
SSProcess.addNewObjToSelObjList()

# 2. 添加到保存列表（必需）
SSProcess.addNewObjToSaveObjList()

# 3. 批量保存到数据库（必需）
SSProcess.saveBufferObjToDatabase()
```

Sources: [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L436-L464)

## 错误处理

常见错误及处理方法：

| 错误现象 | 可能原因 | 解决方法 |
|---------|---------|---------|
| 返回 False | 当前没有新建对象 | 先调用 `createNewObjByCode` 创建对象 |
| 对象不显示 | 未保存到数据库 | 调用 `saveBufferObjToDatabase` 保存 |
| 点顺序错误 | 线或面对象点序混乱 | 按正确的路径顺序添加点 |
| 坐标超出范围 | 坐标值不在地图范围内 | 检查并修正坐标值 |

Sources: [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L417-L424)

## 相关功能

添加坐标点操作与以下功能紧密相关：

- **[通过编码创建对象](20-tong-guo-bian-ma-chuang-jian-dui-xiang)**: 创建地理对象的前提步骤
- **[对象缓存机制](23-dui-xiang-huan-cun-ji-zhi)**: 了解坐标点的缓存和保存机制
- **[批量保存到数据库](24-pi-liang-bao-cun-dao-shu-ju-ku)**: 将坐标点持久化的详细说明
- **[删除对象操作](22-shan-chu-dui-xiang-cao-zuo)**: 对象管理的补充操作

Sources: [ssprocess_mixins/geo_edit_mixin.py](ssprocess_mixins/geo_edit_mixin.py#L417-L530)

## 最佳实践

1. **批量操作**: 对于需要创建大量对象的场景，建议先创建所有对象并添加坐标点，最后统一调用 `saveBufferObjToDatabase` 批量保存，以提高性能。

2. **坐标精度**: 根据地图比例尺和测量精度要求，设置适当的坐标精度。建议使用浮点数保持高精度。

3. **点序管理**: 对于线、面对象，建议在添加点之前规划好点的顺序，避免交叉或自相交。

4. **错误检查**: 在每次添加坐标点后检查返回值，及时发现并处理错误。

5. **命名规范**: 为坐标点设置有意义的名称，便于后续的查询和管理。