319 lines
12 KiB
Markdown
319 lines
12 KiB
Markdown
SunvStation 地理信息系统采用分层架构设计，其中工作空间与地图是理解整个系统的核心概念。本页将详细阐述这两个核心组件的职责、相互关系以及在 Python 脚本中的使用方式。掌握这些概念是高效使用 sunvpy 库进行二次开发的基础。
|
||
|
||
## 系统架构概览
|
||
|
||
SunvStation 系统采用单例模式的工作空间作为顶级容器，管理所有地图实例和系统资源。工作空间通过 `getInstance()` 方法获取全局唯一实例，确保整个应用程序共享同一资源上下文。地图对象则表示特定比例尺的地理数据视图，包含图层、地物、数据源等子组件。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "应用程序级别"
|
||
WS[WorkSpace 工作空间<br/>单例实例]
|
||
end
|
||
|
||
subgraph "地图级别"
|
||
SM1[ScaleMap 地图1<br/>比例尺1:500]
|
||
SM2[ScaleMap 地图2<br/>比例尺1:1000]
|
||
end
|
||
|
||
subgraph "SM1 组件"
|
||
L1[图层1]
|
||
L2[图层2]
|
||
DS1[数据源EPS]
|
||
end
|
||
|
||
subgraph "SM2 组件"
|
||
L3[图层3]
|
||
L4[图层4]
|
||
DS2[数据源EPS]
|
||
end
|
||
|
||
subgraph "Python 脚本"
|
||
PSS[SSProcessManager<br/>SSProcess全局实例]
|
||
end
|
||
|
||
PSS --> |WorkSpace.getInstance| WS
|
||
PSS --> |getCurrentScaleMap| SM1
|
||
WS --> |管理多个| SM1
|
||
WS --> |管理多个| SM2
|
||
SM1 --> |包含| L1
|
||
SM1 --> |包含| L2
|
||
SM1 --> |引用| DS1
|
||
SM2 --> |包含| L3
|
||
SM2 --> |包含| L4
|
||
SM2 --> |引用| DS2
|
||
```
|
||
|
||
上图展示了系统的核心架构。工作空间作为顶级容器，管理所有地图实例。每个地图对象包含一组图层和关联的数据源。Python 脚本通过 `SSProcess` 全局实例访问工作空间和当前地图，实现与系统资源的交互。
|
||
|
||
Sources: [PySSProcess.py](PySSProcess.py#L30-L60)
|
||
|
||
## 工作空间
|
||
|
||
工作空间是 SunvStation 系统的全局单例对象，负责管理整个应用程序的资源和上下文。它提供统一的入口点来访问当前活动的地图、配置信息和系统路径。
|
||
|
||
### 核心特性
|
||
|
||
工作空间采用单例设计模式，确保整个应用程序中只有一个工作空间实例。这种设计有以下优势：
|
||
|
||
- **资源统一管理**：所有地图实例和共享资源由工作空间统一分配和协调
|
||
- **全局状态一致性**：确保不同模块访问的系统状态保持一致
|
||
- **生命周期控制**：工作空间控制整个应用程序的生命周期，包括资源的创建和销毁
|
||
|
||
### 获取工作空间实例
|
||
|
||
在 Python 脚本中，通过 `WorkSpace.getInstance()` 方法获取工作空间实例。`SSProcessManager` 在初始化时会自动获取工作空间实例并存储为成员变量 `self.workspace`。
|
||
|
||
Sources: [PySSProcess.py](PySSProcess.py#L42-L43)
|
||
|
||
### 主要职责
|
||
|
||
工作空间的核心职责包括：
|
||
|
||
- **地图管理**：维护所有打开的地图实例，提供获取当前活动地图的接口
|
||
- **资源协调**：协调地图之间的资源共享和互斥访问
|
||
- **全局配置**：存储和管理全局配置信息
|
||
- **系统路径**：提供系统级路径信息（配置路径、模板路径、脚本路径等）
|
||
|
||
### 便捷访问方法
|
||
|
||
`ProjectMixin` 提供了便捷方法 `getWorkspace()` 来获取工作空间实例：
|
||
|
||
Sources: [ssprocess_mixins/project_mixin.py](ssprocess_mixins/project_mixin.py#L36-L43)
|
||
|
||
## 地图
|
||
|
||
地图对象（`ScaleMap`）表示特定比例尺的地理数据视图，是工作空间中最核心的可视化和编辑单元。每个地图包含一组图层、地物对象和关联的数据源。
|
||
|
||
### 地图对象定义
|
||
|
||
`ScaleMap` 类定义在 `PySSMap` 模块中，通过 SWIG 从 C++ 封装而来。它是地图数据的主要容器和管理者。
|
||
|
||
Sources: [PySSMap.py](PySSMap.py#L303-L330)
|
||
|
||
### 地图组成结构
|
||
|
||
地图由以下核心组件构成：
|
||
|
||
| 组件类型 | 职责 | Python 类型 |
|
||
|---------|------|-----------|
|
||
| 图层 | 组织和管理地物对象，控制可见性和锁定状态 | Layer |
|
||
| 数据源 | 存储地物数据的底层存储（EPS 数据库） | DataSource |
|
||
| 地物对象 | 点、线、面等地理要素 | GeoObject |
|
||
| 选择集 | 当前选中的地物集合 | GeoBaseList |
|
||
| 符号表 | 要素编码和符号样式定义 | FeatureList |
|
||
|
||
### 图层管理
|
||
|
||
图层是地图中组织地物的逻辑单元。每个图层对应特定的数据类型（点、线、面、注记），可以独立控制其可见性和编辑锁定状态。
|
||
|
||
#### 图层操作 API
|
||
|
||
| 方法 | 功能描述 |
|
||
|-----|---------|
|
||
| `getLayerSize()` | 获取图层数量 |
|
||
| `getLayerName(index)` | 获取指定索引的图层名称 |
|
||
| `setLayerVisible(layerName, status)` | 设置图层可见性 |
|
||
| `isLayerVisible(layerName)` | 检查图层是否可见 |
|
||
| `setLayerLock(layerName, status)` | 设置图层锁定状态 |
|
||
| `isLayerLock(layerName)` | 检查图层是否锁定 |
|
||
|
||
Sources: [PySSMap.py](PySSMap.py#L355-L430)
|
||
|
||
#### 便捷访问方法
|
||
|
||
`ProjectMixin` 提供了简化的图层访问接口：
|
||
|
||
Sources: [ssprocess_mixins/project_mixin.py](ssprocess_mixins/project_mixin.py#L180-L198)
|
||
|
||
### 数据源管理
|
||
|
||
数据源是存储地物数据的底层存储，通常是 EPS 格式的数据库。地图可以加载多个数据源，每个数据源包含多个数据集。
|
||
|
||
| 方法 | 功能描述 |
|
||
|-----|---------|
|
||
| `getCurrentDataSource()` | 获取当前激活的数据源 |
|
||
| `setCurrentDataSource(dataSource)` | 设置当前数据源 |
|
||
| `unloadDataSource(dataSource)` | 卸载指定的数据源 |
|
||
| `getDataSourceSet(dataSourceSet)` | 获取所有可见图层使用的数据源集合 |
|
||
|
||
Sources: [PySSMap.py](PySSMap.py#L445-L480)
|
||
|
||
### 地物搜索与检索
|
||
|
||
地图提供了强大的地物搜索功能，支持多种搜索条件：
|
||
|
||
| 方法 | 功能描述 |
|
||
|-----|---------|
|
||
| `searchObject(objList, ...)` | 根据编码、矩形范围、点位置等条件搜索地物 |
|
||
| `searchMarkNote(geoList, ...)` | 搜索注记对象 |
|
||
| `getNearObject(point, range, ...)` | 获取指定点附近的地物或注记 |
|
||
| `getObjectSize(objType)` | 获取指定类型的地物个数 |
|
||
|
||
Sources: [PySSMap.py](PySSMap.py#L650-L1000)
|
||
|
||
### 撤销与重做
|
||
|
||
地图内置了完整的撤销/重做机制，所有可撤销操作都会被记录在命令栈中。
|
||
|
||
| 方法 | 功能描述 |
|
||
|-----|---------|
|
||
| `pushUndoMark(action)` | 创建撤销标记，用于分组多个操作 |
|
||
| `undo(step=1)` | 执行撤销操作，step 指定步数 |
|
||
| `redo(step=1)` | 执行重做操作 |
|
||
| `getUndoStackSize()` | 获取撤销栈的大小 |
|
||
| `getRedoStackSize()` | 获取重做栈的大小 |
|
||
|
||
Sources: [PySSMap.py](PySSMap.py#L1565-L1610)
|
||
|
||
## 工作空间与地图的关系
|
||
|
||
工作空间和地图之间的关系是整体与部分的关系。工作空间作为全局容器，可以管理多个地图实例，但通常只有一个当前活动的地图。
|
||
|
||
### 访问当前地图
|
||
|
||
通过工作空间的 `getCurrentScaleMap()` 方法获取当前活动的地图实例。在 `SSProcessManager` 初始化时，会自动获取当前地图并存储为成员变量 `self.map`。
|
||
|
||
Sources: [PySSProcess.py](PySSProcess.py#L42-L43)
|
||
|
||
### 地图切换
|
||
|
||
当用户切换地图时（例如从不同比例尺的地图视图切换），工作空间会更新当前活动的地图引用。Python 脚本可以通过以下方式获取最新的当前地图：
|
||
|
||
```python
|
||
# 方法1：直接使用 SSProcess 的 map 成员
|
||
current_map = SSProcess.map
|
||
|
||
# 方法2：通过工作空间获取
|
||
current_map = SSProcess.workspace.getCurrentScaleMap()
|
||
|
||
# 方法3：使用便捷方法
|
||
current_map = SSProcess.getCurrentMap()
|
||
```
|
||
|
||
Sources: [ssprocess_mixins/project_mixin.py](ssprocess_mixins/project_mixin.py#L45-L50)
|
||
|
||
## 系统路径管理
|
||
|
||
工作空间和相关组件提供了获取系统路径的接口，这些路径对于脚本操作文件和配置非常重要。
|
||
|
||
### 路径类型表
|
||
|
||
| 模式 | 路径类型 | 说明 |
|
||
|-----|---------|------|
|
||
| 0 | 配置路径 | 存放系统配置文件 |
|
||
| 1 | 模板路径 | 存放模板文件 |
|
||
| 2 | Comm 路径 | 公共资源路径 |
|
||
| 3 | Script 路径 | 脚本文件路径 |
|
||
| 4 | SSTemp 路径 | 临时文件路径 |
|
||
| 5 | 工程文件路径 | 当前工程所在目录 |
|
||
| 6 | 系统目录 | Windows 系统目录或 Unix /usr |
|
||
| 7/8 | 工作台面目录 | 用户工作台面目录 |
|
||
|
||
Sources: [ssprocess_mixins/project_mixin.py](ssprocess_mixins/project_mixin.py#L52-L80)
|
||
|
||
### 使用示例
|
||
|
||
```python
|
||
# 获取脚本路径
|
||
script_path = SSProcess.getSysPathName(3)
|
||
|
||
# 获取当前工程文件所在目录
|
||
project_dir = SSProcess.getSysPathName(5)
|
||
|
||
# 获取配置路径
|
||
config_path = SSProcess.getSysPathName(0)
|
||
```
|
||
|
||
## 符号表管理
|
||
|
||
地图使用符号表来定义地物的显示样式和要素编码。符号表包括要素代码表、符号脚本表和注记模板表。
|
||
|
||
| 方法 | 功能描述 |
|
||
|-----|---------|
|
||
| `getFeatureCodeTB()` | 获取当前要素代码表名称 |
|
||
| `getSymbolScriptTB()` | 获取当前符号表名称 |
|
||
| `getNoteTemplateTB()` | 获取当前注记模板表名称 |
|
||
| `setFeatureCodeTB(codeTB, symbolTB)` | 设置要素代码表和符号表 |
|
||
| `setNoteTemplateTB(templateTB)` | 设置注记模板表 |
|
||
|
||
Sources: [ssprocess_mixins/project_mixin.py](ssprocess_mixins/project_mixin.py#L200-L267)
|
||
|
||
## 地图图幅管理
|
||
|
||
地图图幅是地图的一个逻辑划分单位，用于组织和管理地图的分幅显示。`ProjectMixin` 提供了图幅相关操作：
|
||
|
||
| 方法 | 功能描述 |
|
||
|-----|---------|
|
||
| `createMapFrame()` | 创建当前地图的图幅列表 |
|
||
| `getMapFrameCount()` | 获取图幅数量 |
|
||
| `getMapFrameCenterPoint(index)` | 获取指定图幅的中心点坐标 |
|
||
| `setCurMapFrame(x, y)` | 设置当前图幅 |
|
||
| `getCurMapFrame()` | 获取当前图幅的编号 |
|
||
| `getMapFrameNumber(x, y)` | 获取指定坐标所在的图幅号 |
|
||
| `freeMapFrame()` | 释放图幅资源 |
|
||
|
||
Sources: [ssprocess_mixins/project_mixin.py](ssprocess_mixins/project_mixin.py#L122-L178)
|
||
|
||
## 最佳实践
|
||
|
||
在使用工作空间和地图时，遵循以下最佳实践可以编写更健壮和高效的代码：
|
||
|
||
### 1. 始终检查空引用
|
||
|
||
访问地图或工作空间对象前，检查是否为 None：
|
||
|
||
```python
|
||
current_map = SSProcess.getCurrentMap()
|
||
if current_map is None:
|
||
print("当前没有打开的地图")
|
||
return
|
||
```
|
||
|
||
### 2. 使用便捷方法优先
|
||
|
||
`ProjectMixin` 提供的便捷方法已经处理了常见的边界情况，优先使用这些方法而不是直接访问底层对象。
|
||
|
||
### 3. 批量操作使用撤销标记
|
||
|
||
执行批量修改操作前，先创建撤销标记：
|
||
|
||
```python
|
||
SSProcess.pushUndoMark("批量属性修改")
|
||
# 执行批量操作...
|
||
```
|
||
|
||
### 4. 及时释放资源
|
||
|
||
对于创建的临时资源（如图幅列表），使用完毕后及时释放：
|
||
|
||
```python
|
||
try:
|
||
SSProcess.createMapFrame()
|
||
# 处理图幅...
|
||
finally:
|
||
SSProcess.freeMapFrame()
|
||
```
|
||
|
||
### 5. 尊重图层锁定状态
|
||
|
||
修改地物前检查图层是否锁定：
|
||
|
||
```python
|
||
layer_name = "DLG"
|
||
if not SSProcess.map.isLayerLock(layer_name):
|
||
# 执行修改操作
|
||
pass
|
||
else:
|
||
print(f"图层 {layer_name} 已锁定，无法编辑")
|
||
```
|
||
|
||
## 与其他文档的关联
|
||
|
||
理解工作空间与地图概念后，可以继续深入学习以下主题：
|
||
|
||
- **选择集与查询**：[清除与初始化选择集](11-qing-chu-yu-chu-shi-hua-xuan-ze-ji) 了解如何在地图中查询和选择地物
|
||
- **地理对象编辑**：[创建默认地物对象](19-chuang-jian-mo-ren-di-wu-dui-xiang) 学习如何在工作空间和地图中创建地物
|
||
- **项目与工作流**：[获取工作空间信息](34-huo-qu-gong-zuo-kong-jian-xin-xi) 探索更多工作空间信息获取方法
|
||
- **Mixin 设计模式**：[Mixin 设计模式](9-mixin-she-ji-mo-shi) 理解 ProjectMixin 等模块的设计理念
|
||
|
||
通过掌握工作空间与地图的核心概念，您将能够更高效地使用 sunvpy 库进行二次开发，构建功能强大的地理信息处理脚本。 |