cesmGUITools 安装、配置与运行报告

0. 最小复现流程

powershell

# 1. 初始化一次；随后关闭并重新打开 PowerShell
conda init powershell

# 2. 添加历史通道
conda config --add channels https://repo.anaconda.com/pkgs/free

# 3. 创建环境
conda create -n cesmGUI_py27 python=2.7
conda activate cesmGUI_py27

# 4. 安装依赖
conda install numpy=1.9.2 matplotlib=1.4.3 basemap=1.0.7 pyqt=4
conda install -c conda-forge netcdf4=1.3.1

# 5. 配置项目路径
$env:PYTHONPATH = "D:\Documents"
Set-Location "D:\Documents\cesmGUITools"

# 6. 建立工作副本
New-Item -ItemType Directory -Force work
Copy-Item "origin\PIdefault.pop.gx3v7_gridinfo.nc" "work\PIdefault.pop.gx3v7_gridinfo.nc"

# 7. 启动已经适配 origin 数据的 KMTEditor
python editors\KMTEditor.py "work\PIdefault.pop.gx3v7_gridinfo.nc" -s 60

1. 项目结构

text

cesmGUITools/
├── README.md
├── __init__.py
├── editors/
│   ├── TopoEditor.py
│   ├── KMTEditor.py
│   ├── RMaskEditor.py
│   └── resources/
├── utilities/
│   ├── __init__.py
│   ├── nccopy.py
│   └── topoutils.py
├── origin/                 # 原始 POP 网格文件，只读保留
├── work/                   # 建议用于编辑的工作副本
└── figure/
    ├── KMTEditor_run.png
    └── RMaskEditor_run.png

程序	设计用途	对 origin 数据的适用性
KMTEditor.py	编辑 POP 海洋有效垂向层数 KMT	适用，当前已完成必要适配
RMaskEditor.py	用套索批量编辑海洋区域编号	适用，但还存在部分问题
TopoEditor.py	编辑规则经纬度上的任意二维地理场	不适用于当前二维 POP 曲线网格

2. 安装流程

2.1 初始化 Conda

如果 PowerShell 尚不能使用 conda activate，先执行：

powershell

conda init powershell

执行后必须关闭当前 PowerShell，再打开一个新窗口。否则可能仍出现：

text

CondaError: Run 'conda init' before 'conda activate'

2.2 添加历史 `free` 通道

新版本 Conda 已移除 restore_free_channel 配置项，因此下面的旧命令会报错，不应再使用：

powershell

conda config --set restore_free_channel true

正确做法是显式添加历史通道：

powershell

conda config --add channels https://repo.anaconda.com/pkgs/free
conda config --show channels

期望至少看到：

yaml

channels:
  - https://repo.anaconda.com/pkgs/free
  - defaults

首次访问 Anaconda 官方通道时，Conda 可能要求接受服务条款（Terms of Service），按提示输入 a 接受即可。

2.3 创建 Python 2.7 环境

根据 README.md 中的环境要求，项目需要的各库所需环境为 Python 2.7 或 Python 3.4，用 Python 3.4 安装时遇到了 basemap=1.0.7 要求 Python 2.7、netcdf4=1.1.7 在 conda-forge 频道中不存在的问题，因此选定 Python 2.7 作为环境 Python 版本。

powershell

conda create -n cesmGUI_py27 python=2.7
conda activate cesmGUI_py27
python --version

本机实际版本为 Python 2.7.13。

2.4 安装依赖

先安装相互绑定的旧版图形依赖：

powershell

conda install numpy=1.9.2 matplotlib=1.4.3 basemap=1.0.7 pyqt=4

再从 conda-forge 安装已验证可用的 netCDF4：

powershell

conda install -c conda-forge netcdf4=1.3.1

README 中记录的 netcdf4=1.1.7 无法安装，该版本在当前通道元数据中无法解析。1.3.1 版本已在本机与 Python 2.7 下完成导入和数据读取验证。

2.5 验证依赖

powershell

python -c "import sys,numpy,matplotlib,netCDF4; from mpl_toolkits import basemap; from PyQt4.QtCore import QT_VERSION_STR,PYQT_VERSION_STR; print(sys.version); print('numpy='+numpy.__version__); print('matplotlib='+matplotlib.__version__); print('basemap='+basemap.__version__); print('netCDF4='+netCDF4.__version__); print('Qt='+QT_VERSION_STR); print('PyQt='+PYQT_VERSION_STR)"

