SDK Driver Camera Class

class Metavision::Camera

Main class for the camera interface.

Public Functions

Camera()

Constructor.

Creates an uninitialized camera instance.

Camera(Camera &camera) = delete

Copy constructor.

A Camera object can not be copy-constructed, but it can be move-constructed.

See also

Camera(Camera &&camera);

Camera(Camera &&camera)

Move constructor.

A Camera can not be copied, but it can be move-constructed from another instance.

Camera &operator=(Camera &camera) = delete

Copy assignment.

A Camera object can not be copy-assigned, but it can be move-assigned.

See also

Camera & operator=(Camera &&camera);

Camera &operator=(Camera &&camera)

Move assignment.

A Camera can not be copied, but it can be move-assigned from another instance.

~Camera(): Destructor.

RawData &raw_data()

Gets class to handle RAW data from the camera.

Throws: CameraException – if the camera has not been initialized.

CD &cd()

Gets class to handle CD events.

Throws: CameraException – if the camera has not been initialized.

ExtTrigger &ext_trigger()

Gets class to handle External Triggers events.

Throws: CameraException – if the camera has not been initialized.

TriggerOut &trigger_out()

Gets class to handle trigger out signal.

Throws

CameraException – if the camera has not been initialized.
CameraException – in case of failure (for example if camera runs from an offline source).

ERCCounter &erc_counter()

Gets class to handle ERCCounter events.

Throws: CameraException – if the camera has not been initialized.

FrameHisto &frame_histo()

Gets class to handle RawEventFrameHisto.

Throws: CameraException – if the camera has not been initialized.

FrameDiff &frame_diff()

Gets class to handle RawEventFrameDiff.

Throws: CameraException – if the camera has not been initialized.

Roi &roi()

Gets class to handle Roi on the sensor.

Throws: CameraException – in case of failure (for instance if the camera is not initialized or the camera is running from an offline source).

AntiFlickerModule &antiflicker_module()

Gets class to handle AFK on the hardware side.

Throws: CameraException – in case of failure (for instance if the camera is not initialized or the camera is running from an offline source).

ErcModule &erc_module()

Gets class to handle Event Rater Controller on the hardware side.

Throws: CameraException – in case of failure (for instance if the camera is not initialized or the camera is running from an offline source).

EventTrailFilterModule &event_trail_filter_module()

Gets class to handle STC or TRAIL Event Trail Filter Module on the hardware side.

Throws: CameraException – in case of failure (for instance if the camera is not initialized or the camera is running from an offline source).

CallbackId add_runtime_error_callback(RuntimeErrorCallback error_callback)

Registers a callback that will be called when a runtime error occurs.

When a camera runtime error occurs, the camera thread is left and events are no longer sent. You are notified by this callback whenever this happens.

See also

RuntimeErrorCallback

Warning

It is forbidden to call the stop from a runtime error callback.

Throws: CameraException – if the camera has not been initialized.
Parameters: error_callback – The error callback to call
Returns: ID of the added callback

bool remove_runtime_error_callback(CallbackId callback_id)

Removes a previously registered callback.

See also

CD::add_callback

See also

ExtTrigger::add_callback

Parameters: callback_id – Callback ID
Returns: true if the callback has been unregistered correctly, false otherwise.

CallbackId add_status_change_callback(StatusChangeCallback status_change_callback)

Registers a callback that will be called when the camera status changes.

The callback will be called with the new status of the Camera as a parameter, when the camera is started or stopped (by a call to stop or when no more events are available in a recording).

See also

StatusChangeCallback

Warning

It is forbidden to call the stop from the status callback.

Parameters: status_change_callback – The status change callback to call
Returns: ID of the added callback

bool remove_status_change_callback(CallbackId callback_id)

Removes a previously registered callback.

Parameters: callback_id – Callback ID
Returns: true if the callback has been unregistered correctly, false otherwise.

Biases &biases()

Gets class to handle camera biases.

Throws: CameraException – in case of failure (for example if camera runs from an offline source).

OfflineStreamingControl &offline_streaming_control()

Gets class to control offline streaming.

