matlab-use-cameras

在 MATLAB 中使用相机

将 Image Acquisition Toolbox 的 videoinput 用作所有相机工作流的主要接口。其他接口（webcam、gigecam）是次要选择，仅应在用户明确要求或 videoinput 不可用时使用。

适用场景

• 用户想连接相机（网络摄像头、USB、GigE、USB3 Vision、CoaXPress、Camera Link）
• 用户想采集图像或视频帧
• 用户想预览实时相机画面
• 用户想列出或枚举可用相机
• 用户想从 CoaXPress 帧采集卡采集图像
• 用户想通过 Camera Link 帧采集卡采集图像
• 用户询问“如何在 MATLAB 中使用我的网络摄像头／相机？”
• 用户提到 Image Acquisition Toolbox

不适用场景

• 用户明确要求使用网络摄像头支持包中的 webcam()
• 用户使用 MATLAB Online（其中不提供 videoinput，请改用 webcam()）
• 用户正在处理已有文件中的图像（不涉及相机）
• 用户正在使用非成像硬件（示波器、数据采集板）

约定

API 优先级规则

这些规则至关重要。除非用户明确另有要求，否则请遵循这些规则。

1. 始终使用 Image Acquisition Toolbox 中的 videoinput() 作为主要相机接口
2. 始终使用 imaqhwinfo 枚举设备，不要使用 webcamlist 或 gigecamlist
3. **对于 GigE Vision 相机：**使用 videoinput("gentl", ...)，不要使用 gigecam 或 videoinput("gige")
4. **对于 Windows 上的 USB／内置网络摄像头：**使用 videoinput("winvideo", ...)
5. **对于 macOS 上的 USB／内置网络摄像头：**使用 videoinput("macvideo", ...)
6. **对于 Linux 上的 USB／内置网络摄像头：**使用 videoinput("linuxvideo", ...)
7. **对于 CoaXPress 相机：**使用 videoinput("gentl", ...)——CoaXPress 帧采集卡始终提供 GenTL producer
8. **对于 Camera Link 相机：**如果帧采集卡提供 GenTL producer，优先使用 videoinput("gentl", ...)；否则使用厂商特定的适配器（例如 videoinput("ni", ...)、videoinput("dalsa", ...)）
9. **如果用户提到 CoaXPress 或 Camera Link 相机，但未说明帧采集卡型号：**在编写代码前询问用户使用的是哪种帧采集卡——适配器的选择取决于帧采集卡
10. 绝不要将 videoinput 描述为“旧版”或“高级”接口——它是主要的全功能接口

何时改用 webcam()

仅适用于以下情况：

• 用户明确要求使用
• 用户使用 MATLAB Online
• 未安装 Image Acquisition Toolbox（请通过 imaqhwinfo 确认）

所需支持包

相机类型	适配器	支持包	厂商 GenTL Producer（.cti）
USB／内置网络摄像头（Windows）	"winvideo"	OS Generic Video Interface	不需要
USB／内置网络摄像头（macOS）	"macvideo"	OS Generic Video Interface	不需要
USB／内置网络摄像头（Linux）	"linuxvideo"	OS Generic Video Interface	不需要
GigE Vision 相机	"gentl"	GenICam Interface	必需——由相机厂商提供
USB3 Vision 相机	"gentl"	GenICam Interface	必需——由相机厂商提供
CoaXPress 相机（通过帧采集卡）	"gentl"	GenICam Interface	必需——由帧采集卡厂商提供
Camera Link 相机（GenTL producer）	"gentl"	GenICam Interface	必需——由帧采集卡厂商提供
Camera Link 相机（厂商适配器）	厂商特定（例如 "ni"、"dalsa"）	厂商提供的硬件适配器	不适用

**重要提示：**GenICam Interface 支持包仅提供 MATLAB 端的使用者组件。对于 gentl 相机，还必须安装厂商的 GenTL producer（.cti 文件）。例如：FLIR 的 Spinnaker SDK、Allied Vision 的 Vimba X、Balluff 的 ImpactAcquire，以及 Euresys 帧采集卡的 eGrabber。MATLAB 支持包中不包含该 producer。

工作流

1. 枚举设备

% List all available adaptors and devices
info = imaqhwinfo;
disp(info.InstalledAdaptors)

% Get details for a specific adaptor
adaptorInfo = imaqhwinfo("winvideo");
disp(adaptorInfo.DeviceInfo)

2. 连接相机

% USB/built-in webcam on Windows
vid = videoinput("winvideo", 1);

% GigE Vision camera via GenTL
vid = videoinput("gentl", 1);

% Specify a format
vid = videoinput("winvideo", 1, "YUY2_1280x720");

3. 配置属性

% Set color space
vid.ReturnedColorSpace = "rgb";

% Set region of interest [x_offset y_offset width height]
vid.ROIPosition = [0 0 640 480];

% Access device-specific properties via the source object
src = getselectedsource(vid);

4. 预览实时视频

preview(vid);
pause(3);

5. 获取帧

单帧快照：

img = getsnapshot(vid);
imshow(img);

多帧（立即触发）：

vid.FramesPerTrigger = 10;
start(vid);
wait(vid);
[frames, timestamps] = getdata(vid);

手动触发（按需获取）：

triggerconfig(vid, "manual");
vid.FramesPerTrigger = 1;
start(vid);
trigger(vid);
img = getdata(vid);

6. 清理

stoppreview(vid);
stop(vid);
delete(vid);
clear vid;

关键函数

