244 lines
11 KiB
Markdown
244 lines
11 KiB
Markdown
本页面介绍 sunvpy Python 库的安装流程、环境配置要求以及验证方法。sunvpy 是 SunvStation 地理信息系统的官方 Python 脚本接口，通过 SWIG 技术将 C++ 核心功能封装为 Python 模块，为开发者提供高效的二次开发和自动化数据处理能力。
|
||
|
||
Sources: [__init__.py](__init__.py#L1-L5)
|
||
|
||
## 系统要求
|
||
|
||
使用 sunvpy 库需要满足以下软硬件环境要求。下表详细列出了各项配置要求和建议。
|
||
|
||
| 配置项 | 最低要求 | 推荐配置 | 说明 |
|
||
|-------|---------|---------|------|
|
||
| 操作系统 | Windows 7/8.1/10 | Windows 10/11 | sunvpy 目前仅支持 Windows 平台 |
|
||
| Python 版本 | Python 3.8+ | Python 3.10 - 3.13 | 需要与 SunvStation 版本匹配的 Python 版本 |
|
||
| SunvStation | SunvStation 10.0+ | 最新稳定版 | SunvStation 软件本体必须已正确安装 |
|
||
| 磁盘空间 | 100 MB | 200 MB+ | 包含 sunvpy 模块及其依赖库 |
|
||
| 内存 | 2 GB RAM | 4 GB RAM+ | 处理大规模数据集时需要更多内存 |
|
||
| 架构 | x86-64 | x86-64 | 仅支持 64 位操作系统和 Python |
|
||
|
||
Python 版本的选择尤为重要，因为 sunvpy 中的 `.pyd` 扩展模块是编译好的二进制文件，必须与 Python 解释器的版本和位数完全匹配。错误的环境配置会导致模块加载失败。
|
||
|
||
Sources: [PySSCore.py](PySSCore.py#L1-L10)
|
||
|
||
## 安装方法
|
||
|
||
sunvpy 通常作为 SunvStation 安装包的一部分自动安装到 Python 的 site-packages 目录。安装流程可以分为自动安装和手动安装两种方式。
|
||
|
||
### 自动安装
|
||
|
||
自动安装是最推荐的方式，由 SunvStation 安装程序自动完成所有配置工作。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[运行 SunvStation 安装程序] --> B{选择 Python 版本}
|
||
B -->|指定 Python 安装路径| C[安装程序自动检测 Python 环境]
|
||
B -->|使用自带 Python| D[安装程序部署内置 Python 环境]
|
||
C --> E[复制 sunvpy 到 site-packages]
|
||
D --> E
|
||
E --> F[注册环境变量]
|
||
F --> G[创建桌面快捷方式]
|
||
G --> H[完成安装]
|
||
```
|
||
|
||
在安装 SunvStation 时，安装程序会自动检测系统中的 Python 环境，并提示用户选择使用现有的 Python 解释器还是安装 SunvStation 自带的 Python 版本。安装程序会将 sunvpy 包复制到指定 Python 版本的 `Lib\site-packages\sunvpy` 目录下。
|
||
|
||
### 手动安装
|
||
|
||
如果需要手动配置 sunvpy 环境，可以按照以下步骤操作。
|
||
|
||
| 步骤 | 操作 | 详细说明 |
|
||
|-----|------|---------|
|
||
| 1 | 定位安装目录 | 找到 SunvStation 安装目录下的 script 子目录 |
|
||
| 2 | 复制文件 | 将 sunvpy 整个文件夹复制到 Python 的 site-packages 目录 |
|
||
| 3 | 验证依赖 | 确保所有 .pyd 文件和对应的 .py 文件完整 |
|
||
| 4 | 配置环境变量 | 如有需要，添加相关路径到 PATH 环境变量 |
|
||
| 5 | 测试导入 | 运行 Python 测试导入是否成功 |
|
||
|
||
手动安装需要确保所有模块文件完整，包括 Python 封装文件（.py）和 C++ 扩展文件（.pyd）。缺失任何一个文件都可能导致模块功能异常。
|
||
|
||
Sources: [PySSProcess.py](PySSProcess.py#L1-L19)
|
||
|
||
## 环境验证
|
||
|
||
安装完成后，通过以下步骤验证环境配置是否正确。验证过程分为导入测试、功能测试和版本检查三个环节。
|
||
|
||
### 导入测试
|
||
|
||
打开命令行或 Python 解释器，尝试导入 sunvpy 模块。
|
||
|
||
```python
|
||
# 测试基本导入
|
||
import sunvpy
|
||
print(f"sunvpy 版本: {sunvpy.get_version()}")
|
||
|
||
# 测试 SSProcess 导入
|
||
from sunvpy import SSProcess
|
||
print("SSProcess 导入成功")
|
||
```
|
||
|
||
如果导入成功且没有报错，说明基本环境配置正确。如果出现 `ModuleNotFoundError` 或 `ImportError`，请检查 Python 版本匹配和文件完整性。
|
||
|
||
### 功能测试
|
||
|
||
运行一个简单的功能测试脚本，验证核心模块是否正常工作。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[启动功能测试] --> B[导入 SSProcess]
|
||
B --> C{导入成功?}
|
||
C -->|否| D[检查 .pyd 文件完整性]
|
||
C -->|是| E[获取工作空间实例]
|
||
E --> F{工作空间可用?}
|
||
F -->|否| G[检查 SunvStation 许可]
|
||
F -->|是| H[测试地图连接]
|
||
H --> I[输出测试结果]
|
||
D --> J[修复问题后重试]
|
||
G --> J
|
||
```
|
||
|
||
功能测试脚本可以验证 sunvpy 是否能够正确连接到 SunvStation 的核心服务。测试失败通常意味着 SunvStation 主程序未运行或许可证配置有问题。
|
||
|
||
### 版本信息检查
|
||
|
||
通过版本信息确认安装的 sunvpy 版本，确保与 SunvStation 主程序版本兼容。
|
||
|
||
```python
|
||
# 完整版本检查
|
||
import sunvpy
|
||
|
||
print("=" * 50)
|
||
print("sunvpy 环境信息")
|
||
print("=" * 50)
|
||
print(f"模块版本: {sunvpy.__version__}")
|
||
print(f"模块作者: {sunvpy.__author__}")
|
||
print(f"模块描述: {sunvpy.__description__}")
|
||
print("=" * 50)
|
||
|
||
# 检查 SSProcess 实例
|
||
from sunvpy import SSProcess
|
||
|
||
print(f"工作空间实例: {SSProcess.getWorkspace()}")
|
||
print(f"当前地图实例: {SSProcess.getCurrentMap()}")
|
||
```
|
||
|
||
Sources: [__init__.py](__init__.py#L1-L12) [PySSProcess.py](PySSProcess.py#L47-L56)
|
||
|
||
## 常见问题排查
|
||
|
||
在安装和使用过程中可能会遇到一些常见问题。下表列出了典型问题及其解决方案。
|
||
|
||
| 问题现象 | 可能原因 | 解决方案 |
|
||
|---------|---------|---------|
|
||
| `ImportError: DLL load failed` | Python 版本与 .pyd 编译版本不匹配 | 使用与 sunvpy 编译版本相同的 Python 解释器 |
|
||
| `ModuleNotFoundError: No module named 'sunvpy'` | sunvpy 未安装到 site-packages 目录 | 检查安装路径或重新安装 SunvStation |
|
||
| `AttributeError: module has no attribute 'SSProcess'` | PySSProcess.py 文件缺失或损坏 | 重新复制完整的 sunvpy 文件夹 |
|
||
| 程序运行时提示"工作空间不可用" | SunvStation 主程序未运行或许可证问题 | 启动 SunvStation 并检查许可证配置 |
|
||
| SWIG 扩展模块无法加载 | 缺少必要的 VC++ 运行库 | 安装 Microsoft Visual C++ Redistributable |
|
||
| 属性访问异常 | ObjBaseAttr.py 配置文件损坏 | 检查或重新安装属性定义文件 |
|
||
|
||
### 调试技巧
|
||
|
||
当遇到问题时，可以使用以下调试方法定位具体原因。
|
||
|
||
1. **检查模块完整性**：验证所有必要的文件是否存在
|
||
```python
|
||
import os
|
||
sunvpy_path = os.path.dirname(sunvpy.__file__)
|
||
required_files = [
|
||
'PySSCore.py', '_PySSCore.pyd',
|
||
'PySSMap.py', '_PySSMap.pyd',
|
||
'PySSProcess.py', 'ObjBaseAttr.py'
|
||
]
|
||
|
||
for file in required_files:
|
||
full_path = os.path.join(sunvpy_path, file)
|
||
exists = os.path.exists(full_path)
|
||
print(f"{file}: {'✓' if exists else '✗'}")
|
||
```
|
||
|
||
2. **检查 Python 环境信息**：确认 Python 版本和架构
|
||
```python
|
||
import sys
|
||
print(f"Python 版本: {sys.version}")
|
||
print(f"Python 路径: {sys.executable}")
|
||
print(f"架构位数: {'64位' if sys.maxsize > 2**32 else '32位'}")
|
||
```
|
||
|
||
3. **查看详细错误信息**：使用 traceback 模块获取完整堆栈
|
||
```python
|
||
import traceback
|
||
try:
|
||
from sunvpy import SSProcess
|
||
except Exception as e:
|
||
traceback.print_exc()
|
||
```
|
||
|
||
Sources: [PySSCore.py](PySSCore.py#L1-L20) [__init__.py](__init__.py#L1-L12)
|
||
|
||
## 目录结构说明
|
||
|
||
理解 sunvpy 的目录结构有助于调试问题和学习模块组织方式。下表详细说明了目录中各文件的用途。
|
||
|
||
| 文件/目录 | 类型 | 说明 |
|
||
|----------|------|------|
|
||
| `__init__.py` | Python 文件 | 包初始化文件，定义版本信息和导出接口 |
|
||
| `PySSProcess.py` | Python 文件 | SSProcessManager 主类实现，提供统一 API 入口 |
|
||
| `ObjBaseAttr.py` | Python 文件 | 地物基本属性名称索引和类型定义 |
|
||
| `PySS*.py` | Python 文件 | SWIG 生成的 Python 封装文件 |
|
||
| `_PySS*.pyd` | 二进制文件 | 编译好的 C++ 扩展模块 |
|
||
| `ssprocess_mixins/` | 目录 | Mixin 功能模块目录 |
|
||
| `ssprocess_mixins/selection_mixin.py` | Python 文件 | 选择集操作功能实现 |
|
||
| `ssprocess_mixins/geo_edit_mixin.py` | Python 文件 | 地理编辑功能实现 |
|
||
| `ssprocess_mixins/project_mixin.py` | Python 文件 | 工程管理功能实现 |
|
||
| `ssprocess_mixins/log_mixin.py` | Python 文件 | 日志记录功能实现 |
|
||
| `ssprocess_mixins/progress_mixin.py` | Python 文件 | 进度管理功能实现 |
|
||
|
||
目录结构体现了 sunvpy 的分层设计理念。顶层目录包含所有对外暴露的模块，`ssprocess_mixins` 子目录包含内部实现细节，通过 Mixin 模式组织功能，提高了代码的可维护性和扩展性。
|
||
|
||
Sources: [PySSProcess.py](PySSProcess.py#L21-L26) [ssprocess_mixins/project_mixin.py](ssprocess_mixins/project_mixin.py#L1-L50)
|
||
|
||
## 环境配置最佳实践
|
||
|
||
遵循以下最佳实践可以避免大多数环境配置问题，提高开发效率。
|
||
|
||
| 实践 | 说明 | 收益 |
|
||
|-----|------|------|
|
||
| 使用虚拟环境 | 为每个项目创建独立的 Python 虚拟环境 | 避免依赖冲突，便于环境隔离 |
|
||
| 版本固定 | 在项目中记录使用的 Python 版本 | 确保团队环境一致，减少兼容性问题 |
|
||
| 定期备份 | 备份 sunvpy 安装目录和相关配置 | 快速恢复损坏的环境 |
|
||
| 文档记录 | 记录安装步骤和配置细节 | 便于团队共享和问题排查 |
|
||
| 测试驱动 | 编写自动化测试脚本验证环境 | 提前发现问题，提高环境可靠性 |
|
||
|
||
### 推荐开发环境设置
|
||
|
||
对于开发团队，建议使用以下环境配置流程。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[创建虚拟环境] --> B[安装 SunvStation]
|
||
B --> C[配置 Python 路径]
|
||
C --> D[验证 sunvpy 导入]
|
||
D --> E[运行环境测试脚本]
|
||
E --> F{测试通过?}
|
||
F -->|否| G[检查错误日志]
|
||
F -->|是| H[保存环境配置]
|
||
G --> I[修复配置问题]
|
||
I --> D
|
||
H --> J[开始开发工作]
|
||
```
|
||
|
||
虚拟环境可以通过 `venv` 或 `conda` 创建，确保每个项目都有独立且一致的运行环境。测试脚本应该包含基本导入测试、功能测试和性能基准测试，在环境配置完成后立即运行。
|
||
|
||
Sources: [PySSProcess.py](PySSProcess.py#L124-L140)
|
||
|
||
## 下一步学习
|
||
|
||
完成环境配置后，建议按照以下学习路径深入掌握 sunvpy 的使用方法。
|
||
|
||
- [第一个脚本：查询地物属性](3-di-ge-jiao-ben-cha-xun-di-wu-shu-xing) — 学习编写第一个实用的 sunvpy 脚本，掌握地物属性查询的基本操作
|
||
- [使用 SSProcess 管理选择集](4-shi-yong-ssprocess-guan-li-xuan-ze-ji) — 深入了解选择集的概念和操作方法
|
||
- [运行内置示例脚本](5-yun-xing-nei-zhi-shi-li-jiao-ben) — 通过实际案例学习常用 API 的组合使用
|
||
|
||
对于想要理解 sunvpy 底层原理的开发者，可以继续阅读：
|
||
- [SunvStation 系统架构](6-sunvstation-xi-tong-jia-gou) — 了解整个系统的架构设计
|
||
- [SWIG 封装机制说明](7-swig-feng-zhuang-ji-zhi-shuo-ming) — 深入理解 Python 与 C++ 的交互机制
|
||
- [Mixin 设计模式](9-mixin-she-ji-mo-shi) — 学习代码组织和功能扩展的设计思想 |