Video source run time properties

Previous tutorial: Detection of 1D linear bar codes


Starting from version 1.2.5, Computer Vision Sandbox provides support for new type of plug-ins' properties - run time properties, which can be provided by video source plug-ins for now. The reason for those is the fact that some video sources (cameras) may provide additional properties, which can be configured only when the device is running, but not at the initial configuration phase of the corresponding plug-in.

For example, let's have a look at configuration of Local Capture Device plug-in, which provides access to devices supporting DirectShow API (USB/integrated cameras, etc.). The initial configuration allows to choose the target device to use, its resolution and frame rate if supported. Although all these values are not static and require some code to be executed to obtain them, this all is done without starting the actual device. Let's call them as configuration properties - properties, which are required to configure device so it can be started.

However, the configuration properties are not the only properties, which can be exposed by a video source. For example, some DirectShow devices may provide properties to set values like brightness, contrast, saturation, etc. As it was just said, some devices may provide, but some may not. Also, different devices may support different ranges for their properties (minimum/maximum values), different default values, etc. In many cases all this cannot be obtained without talking to the video source itself. Instead, the device may need to be running to resolve what is supported. More of it, it is not always intuitive to change some properties of a camera, without being able see the effect of the change.

To address the above issues, the run time properties were introduced - properties, which can be set while a video source is running. To get access to them, it is required to use camera's context menu, available when running an individual camera or a sandbox. If the corresponding plug-in supports any run time properties, the context menu will have the "Camera settings" option, which leads to properties configuration form:

The run time properties form really allows changing all properties at run time - once a property is changed and takes effect, the video produced by the corresponding camera should update as the result of the change. After properties are changed to achieve the desired result, the new values can be persisted in the project object of the video source, so the next time it starts, it gets the configured values.

Changing run time properties of video sources can be a really useful feature in many applications. Before the 1.2.5 version of Computer Vision Sandbox, it was required to use image processing filter plug-ins to adjust things like brightness, contrast, saturation, sharpness, etc. This all was using CPU time to do the necessary job. With the run time properties of video sources, however, the job is usually shifted to the camera's hardware, which saves host's CPU usage and power consumption. In addition, some cameras/plug-ins may provide configuration properties, which effect may not be easily achieved with the collection of image processing plug-ins provided.

Although it is nice to have the option of changing run time properties manually and observe the immediate result, in some cases it may be required to set them from a script running for a certain video source. The scripting API level 6 introduces the new Host.GetVideoSource() function, which allows getting access to the video source's object, for which the script is running. Once the object is obtained, its run time properties can be set in the same way as any other property:

videoSource = Host.GetVideoSource( )

function Main( )
    -- check if it is time to change brightness
    if ... then
        -- set brightness to whatever value we need
        videoSource:SetProperty( 'brightness', 60 )
    -- do the rest of image processing if needed or leave as is

Note: depending on the video source in use and its implementation, changing run time properties on every new frame may not be ideal. Setting cameras properties requires communication to the device, which may have its own latency - in some cases even bigger, than running a simple image processing routine. So, don't forget to do some basic profiling to get an idea of how much time is taken by video processing steps.


Next tutorial: Device plug-ins