Jetson Orin NXでライン座標設定GUIが起動しない

[ucn-yushin]

概要

Jetson Orin NX上でライン座標設定ツールを実行すると、OpenCVのマウスコールバック登録時にエラーが発生する。

対象ファイル:

scripts/setup_lines.py

実行例:

uv run python scripts/setup_lines.py --video <動画ファイル>

発生するエラー:

NULL window handler in function 'cvSetMouseCallback'

原因の見込み

uv runでは、JetPack標準のOpenCVではなく、venv内のPyPI版 opencv-python 4.11.0.86 が使用される。

PyPI版OpenCVのQtバックエンドと、JetsonのX11／Wayland環境が正しく連携できず、OpenCVウィンドウの作成に失敗している可能性がある。

同様のエラーは、Ubuntu環境でpip版OpenCVを使用した場合にも報告されている。

• https://stackoverflow.com/questions/62801244/null-window-handler-in-function-cvsetmousecallback/63708673
• Could not find the Qt platform plugin "wayland" in opencv path opencv/opencv-python#729

対応内容

以下を確認し、Jetson上でライン設定GUIを利用できるようにする。

• uv runで読み込まれるOpenCVとGUIバックエンドを確認する
• X11／Waylandによる動作の違いを確認する
• ASCIIのウィンドウ名で動作するか確認する
• ウィンドウ生成後にwaitKey()を挟む必要があるか確認する
• 必要に応じて、Jetson向けのOpenCV依存関係を見直す
• Jetsonでの実行方法をREADMEへ記載する

確認用コマンド:

uv run python -c '
import cv2
print("version:", cv2.__version__)
print("path:", cv2.__file__)
print("GUI:", cv2.currentUIFramework())
'

回避策（未検証）

GUIが直らない場合でも、次の手順で設置を進められる見込み。ただし未検証。

カメラ設置 → Jetsonでクリップを録画（GUI不要）
  → 開発機へ転送 → 開発機で scripts/setup_lines.py を実行してライン設定
  → LINE1_* / LINE2_* / PARKING_REF_* の10キーを Jetson の .env へ転記

scripts/setup_lines.py は対象キー以外を保持する契約になっている
（tests/scripts/test_setup_lines_env.py が固定）ため、キーの転記で
他の設定が壊れることはない。

なお SHOW_DISPLAY=false であればカウント処理自体はJetsonでも動作する
（ADR 0001「残っている既知の課題」に記録済み）。GUIが必要なのは
ライン座標の設定時だけ。

完了条件

• Jetson Orin NX上でライン設定画面が表示される
• マウスクリックで5点を設定できる
• 設定内容を.envへ保存できる
• 必要なOpenCVおよびGUI環境がドキュメント化されている

考えられる開発時間

半日〜1日程度

備考

本プロジェクトはPython 3.12以上を使用するため、JetPack標準OpenCVへ切り替える場合はPythonバージョンとの互換性確認が必要。

---

パス修正（2026-09-17）: 本文が参照していた raspi/line_detection/line_setup/setup_lines.py は
PR #104（2ライン方式の採用に伴うディレクトリ整理）以前のパスだったため、現行の
scripts/setup_lines.py へ更新した。あわせて未検証の回避策を追記。