WebCamera_GrabImage

This filter uses DirectShow API to acquire images from devices registered in the system. Images can be acquired from many sources like: web cameras with support for DirectShow, video grabbers and system video streams.

The inCameraIndex input selects the capture device, out of multiple devices available in the system, by the numeric index in order provided by the operating system. This input can be used for quick experimental programs and is provided for backward compatibility, but it is advised to use the inCameraID input for selecting the camera instead as the numeric index is very unstable and can change frequently after hardware state changes in the system.

The inCameraID input specifies which web camera device in the system to use by the camera unique ID. Use the WebCamera_ListDevices filter to determine the camera ID. It is preferred to use this input instead of inCameraIndex as the unique ID of the camera is more stable in the system over time and can be, for example, used to save the camera selection in the application configuration.

Inputs inCameraIndex and inCameraID cannot be used at the same time (the device can be selected either by index or by ID, not both). Leaving both inputs unset will select the first video grabber in the system.

The inFrameSize input selects the output image size in pixels. If the requested size is not provided by the camera an error occurs. When this input is left unset the filter selects the first available size found.

inPixelType specifies what kind of pixel format should be preferred when selecting the output format from the camera. Selecting a format that the camera does not support will result in an error. Setting the input to "Any" will cause the filter to accept the first supported pixel format provided by the camera. The selected camera pixel format will be converted to the most appropriate format suitable for the vision application, including conversion from YUV to RGB color space.

Best quality of the image can be achieved using inPixelType with values RGB24 or RGB32. Format YUY2 stores two RGB pixels using only 4 bytes.

inExposure can be used to select a manually specified, fixed exposure time for the camera. This parameter is usually specified in base 2 log values and its valid range includes negative values (like -15 to 0) but the actual interpretation and range depends on the specific camera. Leaving this input unset (on "Auto") results in the camera setting to be left unchanged. This input is ignored when the inExposureAuto is set to True.

Setting the inExposureAuto input to True will result in enabling of the automatic control of the exposure time in the camera. Setting this input to False will leave the camera settings unchanged (use inExposure input to force a fixed exposure time value and to disable the automatic exposure control).

inGain sets the gain value of the camera sensor (the sensitivity of the sensor). Leaving this input unset (on "Auto") results in the camera setting to be left unchanged. Some cameras might ignore this setting when automatic exposure control is active.

inBrightness sets the image brightness correction factor (the black level of the image). Leaving this input unset (on "Auto") results in the camera setting to be left unchanged.

The inWhiteBalance input, when set, specifies a manual, fixed white balance factor. The interpretation of the value depends on the camera. Leaving this input unset (on "Auto") results in the camera setting to be left unchanged. This input is ignored when the inWhiteBalanceAuto is set to True.

Setting the inWhiteBalanceAuto input to True will enable the automatic white balance control in the camera. Setting this input to False will leave the camera settings unchanged (use inWhiteBalance input to force a fixed factor and to disable the automatic white balance control).

Various cameras might not support any of the image control settings like exposure, gain, brightness and white balance. Setting such input to non-default value when the camera does not support a given property will result in an IOError. Various cameras can also support different valid ranges for those parameters and setting a given input to values outside of the range supported by the camera will result in an IOError.

To check which pixel types are supported you can use application GraphStudioNext.

This filter can throw an exception to report error. Read how to deal with errors in Error Handling.

"Unable to connect with the web camera. No web camera devices found in the system." - no compatible video grabber device is present in the system.

"Unable to connect with the web camera. Camera with specified ID not found." - the unique ID specified on the inCameraID input is not valid or the camera with the specified ID is not present in the system.

"Unable to connect with the web camera. The camera device index might be out of a valid range." - provided inCameraIndex is not a valid device number (is outside of range of available devices).

"Unable to connect with the web camera. Ensure access to the camera is enabled in the system privacy settings." - access to the requested video grabber device was denied, possible due to the system and/or application privacy settings.

"Web Camera does not support the requested image format." - selected inFrameSize and/or inPixelType or their combination is not supported by the selected device.

"Unable to decode the Web Camera output stream" - the camera is outputting the images in the format that cannot be decoded by the filter.

List of possible exceptions:

This filter is available on Basic Complexity Level.

• WebCamera_ListDevices – Generates a list of web camera devices available in the system.