Class vl::ICamera#

Public Functions#

Type	Name
virtual StreamId	addStream (const std::shared_ptr< IFrameObserver > & frameObserver, const ImageSettings & imageSettings=ImageSettings()) = 0 Add an observer to the camera output (being called for every inbound frame)
virtual AutoExposureMode	autoExposureMode () const = 0 query the currently active auto exposure mode, used by the camera
virtual std::vector< AutoExposureMode >	autoExposureModesAvailable () const = 0 query the auto exposure modes available on the hardware of this camera
virtual vl::AwbMode	awbMode () const = 0 Query the currently active auto white balancing (AWB) mode.
virtual std::vector< vl::AwbMode >	awbModesAvailable () const = 0 Query all auto white balancing (AWB) modes available on this hardware / camera.
virtual BinningMode	binningMode (void) const = 0 Returns the active binning mode.
virtual std::vector< BinningMode >	binningModesAvailable () const = 0 Query all binning modes available on this hardware / camera.
virtual float	exposure () const = 0 get the current exposure time [µs] used by the camera
virtual vl::Range< float >	exposureLimits () const = 0 Returns the exposure limits of the device [µs].
virtual vl::Range< float >	exposureRange () const = 0 Returns the currently configured auto exposure range [µs].
virtual FlashOutputMode	flashOutputMode () const = 0 Query the currently configured flash output mode (how the camera shall trigger the flash / strobe light)
virtual std::vector< FlashOutputMode >	flashOutputModesAvailable () = 0 Query all flash output modes available on this hardware / camera.
virtual float	frameRate () const = 0 get the camera's frame rate
virtual bool	frameRateAvailable () const = 0 Query if frame rate control is available.
virtual vl::Range< float >	frameRateLimits () const = 0 get the camera's minimum / maximum frame rate
virtual float	gain () const = 0 get the current gain value [dB] used by the camera
virtual vl::Range< float >	gainLimits () const = 0 Returns the gain limits of the device [dB].
virtual vl::Range< float >	gainRange () const = 0 Returns the currently configured auto gain range [dB].
virtual float	gamma () const = 0 Query the currently active (user set) gamma value of the camera.
virtual Frame	grabImage (const ImageSettings & imageSettings=ImageSettings(), int64_t tsNotBefore=vl::timestamp_us()) = 0 grab a single image (synchronous)
virtual void	grabImage (const std::shared_ptr< IFrameObserver > & frameObserver, const ImageSettings & imageSettings=ImageSettings(), int64_t tsNotBefore=vl::timestamp_us()) = 0 grab a single image (asynchronous)
virtual void	loadSettings (const std::string & filepath) = 0 load camera settings from file
virtual void	removeStream (StreamId streamId) = 0 Remove an observer from the camera output.
virtual void	resetToDefaults () = 0 reset camera settings to defaults
virtual bool	running () const = 0 Query the current state (running / not running) of the camera.
virtual void	saveSettings (const std::string & filepath) = 0 write camera settings to file
virtual void	setAutoExposureMode (AutoExposureMode mode) = 0 set a new active auto exposure mode, used by the camera
virtual void	setAwbMode (vl::AwbMode mode) = 0 Set a new auto white balancing (AWB) mode for the camera.
virtual void	setBinningMode (BinningMode const mode) = 0 Set the binning mode.
virtual void	setExposure (float exposure) = 0 set a new exposure time [µs] used by the camera
virtual void	setExposureRange (const vl::Range< float > & range) = 0 Set the auto exposure range (min, max) [µs].
virtual void	setFlashOutputMode (FlashOutputMode mode) = 0 Set new flash output mode for operation (must be contained in vector returned from flashOutputModesAvailable() )
virtual void	setFrameRate (float frameRate) = 0 set the camera's target frame rate
virtual void	setGain (float gain) = 0 set a new gain value [dB] used by the camera
virtual void	setGainRange (const vl::Range< float > & range) = 0 Set the auto gain range (min, max) [dB].
virtual void	setGamma (float gamma) = 0 Set a new gamma value for the camera.
virtual void	setTriggerDelay (float triggerDelay) = 0 set a new trigger delay [µs] for hardware trigger
virtual void	setTriggerMode (TriggerMode mode) = 0 Set new trigger mode for operation (must be contained in vector returned from triggerModesAvailable() )
virtual CameraStatus	start () = 0 Starts the camera operation.
virtual void	stop () = 0 Stops the camera operation.
virtual void	trigger () = 0 Trigger (software trigger) the camera, need to configure software trigger mode first for this to have an effect.
virtual float	triggerDelay () const = 0 Query the currently configured trigger delay.
virtual bool	triggerDelayAvailable () const = 0 Query if trigger delay is available.
virtual vl::Range< float >	triggerDelayLimits () const = 0 get the camera's minimum / maximum trigger delay
virtual TriggerMode	triggerMode () const = 0 Query the currently configured trigger mode.
virtual std::vector< TriggerMode >	triggerModesAvailable () = 0 Query all trigger modes available on this hardware / camera.
virtual	~ICamera () = default

