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