Back to FabImage Studio website

You are here: Start » Filter Reference » Camera Support » WebCamera » WebCamera_GrabImage

WebCamera_GrabImage

Basic

Module: ThirdParty

Captures a frame from a camera using Direct Show interface.

Applications

Not recommended for industrial operation.
Name Type Range Description
Input value inCameraIndex Integer* 0 - + Index number of camera device to connect with
Input value inFrameSize Size* Requested size of source frame in pixels selected from camera output formats
Input value inPixelType WebCameraInputFormat Requested specific pixel type from camera (may change image quality)
Input value inExposure Integer* Manual (fixed) exposure time in log base 2 seconds
Input value inExposureAuto Bool Activates the automatic exposure time control by the camera
Input value inGain Integer* Gain value
Input value inBrightness Integer* Image brightness setting (black level value)
Input value inWhiteBalance Integer* Manual (fixed) white balance setting
Input value inWhiteBalanceAuto Bool Activates the automatic white balance control by the camera
Output value outFrame Image Captured frame

Description

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, in numeric order provided by the operating system. Leaving this input 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.

Examples

Description of usage of this filter can be found in examples and tutorial: Dynamic Template Matching, Starting Notepad with Execute filter, Turning computer off using Execute.

Remarks

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

Parallel execution

This filter cannot be placed in multiple Workers.

Errors

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

"Unable to connect with chosen Web Camera." - no compatible video grabber device is present in the system or provided inCameraIndex is not a valid device number.

"Unable to connect with chosen 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.

Complexity Level

This filter is available on Basic Complexity Level.