Public Functions Documentation#

function addStream#

Add an observer to the camera output (being called for every inbound frame)

virtual StreamId vl::ICamera::addStream (
    const std::shared_ptr< IFrameObserver > & frameObserver,
    const  ImageSettings & imageSettings=ImageSettings ()
) = 0

Parameters:

frameObserver IFrameObserver used as an observer / callback for incoming frames
imageSettings ImageSettings (post-processing) to be applied for frames for this observer

Returns:

a StreamId for this observer

function autoExposureMode#

query the currently active auto exposure mode, used by the camera

virtual AutoExposureMode vl::ICamera::autoExposureMode () const = 0

Returns:

currently used auto exposure mode

function autoExposureModesAvailable#

query the auto exposure modes available on the hardware of this camera

virtual std::vector< AutoExposureMode > vl::ICamera::autoExposureModesAvailable () const = 0

result can be used for pre-selecting valid values of setAutoExposureMode()

Returns:

std::vector of supported auto exposure modes

function awbMode#

Query the currently active auto white balancing (AWB) mode.

virtual vl::AwbMode vl::ICamera::awbMode () const = 0

Returns:

the AwbMode currently active

function awbModesAvailable#

Query all auto white balancing (AWB) modes available on this hardware / camera.

virtual std::vector< vl::AwbMode > vl::ICamera::awbModesAvailable () const = 0

Can be used for pre-selecting available modes for setAwbMode().

Returns:

a std::vector of AWB modes available

function binningMode#

Returns the active binning mode.

virtual BinningMode vl::ICamera::binningMode (
    void
) const = 0

See also setBinningMode() for detailed explanation!

Returns:

BinningMode currently active

function binningModesAvailable#

Query all binning modes available on this hardware / camera.

virtual std::vector< BinningMode > vl::ICamera::binningModesAvailable () const = 0

Can be used for pre-selecting available modes for setBinningMode().

Returns:

a std::vector of binning modes available

function exposure#

get the current exposure time [µs] used by the camera

virtual float vl::ICamera::exposure () const = 0

Only valid if AutoExposureMode set to ExposureAuto::Off

Returns:

exposure time in µs (float)

function exposureLimits#

Returns the exposure limits of the device [µs].

virtual vl::Range < float > vl::ICamera::exposureLimits () const = 0

These are the hardware limits, the configured exposure()/exposureRange() must be within these limits or will be capped to these limits if lower or higher values are entered. See exposure(), setExposure(), exposureRange(), setExposureRange()

Returns:

Range [µs]

function exposureRange#

Returns the currently configured auto exposure range [µs].

virtual vl::Range < float > vl::ICamera::exposureRange () const = 0

The auto exposure is controlled automatically within this range if the corresponding AutoExposureMode is active. See autoExposureMode(), setAutoExposureMode()

Returns:

Range in [µs]

function flashOutputMode#

Query the currently configured flash output mode (how the camera shall trigger the flash / strobe light)

virtual FlashOutputMode vl::ICamera::flashOutputMode () const = 0

Returns:

FlashOutputMode currently active

function flashOutputModesAvailable#

Query all flash output modes available on this hardware / camera.

virtual std::vector< FlashOutputMode > vl::ICamera::flashOutputModesAvailable () = 0

Returns:

std::vector of FlashOutputMode(s) available

function frameRate#

get the camera's frame rate

virtual float vl::ICamera::frameRate () const = 0

Returns:

frame rate in Hz

function frameRateAvailable#

Query if frame rate control is available.

virtual bool vl::ICamera::frameRateAvailable () const = 0

Returns:

true if camera supports frame rate setting, false otherwise

function frameRateLimits#

get the camera's minimum / maximum frame rate

virtual vl::Range < float > vl::ICamera::frameRateLimits () const = 0

Returns:

frame rate range [Hz]

function gain#

get the current gain value [dB] used by the camera

virtual float vl::ICamera::gain () const = 0

Only valid if AutoExposureMode set to ExposureAuto::Off

Returns:

gain value in dB (float)

function gainLimits#