本机验证结果：

text

Python 2.7.13
numpy=1.9.2
matplotlib=1.4.3
basemap=1.0.7
netCDF4=1.3.1
Qt=4.8.7
PyQt=4.11.4

参考环境描述：

yaml

name: cesmGUI_py27
channels:
  - https://repo.anaconda.com/pkgs/free
  - conda-forge
  - defaults
dependencies:
  - python=2.7
  - numpy=1.9.2
  - matplotlib=1.4.3
  - basemap=1.0.7
  - pyqt=4
  - netcdf4=1.3.1

3. Matplotlib 与 PyQt4 后端

项目使用 FigureCanvasQTAgg，因此 Matplotlib 必须使用 Qt4Agg 和 PyQt4。检查配置：

powershell

python -c "import matplotlib; print(matplotlib.matplotlib_fname()); print(matplotlib.get_backend()); print(matplotlib.rcParams.get('backend.qt4'))"

本机输出为 Qt4Agg 和 PyQt4。如果出现 PySide 与 PyQt4 的 QWidget.setParent 类型冲突，在 matplotlibrc 中确认：

ini

backend      : Qt4Agg
backend.qt4  : PyQt4

4. 项目包路径配置

源码使用绝对包导入：

python

from cesmGUITools.utilities.topoutils import ...
from cesmGUITools.utilities import nccopy

因此目录名必须是合法且匹配的包名：

text

D:\Documents\cesmGUITools

不要保留下载压缩包产生的 cesmGUITools-publicmaster 名称。项目父目录需要加入 PYTHONPATH：

powershell

$env:PYTHONPATH = "D:\Documents"
Set-Location "D:\Documents\cesmGUITools"

此处 D:\Documents 可更换为任意项目环境，但项目文件目录必须命名为 cesmGUITools 并按此配置环境变量。出现 ImportError: No module named cesmGUITools.utilities.topoutils 时，依次检查：

目录是否确实叫 cesmGUITools；
根目录的 __init__.py 是否存在；
$env:PYTHONPATH 是否包含父目录 D:\Documents；
当前解释器是否来自 cesmGUI_py27。

5. `origin` 数据检查

有效 POP 文件的水平维度为：

text

nlat = 116
nlon = 100

变量	形状	含义/范围
KMT	(116, 100)	T 网格有效海洋垂向层数，0-60，0 表示陆地
KMU	(116, 100)	U 网格有效海洋垂向层数，0-60
REGION_MASK	(116, 100)	海洋区域编号，当前数据范围约 -14 至 11
TLAT, TLONG	(116, 100)	T 网格二维纬度和经度
ULAT, ULONG	(116, 100)	U 网格二维纬度和经度

文件检查结果：

文件	状态
EP_BASclosed.pop.gx3v7_gridinfo.nc	有效
EP_BASopen2000.pop.gx3v7_gridinfo.nc	无效，文件内容全部为 0x00
LP_BASopen250m.pop.gx3v7_gridinfo.nc	有效
PIdefault.pop.gx3v7_gridinfo.nc	有效
PI_ovm.pop.gx3v7_gridinfo.nc	有效

EP_BASopen2000.pop.gx3v7_gridinfo.nc 虽有约 1.35 MB，但所有字节均为零，需要从原始数据源重新复制或生成。

查看文件变量和形状：

powershell

python -c "from netCDF4 import Dataset; f=Dataset(r'origin\PIdefault.pop.gx3v7_gridinfo.nc'); print('\n'.join('%s: dimensions=%s, shape=%s' % (n,v.dimensions,v.shape) for n,v in f.variables.items())); f.close()"

6. 建立工作副本

origin 应作为只读原始数据保存。编辑前复制到 work：

powershell

Set-Location "D:\Documents\cesmGUITools"
New-Item -ItemType Directory -Force work
Copy-Item "origin\PIdefault.pop.gx3v7_gridinfo.nc" "work\PIdefault.pop.gx3v7_gridinfo.nc"

7. 运行 KMTEditor

7.1 当前已应用的兼容修改

