Ocean
Ocean::Devices::Measurement Class Reference

This class implements the base class for all devices providing measurement samples. More...

Inheritance diagram for Ocean::Devices::Measurement:

Data Structures

class  ObjectMapper
 This class implements a helper class to simplify the mapping between internal object ids (of the actual tracking implementation) and extern object ids (of the device system). More...
 
class  Sample
 Definition of a sample holding a measurement. More...
 
class  SampleEventSubscription
 This class manages the lifetime of an event subscription for sample events. More...
 

Public Types

enum  InterpolationStrategy { IS_INVALID , IS_TIMESTAMP_NEAREST , IS_TIMESTAMP_INTERPOLATE }
 Definition of individual interpolation strategies for samples. More...
 
typedef unsigned int ObjectId
 Definition of an object id. More...
 
typedef std::vector< ObjectIdObjectIds
 Definition of a vector holding object ids. More...
 
typedef std::unordered_set< ObjectIdObjectIdSet
 Definition of an unordered set holding object ids. More...
 
typedef std::unordered_map< std::string, ValueMetadata
 Definition of an unordered map mapping keys to values. More...
 
typedef ObjectRef< SampleSampleRef
 Definition of an object reference for samples. More...
 
typedef Callback< void, const Measurement *, const SampleRef & > SampleCallback
 Definition of a callback function to subscribe for new measurement sample events. More...
 
- Public Types inherited from Ocean::Devices::Device
enum  MajorType : uint32_t { DEVICE_INVALID = 0u , DEVICE_MEASUREMENT = (1u << 0u) , DEVICE_SENSOR = (1u << 1u) | DEVICE_MEASUREMENT , DEVICE_TRACKER = (1u << 2u) | DEVICE_MEASUREMENT }
 Definition of all major device types. More...
 
enum  MinorType : uint32_t { MINOR_INVALID = 0u }
 Base definition of a minor type. More...
 

Public Member Functions

size_t sampleCapacity () const
 Returns the capacity of the internal sample container. More...
 
bool setSampleCapacity (const size_t capacity)
 Sets the capacity of the internal sample container. More...
 
virtual SampleRef sample () const
 Returns the most recent sample. More...
 
virtual SampleRef sample (const Timestamp timestamp) const
 Returns the sample with a specific timestamp. More...
 
virtual SampleRef sample (const Timestamp &timestamp, const InterpolationStrategy interpolationStrategy) const
 Returns the sample best matching with a specified timestamp. More...
 
SampleEventSubscription subscribeSampleEvent (SampleCallback &&callback)
 Subscribes a callback event function for new measurement sample events. More...
 
ObjectId objectId (const std::string &description) const
 Returns the object id for an object description. More...
 
Strings objectDescriptions () const
 Returns descriptions of all objects currently available. More...
 
std::string objectDescription (const ObjectId objectId) const
 Returns the description of one object of this measurement. More...
 
- Public Member Functions inherited from Ocean::Devices::Device
const std::string & name () const
 Returns the name of this device. More...
 
virtual const std::string & library () const =0
 Returns the name of the owner library. More...
 
virtual bool isStarted () const
 Returns whether this device is active. More...
 
bool isValid () const
 Returns whether this device is valid. More...
 
bool isExclusive () const
 Returns whether this device can be use exclusively. More...
 
virtual bool start ()
 Starts the device. More...
 
virtual bool pause ()
 Pauses the device. More...
 
virtual bool stop ()
 Stops the device. More...
 
virtual bool setParameter (const std::string &parameter, const Value &value)
 Sets an abstract parameter of this device. More...
 
virtual bool parameter (const std::string &parameter, Value &value)
 Returns an abstract parameter of this device. More...
 
DeviceType type () const
 Returns the major and minor type of this device. More...
 

Static Public Member Functions

static constexpr ObjectId invalidObjectId ()
 Returns an invalid object id. More...
 
- Static Public Member Functions inherited from Ocean::Devices::Device
static std::string translateMajorType (const MajorType majorType)
 Translates the major devices type to a readable string. More...
 
static MajorType translateMajorType (const std::string &majorType)
 Translates the major devices type from a readable string to a value. More...
 

Protected Types

typedef std::map< Timestamp, SampleRefSampleMap
 Definition of a map holding the most recent samples. More...
 
typedef std::unordered_map< std::string, ObjectIdObjectDescriptionToIdMap
 Definition of an unordered map mapping descriptions to unique object ids. More...
 
typedef std::unordered_map< ObjectId, std::string > ObjectIdToDescriptionMap
 Definition of an unordered map mapping unique object ids to descriptions. More...
 
typedef std::unordered_map< SubscriptionId, SampleCallbackSampleSubscriptionMap
 Definition of a map mapping subscription ids to event sample callback functions. More...
 
