Set video capture parameter ‘parameterName’ on video capture device
If ‘value’ is provided, then the parameter is set to ‘value’ and the parameter
is switched to manual control mode. If ‘value’ is left out, then the current
setting of ‘parameterName’ is queried and returned. If ‘parameterName’ starts
with the word ‘Auto’ then the parameter is switched to automatic control, if
supported. In any case, the old value is returned. Type and range of supported
capture parameters varies between different capture devices and operating
systems. Your specific device may only support a subset (or none) of the
available parameters. If you specify an unsupported ‘parameterName’, your
request will be silently ignored, except that the return value is set to DBL_MAX
- a very high number. The following settings are currently available on devices
that support them: ‘Brightness’, ‘Gain’, ‘Exposure’, ‘Shutter’, ‘Sharpness’,
‘Hue’, ‘Saturation’, ‘Gamma’, ‘Iris’, ‘Focus’, ‘Zoom’, ‘Pan’, ‘Tilt’,
‘OpticalFilter’, ‘CaptureSize’, ‘CaptureQuality’, ‘FrameRate’, ‘TriggerDelay’.
The special setting ‘PrintParameters’ prints all features to the command window.
‘GetVendorname’ and ‘GetModelname’ return the name of the device vendor, resp.
the device model name. ‘GetROI’ returns the capture region of interest (ROI),
which can deviate from the ROI requested in Screen(‘OpenVideoCapture’),
depending on the capabilities of the capture device. ‘SetNextCaptureBinSpec=xxx’
Will set the gst-launch line which describes the video capture source to be used
during the next call to Screen(‘OpenVideoCapture’, -9, …); Opening a video
capture device with the special deviceIndex -9 means to create a [GStreamer](GStreamer) bin
and use it as video source. The bin is created by parsing the string passed
here. Use the special ‘capturePtr’ value -1 when setting this bin description,
as this call may need to be made while a capture device is not yet opened, so no
valid ‘capturePtr’ exists. This setting is only honored on the [GStreamer](GStreamer) video
‘GetFramerate’ Returns the nominal capture rate of the capture device.
‘GetBandwidthUsage’ Returns firewire bandwidth used by camera at current
settings in so called bandwidth units. The 1394 bus has 4915 bandwidth units
available per cycle. Each unit corresponds to the time it takes to send one
quadlet at ISO speed S1600. The bandwidth usage at S400 is thus four times the
number of quadlets per packet. In other words, it is complicated. This returns
normalized bus bandwidth usage between 0.0 for 0% and 1.0 for 100%, assuming
4915 units correspond to 100% bus utilization.
‘SetNewMoviename=xxx’ Will change the name of the videofile used for video
recording to xxx. This allows you to change target files for video recordings
without the need to close and reopen the capture device. You must stop capture
though and then restart it after assigning a new filename.
‘SetGStreamerProcessingPipeline=xxx’ This assigns a [GStreamer](GStreamer) gst-launch style
pipeline for use during post-processing of captured video on a libdc1394 capture
device. This is only supported if multi-threaded video capture or recording is
active via recordingflags & 16 and video capture was started with the
‘dropframes’ = 0 setting, so that all captured video is processed by a realtime
thread and pushed through a [GStreamer](GStreamer) processing pipeline. You can build a
processing pipeline of standard [GStreamer](GStreamer) plugins to do something to the video
frames after they’ve been captured but before they are returned via
Screen(‘GetCapturedImage’). The processing does not have any effect on recorded
‘StopAtFramecount’ Set or retrieve the framecounter value at which the camera
should stop its capture operation. By default the camera will empty its queue of
captured images before stopping in free-running mode. In synchronized mode it
will stop at the same framecounter value as the master camera, so all cams
capture the same number of frames. You can override these defaults and specify
an arbitrary value with this setting. However, be careful in synchronized mode
to not specify a target stop count which can’t be reached by a slave camera once
capture stops synchronously on all cameras, otherwise stopping that camera will
be impossible and result in a hard hang of your script!
‘GetCorruptFramecount’ Retrieve current count of corrupted frames received from
a camera. Not all cameras and operating systems can detect and report corrupt
frames. Currently only implemented on libdc1394 capture engine.
‘GetCurrentFramecount’ Retrieve current count of captured frames on a camera.
‘GetFutureMaxFramecount’ Retrieve current maximum count which could be reached
if you’d try to stop capture right now.
‘GetFetchedFramecount’ Retrieve framecount of last frame fetched via
Screen(‘GetCapturedImage’). This is the running counter value at the time the
video frame was captured, essentially a copy of ‘GetCurrentFramecount’ stamped
onto the retrieved video frame.
‘PreferFormat7Modes’ If set to 1, prefer Format-7 video capture modes over other
modes, even if given capture settings for fps and resolution and ROI would allow
otherwise. Format-7 modes are only supported by more high-end cams, but using
them sometimes allows to save bus-bandwidth in addition to the higher
flexibility. If you find yourself starving for bandwidth it may be worth a try
to set this preference. The default setting 0 will use non-Format-7 by default
and only choose Format-7 if this is needed to satisfy given ROI, framerate and
‘DataConversionMode’ What kind of image data should be requested from the camera
and how should it be postprocessed? This controls the tradeoff between required
bus-bandwidth on Firewire/USB busses and processing load on the cpu or gpu of
the host computer, allowing to prioritize one over the other. Possible settings:
0 = Don’t care (Default setting), 1 = Request raw data and return it
unprocessed. 2 = Request raw data but post-process it into a standard format
(Luminance for 1 layer, RGB for 3 layer images), 3 = Request mono/rgb filtered
data from camera and return it unprocessed (as processing should not be needed),
4 = Request mono data but post-process it as if it were raw data (convert to
mono or rgb). Option 1 minimizes bus bandwidth, memory consumption and cpu load
but requires manual post processing by you at some time. Option 2 minimizes bus
bandwidth but not memory consumption and it significantly increases cpu load.
Option 3 minimizes cpu load but maximizes bus bandwidth consumption. The default
option 0 will do whatever is convenient for the attached camera. Option 1 only
makes sense if you request 1 layer data. Option 4 is like option 2, but for
broken cameras which deliver raw data in mono format instead of the
spec-compliant raw format. Option 3 in combination with 1 layer image format can
be used to get raw data from broken cameras which deliver raw data mislabeled as
‘DebayerMethod’ Select method of bayer filtering for conversion of raw sensor
data to RGB images. Different methods represent different tradeoffs between
quality and computation time. Method 0 (the Default) is the fastest and lowest
quality method, whereas higher numbers select higher quality and more cpu load.
Currently values 0 to 7 may be valid for your system. This can be also used with
a ‘capturePtr’ of -1 to set the method used during movie playback.
‘OverrideBayerPattern’ If you choose color image output from raw sensor input,
via one of the ‘DataConversionMode’ settings, then a bayer filter operation must
be performed to convert raw sensor data to RGB data. The filter operation must
know the bayer filter layout of your cameras sensor, but this layout can’t get
auto-detected on all cameras in all modes of operation. If the bayer conversion
aborts due to this, you may need to manually specify the bayer filter pattern to
use with the ‘OverrideBayerPattern’ setting: 0 = RGGB, 1 = GBRG, 2 = GRBG, 3 =
BGGR. This can be also used with a ‘capturePtr’ of -1 to set the method used
during movie playback.
‘SyncMode’ Query or set mode flags for synchronization of the video capture
operation of multiple cameras. This setting is currently only supported with the
dedicated libdc1394 video capture engine (engine id 1), and only for some types
of cameras on some operating systems, specifically as of Nov 2013 it only works
on Linux with firewire cameras. The default setting for ‘SyncMode’ is zero,
which means the camera is free-running, independent of any other camera.
Non-zero values allow to synchronize the capture operation of the camera with
other cameras. Each camera can be either a sync-master, which means it controls
all capture operations (start, stop and timing of capture), or a sync-slave,
which means its timing is controlled by the master camera. There can be at most
one master for synchronized operation. If hardware sync is selected and an
external trigger signal source is used, no master camera is needed. For the
master camera, set the ‘SyncMode’ to 1, for a slave camera set it to 2. There
are three different sync strategies. Select exactly one by adding the value 4, 8
or 16 to the ‘SyncMode’ value of 1 or 2, e.g., 1+4 to select soft-sync mode and
define a soft-sync master:
4 = Soft-Sync: Synchronisation happens purely in software. Works always but less
8 = Bus-Sync: All cameras on a given firewire bus are synchronized down to ~125
usecs. This only works with some cameras which support bus-sync, and usually
only if they are identical camera models with identical settings. Also it only
works for cameras on the same firewire bus, e.g., multiple cams connected to the
same port on the computer via a common firewire hub or via daisy-chaining. Bus
sync is elegant if it works, with no need for extra cabling and electronics.
16 = Hw-Sync: All slave cameras are connected via some dedicated trigger signal
distribution cables to a master camera or to an external trigger signal source.
The master camera or external source drives capture operations and timing of all
connected slave cameras. This is most reliable and accurate, but requires extra
cabling and hardware. If you use this option, also use the trigger configuration
commmands below to configure each camera individually as a master or slave, the
trigger source port, and the type and polarity of the external trigger signal to
In any case, for synchronized operation you must always first start capture on
all participating slave cameras, then finally on the designated master - which
will actually truly start capture of the whole pack. For stopping capture you
first stop the master, which will actually stop capture of the whole setup, then
all slaves to disengage them. If you need cameras to start and perform capture
and recording in sync, but you don’t need them to stop in exact synchrony, you
can add the flag 32 = No lock-step. This allows for some slack and inaccuracy in
stopping capture and recording, but may allow for reduced latency for realtime
applications of video capture.
The way trigger signals are used if ‘SyncMode’ is selected as mode 16 aka
hardware sync, can be controlled via the following settings:
‘TriggerMode’ The way a trigger signal controls camera capture operation: 0 =
Start of exposure is triggered by falling edge of trigger signal, duration of
exposure is controlled by shutter setting. 1 = Exposure starts with falling edge
and stops with rising edge. Modes 2, 3, 4 and 5 are multiple exposure modes.
Modes 6 and 7 are vendor specific modes.
‘TriggerPolarity’ 0 = Active low / falling edge. 1 = Active high / rising edge =
‘TriggerSource’ Which source input port to use: Sources 0 to 3 are available,
corresponding to ports 0 - 3.
‘GetTriggerSources’ Returns a list of supported source ports for given camera.
‘PIO’ Set or get general purpose programmable IO pins on camera. Accepts/returns
a 32-Bit integer value to control up to 32 pins. The value is provided and
expected as a double, ie. a uint32 cast from/to a double.
‘1394BModeActive’ Set or get if Firewire-800 mode aka 1394B mode is active: 1 =
Activate, 0 = Use default classic mode.
‘ISOSpeed’ Get/Set Firewire ISO bus speed: Valid values are 100, 200, 400, 800,
1600, 3200 MBit/s. Default is 400 MBit, higher values require ‘1394BModeActive’
to be set to 1 - and a camera and firewire controller which support 1394B mode
and higher speeds than 400 MBit/s.
‘GetCycleTimer’ Returns the current decoded 32-Bit firewire bus cycle count in
return argument 1 and the GetSecs() time at which that count was queried in the
second return argument: [firewireSeconds, GetSecsSeconds, busSeconds,
busIsoCycles, busTicks]. A busIsoCycles takes 125 usecs, busTicks are 1/24.576
Mhz on top of that. The combination of busSeconds, busIsoCycles and busTicks is
decoded into firewireSeconds for your convenience. Firewire bus time wraps to
zero every 128 seconds.
‘ResetBus’ Resets the firewire or USB bus to which a camera is attached.
‘ResetCamera’ Resets the camera.
‘Temperature’ Retrieves and/or sets the target temperature (returned in 1st
argument). Returns current temperature in 2nd return argument.
‘WhiteBalance’ Get/Set white balance settings: 1st argument is U (in YUV mode)
or Blue value (in RGB mode). 2nd argument is V (in YUV mode) or Red (in RGB
mode). E.g., [u, v] = Screen(‘…’, camera, ‘WhiteBalance’ [, newU, newV]);
‘WhiteShading’ Sets or gets white shading correction point: In/Out values 1, 2
and 3 correspond to Red, Green and Blue, e.g., [r,g,b] = Screen(‘…’, camera,
‘WhiteShading’ [, newR, newG, newB]);
‘BaslerChecksumEnable’ Enable extra CRC checksumming on Basler cameras, to
detect corrupt video frames. Compute intense!
‘BaslerFrameTimestampEnable’ Use Basler cameras builtin timestamping of start of
image exposure to compute extra precise capture timestamps. By default, the time
of reception of a frame in the host computer is timestamped. Doesn’t work on
many Basler cameras though.
‘BaslerFrameCounterEnable’ Retrieve framecounter values from Basler camera
itself instead of using our own software frame counter. Theoretically extra
robust. In practice only useful if your Basler camera allows software controlled
power-cycling, which some Basler cameras do not allow. If the camera doesn’t
allow power-cycling then use of this feature will cause a hard hang of
‘LoadMarkerTrackingPlugin=’ Specify the name of a special markertracker plugin
to load and use during video capture. The name must be the path and filename of
a shared library which implements this plugin. EXPERIMENTAL and subject to
change without notice!
‘SendCommandToMarkerTrackingPlugin=’ Send an ASCII string containing commands to
a loaded markertracker plugin. EXPERIMENTAL!