Returns the gain limits of the device [dB].

virtual vl::Range < float > vl::ICamera::gainLimits () const = 0

These are the hardware limits, the configured gain()/gainRange() must be within these limits or will be capped to these limits if lower or higher values are entered. See gain(), setGain(), gainRange(), setGainRange()

Returns:

Range [db]

function gainRange#

Returns the currently configured auto gain range [dB].

virtual vl::Range < float > vl::ICamera::gainRange () const = 0

The auto gain is controlled automatically within this range if the corresponding AutoExposureMode is active. See autoExposureMode(), setAutoExposureMode()

Returns:

Range [dB]

function gamma#

Query the currently active (user set) gamma value of the camera.

virtual float vl::ICamera::gamma () const = 0

There is no auto-gamma function, thus the value is static until a new value is set via the API.

Returns:

current gamma value as float

function grabImage [1/2]#

grab a single image (synchronous)

virtual Frame vl::ICamera::grabImage (
    const  ImageSettings & imageSettings=ImageSettings (),
    int64_t tsNotBefore=vl::timestamp_us()
) = 0

Blocking call for grabbing an image. This function waits until a new frame with timestamp >= tsNotBefore arrives, applies post-processing and returns the frame to the caller.

Parameters:

imageSettings ImageSettings (post-processing) to be applied for the frame of this single grab
tsNotBefore return only frames with timestamp >= tsNotBefore

function grabImage [2/2]#

grab a single image (asynchronous)

virtual void vl::ICamera::grabImage (
    const std::shared_ptr< IFrameObserver > & frameObserver,
    const  ImageSettings & imageSettings=ImageSettings (),
    int64_t tsNotBefore=vl::timestamp_us()
) = 0

Non-blocking call for grabbing an image. This function installs a frame observer which receives the next frame with timestamp >= tsNotBefore.

Parameters:

frameObserver a shared pointer on an initialized IFrameObserver callback class
imageSettings ImageSettings (post-processing) to be applied for the frame of this single grab
tsNotBefore return only frames with timestamp >= tsNotBefore

function loadSettings#

load camera settings from file

virtual void vl::ICamera::loadSettings (
    const std::string & filepath
) = 0

Parameters:

filepath path to the camera settings file

function removeStream#

Remove an observer from the camera output.

virtual void vl::ICamera::removeStream (
    StreamId streamId
) = 0

Parameters:

streamId a StreamId for this observer (as returned from addStream)

function resetToDefaults#

reset camera settings to defaults

virtual void vl::ICamera::resetToDefaults () = 0

function running#

Query the current state (running / not running) of the camera.

virtual bool vl::ICamera::running () const = 0

Returns:

true if the camera is running, false else

function saveSettings#

write camera settings to file

virtual void vl::ICamera::saveSettings (
    const std::string & filepath
) = 0

Parameters:

filepath path to the camera settings file

function setAutoExposureMode#

set a new active auto exposure mode, used by the camera

virtual void vl::ICamera::setAutoExposureMode (
    AutoExposureMode mode
) = 0

new mode must be supported by the hardware, see autoExposureModesAvailable

Parameters:

mode new AutoExposureMode to be used

function setAwbMode#

Set a new auto white balancing (AWB) mode for the camera.

virtual void vl::ICamera::setAwbMode (
    vl::AwbMode mode
) = 0

White balancing (AWB) is a process to modify the cameras color reproduction. Usually this is used for compensating lighting effects.

Example: The camera shall detect white labels, but the lighting of the scene has an orange tint. As a result, the labels in the raw image are light orange and not completely white anymore. This effect can be reduced, if not completely suppressed by the AWB filter.

This filter may cause unwanted effects, e.g. if the target is colored itself and you have a perfect white light. Here, keeping the AWB off might be the better option.

The AWB is a post-processing function, not affecting the sensor directly.

Parameters:

mode the AwbMode to be used (must be included in awbModesAvailable())

function setBinningMode#

Set the binning mode.

virtual void vl::ICamera::setBinningMode (
    BinningMode const mode
) = 0

Binning is done in hardware or software, while hardware options (camera sensor itself or FPGA / ASIC) are preferred by the API. Binning is done by averaging or summing up the intensity values of adjacent pixels, thus creating less noise and a slightly better signal-to-noise ratio. It allows for: (a) lower noise at given gain or (b) higher gain at constant noise while sacrificing sensor resolution.

Also it is beneficial for applications with low resolution requirements, e.g. a preview mode, where the data load through the image pipeline can be significantly reduced (1/4 for 2x2 and 1/16 for 4x4 binning). Thus the framerate can be increased and images are better transportable via e.g. network.

