matlab-enhance-camera-image

目的

接続されているあらゆるカメラの画質の問題を診断し、ハードウェア設定の調整とソフトウェアによる後処理を組み合わせて改善します。ハードウェアを優先し、ソフトウェアを後回しにする方針で動作します。後処理に頼る前に、必ず撮影時点での改善を試みてください。

使用する場面

• カメラの画質が悪い（暗すぎる、ぼやける、ノイズが多い、白っぽい）とユーザーが訴えている
• カメラ設定の改善または最適化方法をユーザーが尋ねている
• ユーザーが画像を撮影し、画質を高めたいと考えている
• 逆光の被写体、露出不足、露出過多、ピントが合っていないなどの話題が出ている

使用しない場面

• カメラで撮影したものではないファイルの一般的な画像処理（IPTを直接使用してください）
• 画像取得パイプラインを一から構築する場合（Image Acquisition Toolbox のドキュメントを使用してください）
• カメラの幾何学的キャリブレーション（Camera Calibrator アプリを使用してください）

参考ドキュメント（必要に応じて読み込む）

• 詳細な指標のしきい値と逆光検出アルゴリズムについては、references/diagnosis-guidance.mdを読んでください
• プロパティの検出パターン、カメラの種類別プロパティ表、安全な調整方法（すべてのカメラの種類に適用）については、references/hardware-tuning-guidance.mdを読んでください
• IPT関数のパラメーター、パイプラインの順序、よくあるエラーについては、references/enhancement-guidance.mdを読んでください

スクリプトのエントリーポイント

• scripts/diagnoseImageQuality.m — 再利用可能な診断関数です。画像を受け取り、評価結果を含む画質指標の構造体を返します

必須要件

• Image Acquisition Toolbox と Image Processing Toolbox がインストールされていることを確認するため、最初に detect_matlab_toolboxes を呼び出してください
• スクリプトを実行する前に、必ず check_matlab_code を呼び出してください
• カメラのプロパティ名をハードコードしないでください。必ず実行時に検出してください

手順

ステップ 1 — カメラに接続し、機能を検出する

APIの選択： Image Acquisition Toolbox が利用できる場合は、webcam() などの他のインターフェイスよりも、必ず videoinput を優先してください。videoinput はより多くのプロパティを公開し（propinfo経由）、複数フレームの一括取得（getdata）をサポートし、ストリーミング用の FramesAcquiredFcn を提供します。webcam() を使用するのは、Image Acquisition Toolbox がインストールされておらず、ユーザーが代わりに MATLAB Support Package for USB Webcams を使用している場合に限ります。

カメラに接続し、利用可能なすべてのプロパティを列挙してください。

% For videoinput (preferred when Image Acquisition Toolbox is available):
vid = videoinput(adaptorName, deviceID, format);
vid.ReturnedColorSpace = 'rgb';  % Critical for YUY2 cameras
src = getselectedsource(vid);
props = properties(src);

% For webcam (fallback when only USB Webcams support package is installed):
cam = webcam();
props = properties(cam);

検出した各プロパティを機能ごとに分類してください。

問題領域	一般的なプロパティ名
明るさ／露出	Exposure, ExposureTime, ExposureMode, Brightness, Gain, BacklightCompensation
フォーカス	Focus, FocusMode
色	WhiteBalance, WhiteBalanceMode, Hue, Saturation, ColorEnable
コントラスト／階調	Contrast, Gamma, Sharpness

各プロパティの有効範囲を記録してください。検出した機能をユーザーに報告してください。

上記の分類表に一致しないプロパティには、高度なプロパティ調査手順を適用してください。

1. 認識されていないプロパティを、名前のパターンごとにグループ化します（例：「Trigger」、「Pixel」、「Bin」、「LUT」、「ROI」、「Offset」、「Decimation」を含む名前）
2. videoinput のソースでは、propinfo(src, propName) を使って型、制約、範囲、読み取り専用かどうかを確認します
3. 画質に関係する（画像の見た目に影響する可能性があるもの：Binning、BlackLevel、LUT、DigitalGain、HDR）プロパティと、機能に関係する（画質ではなく取得モードに影響するもの：TriggerMode、PixelFormat、PacketSize、AcquisitionFrameRate）プロパティに分類します
4. 検出したすべてのプロパティを、標準（既知）と高度なもの（検出されたもの）を区別してユーザーに報告します
5. 画質に関係する未知のプロパティについては、references/hardware-tuning-guidance.mdに記載されている安全な調査手順に従ってください

