188 lines
9.0 KiB
Markdown
188 lines
9.0 KiB
Markdown
sunvpy是SunvStation地理信息系统的Python脚本接口库，专为二次开发和自动化数据处理任务设计。该库通过SWIG封装技术将C++核心功能暴露给Python，提供了完整的地理对象管理、空间查询、数据交换和质量检查能力。
|
||
|
||
Sources: [__init__.py](__init__.py#L1-L12)
|
||
|
||
## 核心架构
|
||
|
||
sunvpy采用分层架构设计，底层为SWIG封装的C++扩展模块，上层为面向Python的高级API封装。SSProcessManager作为主要入口类，通过Mixin模式组织功能模块，实现了关注点分离和代码复用。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "Python API层"
|
||
A[SSProcessManager<br/>进程管理器]
|
||
B[ObjBaseAttr<br/>属性管理器]
|
||
C[SelectionMixin<br/>选择集操作]
|
||
D[GeoEditMixin<br/>地理编辑]
|
||
E[ProjectMixin<br/>工程管理]
|
||
F[LogMixin<br/>日志记录]
|
||
G[ProgressMixin<br/>进度管理]
|
||
end
|
||
|
||
subgraph "SWIG封装层"
|
||
H[PySSCore.pyd<br/>核心功能]
|
||
I[PySSMap.pyd<br/>地图操作]
|
||
J[PySSDataSource.pyd<br/>数据源管理]
|
||
K[PySSDatabase.pyd<br/>数据库操作]
|
||
L[PySSDataX.pyd<br/>数据交换]
|
||
M[PySSCheck.pyd<br/>数据检查]
|
||
N[PySSMath.pyd<br/>数学计算]
|
||
O[PySSWidget.pyd<br/>UI组件]
|
||
P[PySSView.pyd<br/>视图控制]
|
||
Q[PySSGisDBUpdate.pyd<br/>GIS数据库更新]
|
||
end
|
||
|
||
subgraph "C++核心层"
|
||
R[SunvStation<br/>C++引擎]
|
||
end
|
||
|
||
A --> C
|
||
A --> D
|
||
A --> E
|
||
A --> F
|
||
A --> G
|
||
A --> H
|
||
A --> I
|
||
A --> J
|
||
A --> K
|
||
A --> L
|
||
A --> M
|
||
A --> N
|
||
A --> O
|
||
A --> P
|
||
A --> Q
|
||
B --> H
|
||
|
||
H -.-> R
|
||
I -.-> R
|
||
J -.-> R
|
||
K -.-> R
|
||
L -.-> R
|
||
M -.-> R
|
||
N -.-> R
|
||
O -.-> R
|
||
P -.-> R
|
||
Q -.-> R
|
||
```
|
||
|
||
SSProcessManager继承自五个功能Mixin类，每个Mixin负责特定的功能域。这种设计使得代码组织清晰，易于维护和扩展。全局单例SSProcess提供统一访问入口，确保工作空间和地图实例的一致性。
|
||
|
||
Sources: [PySSProcess.py](PySSProcess.py#L28-L46)
|
||
|
||
## 模块功能概览
|
||
|
||
sunvpy包含多个功能模块，每个模块对应特定的地理信息系统操作领域。下表列出了主要模块及其功能描述。
|
||
|
||
| 模块名称 | 文件名 | 功能描述 | 封装类型 |
|
||
|---------|--------|---------|---------|
|
||
| 核心功能 | PySSCore.pyd | 提供基础数据结构、工作空间管理、地物对象等核心类 | SWIG封装 |
|
||
| 地图操作 | PySSMap.pyd | 地图显示、缩放控制、坐标系转换等地图相关功能 | SWIG封装 |
|
||
| 数据源管理 | PySSDataSource.pyd | 数据集访问、数据源管理、数据浏览等功能 | SWIG封装 |
|
||
| 数据库操作 | PySSDatabase.pyd | 数据库连接、查询、更新等数据库操作功能 | SWIG封装 |
|
||
| 数据交换 | PySSDataX.pyd | 数据导入导出、格式转换等数据交换功能 | SWIG封装 |
|
||
| 数据检查 | PySSCheck.pyd | 拓扑检查、规则验证等数据质量检查功能 | SWIG封装 |
|
||
| 数学计算 | PySSMath.pyd | 几何计算、坐标变换、数学运算等数学工具 | SWIG封装 |
|
||
| UI组件 | PySSWidget.pyd | 进度条、对话框、全局选项等用户界面组件 | SWIG封装 |
|
||
| 视图控制 | PySSView.pyd | 视图刷新、窗口管理、显示控制等视图功能 | SWIG封装 |
|
||
| GIS数据库更新 | PySSGisDBUpdate.pyd | GIS数据库批量更新、同步等高级功能 | SWIG封装 |
|
||
| 进程管理器 | PySSProcess.py | 统一API入口，整合所有功能的Python封装 | Python层 |
|
||
| 属性管理器 | ObjBaseAttr.py | 地物基本属性名称注册和索引管理 | Python层 |
|
||
|
||
Sources: [PySSProcess.py](PySSProcess.py#L5-L19)
|
||
|
||
## 主要特性
|
||
|
||
sunvpy提供了丰富的GIS操作功能，覆盖了地理数据处理的主要场景。选择集管理允许用户通过灵活的查询条件筛选地物对象，支持属性过滤和空间查询。地物编辑功能包括创建新对象、修改几何坐标、调整属性值等完整操作流程。
|
||
|
||
数据交换能力支持多种格式的导入导出，可以方便地与其他GIS系统进行数据交互。数据检查模块提供拓扑检查、属性验证、规则检测等质量保证功能，确保数据符合规范要求。批量操作和缓存机制优化了大数据量场景下的性能，有效减少数据库访问次数。
|
||
|
||
进度条和日志系统为长时间运行的任务提供了用户反馈和调试支持，增强了脚本的可维护性和用户体验。撤销标记管理实现了操作的撤销功能，提高了数据操作的安全性。
|
||
|
||
Sources: [PySSProcess.py](PySSProcess.py#L57-L88)
|
||
|
||
## 快速上手
|
||
|
||
使用sunvpy进行地物查询和属性修改非常直观。以下示例展示了如何筛选编码为"3103013"的地物，并修改其属性值。
|
||
|
||
```python
|
||
from sunv import SSProcess
|
||
|
||
# 清空选择集和查询条件
|
||
SSProcess.clearSelection()
|
||
SSProcess.clearSelectCondition()
|
||
|
||
# 设置查询条件：编码等于"3103013"
|
||
SSProcess.setSelectCondition("SSObj_Code", "==", "3103013")
|
||
|
||
# 执行过滤查询
|
||
SSProcess.selectFilter()
|
||
|
||
# 获取选择集中的地物数量
|
||
geo_count = SSProcess.getSelGeoCount()
|
||
print(f"选择集中的地物对象数量: {geo_count}")
|
||
|
||
# 遍历前10个对象并修改属性
|
||
for i in range(min(10, geo_count)):
|
||
# 修改地物ID
|
||
SSProcess.setSelGeoValue(i, "SSObj_ID", f"{i+1000}")
|
||
# 修改线型和线宽
|
||
SSProcess.setSelGeoValue(i, "SSObj_LineType", "3")
|
||
SSProcess.setSelGeoValue(i, "SSObj_LineWidth", "2")
|
||
# 修改颜色为白色
|
||
SSProcess.setSelGeoValue(i, "SSObj_Color", "16777215")
|
||
# 设置名称和别名
|
||
SSProcess.setSelGeoValue(i, "SSObj_Name", f"对象{i+1}")
|
||
SSProcess.setSelGeoValue(i, "SSObj_Byname", f"别名{i+1}")
|
||
```
|
||
|
||
SSProcess是全局单例对象，无需手动创建实例即可直接使用。该对象在首次访问时自动初始化工作空间和地图连接，确保后续操作的正确性。
|
||
|
||
Sources: [PySSProcess.py](PySSProcess.py#L124-L140)
|
||
|
||
## 项目结构
|
||
|
||
sunvpy包采用清晰的目录结构组织代码，将Python实现和C++扩展分离。顶层目录包含所有PySS开头的SWIG封装模块、对应的.pyd二进制文件、以及纯Python实现的功能模块。
|
||
|
||
```
|
||
sunvpy/
|
||
├── __init__.py # 包初始化文件
|
||
├── PySSProcess.py # 进程管理器（主要API入口）
|
||
├── ObjBaseAttr.py # 地物基本属性管理器
|
||
├── PySSCore.py # 核心功能SWIG封装
|
||
├── PySSMap.py # 地图操作SWIG封装
|
||
├── PySSDataSource.py # 数据源管理SWIG封装
|
||
├── PySSDatabase.py # 数据库操作SWIG封装
|
||
├── PySSDataX.py # 数据交换SWIG封装
|
||
├── PySSCheck.py # 数据检查SWIG封装
|
||
├── PySSMath.py # 数学计算SWIG封装
|
||
├── PySSWidget.py # UI组件SWIG封装
|
||
├── PySSView.py # 视图控制SWIG封装
|
||
├── PySSGisDBUpdate.py # GIS数据库更新SWIG封装
|
||
├── _PySSCore.pyd # 核心功能C++扩展
|
||
├── _PySSMap.pyd # 地图操作C++扩展
|
||
├── _PySSDataSource.pyd # 数据源管理C++扩展
|
||
├── _PySSDatabase.pyd # 数据库操作C++扩展
|
||
├── _PySSDataX.pyd # 数据交换C++扩展
|
||
├── _PySSCheck.pyd # 数据检查C++扩展
|
||
├── _PySSMath.pyd # 数学计算C++扩展
|
||
├── _PySSWidget.pyd # UI组件C++扩展
|
||
├── _PySSView.pyd # 视图控制C++扩展
|
||
├── _PySSGisDBUpdate.pyd # GIS数据库更新C++扩展
|
||
└── ssprocess_mixins/ # 功能Mixin模块目录
|
||
├── selection_mixin.py # 选择集操作Mixin
|
||
├── geo_edit_mixin.py # 地理编辑Mixin
|
||
├── project_mixin.py # 工程管理Mixin
|
||
├── log_mixin.py # 日志记录Mixin
|
||
└── progress_mixin.py # 进度管理Mixin
|
||
```
|
||
|
||
ssprocess_mixins目录将SSProcessManager的功能分解为多个独立的Mixin类，每个类专注于特定的功能域。这种模块化设计便于理解、测试和扩展功能。
|
||
|
||
Sources: [PySSProcess.py](PySSProcess.py#L21-L26)
|
||
|
||
## 学习路径建议
|
||
|
||
为了帮助初学者系统地掌握sunvpy，建议按照以下顺序学习文档。首先从[安装与环境配置](2-an-zhuang-yu-huan-jing-pei-zhi)开始，了解如何正确安装和配置运行环境。接着阅读[第一个脚本：查询地物属性](3-di-ge-jiao-ben-cha-xun-di-wu-shu-xing)，通过实际操作建立直观认识。
|
||
|
||
掌握基础操作后，深入学习[使用 SSProcess 管理选择集](4-shi-yong-ssprocess-guan-li-xuan-ze-ji)和[运行内置示例脚本](5-yun-xing-nei-zhi-shi-li-jiao-ben)，熟悉常用API的使用方法。当需要理解底层原理时，可以参考[SunvStation 系统架构](6-sunvstation-xi-tong-jia-gou)和[SWIG 封装机制说明](7-swig-feng-zhuang-ji-zhi-shuo-ming)。
|
||
|
||
对于高级应用场景，建议学习[Mixin 设计模式](9-mixin-she-ji-mo-shi)以理解代码组织方式，以及查阅[SSProcessManager 完整 API](40-ssprocessmanager-wan-zheng-api)获取详细的接口说明。 |