原始脚本使用 kmt、ULON 和 latitude/longitude，但 origin 使用 KMT、ULONG 和 nlat/nlon。当前 editors/KMTEditor.py 已修改为，上传附件中的editors/KMTEditor.py已经做好了修改：

python

self.kmt_lons = np.flipud(ncfile.variables["ULONG"][:,:])
okmt = ncfile.createVariable("original_kmt", "f4", ("nlat", "nlon"))
kmtvar = ncfile.variables["KMT"]
mw = KMTEditor(args.fname[0], "KMT", dwx=args.s[0], dwy=args.s[0])

7.2 启动命令

powershell

conda activate cesmGUI_py27
$env:PYTHONPATH = "D:\Documents"
Set-Location "D:\Documents\cesmGUITools"

python editors\KMTEditor.py `
  "work\PIdefault.pop.gx3v7_gridinfo.nc" `
  -s 60

-s 60 表示主窗口一次显示 60 x 60 个网格。程序变量固定为 KMT，无需再提供变量名。

KMTEditor 运行界面

7.3 编辑操作

按键	功能
方向键	移动当前网格光标
H/J/K/L	向左/下/上/右移动整个视窗
=	聚焦数值输入框，输入后按 Enter
C	复制当前单元格值
V	粘贴复制值
A	使用周围有效网格的平均值
M	聚焦配色选择器
Esc	返回主网格焦点
Ctrl+S	保存
F1	显示 About 信息

KMT 值必须是 0-60 的整数：0 表示陆地，1-60 表示有效海洋垂向层数。

7.4 保存结果

输入文件 work\PIdefault.pop.gx3v7_gridinfo.nc 默认保存为 work\PIdefault_fixed.nc。输出文件包含修改后的 KMT、original_kmt、changes 修改记录以及 history、input_file、created 等属性。

如果输出文件已存在，程序会询问是否覆盖。建议每次编辑前备份或使用新输出名。

8. 运行 RMaskEditor

8.1 启动前检查

激活环境后，必须在同一个 PowerShell 会话中把项目父目录加入 PYTHONPATH：

powershell

conda activate cesmGUI_py27
$env:PYTHONPATH = "D:\Documents"
Set-Location "D:\Documents\cesmGUITools"

注意此处应设置为项目父目录 D:\Documents，与项目目录本身 D:\Documents\cesmGUITools 不同。验证包导入：

powershell

python -c "import cesmGUITools.utilities; print('import OK')"

期望输出：

text

import OK

8.2 启动和编辑

已验证的启动命令：

powershell

python editors\RMaskEditor.py `
  "work\PIdefault.pop.gx3v7_gridinfo.nc" `
  -s 60

其中 -s 60 表示主编辑窗口一次显示 60 x 60 个网格。

主要操作：

操作	功能
方向键	移动当前网格光标
H/J/K/L	向左/下/上/右移动整个视窗
鼠标按住并拖动	绘制套索，批量选择海洋网格
松开鼠标	弹出区域编号输入框
=	聚焦单格数值输入框
C / V	复制/粘贴当前格点值
M	聚焦配色选择器
Esc	返回主网格焦点
Ctrl+S	保存到输出文件
F1	显示 About 信息

套索编辑流程：

在主网格中按住鼠标并拖动形成套索；
松开鼠标；
输入海洋区域编号；
确认后，选中海洋网格的值会立即更新；
使用 Ctrl+S 保存。

这些数据中 REGION_MASK == 0 与 KMT == 0 完全对应，因此零值陆地区域会被遮罩，套索只修改未遮罩的海洋格点。

8.3 保存行为

保存时，程序先通过 nccopy 复制输入文件，再把编辑结果写入输出文件的 REGION_MASK，不会直接修改输入文件。

对于：

text

work\PIdefault.pop.gx3v7_gridinfo.nc

默认候选输出名为：

text

work\PIdefault_fixed.nc

当前保存对话逻辑可能仍要求输入另一个输出文件名；应选择 work 目录中的新文件，并避免覆盖 origin 中的原始数据。

9. 运行 TopoEditor

一般格式：

powershell

python editors\TopoEditor.py <NetCDF文件> <二维变量名> [-s 窗口大小] [--scale 缩放]

示例：

powershell

python editors\TopoEditor.py `
  "D:\data\topography.nc" `
  "PHIS" `
  -s 80 `
  --scale 0.001

