実機自動テスト計画 (Hardware-in-the-Loop Test Plan)

目的 (Purpose)

PLAN_05 の 4 層モデルで「層④: 実機」に残っている確認（SDK の実呼び出し・実画像）を，Claude が実機を操作して自動で確認するようにする．人間の役割を「機材をつなぐ・チャートを置く・テストしてよいと合図する」という物理的な準備だけに絞る．

前提 (Preconditions)

2026-10-06 にユーザーと確認した．

仕組み (Design)

既存のセルフテスト（TIASshot.exe --selftest．偽カメラ・ヘッドレス）と同じ考え方で，実機版の検査モードを追加する．

• 起動: TIASshot.exe --hwtest --camera <lucam|iscam> [--with-chart] --hwtest-out <結果ファイル>．ランナー scripts/verify/run_hwtest.py がビルドから実行・判定までを行う（run_selftest.py と同じ形）
• ビルドフラグ: HWTEST（Debug 系の構成のみ）．診断・評価機能を Release に含めない方針（CLAUDE.md・ENV_06）に従う
• フォーム: ImagingSource は SDK の画面部品（ICImagingControl）を使うため，ヘッドレスではなく実際の Form1 を表示して動かす．人間がその場にいる前提なので表示してよい
• カメラの選択: 両機種を同時につないでも，--camera で指定した機種だけを使う（通常起動の Form1_Load は Lumenera を優先して探すため，そのままでは ImagingSource を検査できない）
• 結果: 項目ごとの PASS / FAIL と測定値を結果ファイルに書き，終了コード（0=合格，1=不合格あり，2=実機テスト自体の異常，3=タイムアウト）で返す．セルフテストの結果ファイルと同じ書式にする

守ること (Safety)

• 保存先は一時フォルダ（%TEMP% 配下）にする．本番の保存先（C:\TIAS_Data 等）には書き込まない
• 同梱の config.xml は変更しない（一時フォルダに複製して保存先等を差し替える）
• カメラのデバイス状態ファイル（{DeviceName}.xml）は読むだけで，上書きしない．露光・ゲイン等を検査で変えた場合は，終了時に元の値へ戻す
  • ImagingSource の露光・ゲインは絶対値（VCDAbsoluteValueProperty．露光は秒，ゲインは dB）で読み書きし，元の絶対値そのものへ戻して読み戻しで確かめる（整数の段（VCDRangeProperty）で扱うと元の値に戻せないため）
• チャート不要の検査の間は自動校正（チャート検出・ホワイトバランスの調整・変換行列の算出）を止める（CameraBase の校正停止フラグ．HWTEST ビルド限定）．はめたチャートで校正が走ると露光・ゲイン・ホワイトバランスが検査中に変わるため
• 光源は検査の最後に必ずポートを閉じる（失敗した場合も）．消灯はしない（アプリ終了時に光源を消さない仕様に合わせる．light 項目の最後に再点灯した状態で終わる）
• 待機には必ずタイムアウトを付ける

検査項目 (Test Items)

チャート不要（--with-chart なし）

※ 穴に何もはめないと中が暗く明るさの変化を評価しにくいため，カラーチャート（または白板）をはめた状態で行う．この検査の間は，チャートが写っても自動校正を走らせない（テストモードだけの処理．2026-10-08 にユーザーと合意）．

露光・ゲインの基準探し: 元の露光に最も近い 2^{n 秒の段に合わせ，平均輝度が中間（30〜220）かつ飽和画素（254 以上）の割合が 1% 以下になるまで露光を 1 段ずつ動かす（最大 12 段）．実測で露光 1 段は 0.497 倍（黒レベル 15.2 を引いた値）≈ 0.5 倍，ゲイン 1 dB は 1.122 倍 ≈ 10}(1/20) と理論どおりに効いた．

チャートが必要（--with-chart．人間がチャートをカメラの前に置いてから実行する）

※ チャート不要の検査と同じくカラーチャートをはめたまま続けて実行できる（付け外しは不要）．こちらは自動校正を走らせて結果を確かめる．

※ 判定のしきい値（色差の上限，撮影間隔の許容誤差等）は，最初の実行で実測値を見てから決める．チャート不要の検査のしきい値はフェーズ 1 で決めた（下記「確定したしきい値と実測値」）．

確定したしきい値と実測値 (Thresholds and Measurements)

フェーズ 1 の実測（ImagingSource DFK 33UX178．シリアル 35620307・10620446．カラーチャートをはめた状態）から決めた．しきい値の本体は HwTest/HwTestJudge.cs．

進め方 (Workflow)

1. 人間が機材をつなぎ，カラーチャート（または白板）を穴にはめて，「実機テストして」等と合図する
2. Claude（verifier）が python scripts/verify/run_hwtest.py --camera <機種> [--with-chart] を実行し，結果ファイルと終了コードで判定する
3. 対象は ImagingSource（--camera iscam）だけ．Lumenera は行わない（上記「対象機種」）
4. 人間に残る確認は，画面の見た目の最終確認など，数値で置き換えられないものだけにする

変更が必要なもの (Changes)

フェーズ (Phases)

フェーズ 1: 基盤とチャート不要の検査

• HWTEST フラグ，--hwtest，機種指定の接続，結果ファイル，ランナーを作る
• チャート不要の検査（connect・preview・exposure-gain・light・close-preview・reconnect）を実装する
• 検証プロファイルを更新する
• 完了条件: ImagingSource で人間の合図のもと実行でき，しきい値を実測から決めて全項目が合格する（当初は両機種としていたが，2026-10-08 に Lumenera を対象外とした）
• 状態: ImagingSource で完了（2026-10-08．DFK 33UX178 の 2 個体で 7/7 合格）．Lumenera の実機テストは行わない（対象外）
• 実機テストで見つかった不具合: 同梱の DFK33UX178.xml は別個体（シリアル 41520093）のものを指しており，旧 IScam.Connect はファイルのデバイスを開いていたため，別個体では接続できず例外が外へ漏れていた．機種名でデバイスを開いてから設定だけを適用し，失敗は ErrorMsg＋false で返すように直した（Cameras/IScamDeviceSelector．TECH_02）
• 仕様変更: アプリ終了時に光源を消灯しない（ポートを閉じるだけ．上流 v1.7 と同じ．2026-10-08 にユーザーが確定）．実機テストの後始末も同じく消灯しない

フェーズ 2: チャートが必要な検査

• calibrate・shot・close-saving・close-calibrating を実装する
• 完了条件: ImagingSource で実物のチャートを使って全項目が合格する

フェーズ 3: 手動テストの縮小

• TEST_01 の手動テストと PLAN_05 の「手動確認の目標形」を，実機テストで置き換えた分だけ縮める

PLAN_05 との関係 (Relation to PLAN_05)

• PLAN_05 フェーズ 3b（SDK アダプタからの判断ロジックの切り出し）とは独立に進められる．3b で切り出したロジックは層①で，SDK の呼び出しそのものは本計画の実機テストで確認する，という分担になる
• PLAN_05 フェーズ 4（実機録画データによる回帰）の撮影は，本計画の実機テストの仕組みを使って自動化できる可能性がある（録画フレームの保存を検査モードに加える）

リスクと対策 (Risks)