- Protected Types inherited from Ocean::Devices::Device
typedef unsigned int SubscriptionId
 Definition of a subscription id for event callbacks. More...
 

Protected Member Functions

 Measurement (const std::string &name, const DeviceType type)
 Creates a new measurement object. More...
 
 ~Measurement () override
 Destructs a measurement object. More...
 
void postNewSample (const SampleRef &newSample)
 Posts a new measurement sample. More...
 
ObjectId addUniqueObjectId (const std::string &description)
 Creates a unique object id for a new object (e.g., a tracking object like an image, a marker, or a location). More...
 
void unsubscribeSampleEvent (const SubscriptionId subscriptionId)
 Unsubscribes a sample event callback function. More...
 
- Protected Member Functions inherited from Ocean::Devices::Device
 Device (const Device &device)=delete
 Disabled copy constructor. More...
 
 Device (const std::string &name, const DeviceType type)
 Creates a new device by is name. More...
 
virtual ~Device ()
 Destructs a device. More...
 
Deviceoperator= (const Device &device)=delete
 Disabled copy operator. More...
 

Protected Attributes

Lock samplesLock_
 Sample lock. More...
 
Lock subscriptionLock_
 Subscription lock. More...
 
- Protected Attributes inherited from Ocean::Devices::Device
std::string deviceName
 Name of this device. More...
 
DeviceType deviceType
 Major and minor type of this device. More...
 
bool deviceIsValid
 Flag determining whether this device is valid. More...
 
Lock deviceLock
 Device lock. More...
 

Private Attributes

SampleMap sampleMap_
 The most recent measurement samples. More...
 
size_t sampleCapacity_
 The maximal number of samples this measurement object can hold. More...
 
SampleSubscriptionMap sampleSubscriptionMap_
 Map holding all sample event subscriptions. More...
 
SubscriptionId nextSampleSubscriptionId_ = SubscriptionId(invalidSubscriptionId() + 1u)
 The subscription id of the next event subscription. More...
 
ObjectDescriptionToIdMap objectDescriptionToIdMap_
 The map mapping object descriptions to object ids. More...
 
ObjectIdToDescriptionMap objectIdToDescriptionMap_
 The map mapping object ids to descriptions. More...
 

Additional Inherited Members

- Static Protected Member Functions inherited from Ocean::Devices::Device
static constexpr SubscriptionId invalidSubscriptionId ()
 Returns an invalid subscription id. More...
 

Detailed Description

This class implements the base class for all devices providing measurement samples.

Each measurement holds a container holding several most recent samples provided by the device.
Thus, depending on the number of stored samples a specific sample can be requested.

Member Typedef Documentation

◆ Metadata

typedef std::unordered_map<std::string, Value> Ocean::Devices::Measurement::Metadata

Definition of an unordered map mapping keys to values.

◆ ObjectDescriptionToIdMap

typedef std::unordered_map<std::string, ObjectId> Ocean::Devices::Measurement::ObjectDescriptionToIdMap
protected

Definition of an unordered map mapping descriptions to unique object ids.

◆ ObjectId

Definition of an object id.

◆ ObjectIds

Definition of a vector holding object ids.

◆ ObjectIdSet

Definition of an unordered set holding object ids.

◆ ObjectIdToDescriptionMap

typedef std::unordered_map<ObjectId, std::string> Ocean::Devices::Measurement::ObjectIdToDescriptionMap
protected

Definition of an unordered map mapping unique object ids to descriptions.

◆ SampleCallback

Definition of a callback function to subscribe for new measurement sample events.

The first parameter is the Measurement object sending the sample The second parameter is the sample

◆ SampleMap

Definition of a map holding the most recent samples.

◆ SampleRef

Definition of an object reference for samples.

◆ SampleSubscriptionMap

Definition of a map mapping subscription ids to event sample callback functions.

Member Enumeration Documentation

◆ InterpolationStrategy

Definition of individual interpolation strategies for samples.

Enumerator
IS_INVALID 

An invalid strategy.

IS_TIMESTAMP_NEAREST 

The sample with nearest/closest timestamp is used.

IS_TIMESTAMP_INTERPOLATE 

The sample is interpolated based on two samples.

Constructor & Destructor Documentation

◆ Measurement()

Ocean::Devices::Measurement::Measurement ( const std::string &  name,
const DeviceType  type 
)
protected

Creates a new measurement object.

Parameters
nameThe name of the measurement device
typeMajor and minor device type of the device

◆ ~Measurement()

Ocean::Devices::Measurement::~Measurement ( )
overrideprotected

Destructs a measurement object.

Member Function Documentation

◆ addUniqueObjectId()

ObjectId Ocean::Devices::Measurement::addUniqueObjectId ( const std::string &  description)
protected

Creates a unique object id for a new object (e.g., a tracking object like an image, a marker, or a location).

Parameters
descriptionThe description of the new object, must be valid
Returns
The unique id which is unique across all devices