ステップ 2 — ベースライン画像を取得する

videoinput オブジェクトの場合（推奨）：

% Warm up the camera (critical — first frames are often blank or poorly exposed)
preview(vid);
pause(2);
closepreview(vid);

% Capture the reference image
baselineImg = getsnapshot(vid);
imshow(baselineImg);
title("Baseline Image");

webcam オブジェクトの場合（代替）：

% Warm up the camera (critical — first frames are often blank or poorly exposed)
preview(cam);
pause(2);
closePreview(cam);

% Capture the reference image
baselineImg = snapshot(cam);
imshow(baselineImg);
title("Baseline Image");

注：snapshot() は webcam 専用です。videoinput では getsnapshot(vid) を使用してください。webcam オブジェクトと videoinput オブジェクトは、どちらも preview() をサポートしています。

比較用のベースラインとして、現在のプロパティ値を記録します。

ステップ 3 — ユーザーの懸念を把握する

診断を実行する前に、ユーザーが何を修正しようとしているのかを特定します。

• ユーザーがすでに具体的な問題（例：「画像が暗すぎる」、「縞模様が見える」）を伝えている場合は、それを主な懸念事項として記録します
• ユーザーが具体的な問題を伝えていない場合は、「どのような画質の問題が見られますか？ それとも、全般的な評価を実行しましょうか？」と尋ねます
• ユーザーが「とにかく改善して」と言った場合や、具体的な懸念がない場合は、標準の 6 指標による評価のみを実行します

ユーザーの懸念を、次のいずれかのカテゴリに分類します。

• 標準指標（diagnoseImageQuality.m で評価）：明るさ、コントラスト、シャープネス、ノイズ、色バランス、逆光
• 拡張された懸念事項（動的なインライン評価が必要）：周辺減光、縞模様／ストライプ、彩度クリッピング、ちらつき／不安定さ、色収差、歪み、その他

懸念が拡張されたものである場合は、ステップ 4 で動的に評価するために記録しておきます。

ステップ 4 — 画質を診断する

診断スクリプトを必ず実行します（標準的なベースラインを取得できます）。

addpath("scripts");
results = diagnoseImageQuality(baselineImg);
disp(results);

この関数は、次のフィールドを持つ構造体を返します。

• brightness — 平均輝度、評価
• clipping — ハイライトのクリッピング（ピクセルの % ≥ 250）およびシャドウのクリッピング（ピクセルの % ≤ 5）、評価
• contrast — 標準偏差、評価
• sharpness — ラプラシアン分散、評価
• noise — 推定ノイズレベル、評価
• colorBalance — R/G および B/G の比率、評価
• backlightRatio — 中央と境界の輝度比、評価

各フィールドには .value（数値または構造体）と .assessment（「OK」、「問題あり」、または「重大」）があります。

主な問題を特定します。「問題あり」または「重大」と評価されたフィールドに注目してください。

拡張された懸念事項の動的評価： ステップ 3 で挙げられたユーザーの懸念が標準の 6 指標で扱われていない場合は、評価用の MATLAB コードをインラインで生成します。評価パターンとコードテンプレートについては、references/diagnosis-guidance.md の「拡張指標」を参照してください。標準の結果と併せて、拡張指標の結果も報告します。

ステップ 5 — ハードウェア設定の調整を提案する

以下の判断表を使って、診断された問題を利用可能なカメラプロパティに対応付けます。カメラに実際に備わっているプロパティのみ、調整を提案してください。

設定を適用し、画像を再取得して指標を比較します。プロパティは一度に 1 つずつ変更してください。

videoinput オブジェクトの場合（推奨）：

% Example: increase exposure for dark image
src.Exposure = src.Exposure + 2;
newImg = getsnapshot(vid);
newResults = diagnoseImageQuality(newImg);

