简介：面向使用 PyQt5 与 pyqtgraph 开发图像显示工具的 Python 开发者，尤其是需要处理超大遥感影像、SAR 影像而遭遇界面卡顿的工程人员。资源围绕「瓦片分割 + QGraphicsItem 循环加载」的思路，将大图切分为小块后分片渲染，并在分片基础上实现缩放、平移、范围选取与点选取，可展示普通图片、遥感影像与 SAR 影像，支持图层切换，还附带若干图像质量评价工具。压缩包共 194 个文件，以 88 个 py 源码与 72 个 pyc 编译文件为主体，另有 22 个 png 界面图标、3 个 qrc 资源文件及少量 m 脚本、spec 打包配置等，整体约 2.52MB，结构紧凑便于直接运行与二次改造。已有 1788 人学习下载，适合想参考大图分片渲染与交互实现细节的中级开发者对照研读。

1. 遥感影像加载卡成幻灯片？这套 PyQt5 + pyqtgraph 方案值得拆

去年帮某实验室做一个遥感影像标注工具，需求很朴素：打开一张 2 万像素见方的 SAR 影像，能缩放、能平移、能叠加标注层。我一开始用 QGraphicsView 直接塞 QPixmap，结果 4 万像素的图一加载，内存直接飙到 3 个 G，鼠标滚轮一滚，界面卡成 PPT。后来换成 pyqtgraph 的 ImageView，配合分块加载和 LOD 策略，同样的图内存压到 400M 以内，缩放平移丝滑得像本地看图软件。这套 PyQt5 + pyqtgraph 的组合，核心解决的就是超大栅格影像在桌面端的交互展示问题——遥感影像、SAR 影像、航拍正射图都吃这一套。适合谁？做 GIS 桌面工具、遥感标注平台、影像质检系统的 Python 开发者，尤其是那些不想上 WebGIS 全家桶、只想用纯 Python 快速出活的人。

2. 技术选型与整体架构：为什么是 PyQt5 + pyqtgraph 而不是 QGraphicsView

2.1 三个候选方案的横向对比

在动手写代码之前，先把选型逻辑讲清楚，不然后面改起来全是坑。桌面端展示超大影像，常见三条路：纯 QGraphicsView、OpenCV + QLabel 手动绘制、pyqtgraph 的 ImageView / GraphicsLayoutWidget。我拿一张 30000×30000 的 8bit 单波段影像做过粗略对比：

QGraphicsView 的问题在于它把整张图当一个大 QPixmap 塞进场景，Qt 内部会做一次全量纹理上传，图一大就爆。OpenCV 方案灵活但坐标变换、鼠标事件、缩放锚点全得自己写，维护成本高。pyqtgraph 底层用 QGraphicsScene 但做了视图裁剪和自动降采样，ImageView 自带坐标轴、直方图、ROI，省掉大量胶水代码。

2.2 整体模块划分

这套方案我一般拆成四层，职责清晰，后面加功能不打架：

• 数据层：负责影像读取，用 rasterio 或 GDAL 打开文件，拿到波段数组和地理变换参数。大图不一次性读全，按窗口分块读。
• 缓存层：维护一个金字塔（pyramid）结构，预生成多级降采样缩略图，缩放时按当前视口选层级。
• 视图层：pyqtgraph 的 ImageView 或自定义 GraphicsLayoutWidget，挂载图像项、坐标轴、ROI 标注。
• 交互层：鼠标滚轮缩放、拖拽平移、双击复位，事件绑定在视图的 ViewBox 上。

目录结构大概长这样，方便你对照自己的项目改：

image_viewer/ ├── main.py # 入口，QApplication 启动 ├── core/ │ ├── reader.py # rasterio 分块读取 │ ├── pyramid.py # 金字塔构建与缓存 │ └── transform.py # 像素坐标 <-> 地理坐标 ├── ui/ │ ├── main_window.py # 主窗口布局 │ ├── image_view.py # pyqtgraph 视图封装 │ └── toolbar.py # 缩放/复位/图层按钮 └── utils/ └── config.py # 分块大小、缓存上限等参数

2.3 关键依赖与版本约束

依赖不多，但版本要对齐，不然 pyqtgraph 和 PyQt5 的 API 对不上会报一堆 AttributeError。我一般锁这几个：

