The Imaging Source Gstreamer Plugins

The following plugins are offered by us. When an element property is also available through the property interface its name in said interface will be explicitly listed as “PI: property-name”.

tcammainsrc

Source element that retrieves images from a device. The tcammainsrc existed as tcamsrc prior to tiscamera 0.13.0. It is used for v4l2, aravis and libusb devices.

tcamsrc properties

fieldname

type

description

serial

string

Serial number of the device that shall be used

type

string

Backend the camera shall use. Available options: v4l2, aravis, libusb, unknown

camera-buffers

int

Number of internal buffers the backend can use.

num-buffers

int

Only send the specified number of images. With ‘num-buffers=200’ tcamsrc will automatically send an EOS and stop the device after 200 buffers have been sent to the pipeline.

drop-incomplete-buffer

bool

When incomplete buffers should be delivered this has to be set to false.

property-state

string

JSON string describing the state of all device properties. See State.

MetaData

Each image buffer the tcamsrc send has associated meta data that contains multiple information concerning the buffer.

The meta object contains a GstStructure which contains all information. This is to ensure extensibility without interfering with user applications.

The following fields are available:

GstTcamMeta fields

fieldname

type

description

frame_count

uint64

number of frames delivered. Starts at 0 with every stream start.

frames_dropped

uint64

number of frames dropped by backend

capture_time_ns

uint64

Timestamp in Nanoseconds when the backend received the image

camera_time_ns

uint64

Timestamp when the device itself captured the image. Only useful for GigE.

framerate

double

framerate the backend has.

is_damaged

bool

Flag noting if the buffer is damaged in any way. Only useful when drop-incomplete-buffer=false.

For timestamp point of reference values look Timestamps. Please be aware that not all GStreamer elements correctly pass GstMeta information through. Elements like bayer2rgb to not copy the meta information. This may affect your usage of elements like tcambin as they can use such elements internally.

Messages

The tcammainsrc element can send multiple possible messages to the GstBus. It is generally recommended to listen for error messages as these will be considered lethal to the video stream and cause a stream stop.

Device lost

An error message containing the string “Device lost” will always be sent when the device does not respond or is not reachable.

The received message will be in the format “Device lost (<SERIAL>)”. For an example of message handling, see the example 09-device-lost.

Note

The following requires GStreamer >= 1.10

To simplify error handling the tcamsrc sends an additional “Device lost” message with a GstStructure attached. This structure contains the string field “serial”. This implies tiscamera was compiled with gstreamer >= 1.10.

/* This code only works when using gstreamer version 1.10 or higher */
GstStructure* struc = gst_message_parse_error_details(message);
const char* lost_serial = gst_structure_get_string(struc, "serial");

tcamsrc

The tcamsrc is a source bin that allows access to all source elements supported by tiscamera. It is a convenience wrapper and offers no additional properties.

As of tiscamera 0.13.0 the supported source elements include tcammainsrc and tcampimipisrc.

tcamautoexposure

Automatically adjust exposure and gain to reach the wished image brightness.

tcamautoexposure properties

Name

Description

Default

Property Interface

auto-exposure

Bool stating if the exposure value will be changed or not.

True

Exposure Auto

auto-gain

Bool stating if the gain value will be changed or not.

True

Gain Auto

auto-iris

Bool stating if the iris value will be changed or not.

True

Iris Auto

brightness-reference

Image brightness that shall be considered ideal. The auto algorithm will try to get within a certain range of this value and adjust exposure/gain to remain within the range. The range is +/- 5 of the brightness reference value. Minimum: 0 Maximum: 255

128

Brightness Reference

exposure-min

Minimum Exposure Value the element is allowed to set. If the user defined value is lower than the camera internal value the camera minimum will be used. If the user defined value is not a possible value it will be rejected.

Minimum of the camera

Exposure Auto Min

exposure-max

Maximum Exposure Value the element is allowed to set. If the user defined value is higher than the camera internal maximum the camera maximum will be used. If the user defined value is higher than the value that is possible with the current framerate the value will be set. This can cause problems. Default: Highest value the framerate allows i.e. 30 fps => 1000000 / (30 / 1) = 33333.3 This is a maximum exposure time of 33333 micro seconds.

Maximum of the camera / Exposure time the format allows

Exposure Auto Max

gain-min

Minimum Gain Value the element is allowed to set. If the user defined value is lower than the camera internal value the camera minimum will be used. If the user defined value is not a possible value it will be rejected.

Minimum of the camera

Gain Auto Min

gain-max

Maximum Gain Value the element is allowed to set.