webcam オブジェクトの場合（代替）：

% Example: increase exposure for dark image
cam.Exposure = cam.Exposure + 2;
newImg = snapshot(cam);
newResults = diagnoseImageQuality(newImg);

注：videoinput では、プロパティは videoinput オブジェクトではなく、ソースオブジェクト（src）に設定してください。snapshot() の代わりに getsnapshot(vid) を使用します。

指標が改善するか、ハードウェアの調整手段が尽きるまで、必要に応じて繰り返します。

ステップ 6 — 後処理で画質を向上させる

ハードウェア調整後に残っている問題に応じて、IPT 関数を正しい順序で適用します。

1. 明るくする（まだ暗い場合）：imlocalbrighten、imadjust、ガンマ補正
2. コントラストを調整する（まだ平坦な場合）：locallapfilt、輝度チャンネルに対する adapthisteq
3. シャープにする（まだぼやけている場合）：imsharpen — 必ず最後に実行します

enhanced = baselineImg;

% Example: brighten a backlit image
enhanced = imlocalbrighten(enhanced, 0.8);

% Example: enhance local contrast
enhanced = locallapfilt(enhanced, 0.3, 1.5);

% Example: sharpen (last step)
enhanced = imsharpen(enhanced, 'Radius', 1.5, 'Amount', 1.0);

処理前と処理後を比較して表示します。

montage({baselineImg, enhanced}, 'Size', [1 2]);
title("Before vs After Enhancement");

ステップ 7 — レポートの作成と再利用可能なパイプラインの生成

ワークフロー全体を要約します。

1. 特定した元の問題
2. 適用したハードウェア調整とその効果
3. 適用したソフトウェアの強化
4. 最終的な指標の比較（調整前と調整後）

再利用可能な .m 関数ファイルを生成し、ユーザーが以降の撮影でエージェントを使わずに呼び出せるようにします。ユーザーが指定したフォルダーがあればそこに、指定がなければ現在の MATLAB 作業ディレクトリ（pwd）に保存します。スキル独自のヘルパー関数用に予約されている、スキルの scripts/ フォルダーには保存しないでください。

ファイルを書き込んだ後：

• check_matlab_code を実行して構文を確認します
• 呼び出し方をユーザーに示します
• 組み込まれている設定と強化処理について説明します

単発撮影パイプライン

関数は次の処理を行います。

1. 検出したアダプター、デバイス ID、フォーマットを使用してカメラに接続します
2. カメラの出力が YUY2 などの非 RGB フォーマットの場合は、ReturnedColorSpace = 'rgb' を設定します
3. 指標を改善した、調整済みのハードウェアプロパティ設定を適用します
4. カメラをウォームアップします（最初のフレームを破棄します）
5. フレームを撮影します
6. 画質を測定可能なほど改善した後処理だけを、正しい順序で適用します
7. 後処理を行います（videoinput オブジェクトを停止して削除します）
8. 強化した画像を返します

判断表

診断された問題	ハードウェアでの修正（利用可能な場合）	ソフトウェアでの修正（IPT）
被写体が暗すぎる（逆光）	BacklightCompensation ↑、Exposure ↑、Brightness ↑	imlocalbrighten、反転した imreducehaze
全体的に露出不足	Exposure ↑、Gain ↑、Brightness ↑	ガンマ補正（.^ 0.7）、imadjust
全体的に露出過多	Exposure ↓、Brightness ↓	出力範囲 [0 0.8] を指定した imadjust
コントラストが低い	Contrast ↑、ガンマ調整	locallapfilt、輝度に対する adapthisteq
モーションブラー	Exposure ↓（シャッター速度を上げる）	imsharpen（限定的）、デコンボリューション
ピントが合っていない	フォーカス調整（利用可能な場合）	imsharpen（効果は限定的）
ノイズが多い	代わりに Gain ↓、Exposure ↑	imgaussfilt、imnlmfilt、wiener2
色かぶり	WhiteBalance を調整、WhiteBalanceMode=auto	手動の白色点補正
色あせている	Gamma ↓、Contrast ↑	imadjust、locallapfilt

生成するパイプラインのテンプレート

検出した値に合わせてプレースホルダーを置き換えます。指標を測定可能なほど改善した強化処理だけを含めます。

単発撮影テンプレート（videoinput）

function img = acquireEnhancedImage()
%acquireEnhancedImage Capture and enhance image from <camera name>.
%   img = acquireEnhancedImage() returns an enhanced RGB image.

    vid = videoinput('<adaptor>', <deviceID>, '<format>');
    vid.ReturnedColorSpace = 'rgb';
    src = getselectedsource(vid);

    % Tuned hardware settings
    src.<Property1> = <value>;
    src.<Property2> = <value>;

    % Warm up
    preview(vid);
    pause(2);
    closepreview(vid);

    % Capture
    img = getsnapshot(vid);
    delete(vid);

    % Enhancement pipeline (only steps that helped)
    img = imlocalbrighten(img, <amount>);
    img = imgaussfilt(img, <sigma>);
end

命名：デフォルトでは acquireEnhancedImage を使用するか、ユーザーに希望する名前を尋ねます。lowerCamelCase に従います。パラメーター化とオプション入力のガイダンスについては、references/enhancement-guidance.md の「Generating Reusable Functions」を参照してください。

注意事項

• localtonemapにはsingle型の入力が必要です — 必ず最初にim2single()で変換してください。uint8を渡すとエラーになります
• カメラのウォームアップは重要です — 最初の5～10フレームは、空白になったり露出が不適切になったりすることがよくあります。撮影前にpreview()を使うか、最初のスナップショットを破棄してください
• adapthisteq（CLAHE）には単一チャンネル画像が必要です — RGBに直接適用せず、Vチャンネル（HSV）またはLチャンネル（Lab）に適用してください
• GainよりExposureを優先してください — カメラに両方ある場合、Exposureを上げるとよりきれいな結果が得られます。Gainはノイズを増幅します
• BacklightCompensationの範囲はカメラによって異なります — 0～1、0～2、または0～255のカメラがあります。必ず実行時に範囲を確認してください
• imlocalbrightenは暗い領域だけを明るくします — すでに明るい領域は維持されます。逆光のシーンでは、全体の明るさを上げるよりこちらを優先してください
• 後処理の順序が重要です — 最初に明るさを上げ、次に局所コントラストを調整し、最後にシャープ化します。ノイズ除去の前にシャープ化すると、ノイズが増幅されます
• 自動モードは手動設定値を上書きします — 対応する値を調整する前に、ExposureMode／WhiteBalanceModeを手動に設定してください
• 解像度を変更するとプロパティがリセットされることがあります — 解像度を変更した後は、プロパティ値を再確認してください
• YUY2カメラではReturnedColorSpace = 'rgb'が必要です — 多くのUSBウェブカメラ（例：Microsoft LifeCam）はYUY2のみを出力します。vid.ReturnedColorSpace = 'rgb'を設定しないと、getsnapshotは未加工のYCbCrデータをRGBとして誤って解釈し、表示色が誤るだけでなく、IPT関数や診断メトリクスの結果も不正確になります
• snapshotとgetsnapshotの違い — snapshot(cam)はウェブカメラ専用です。getsnapshot(vid)はvideoinputオブジェクト用です。両者は互換性がありません
• closePreviewとclosepreviewの違い — ウェブカメラではキャメルケースのclosePreview(cam)を使用し、videoinputでは小文字のclosepreview(vid)を使用します。大文字・小文字を間違えると「Undefined command/function」エラーが発生します
• videoinputでは一括のgetdataが適しています — videoinputで複数フレームを撮影する場合は、getsnapshotをループする代わりにgetdata(vid, N)を使用してください。1回の呼び出しでNフレームを取得でき、オーバーヘッドが少なく、アダプターを最高速度で動作させることができます
• ファイルの保存にはfullfileを使用してください — 画像や生成ファイルを保存する場合は、プラットフォーム間でのパス解決エラーを避けるため、fullfile(pwd, 'filename.png')を使用してください

---

Copyright 2026 The MathWorks, Inc.

---