Throws: CameraException – if the camera has not been initialized or if the feature is not available.

const Geometry &geometry() const

Gets the device’s geometry.

Throws: CameraException – if the camera has not been initialized.

const CameraGeneration &generation() const

Gets the device’s generation.

Throws: CameraException – if the camera has not been initialized.

bool start()

Starts the camera from the given input source.

It will start polling events from the source and calling specified events callbacks.

It has no effect if the start function has been already called and not the stop function.

See also

CD::add_callback

See also

ExtTrigger::add_callback

Throws: CameraException – if the camera has not been initialized.
Returns: true if the camera started successfully, false otherwise. Also returns false, if the camera is already started.

bool is_running()

Checks if the camera is running or there are data remaining from an offline source.

If the source is online, it always returns true unless the stop function has been called.

If the input is offline (from a file), it returns false whenever no data are remaining in the input file.

Returns: true if the camera is running or there are data remaining from an offline source, false otherwise.

bool stop()

Stops polling events from the camera or from the file.

Stops ongoing streaming.

Throws: CameraException – if the camera has not been initialized.
Returns: true if the camera instance has been stopped successfully, false otherwise. If the camera was not running, this function returns false.

bool start_recording(const std::string &file_path)

Records data from camera to a file at the specified path.

The function creates a new file at the given file_path or overwrites the already existing file.

In case of an offline input source, the function can be used to split the file and record only a portion of it.

Note

This functions is the recommended way to save recording with SDK driver. It uses a separate thread to write the file for efficiency, so it will not slow down the decoding thread as opposed to I_EventsStream::log_raw_data and I_EventsStream::stop_log_raw_data It also enables writing to supported formats other than RAW file, although the writing speed will probably decrease for those formats It can also be called several times with different paths to record the stream to multiple files at the same time

Note

For more control over the way the data is recorded and to select with precision which events will be recorded, you may directly use the API provided by EventFileWriter and its inherited classes For more information, refer to the metavision_file_cutter sample

Warning

Calling this function will overwrite the file at the path file_path if it already exists.

Throws: CameraException – if the camera has not been initialized.
Parameters: file_path – Path to the file containing the recorded data
Returns: true if recording could be started, false otherwise

bool stop_recording(const std::string &file_path = std::string())

Stops recording data from camera to the specified path.

This function stops recording data to the file at the given file_path.

If the file_path is empty, all recordings of the current camera stream are stopped.

Parameters: file_path – Path to the file containing the recorded data. If empty, all ongoing recordings are stopped.
Throws: CameraException – if the camera has not been initialized.
Returns: true if recording could be stopped, false otherwise

const CameraConfiguration &get_camera_configuration() const

Returns CameraConfiguration of the camera that holds the available camera properties (serial, systemID, format of events, etc.)

Read-only structure.

See also

CameraConfiguration

const std::unordered_map<std::string, std::string> &get_metadata_map() const

Returns a dictionary of the camera metadata if available (e.g from a file which contains manually added comments)

Read-only structure.

timestamp get_last_timestamp() const

Gets the last decoded timestamp.

Warning

If no event decoding callback has been set, this functions returns -1

Returns: timestamp Last decoded timestamp

bool save(const std::string &path) const

Saves the camera settings to a given file.

Parameters: path – The path of the file to save the camera settings to
Returns: true on success

bool load(const std::string &path)

Loads the camera settings from a given file.

Parameters: path – The path of the file to load the camera settings from
Returns: true on success

Device &get_device()

Gets corresponding Device in HAL library.

This Device retrieved can then be used to call the different facilities of the camera. for example: camera.get_device()->get_facility<Metavision::I_TriggerIn>()->enable(channel_id) or: camera.get_device()->get_facility<Metavision::I_Monitoring>()->get_temperature())

Returns: The Device used internally by the class Camera

const Device &get_device() const

Gets corresponding Device in HAL library.

This Device retrieved can then be used to call the different facilities of the camera. for example: camera.get_device()->get_facility<Metavision::I_TriggerIn>()->enable(channel_id) or: camera.get_device()->get_facility<Metavision::I_Monitoring>()->get_temperature())