Maximum of the camera

Gain Auto Max

iris-min

Minimum iris value the element is allowed to set. Some cameras suggest a minimum value for auto algorithms that is higher than the actual minimal value. This value will be used when available.

Minimum value of the camera.

Iris Auto Min

iris-max

Maximum iris value the element is to set.

Maximum of the camera.

Iris Auto Max

The following properties are related to the region of interest. The region of interest is a section of the entire image that shall be used by the element for its auto algorithm. Per default the region equals the entire image unless the user defines these values.

tcamautoexposure roi properties

Name

Values

TcamProp

Description

left

Default: 0

Exposure ROI Left

X coordinate of the upper left corner. Values are in image pixel.

top

Default: 0

Exposure ROI Top

Y coordinate of the upper left corner. Values are in image pixel.

width

Default: image width
Minimum: 8
Maximum: image width - exposure roi left

Exposure ROI Width

Width the ROI shall have.

height

Default: image height
Minimum: 8
Maximum: image height - exposure roi top

Exposure ROI Height

Height the ROI shall have.

tcamwhitebalance

Color correction for bayer images.

GstTcamMeta fields

fieldname

type

description

red

int

Red Channel

green

int

Green Channel

blue

int

Blue Channel

auto

bool

Bool stating if the module should automatically adjust the rgb values or if static values should be used to allow user defined whitebalance. _Default_: True PI: Whitebalance Auto

module-enabled

bool

Bool stating if whitebalance values will be applied or note Default : True PI: Exposure Auto

camera-whitebalance

bool

Bool stating if the whitebalance values shall be applied via software or in the device. Currently only the 72 USB cameras support this. Default: False PI: Camera Whitebalance

tcamautofocus

Allows for cameras with focus elements to automatically adjust focus.

  • auto - Activate an auto focus run by setting this property to true. It will be set to false once the run is finished. Default: False PI: Focus Auto

The following properties are related to the region of interest. The region of interest is a section of the entire image that shall be used by the element for its auto algorithm. Per default the region equals the entire image unless the user defines these values.

tcamautoexposure properties

Name

Values

TcamProp

Description

left

Default: 0

Focus ROI Left

X coordinate of the upper left corner. Values are in image pixel.

top

Default: 0

Focus ROI Top

Y coordinate of the upper left corner. Values are in image pixel.

width

Default: image width
Minimum: 8
Maximum: image width - focus roi left

Focus ROI Width

Width the ROI shall have.

height

Default: image height
Minimum: 8
Maximum: image height - focus roi top

Focus ROI Height

Height the ROI shall have.

tcamdutils

Closed source optional transformation and interpretation filter. Allows the transformation of bayer 12-bit and 16-bit formats to BGRx 64-Bit. Implements features like HDR. Optimized for x64 platforms.

tcambiteater

Removed with tiscamera 0.13.0. Functionality is now included in tiscamera-dutils

tcambin

Wrapper around all the previous elements, allowing for an easy all-in-one handling. The tcambin will prefer bayer 8-bit over bayer 12/16-bit. Currently tcamdutils are required for a correct conversion of these formats. Since tcamdutils are an optional module its existence can not be expected. To ensure identical behavior whether or not tcamdutils are installed, bayer 8-bit will be preferred unless the user explicitly specifies bayer 12/16-bit for the source through the property ‘device-caps’. The selected caps for the internal tcamscr will be propagated as a gstbus message with the prefix “Working with src caps: “. The offered caps are the sum of unfiltered camera caps and caps that will be available through conversion elements like bayer2rgb.

The format that can always be expected to work is BGRx. All other formats depend on the used device.

TcamSrc properties

fieldname

type

description

serial

string

Serial number of the device that shall be used

type

string

Backend the camera shall use. Available options: v4l2, aravis, libusb, unknown

device-caps

string

String that overwrites the auto-detection of the gstreamer caps that will be set for the internal tcamsrc

use-dutils

bool

Use the tcamdutils element, if present. Default: True

property-state

string

JSON string describing the state of all device properties. See State.

Internal pipelines will always be created when the element state is set to PAUSED.

tcamsrc -> capsfilter -> tcamautoexposure -> tcamwhitebalance -> bayer2rgb

tcamsrc -> capsfilter -> tcamdutils

tcamsrc -> capsfilter -> jpegdec

tcamsrc -> capsfilter

Should the selected camera offer focus properties the element tcamautofocus will also be included.

Elements that offer auto algorithms (auto exposure/focus) will only be included when the camera itself does not offer these functions.