pip install PyQt5==5.15.9 pyqtgraph==0.13.3 rasterio==1.3.9 numpy==1.24.4

pyqtgraph 0.13.x 对 PyQt5 5.15 的兼容性最稳，rasterio 负责读 GeoTIFF 和 SAR 常见的复数影像。numpy 别上 2.x，部分老版本 rasterio 编译的 wheel 会崩。这些版本号不是拍脑袋，是我在三个项目里踩过兼容性坑之后固定下来的组合。

3. 核心模块拆解：分块读取、金字塔缓存与视图渲染

3.1 分块读取：别把 3 万像素的图一次性塞进内存

超大影像的第一个坎是读取。rasterio 支持按窗口读，核心思路是只读当前视口对应的像素区域，视口外的数据不碰。下面这段是 reader.py 的核心：

import rasterio from rasterio.windows import Window import numpy as np class TiledReader: def __init__(self, path, block_size=2048): self.ds = rasterio.open(path) self.block_size = block_size self.width = self.ds.width self.height = self.ds.height def read_window(self, col_off, row_off, width, height, band=1): # 窗口裁剪，防止越界 col_off = max(0, min(col_off, self.width - 1)) row_off = max(0, min(row_off, self.height - 1)) width = min(width, self.width - col_off) height = min(height, self.height - row_off) window = Window(col_off, row_off, width, height) # 只读指定波段，masked=False 避免返回掩膜数组拖慢速度 data = self.ds.read(band, window=window, masked=False) return data def close(self): self.ds.close()

block_size默认 2048，意思是每次最多读 2048×2048 的块。这个值不是随便定的：太小会导致频繁 IO，太大又失去分块意义。我一般按影像总像素和可用内存估算，3 万像素的图用 2048 比较均衡。read_window里做了边界裁剪，因为视口拖到边缘时算出来的窗口可能超出影像范围，不裁会抛 WindowError。masked=False是个小细节，rasterio 默认返回 masked array，多一层包装，pyqtgraph 渲染时还得转回普通 ndarray，直接关掉省事。

3.2 金字塔缓存：缩放不卡的关键

分块读取解决了内存，但缩放时如果每次都重新读全分辨率数据再降采样，照样卡。金字塔的思路是预生成几级缩略图，缩放时按当前缩放比例选最接近的层级。构建逻辑：

import numpy as np class PyramidCache: def __init__(self, reader, levels=4, max_cache_mb=512): self.reader = reader self.levels = levels self.cache = {} self.max_cache_bytes = max_cache_mb * 1024 * 1024 self.current_bytes = 0 def get_level_data(self, level): if level in self.cache: return self.cache[level] # 第 0 级是全分辨率，逐级 2 倍降采样 factor = 2 ** level w = max(1, self.reader.width // factor) h = max(1, self.reader.height // factor) # 按块读取后做均值降采样，避免直接切片丢细节 data = self.reader.read_window(0, 0, self.reader.width, self.reader.height) for _ in range(level): data = data[::2, ::2] self._put_cache(level, data) return data def _put_cache(self, level, data): nbytes = data.nbytes # 超上限就清掉最老的层级 while self.current_bytes + nbytes > self.max_cache_bytes and self.cache: old_key = next(iter(self.cache)) self.current_bytes -= self.cache[old_key].nbytes del self.cache[old_key] self.cache[level] = data self.current_bytes += nbytes

levels=4意味着最多 4 级缩略，对应 1/2、1/4、1/8、1/16 分辨率。实际项目里我一般按影像尺寸动态算，保证最顶层缩略图不超过 2048 像素宽。max_cache_mb控制缓存上限，超了就按插入顺序淘汰最老的层级——这里用的是简易 FIFO，够用，真要精细可以换 LRU。降采样用data[::2, ::2]是隔点取样，速度快但会有锯齿，对精度要求高的场景可以换成块均值，代价是构建慢一点。

3.3 视图渲染：pyqtgraph ImageView 的正确挂法

视图层用 pyqtgraph 的 ImageView，它自带坐标轴、直方图调节、ROI 支持。核心封装：

