1.16. MSMediaFoundation

Summary:	MSMediaFoundation
Type:	DataIO
License:	licensed under LGPL
Platforms:	Windows (Vista, 7, 8)
Devices:	USB Plug&Play Cameras, including cameras from The Imaging Source
Author:	M. Gronle, H. Bieger, ITO, University Stuttgart
Version:	1.3.1
Available:	This plugin will be part of the itom setup from itom 1.2.0 on.

1.16.1. Overview

This plugin uses the Microsoft Media Foundation framework (Windows Vista, 7, 8) for capturing supported camera devices (e.g. ordinary USB or integrated cameras).

This driver detects an interal list of connected cameras. The parameter cameraNumber indicates the device to open (until now, there is no mechanism to open the next not yet opened device!). The camera can either be used as colored camera, as gray valued camera or it is also possible to only select one color channel that is mapped to the gray output.

Any detected and supported device can offer multiple framerates and sizes. Use the parameter mediaTypeID to select the right value. Open your device with mediaTypeID = -1 to let the plugin print a list of supported formats (the plugin initialization then stops with a desired error).

1.16.2. Usage

This plugin is able to connect to any USB Plug&Play Cameras as well as other devices that are readable via the Microsoft Media Foundation framework (Windows Vista or higher). Each connected camera is accessible by an auto-increment camera number, starting with 0. Additionally it is possible to choose between different colorModes:

“auto” opens a color camera in color mode (rgba32) and grayscale cameras in a 8bit grayscale mode
“gray” forces cameras to be opened in 8bit grayscale mode, hence, color images are automatically converted to this format
“color” forces the camera to be opened in a color mode
“red”, “green”, “blue” only uses the desired channel, stored in a 8bit grayscale image

Usually cameras can deliver data in different formats (image size and data format). The desired media type can be choosen using the initialization parameter mediaTypeID. Once the mediaTypeID is set to -1 at initialization, a list of all available media types is printed and the initialization aborts afterwards with a warning. Currently, only cameras with the media type RGB24 or YUY2 are supported.

Some camera images are vertically flipped (y-direction). If this is the case, the initialization parameter flipImage can be set to 1.

An example for opening such a camera device is:

cam = dataIO("MSMediaFoundation", cameraNumber = 0, colorMode = "auto", mediaTypeID = 0)

1.16.3. Initialization

The following parameters are mandatory or optional for initializing an instance of this plugin:

cameraNumber: int, optional
consecutive number of the connected camera (starting with 0, default)

Value range: [0, 255], Default: 0

colorMode: str, optional
color mode of camera (auto|color|red|green|blue|gray, default: auto -> color or gray)

Match: [“auto”, “color”, “red”, “green”, “blue”, “gray”], Default: “auto”

mediaTypeID: int, optional
ID of the media format. 0 (default) takes the first from the list (must be MFVideoFormat_RGBA24 as subtype). -1: prints out a list of devices and quits the initialization, other: other index from the list of available types

Value range: [-1, 1000], Default: 0

flipImage: int, optional
if 1 image is vertically flipped (default: 0)

Value range: [0, 1], Default: 0

1.16.4. Parameters

These parameters are available and can be used to configure the MSMediaFoundation instance. Many of them are directly initialized by the parameters of the constructor. During the runtime of an instance, the value of these parameters is obtained by the method getParam, writeable parameters can be changed using setParam.

backlightCompensation: float

backlightCompensation [0..1]

Value range: [0:0.5:1], Default: 0.5

backlightCompensationAuto: int

auto-controlled backlightCompensation (on:1, off:0)

Value range: [0, 1], Default: 0

bpp: int

bpp

Value range: [8, 8], Default: 8

brightness: float

brightness [0..1]

Value range: [0:0.00392157:1], Default: 0.501961

brightnessAuto: int

auto-controlled brightness (on:1, off:0)

Value range: [0, 1], Default: 0

colorMode: str

