Autoware Universe - rqt_bag 匯入 .db3 影像外掛失敗

問題回報與完整解法

---

1. 環境資訊

項目	內容
OS	Ubuntu 22.04 LTS (jammy)
ROS 2	Humble Hawksbill (ros-humble-desktop-full 2025-07-19 build)
rqt_bag	ros-humble-rqt-bag 1.1.5、ros-humble-rqt-bag-plugins 1.1.5
Python	3.10 (系統內建)
問題套件	Pillow 11.3.0（pip 使用者安裝，路徑：~/.local/lib/python3.10/site-packages）
系統套件	python3-pil 9.0.1-1ubuntu0.3（APT 安裝，路徑：/usr/lib/python3/dist-packages）

---

2. 問題現象

1. 執行 rqt_bag 開啟 SQLite3 rosbag (*.db3) 時，終端機拋出：

   RosPluginProvider.load(rqt_bag_plugins/BagImagePlugin) …
   ImportError: cannot import name 'ImageQt' from 'PIL.ImageQt'

2. rqt_bag GUI 無法載入 BagImagePlugin，影像時間軸/預覽全部失效。

---

3. 原因分析

步驟	發現
python3 -m pip show Pillow	版本 11.3.0、安裝於 ~/.local/...
`dpkg -l	grep python3-pil`	APT 版本為 9.0.1（相容）
匯入測試	import PIL; print(PIL.__file__) 指向 ~/.local/.../PIL
pipdeptree -p Pillow	Pillow 11 為 bokeh 相依；bokeh 曾以 pip install 安裝於全域使用者環境

Pillow 10 之後官方移除 PyQt5 介面 ImageQt，導致由 PyQt5 編譯的 BagImagePlugin 無法匯入。 pip 版路徑優先於 /usr/lib，遂覆蓋掉 APT 版 9.x → 觸發 ImportError。

---

4. 解決方案

4-1 從全域（使用者）環境移除 Pillow ≥ 10

python3 -m pip uninstall Pillow          # 依提示按 Y

驗證：

python3 - <<'PY'
import PIL, pathlib
print("Pillow =", PIL.__version__)        # ⇒ 9.0.1
print("Path   =", pathlib.Path(PIL.__file__).parent)
PY

4-2 重新啟動 rqt_bag

rqt_bag /path/to/bag_directory/          # GUI 成功載入影像外掛

---

5. 為 CARET-report 建立隔離 venv（保留 bokeh 與新 Pillow）

python3 -m venv ~/venv/caret-report
source ~/venv/caret-report/bin/activate
pip install --upgrade pip
pip install caret_report bokeh           # 會自帶 Pillow 11.x
# 使用完成後 deactivate

之後執行 CARET-report 前先 source ~/venv/caret-report/bin/activate，確保新版 Pillow 只影響該 venv。

---

6. 預防措施

1. 系統 Python 盡量只用 APT 套件；資料科學／可視化工具放 venv。

2. 若必須全域安裝 pip 套件，為關鍵套件加版本上限，例如在 requirements.txt：

   pillow<10

3. 在 ~/.config/pip/pip.conf 開啟隔離警示：

   [global]
   require-virtualenv = true

---

7. 結果

• rqt_bag 成功開啟 .db3 rosbag，影像時間軸與預覽正常顯示。
• CARET-report 於獨立 venv 運作，Python 套件不再干擾 ROS 2 系統環境。