◆ invalidObjectId()

constexpr Measurement::ObjectId Ocean::Devices::Measurement::invalidObjectId ( )
staticconstexpr

Returns an invalid object id.

Returns
Id of an invalid object

◆ objectDescription()

std::string Ocean::Devices::Measurement::objectDescription ( const ObjectId  objectId) const

Returns the description of one object of this measurement.

Parameters
objectIdThe id of the object for which the description will be returned, must be valid
Returns
The description of the object, empty if the object is unknown

◆ objectDescriptions()

Strings Ocean::Devices::Measurement::objectDescriptions ( ) const

Returns descriptions of all objects currently available.

Returns
All object descriptions
See also
objectId().

◆ objectId()

ObjectId Ocean::Devices::Measurement::objectId ( const std::string &  description) const

Returns the object id for an object description.

Parameters
descriptionThe description for which the object id will be returned
Returns
The object id, an invalid id if the description is not known
See also
objectDescriptions().

◆ postNewSample()

void Ocean::Devices::Measurement::postNewSample ( const SampleRef newSample)
protected

Posts a new measurement sample.

Parameters
newSampleNew sample to post

◆ sample() [1/3]

virtual SampleRef Ocean::Devices::Measurement::sample ( ) const
virtual

Returns the most recent sample.

Returns
Most recent sample as object reference

◆ sample() [2/3]

virtual SampleRef Ocean::Devices::Measurement::sample ( const Timestamp timestamp,
const InterpolationStrategy  interpolationStrategy 
) const
virtual

Returns the sample best matching with a specified timestamp.

In case, the given timestamp does not fit to an existing sample, the resulting sample will be based on the specified interpolation strategy.

Parameters
timestampThe timestamp for which a sample will be determined, must be valid
interpolationStrategyThe interpolation strategy to be applied in case the timestamp does not fit with an existing sample
Returns
The resulting sample, invalid if no sample could be determined

◆ sample() [3/3]

virtual SampleRef Ocean::Devices::Measurement::sample ( const Timestamp  timestamp) const
virtual

Returns the sample with a specific timestamp.

If no sample exists with the given timestamp the most recent sample is returned.

Parameters
timestampThe timestamp of the sample to be returned
Returns
Requested sample

◆ sampleCapacity()

size_t Ocean::Devices::Measurement::sampleCapacity ( ) const
inline

Returns the capacity of the internal sample container.

Returns
The sample container's capacity, with range [2, infinity)
See also
setSampleCapacity().

◆ setSampleCapacity()

bool Ocean::Devices::Measurement::setSampleCapacity ( const size_t  capacity)

Sets the capacity of the internal sample container.

Parameters
capacityThe number maximal number of samples to be stored, with range [2, infinity)
Returns
True, if succeeded

◆ subscribeSampleEvent()

SampleEventSubscription Ocean::Devices::Measurement::subscribeSampleEvent ( SampleCallback &&  callback)

Subscribes a callback event function for new measurement sample events.

Do not subscribe or unsubscribe from inside an event thread.

Parameters
callbackThe callback function receiving the event calls, must be valid
Returns
The resulting subscription object, dispose the object to unsubscribe from the event call

◆ unsubscribeSampleEvent()

void Ocean::Devices::Measurement::unsubscribeSampleEvent ( const SubscriptionId  subscriptionId)
protected

Unsubscribes a sample event callback function.

Parameters
subscriptionIdThe id of the event subscription to unsubscribe

Field Documentation

◆ nextSampleSubscriptionId_

SubscriptionId Ocean::Devices::Measurement::nextSampleSubscriptionId_ = SubscriptionId(invalidSubscriptionId() + 1u)
private

The subscription id of the next event subscription.

◆ objectDescriptionToIdMap_

ObjectDescriptionToIdMap Ocean::Devices::Measurement::objectDescriptionToIdMap_
private

The map mapping object descriptions to object ids.

◆ objectIdToDescriptionMap_

ObjectIdToDescriptionMap Ocean::Devices::Measurement::objectIdToDescriptionMap_
private

The map mapping object ids to descriptions.

◆ sampleCapacity_

size_t Ocean::Devices::Measurement::sampleCapacity_
private

The maximal number of samples this measurement object can hold.

◆ sampleMap_

SampleMap Ocean::Devices::Measurement::sampleMap_
private

The most recent measurement samples.

◆ samplesLock_

Lock Ocean::Devices::Measurement::samplesLock_
mutableprotected

Sample lock.

◆ sampleSubscriptionMap_

SampleSubscriptionMap Ocean::Devices::Measurement::sampleSubscriptionMap_
private

Map holding all sample event subscriptions.

◆ subscriptionLock_

Lock Ocean::Devices::Measurement::subscriptionLock_
protected

Subscription lock.


The documentation for this class was generated from the following file: