matlab-enhance-camera-image

目的

诊断任何已连接摄像头的图像质量问题，并通过结合调整硬件设置和软件后处理来改善图像质量。遵循硬件优先、软件其次的理念：先尝试从源头解决问题，再考虑后处理。

适用场景

• 用户抱怨摄像头图像质量差（太暗、模糊、有噪点、褪色）
• 用户询问如何改善或优化摄像头设置
• 用户拍摄了图像并希望增强图像
• 用户提到主体逆光、曝光不足、曝光过度或失焦

不适用场景

• 对非摄像头来源的文件进行常规图像处理（直接使用 IPT）
• 从头构建图像采集流水线（使用 Image Acquisition Toolbox 文档）
• 摄像头几何标定（使用 Camera Calibrator 应用）

参考文档（按需加载）

• 阅读 references/diagnosis-guidance.md，了解详细的指标阈值和逆光检测算法
• 阅读 references/hardware-tuning-guidance.md，了解属性发现模式、各类摄像头属性表和安全调整策略（适用于所有摄像头类型）
• 阅读 references/enhancement-guidance.md，了解 IPT 函数参数、流水线顺序和常见错误

脚本入口

• scripts/diagnoseImageQuality.m — 可复用的诊断函数；接收图像，并返回包含质量指标及评估结果的结构体

硬性要求

• 首先调用 detect_matlab_toolboxes，确认已安装 Image Acquisition Toolbox 和 Image Processing Toolbox
• 执行任何脚本前，都要对其调用 check_matlab_code
• 切勿硬编码摄像头属性名称——务必在运行时发现属性

操作流程

步骤 1 — 连接摄像头并发现其功能

API 选择： 如果有 Image Acquisition Toolbox，始终优先使用 videoinput，而不是 webcam() 等其他接口。videoinput 可公开更多属性（通过 propinfo），支持批量采集帧（getdata），并提供用于流式传输的 FramesAcquiredFcn。只有在未安装 Image Acquisition Toolbox，且用户安装了 MATLAB Support Package for USB Webcams 时，才使用 webcam()。

连接摄像头并枚举所有可用属性：

% 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"、"Problem" 或 "Severe"）。

确定主要问题——重点关注评估结果为 "Problem" 或 "Severe" 的字段。

**扩展关注点的动态评估：**如果步骤 3 中用户的关注点未包含在标准的 6 项指标中，请生成内联 MATLAB 代码对其进行评估。评估模式和代码模板请参阅 references/diagnosis-guidance.md § "Extended Metrics"。将扩展指标结果与标准结果一并报告。

步骤 5 — 建议硬件调整

使用下方决策表，将诊断出的问题对应到可用的相机属性。仅建议调整相机实际具备的属性。

应用设置、重新捕获图像并比较指标。每次只更改一个属性。

对于 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，请在源对象（src）上设置属性，而不是在 videoinput 对象上设置。请使用 getsnapshot(vid)，不要使用 snapshot()。

如有需要，重复调整，直到指标有所改善或硬件选项用尽。

步骤 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 函数文件，供用户今后在没有 Agent 的情况下调用。如果用户指定了文件夹，则将文件写入该文件夹；否则写入当前 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 ↑	Gamma 校正（.^ 0.7）、imadjust
整体曝光过度	Exposure ↓、Brightness ↓	使用输出范围 [0 0.8] 的 imadjust
对比度低	Contrast ↑、调整 Gamma	locallapfilt、对亮度应用 adapthisteq
运动模糊	Exposure ↓（加快快门）	imsharpen（效果有限）、反卷积
对焦不准	调整 Focus（如可用）	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 §“生成可复用函数”。

注意事项

• localtonemap 需要 single 类型的输入 — 务必先用 im2single() 转换；传入 uint8 会引发错误
• 摄像头预热至关重要 — 前 5–10 帧通常为空白或曝光不佳。拍摄前请使用 preview() 或丢弃初始快照
• adapthisteq（CLAHE）需要单通道图像 — 请在 V 通道（HSV）或 L 通道（Lab）上应用，而不是直接应用于 RGB
• 优先调整 Exposure，而非 Gain — 如果摄像头同时支持两者，提高 Exposure 可获得更干净的结果；Gain 会放大噪声
• BacklightCompensation 的范围各不相同 — 有些摄像头为 0–1，有些为 0–2，还有些为 0–255。务必在运行时检查范围
• imlocalbrighten 只会提亮暗部 — 保留已经明亮的区域；对于逆光场景，优先于全局提亮
• 后期处理顺序很重要 — 先提亮，再增强局部对比度，最后锐化。降噪前进行锐化会放大噪声
• 自动模式会覆盖手动值 — 调整相应值之前，请先将 ExposureMode/WhiteBalanceMode 设为手动
• 更改分辨率可能会重置属性 — 更改分辨率后，请重新检查属性值
• YUY2 摄像头需要设置 ReturnedColorSpace = 'rgb' — 许多 USB 网络摄像头（例如 Microsoft LifeCam）仅输出 YUY2。如果不设置 vid.ReturnedColorSpace = 'rgb'，getsnapshot 会返回被误解为 RGB 的原始 YCbCr 数据，导致显示颜色错误，并使 IPT 函数和诊断指标产生错误结果
• snapshot 与 getsnapshot 的区别 — snapshot(cam) 仅用于网络摄像头；getsnapshot(vid) 用于 videoinput 对象。两者不能互换
• closePreview 与 closepreview 的区别 — 网络摄像头使用驼峰式 closePreview(cam)；videoinput 使用小写形式 closepreview(vid)。大小写用错会引发“Undefined command/function”错误
• videoinput 更适合批量使用 getdata — 使用 videoinput 捕获多帧时，请使用 getdata(vid, N)，而不是循环调用 getsnapshot。它可在一次调用中获取 N 帧，开销更低，还能让适配器全速运行
• 保存文件时使用 fullfile — 保存图像或生成的文件时，请使用 fullfile(pwd, 'filename.png')，避免跨平台路径解析错误

---

版权所有 2026 The MathWorks, Inc.

---