import pyqtgraph as pg from PyQt5.QtWidgets import QWidget, QVBoxLayout class ImageViewWidget(QWidget): def __init__(self, parent=None): super().__init__(parent) self.layout = QVBoxLayout(self) # 关掉默认的自动降采样，我们自己控制层级 pg.setConfigOptions(imageAxisOrder='row-major') self.view = pg.ImageView() self.view.ui.roiBtn.hide() self.view.ui.menuBtn.hide() self.layout.addWidget(self.view) def show_image(self, data): # autoLevels=False 避免每次渲染重算直方图拖慢大图 self.view.setImage(data, autoLevels=False) def set_levels(self, min_val, max_val): self.view.setLevels(min_val, max_val)

imageAxisOrder='row-major'很关键，rasterio 读出来的数组是 (row, col) 即 (y, x)，pyqtgraph 默认按 (x, y) 解释，不设这个参数图像会转 90 度。autoLevels=False是性能开关，大图每次自动算直方图很耗时，改成手动setLevels控制对比度。roiBtn和menuBtn隐藏掉是因为默认 UI 对遥感场景太花哨，实际项目里我会自己写工具栏替代。

3.4 交互绑定：滚轮缩放与拖拽平移

pyqtgraph 的 ViewBox 默认就支持滚轮缩放和拖拽平移，但默认行为有几个不顺手的地方：缩放锚点不在鼠标位置、双击不复位。我一般重写 ViewBox：

class CustomViewBox(pg.ViewBox): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) self.setMouseMode(pg.ViewBox.PanMode) def wheelEvent(self, ev, axis=None): # 以鼠标位置为锚点缩放 scale = 1.1 if ev.delta() > 0 else 1 / 1.1 center = self.mapToView(ev.pos()) self.scaleBy((scale, scale), center) ev.accept() def mouseDoubleClickEvent(self, ev): # 双击复位到全图 self.autoRange() ev.accept()

mapToView(ev.pos())把鼠标屏幕坐标转成视图坐标，作为缩放锚点，这样滚轮缩放时鼠标下的像素点不动，符合看图习惯。scaleBy的第二个参数就是锚点。双击调autoRange()复位。这段代码不长，但交互手感全靠它，建议直接抄。

4. 从零跑起来：环境搭建、影像加载与第一个可交互窗口

4.1 环境准备与依赖安装

先确认 Python 版本，3.9 到 3.11 都行，3.12 部分 rasterio wheel 还没跟上。建虚拟环境后装依赖：

python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install PyQt5==5.15.9 pyqtgraph==0.13.3 rasterio==1.3.9 numpy==1.24.4

装完跑一句python -c "import rasterio; print(rasterio.__version__)"验证，能打印版本号就说明 GDAL 底层库链接正常。rasterio 的 wheel 自带 GDAL，一般不用单独装，但如果你在 ARM 机器或老系统上，可能需要从源码编译，那就得先装 libgdal-dev。

4.2 最小可运行入口

main.py 把前面几个模块串起来，先跑通一个能加载、能缩放的最小版本：

import sys from PyQt5.QtWidgets import QApplication, QMainWindow from core.reader import TiledReader from core.pyramid import PyramidCache from ui.image_view import ImageViewWidget class MainWindow(QMainWindow): def __init__(self, image_path): super().__init__() self.setWindowTitle("超大影像查看器") self.resize(1200, 800) self.reader = TiledReader(image_path) self.pyramid = PyramidCache(self.reader) self.view = ImageViewWidget() self.setCentralWidget(self.view) # 先加载第 2 级缩略图，快速出图 data = self.pyramid.get_level_data(2) self.view.show_image(data) if __name__ == "__main__": app = QApplication(sys.argv) win = MainWindow("sample_sar.tif") win.show() sys.exit(app.exec_())

启动后先加载第 2 级缩略图（1/4 分辨率），出图快，用户不会盯着白屏等。等交互稳定后再按需加载更高层级，这个策略叫渐进式加载，是遥感工具里的常规做法。sample_sar.tif换成你自己的影像路径，GeoTIFF、ENVI、复数 SAR 的 SLC 数据 rasterio 都能读。

4.3 验证清单：跑通后先检查这几项

窗口起来之后别急着加功能，先按这个清单过一遍，能省掉后面大量排查时间：

• 图像方向对不对：如果 SAR 影像上下颠倒或转了 90 度，回去检查imageAxisOrder和数组维度顺序。
• 缩放锚点准不准：鼠标停在某个地物上滚轮，该地物应该原地放大，如果漂移就是mapToView用错了。
• 内存涨不涨：开任务管理器，反复缩放平移几十次，内存应该稳定在缓存上限附近，持续上涨说明缓存没生效。
• 边缘拖拽崩不崩：把视口拖到影像四角，检查read_window的边界裁剪有没有漏。