Returns: The Device used internally by the class Camera

Private &get_pimpl(): For internal use.

Camera(Private*): For internal use.

Public Static Functions

static AvailableSourcesList list_online_sources()

Lists available sources for the online mode.

Returns: AvailableSourcesList structure containing available cameras (plugged on the system) along with their serial numbers.

static Camera from_first_available()

Initializes a camera instance from the first available camera plugged on the system.

Open the first available camera following at first EMBEDDED and then USB order.

Please note that remote cameras will not be opened with this function. To do that, please specify the OnlineSourceType and use the from_source function, or else specify the serial number and use the from_serial function.

Serial numbers and types of available sources can be found with list_online_sources function.

Throws: CameraException – in case of initialization failure.

static Camera from_first_available(const DeviceConfig &config)

Initializes a camera instance from the first available camera plugged on the system.

Open the first available camera following at first EMBEDDED and then USB order.

Please note that remote cameras will not be opened with this function. To do that, please specify the OnlineSourceType and use the from_source function, or else specify the serial number and use the from_serial function.

Serial numbers and types of available sources can be found with list_online_sources function.

Throws: CameraException – in case of initialization failure.
Parameters: config – Configuration used to open the camera This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static Camera from_source(OnlineSourceType input_source_type, uint32_t source_index = 0)

Initializes a camera instance from an OnlineSourceType and a source index.

Open the source_index camera of online input_source_type if available from list_online_sources.

By default, it opens the first available camera listed by list_online_sources of type input_source_type.

Serial numbers and types of available sources can be found with list_online_sources function.

Throws

CameraException – if the camera corresponding to the input source type and the source index has not been found.

Parameters

input_source_type – OnlineSourceType
source_index – Index of the source in the list of available online sources

Returns

Camera instance initialized from the source

static Camera from_source(OnlineSourceType input_source_type, const DeviceConfig &config, uint32_t source_index = 0)

Initializes a camera instance from an OnlineSourceType and a source index.

Open the source_index camera of online input_source_type if available from list_online_sources.

By default, it opens the first available camera listed by list_online_sources of type input_source_type.

Serial numbers and types of available sources can be found with list_online_sources function.

Throws

CameraException – if the camera corresponding to the input source type and the source index has not been found.

Parameters

input_source_type – OnlineSourceType
config – Configuration used to open the camera
source_index – Index of the source in the list of available online sources

Returns

Camera instance initialized from the source This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static Camera from_serial(const std::string &serial)

Initializes a camera instance from a ‘serial’ number.

Serial numbers of available sources can be found by with list_online_sources function.

If ‘serial’ is an empty string, the function works as the main constructor.

Throws: CameraException – if the camera with the input serial number has not been found.
Parameters: serial – Serial number of the camera
Returns: Camera instance initialized from the serial number

static Camera from_serial(const std::string &serial, const DeviceConfig &config)

Initializes a camera instance from a ‘serial’ number.

Throws

CameraException – if the camera with the input serial number has not been found.

Parameters

serial – Serial number of the camera
config – Configuration used to open the camera

Returns

Camera instance initialized from the serial number This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

static Camera from_file(const std::string &file_path, const FileConfigHints &hints = FileConfigHints())

Initializes a camera instance from a file.

Throws

CameraException – in case of initialization failure.

Parameters

file_path – Path to the file
hints – Hints expressing how the file should be read, for more details see FileConfigHints

Returns

Camera instance initialized from the input file

enum class Metavision::OnlineSourceType : short

Online camera type input sources: USB, embedded, remote.

Values:

enumerator EMBEDDED: Data from an embedded event-based camera.

enumerator USB: Data from an USB event-based camera.

enumerator REMOTE: Data from a remote event-based camera.

enum class Metavision::CameraStatus : short

Values:

enumerator STARTED: Camera is started, see Camera::start and Camera::is_running.

enumerator STOPPED: Camera is stopped, see Camera::stop and Camera::is_running.

struct CameraConfiguration

Struct with the current camera configuration.

In case of an online source, the fields apply to the current online source. In case of an offline source, the fields correspond to the online source used to record the data.