Match: [“auto”, “color”, “red”, “green”, “blue”, “gray”], Default: “auto”

contrast: float

contrast [0..1]

Value range: [0:0.00392157:1], Default: 0.12549

contrastAuto: int

auto-controlled contrast (on:1, off:0)

Value range: [0, 1], Default: 0

deviceName: str, read-only

name of device

gamma: float

gamma [0..1]

Value range: [0:0.0166667:1], Default: 0.5

gammaAuto: int

auto-controlled gamma (on:1, off:0)

Value range: [0, 1], Default: 0

hue: float

hue [0..1]

Value range: [0:0.00277778:1], Default: 0.5

hueAuto: int

auto-controlled hue (on:1, off:0)

Value range: [0, 1], Default: 0

integrationTime: float

Integrationtime of CCD in seconds

Value range: [0.000244141, 0.125], Default: 0.015625

integrationTimeAuto: int

auto-controlled integration time of CCD (on:1, off:0)

Value range: [0, 1], Default: 1

name: str, read-only

name of the plugin

roi: Tuple[int,int,int,int] (rect [x0,y0,width,height])

ROI (x,y,width,height) [this replaces the values x0,x1,y0,y1]

Height: Value range: [0, 719], Default: [0, 0, 1280, 720]

saturation: float

saturation [0..1]

Value range: [0:0.01:1], Default: 0.64

saturationAuto: int

auto-controlled saturation (on:1, off:0)

Value range: [0, 1], Default: 0

sharpness: float

sharpness [0..1]

Value range: [0:0.142857:1], Default: 0

sharpnessAuto: int

auto-controlled sharpness (on:1, off:0)

Value range: [0, 1], Default: 0

sizex: int, read-only

width of ROI (x-direction)

Value range: [1, 1280], Default: 1280

sizey: int, read-only

height of ROI (y-direction)

Value range: [1, 720], Default: 720

whiteBalance: float

whiteBalance [0..1]

Value range: [0:0.0027027:1], Default: 0.486486

whiteBalanceAuto: int

auto-controlled whiteBalance (on:1, off:0)

Value range: [0, 1], Default: 1

x0: int

first pixel index in ROI (x-direction)

Value range: [0, 1279], Default: 0

x1: int

last pixel index in ROI (x-direction)

Value range: [0, 1279], Default: 1279

y0: int

first pixel index in ROI (y-direction)

Value range: [0, 719], Default: 0

y1: int

last pixel index in ROI (y-direction)

Value range: [0, 719], Default: 719

zoom: float

zoom [0..1]

Value range: [0:0.0333333:1], Default: 0

zoomAuto: int

auto-controlled zoom (on:1, off:0)

Value range: [0, 1], Default: 0

The remaining parameters are depending on the connected device and always consist of the real parameter (double, value mapped between [0,1]) and an integer parameter (“auto”). If the auto-parameter is 0, the corresponding parameter is used to really set the setting, if auto is 1, the camera automatically adjusts the real parameters.

Possible parameters are:

integrationTime
brightness
contrast
saturation
sharpness
hue
focus
gamma
iris
zoom
backlightCompensation.

Each parameter not only has a minimum and maximum value but also a step size. All this is considered by their parameter, also having a specific step size.

1.16.5. Compilation

For compiling this plugin, Windows Vista or later is required as well as an installed Windows SDK. From the Microsoft Windows SDK is it mainly necessary to install “Windows Headers and Libraries”. If the installation fails, one reason is, that you need to uninstall the Redistributable Packages (Microsoft Visual C++) at first, that will be installed with the SDK afterwards.

The location of the installed Windows SDK is then automatically detected by CMake.

1.16.6. Affiliation

This plugin internally uses a modified version of VideoInput, proposed by Evgeny Pereguda and published under http://www.codeproject.com/Articles/559437/Capturing-video-from-web-camera-on-Windows-7-and-8 (Code Project Open License).