函数	用途	来源
imaqhwinfo	列出适配器和设备	Image Acquisition Toolbox
videoinput	创建视频输入对象（主要接口）	Image Acquisition Toolbox
preview	显示实时视频流	Image Acquisition Toolbox
getsnapshot	立即捕获单帧	Image Acquisition Toolbox
start	开始采集	Image Acquisition Toolbox
getdata	从缓冲区获取已采集的帧	Image Acquisition Toolbox
stop	停止采集	Image Acquisition Toolbox
getselectedsource	访问设备专属属性	Image Acquisition Toolbox
triggerconfig	配置触发类型（立即、手动、硬件）	Image Acquisition Toolbox
trigger	在 start 后执行手动触发	Image Acquisition Toolbox
imageAcquisitionExplorer	启动交互式采集应用	Image Acquisition Toolbox

使用模式

USB／内置网络摄像头（Windows）

% Enumerate
info = imaqhwinfo("winvideo");
disp(info.DeviceInfo.DeviceName)

% Connect and configure
vid = videoinput("winvideo", 1, "YUY2_1280x720");
vid.ReturnedColorSpace = "rgb";
vid.FramesPerTrigger = 1;

% Preview and capture
preview(vid);
pause(2);
img = getsnapshot(vid);
imshow(img);

% Clean up
stoppreview(vid);
delete(vid);
clear vid;

GigE Vision 相机（GenTL）

GenTL 适配器是 GigE Vision 和 USB3 Vision 相机的首选接口。它支持完整的 GenICam 标准，并兼容不同相机厂商的产品。

% Enumerate
info = imaqhwinfo("gentl");
disp(info.DeviceInfo.DeviceName)

% Connect
vid = videoinput("gentl", 1);
vid.ReturnedColorSpace = "rgb";

% Configure acquisition
vid.FramesPerTrigger = 10;

% Access GenICam properties via source object
src = getselectedsource(vid);

% Acquire
start(vid);
wait(vid);
[frames, timestamps] = getdata(vid);

% Clean up
stop(vid);
delete(vid);
clear vid;

如果未安装 GenTL 适配器，请指导用户完成设置：

1. 通过 Add-On Explorer 安装 "Image Acquisition Toolbox Support Package for GenICam Interface"
2. 安装厂商的 GenTL producer（.cti 文件）——例如，FLIR 相机使用 Spinnaker SDK，Allied Vision 相机使用 Vimba X，或使用厂商的 GigE Vision SDK
3. 使用 imaqhwinfo("gentl") 验证——相机应显示在 DeviceInfo 中

有关 GenTL producer 配置和故障排除的详细信息，请参阅 references/gentl-setup.md。

CoaXPress 相机（通过采集卡）

CoaXPress 采集卡始终提供 GenTL producer，因此其工作流与通过 gentl 适配器连接 GigE Vision 相机相同。

% Enumerate — CoaXPress cameras appear under the gentl adaptor
info = imaqhwinfo("gentl");
disp(info.DeviceInfo.DeviceName)

% Connect and acquire
vid = videoinput("gentl", 1);
vid.ReturnedColorSpace = "rgb";
vid.FramesPerTrigger = 10;
src = getselectedsource(vid);
start(vid);
wait(vid);
[frames, timestamps] = getdata(vid);

% Clean up
stop(vid);
delete(vid);
clear vid;

Camera Link 相机（通过采集卡）

Camera Link 有两种连接方式，具体取决于采集卡厂商是否提供 GenTL producer：

提供 GenTL producer（首选）： 使用 videoinput("gentl", ...)——与上文的 GigE／CoaXPress 相同。

未提供 GenTL producer（厂商适配器）： 使用通过 imaqhwinfo 注册的厂商专用适配器：

% Check which adaptors are available
info = imaqhwinfo;
disp(info.InstalledAdaptors)

% Connect via vendor adaptor (e.g., "ni" for National Instruments)
vid = videoinput("ni", 1);
vid.ReturnedColorSpace = "rgb";
src = getselectedsource(vid);

重要提示： 如果用户提到 Camera Link 或 CoaXPress 相机，却未说明采集卡型号，请询问其使用的是哪种采集卡。正确的适配器取决于采集卡，而非相机。

常见错误

错误	错误原因	正确做法
对 USB 摄像头使用 webcam()	无法使用 IMAQ 的完整功能集（触发、ROI、日志记录、回调）	使用 videoinput("winvideo", ...)
使用 webcamlist 查找摄像头	只能找到 webcam-support-package 设备，会漏掉工业摄像头	使用 imaqhwinfo
对 GigE 摄像头使用 gigecam	接口功能有限，不支持完整的 GenICam 功能集	使用 videoinput("gentl", ...)
使用 videoinput("gige", ...)	这是旧版适配器，目前不再积极维护	使用 videoinput("gentl", ...)
使用 gigecamlist 枚举 GigE 摄像头	仅支持 GigE Vision Hardware Support Package	使用 imaqhwinfo("gentl")
称 videoinput 为“旧版”接口	它是主要且仍在积极维护的接口	将 videoinput 作为推荐方式介绍
使用 snapshot(cam) 进行捕获	这是 webcam support package 函数	将 videoinput 与 getsnapshot(vid) 搭配使用
使用 now/datenum 获取时间戳	这是已弃用的序列日期数字	使用 datetime("now") 获取计时元数据
认为 Camera Link 需要专用接口	如果帧采集卡供应商提供 GenTL Producer，GenTL 也适用于 Camera Link	优先尝试 videoinput("gentl", ...)，失败时再使用供应商适配器

---

版权所有 2026 The MathWorks, Inc.

---