sunvpy-docs/docs/content/2-an-zhuang-yu-huan-jing-pei-zhi.md

本页面介绍 sunvpy Python 库的安装流程、环境配置要求以及验证方法。sunvpy 是 SunvStation 地理信息系统的官方 Python 脚本接口，通过 SWIG 技术将 C++ 核心功能封装为 Python 模块，为开发者提供高效的二次开发和自动化数据处理能力。

Sources: init.py

系统要求

使用 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

安装方法

sunvpy 通常作为 SunvStation 安装包的一部分自动安装到 Python 的 site-packages 目录。安装流程可以分为自动安装和手动安装两种方式。

自动安装

自动安装是最推荐的方式，由 SunvStation 安装程序自动完成所有配置工作。

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

环境验证

安装完成后，通过以下步骤验证环境配置是否正确。验证过程分为导入测试、功能测试和版本检查三个环节。

导入测试

打开命令行或 Python 解释器，尝试导入 sunvpy 模块。

# 测试基本导入
import sunvpy
print(f"sunvpy 版本: {sunvpy.get_version()}")

# 测试 SSProcess 导入
from sunvpy import SSProcess
print("SSProcess 导入成功")

如果导入成功且没有报错，说明基本环境配置正确。如果出现 ModuleNotFoundError 或 ImportError，请检查 Python 版本匹配和文件完整性。

功能测试

运行一个简单的功能测试脚本，验证核心模块是否正常工作。

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 主程序版本兼容。

# 完整版本检查
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 PySSProcess.py

常见问题排查

在安装和使用过程中可能会遇到一些常见问题。下表列出了典型问题及其解决方案。

问题现象	可能原因	解决方案
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. 检查模块完整性：验证所有必要的文件是否存在

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 版本和架构

import sys
print(f"Python 版本: {sys.version}")
print(f"Python 路径: {sys.executable}")
print(f"架构位数: {'64位' if sys.maxsize > 2**32 else '32位'}")

3. 查看详细错误信息：使用 traceback 模块获取完整堆栈

import traceback
try:
    from sunvpy import SSProcess
except Exception as e:
    traceback.print_exc()

Sources: PySSCore.py init.py

目录结构说明

理解 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 ssprocess_mixins/project_mixin.py

环境配置最佳实践

遵循以下最佳实践可以避免大多数环境配置问题，提高开发效率。

实践	说明	收益
使用虚拟环境	为每个项目创建独立的 Python 虚拟环境	避免依赖冲突，便于环境隔离
版本固定	在项目中记录使用的 Python 版本	确保团队环境一致，减少兼容性问题
定期备份	备份 sunvpy 安装目录和相关配置	快速恢复损坏的环境
文档记录	记录安装步骤和配置细节	便于团队共享和问题排查
测试驱动	编写自动化测试脚本验证环境	提前发现问题，提高环境可靠性

推荐开发环境设置

对于开发团队，建议使用以下环境配置流程。

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

下一步学习

完成环境配置后，建议按照以下学习路径深入掌握 sunvpy 的使用方法。

• 第一个脚本：查询地物属性 — 学习编写第一个实用的 sunvpy 脚本，掌握地物属性查询的基本操作
• 使用 SSProcess 管理选择集 — 深入了解选择集的概念和操作方法
• 运行内置示例脚本 — 通过实际案例学习常用 API 的组合使用

对于想要理解 sunvpy 底层原理的开发者，可以继续阅读：

• SunvStation 系统架构 — 了解整个系统的架构设计
• SWIG 封装机制说明 — 深入理解 Python 与 C++ 的交互机制
• Mixin 设计模式 — 学习代码组织和功能扩展的设计思想