这四项过了，基础框架就算立住了，后面加标注、加图层都是在这个骨架上挂东西。

5. 避坑与排查：大图渲染最容易翻车的五个地方

5.1 现象：图像颜色发灰、对比度不对

原因：pyqtgraph 默认按 8bit 显示，但遥感影像常见 16bit 甚至浮点，直接 setImage 会被截断。解决：先做线性拉伸到 0-255，或者用setLevels指定实际数据范围。我一般读数据时顺手算 2% 和 98% 分位数做拉伸，比固定 min/max 稳。

5.2 现象：缩放时图像闪烁、白屏

原因：每次缩放都触发全量重读，主线程被 IO 阻塞。解决：把读取放到 QThread 或 QThreadPool 里，视图先显示低层级缩略图占位，读完再替换。pyqtgraph 的 setImage 本身不阻塞，阻塞的是你喂给它的数据准备过程。

5.3 现象：SAR 复数影像读出来全是噪点

原因：SAR 的 SLC 数据是复数（实部+虚部），rasterio 读出来是 complex64，直接当灰度显示当然不对。解决：先算幅度np.abs(data)或强度np.abs(data)**2，再做对数拉伸20*np.log10(...)，这是 SAR 可视化的标准流程。

5.4 现象：拖拽平移时坐标轴数值跳变

原因：pyqtgraph 的 ViewBox 在 autoRange 状态下会随数据范围动态调整，和手动平移冲突。解决：加载完图像后调一次view.setRange(...)固定初始范围，并关掉 autoRange，坐标轴就稳了。

5.5 现象：程序退出时报 rasterio 句柄未关闭

原因：TiledReader 的 dataset 没在窗口关闭时释放。解决：重写 MainWindow 的 closeEvent，调self.reader.close()。这个坑不致命但很烦，反复开关窗口几次句柄就泄漏了。

6. 二次开发改造：从能看 to 能标注、能量测的工程化路径

基础框架跑通后，真正的工作量在二次开发。我拿一个实际改造过的方向举例：给遥感影像加标注和量测。核心思路是在 ImageView 上叠加自定义 GraphicsObject，利用 pyqtgraph 的坐标系统一管理。

第一步，加一个标注层。pyqtgraph 的 ViewBox 支持 addItem，矩形、多边形都能挂：

from pyqtgraph import RectROI def add_annotation(view, x, y, w, h): roi = RectROI([x, y], [w, h], pen='r') roi.setZValue(10) # 保证标注在图像上层 view.addItem(roi) return roi

setZValue(10)是血泪经验，不加的话标注会被图像盖住，调半天以为没加上。ROI 的坐标是视图坐标，和图像像素坐标一致，前提是前面imageAxisOrder设对了。

第二步，量测功能。量测的本质是把视图坐标转成地理坐标，再算距离。transform.py 里维护一个仿射变换矩阵，从 rasterio 的ds.transform拿：

def pixel_to_geo(transform, col, row): # rasterio 的 transform 是仿射矩阵，直接乘 x, y = transform * (col, row) return x, y

量测时监听鼠标点击，收集两个点，转地理坐标后算欧氏距离。注意 SAR 影像如果是斜距坐标，还得做地理编码才能得到真实地面距离，这一步超出展示层范畴，一般交给后端处理。

第三步，图层管理。多波段、多时相影像叠加时，建议用 GraphicsLayoutWidget 管理多个 ViewBox，每个图层一个 ImageItem，通过 setVisible 控制显隐。别把所有波段塞进一个 RGB 合成图，后期调波段组合会疯。

改造时有个习惯我一直保持：每加一个交互功能，先在最小 demo 上验证坐标变换对不对，再往主工程里合。坐标变换是这类工具最容易出错的地方，像素坐标、视图坐标、地理坐标三套系统混用，一个符号错了图像就偏到天边。从那以后我每次改视图相关代码，都强制走一遍「加载已知坐标的测试图 → 点三个角 → 核对地理坐标」的流程，宁可多花十分钟，也不想到处找 bug。希望帮到你。

本文还有配套的精品资源，点击获取