Example:

| Camera native | 4000x3000 px | | Binning 2x2 | 2000x1500 px | | Binning 4x4 | 1000x 750 px |

Parameters:

mode BinningMode to set

function setExposure#

set a new exposure time [µs] used by the camera

virtual void vl::ICamera::setExposure (
    float exposure
) = 0

Only valid if AutoExposureMode set to ExposureAuto::Off

Parameters:

exposure exposure time in µs (float)

function setExposureRange#

Set the auto exposure range (min, max) [µs].

virtual void vl::ICamera::setExposureRange (
    const  vl::Range < float > & range
) = 0

The auto exposure is controlled automatically within this range if the corresponding AutoExposureMode is active. See autoExposureMode(), setAutoExposureMode()

Parameters:

range Range in µs

function setFlashOutputMode#

Set new flash output mode for operation (must be contained in vector returned from flashOutputModesAvailable() )

virtual void vl::ICamera::setFlashOutputMode (
    FlashOutputMode mode
) = 0

Parameters:

mode the new FlashOutputMode to activate

function setFrameRate#

set the camera's target frame rate

virtual void vl::ICamera::setFrameRate (
    float frameRate
) = 0

The real frame rate also depends on the exposure time, so it can be slower.

Parameters:

frameRate in Hz

function setGain#

set a new gain value [dB] used by the camera

virtual void vl::ICamera::setGain (
    float gain
) = 0

Only valid if AutoExposureMode set to ExposureAuto::Off

Parameters:

gain signal amplification in dB (float)

function setGainRange#

Set the auto gain range (min, max) [dB].

virtual void vl::ICamera::setGainRange (
    const  vl::Range < float > & range
) = 0

The auto gain is controlled automatically within this range if the corresponding AutoExposureMode is active. See autoExposureMode(), setAutoExposureMode()

Parameters:

range Range in dB

function setGamma#

Set a new gamma value for the camera.

virtual void vl::ICamera::setGamma (
    float gamma
) = 0

There is no auto-gamma function, thus the value is static until a new value is set via the API. The gamma function is a post-processing function, not affecting the sensor directly. The gamma value represents an intensity curve, which is applied on the individual pixel brightness.

For detailed explanations, refer to (external link) https://en.wikipedia.org/wiki/Gamma_correction

Parameters:

gamma new value to use

function setTriggerDelay#

set a new trigger delay [µs] for hardware trigger

virtual void vl::ICamera::setTriggerDelay (
    float triggerDelay
) = 0

Parameters:

triggerDelay trigger delay in µs

function setTriggerMode#

Set new trigger mode for operation (must be contained in vector returned from triggerModesAvailable() )

virtual void vl::ICamera::setTriggerMode (
    TriggerMode mode
) = 0

Parameters:

mode the new TriggerMode to activate

function start#

Starts the camera operation.

virtual CameraStatus vl::ICamera::start () = 0

Returns:

CameraStatus::Success on success, CameraStatus::UnknownError else

function stop#

Stops the camera operation.

virtual void vl::ICamera::stop () = 0

function trigger#

Trigger (software trigger) the camera, need to configure software trigger mode first for this to have an effect.

virtual void vl::ICamera::trigger () = 0

Please be aware that triggers might clash (triggering faster than exposure + delay + processing will lead to no action and no new images)

function triggerDelay#

Query the currently configured trigger delay.

virtual float vl::ICamera::triggerDelay () const = 0

Returns:

trigger delay in µs

function triggerDelayAvailable#

Query if trigger delay is available.

virtual bool vl::ICamera::triggerDelayAvailable () const = 0

Returns:

true if camera supports trigger delay setting, false otherwise

function triggerDelayLimits#

get the camera's minimum / maximum trigger delay

virtual vl::Range < float > vl::ICamera::triggerDelayLimits () const = 0

Returns:

trigger delay range [µs]

function triggerMode#

Query the currently configured trigger mode.

virtual TriggerMode vl::ICamera::triggerMode () const = 0

Please also refer to the explanations on the TriggerMode enum!

Returns:

TriggerMode currently active

function triggerModesAvailable#

Query all trigger modes available on this hardware / camera.

virtual std::vector< TriggerMode > vl::ICamera::triggerModesAvailable () = 0

Returns:

std::vector of TriggerMode(s) available

function ~ICamera#

virtual vl::ICamera::~ICamera () = default

The documentation for this class was generated from the following file docs/libvl/build/2.1.0/doxygen/source/vl/camera.h