Pyqtgraph ImageView问题：ImageItem初始显示在ViewBox可视区域外

开发PyQt GUI程序时，需要展示相机采集的长水平ROI画面。基于pyqtgraph的ImageView搭配ViewBox、ImageItem编写了自定义显示控件，把控件放入GUI布局的受限空间（最大高度设为100）后出现显示异常：窗口初次打开时相机画面不在可视区域内，整体偏移到视口偏下的外侧位置，只有手动拖动调整窗口大小后，图像才会正常居中显示。

class CameraViewerWidget(QWidget):
    def __init__(self, parent=None):
        super().__init__(parent=parent)
        self.viewport = GraphicsLayoutWidget()
        self.view = self.viewport.addViewBox(lockAspect=False, enableMenu=True)
        self.img = pg.ImageItem()
        self.view.addItem(self.img)
        self.imv = pg.ImageView(view=self.view, imageItem=self.img)
        layout = self.layout()
        layout.addWidget(self.imv)
    def update_image(self, image, auto_range=True, auto_histogram_range=False):
        self.imv.setImage(image, autoRange=auto_range, autoHistogramRange=auto_histogram_range)

控件通过addWidget()方法加入主GUI布局，update_image()由QTimer定时触发实现相机画面实时刷新。
已尝试过修改auto_range参数、调用ViewBox的setLimits()/setRange()方法，都没有解决问题。初步猜测是尺寸受限时ImageView无法正确感知实际可用空间，但不确定如何验证，同时对pyqtgraph的多套坐标系逻辑不熟悉，需要排查代码错误或找到同类问题的解决方案。

代码存在两个核心错误，共同导致首次加载时视口范围计算错位：

1. 自定义QWidget没有初始化布局，直接调用self.layout()会返回空值，本身就会导致布局渲染逻辑异常
2. 冗余创建了独立的GraphicsLayoutWidget和ViewBox实例：pg.ImageView本身已经内置了完整的视图组件和ViewBox，额外创建的视图实例没有被加入布局层级，传递给ImageView后会造成组件树层级混乱。首次窗口渲染时，ViewBox读取的是控件未受布局约束时的默认尺寸，等布局完成、控件实际尺寸被限制为最大高度100后，没有触发视口范围自动重算，最终图像偏移到可视区域外。手动resize窗口时会触发组件的resize事件，连带触发ViewBox的自动范围校准，所以调整大小后显示就恢复正常。

最简修正（无额外图元需求时使用） #

直接使用ImageView内置的视图组件，补全布局初始化逻辑即可：

import pyqtgraph as pg
from PyQt5.QtWidgets import QWidget, QVBoxLayout

class CameraViewerWidget(QWidget):
    def __init__(self, parent=None):
        super().__init__(parent=parent)
        # 初始化当前控件的布局，清除默认边距避免空间浪费
        layout = QVBoxLayout(self)
        layout.setContentsMargins(0, 0, 0, 0)
        # 直接初始化ImageView，不需要额外创建GraphicsLayoutWidget和ViewBox
        self.imv = pg.ImageView()
        layout.addWidget(self.imv)
        # 直接取ImageView内置的ViewBox和ImageItem使用
        self.view = self.imv.view
        self.img = self.imv.imageItem
        # 关闭宽高比锁定，适配长条形ROI显示
        self.view.setAspectLocked(False)
        
    def update_image(self, image, auto_range=True, auto_histogram_range=False):
        self.imv.setImage(
            image, 
            autoRange=auto_range, 
            autoHistogramRange=auto_histogram_range
        )

保留自定义ViewBox的修正（需要叠加其他图元时使用） #

如果需要在同一个视图中叠加其他图元、必须手动创建ViewBox，除了补全布局逻辑外，还要在控件首次显示、尺寸变化时主动触发视口范围校准，注意不要在刷新图像的高频逻辑里无差别调用autoRange，否则会导致鼠标拖拽缩放失效：

import pyqtgraph as pg
from PyQt5.QtWidgets import QWidget, QVBoxLayout

class CameraViewerWidget(QWidget):
    def __init__(self, parent=None):
        super().__init__(parent=parent)
        layout = QVBoxLayout(self)
        layout.setContentsMargins(0, 0, 0, 0)
        self.viewport = pg.GraphicsLayoutWidget()
        self.view = self.viewport.addViewBox(lockAspect=False, enableMenu=True)
        self.img = pg.ImageItem()
        self.view.addItem(self.img)
        self.imv = pg.ImageView(view=self.view, imageItem=self.img)
        layout.addWidget(self.imv)

    def showEvent(self, event):
        super().showEvent(event)
        # 控件首次显示时强制校准一次视口范围
        self.view.autoRange()

    def resizeEvent(self, event):
        super().resizeEvent(event)
        # 控件尺寸变化时同步校准视口
        self.view.autoRange()
        
    def update_image(self, image, auto_range=True, auto_histogram_range=False):
        self.imv.setImage(
            image, 
            autoRange=auto_range, 
            autoHistogramRange=auto_histogram_range
        )

内容的提问来源于stack exchange，提问作者jmschr