输入文件必须包含二维编辑变量，以及下列一维坐标之一：

text

经度：longitudes / longitude / lons
纬度：latitudes  / latitude  / lats

origin 文件的坐标是二维 TLAT/TLONG 或 ULAT/ULONG，因此不能直接使用 TopoEditor。支持 POP 曲线网格需要重写坐标读取、预览地图、点击定位和视窗范围绘制逻辑。

TopoEditor 保存时会要求输入变量名，并把结果写回原 NetCDF 文件。若输入已有变量名会覆盖该变量，因此运行前务必复制工作文件。

10. 常见错误与解决方法

10.1 Python 3.4 环境配置失败

text

basemap-1.0.7-... requires python 2.7
netcdf4 =1.1.7 does not exist
python=3.4 conflicts with installable versions

原因：Windows 上可解析的 Basemap 1.0.7 构建绑定 Python 2.7，而指定的 netCDF4 1.1.7 不存在。解决方法是放弃 Python 3.4 环境，使用 Python 2.7。

10.2 `restore_free_channel` unknown parameter

text

CondaKeyError: 'restore_free_channel': unknown parameter

新版本 Conda 已删除该配置。改用：

powershell

conda config --add channels https://repo.anaconda.com/pkgs/free

10.3 `conda activate` 提示先运行 `conda init`

powershell

conda init powershell

随后关闭并重新打开 PowerShell，不能只在原窗口重复激活。

10.4 找不到 `cesmGUITools.utilities`

确保项目路径为 D:\Documents\cesmGUITools，并执行：

powershell

$env:PYTHONPATH = "D:\Documents"

10.5 TopoEditor 参数不足

text

TopoEditor.py: error: too few arguments

这说明导入已经成功，但缺少文件名和变量名：

powershell

python editors\TopoEditor.py "D:\data\topography.nc" "PHIS"

10.6 `README` 的 `--help` 不可用

三个编辑器均设置 add_help=False，因此 README 所说的 --help 与当前源码不符。不带参数运行会打印 usage 提示，随后以参数不足结束。

cesmGUITools 安装、配置与运行报告 ​

0. 最小复现流程 ​

1. 项目结构 ​

2. 安装流程 ​

2.1 初始化 Conda ​

2.2 添加历史 free 通道 ​

2.3 创建 Python 2.7 环境 ​

2.4 安装依赖 ​

2.5 验证依赖 ​

3. Matplotlib 与 PyQt4 后端 ​

4. 项目包路径配置 ​

5. origin 数据检查 ​

6. 建立工作副本 ​

7. 运行 KMTEditor ​

7.1 当前已应用的兼容修改 ​

7.2 启动命令 ​

7.3 编辑操作 ​

7.4 保存结果 ​

8. 运行 RMaskEditor ​

8.1 启动前检查 ​

8.2 启动和编辑 ​

8.3 保存行为 ​

9. 运行 TopoEditor ​

10. 常见错误与解决方法 ​

10.1 Python 3.4 环境配置失败 ​

10.2 restore_free_channel unknown parameter ​

10.3 conda activate 提示先运行 conda init ​

10.4 找不到 cesmGUITools.utilities ​

10.5 TopoEditor 参数不足 ​

10.6 README 的 --help 不可用 ​

cesmGUITools 安装、配置与运行报告

0. 最小复现流程

1. 项目结构

2. 安装流程

2.1 初始化 Conda

2.2 添加历史 `free` 通道

2.3 创建 Python 2.7 环境

2.4 安装依赖

2.5 验证依赖

3. Matplotlib 与 PyQt4 后端

4. 项目包路径配置

5. `origin` 数据检查

6. 建立工作副本

7. 运行 KMTEditor

7.1 当前已应用的兼容修改

7.2 启动命令

7.3 编辑操作

7.4 保存结果

8. 运行 RMaskEditor

8.1 启动前检查

8.2 启动和编辑

8.3 保存行为

9. 运行 TopoEditor

10. 常见错误与解决方法

10.1 Python 3.4 环境配置失败

10.2 `restore_free_channel` unknown parameter

10.3 `conda activate` 提示先运行 `conda init`

10.4 找不到 `cesmGUITools.utilities`

10.5 TopoEditor 参数不足

10.6 `README` 的 `--help` 不可用