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

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

方法概述

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

方法签名:

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

工作流程

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

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

使用场景

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

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

Sources: ssprocess_mixins/geo_edit_mixin.py

代码示例

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

# 创建点对象（代码 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

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

# 创建线对象（代码 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

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

# 创建面对象（代码 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

点类型枚举

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

注意事项

前置条件检查

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

# 检查当前新建对象是否存在
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

坐标系统

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

对象类型适配

添加坐标点的数量和顺序必须与对象类型匹配：

• 点对象：只添加一个点
• 线对象：至少添加两个点，按路径顺序
• 面对象：至少添加三个点，形成闭合多边形
• 注记对象：只添加一个定位点

保存机制

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

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

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

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

Sources: ssprocess_mixins/geo_edit_mixin.py

错误处理

常见错误及处理方法：

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

Sources: ssprocess_mixins/geo_edit_mixin.py

相关功能

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

• 通过编码创建对象: 创建地理对象的前提步骤
• 对象缓存机制: 了解坐标点的缓存和保存机制
• 批量保存到数据库: 将坐标点持久化的详细说明
• 删除对象操作: 对象管理的补充操作

Sources: ssprocess_mixins/geo_edit_mixin.py

最佳实践

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

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

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

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

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