Template Class Decoder

Class Documentation

template<class MsgT, class EventProcT = NoOpEventProcessor>
class Decoder

Base class of decoders for different encodings.

The Decoder class is templated by message type so it can leverage all fields of a message. It is also templated by the event processor which permits for efficient inlining of the processing code, i.e. a decoded event can be processed immediately without incurring the cost of storing the event in memory.

Warning

This API is unstable and may change in the near future.

Template Parameters:

  • MsgT – ROS message type to decode, e.g. EventPacket

  • EventProcT – EventProcessor class that gets called once an event is decoded.

Public Functions

virtual ~Decoder() = default
inline void decode(const MsgT &msg, EventProcT *processor)

Decodes entire message, produces callbacks to processor. Use this method to feed the decoder with messages in case you want the entire message decoded.

Parameters:

  • msg – message to decode

  • processor – event processor to call when events are decoded

inline bool decodeUntil(const MsgT &msg, EventProcT *processor, uint64_t timeLimit, uint64_t *nextTime)

Decodes a message up to, but not including, timeLimit .

If the time limit has been reached (implying not the entire message has been processed), decodeUntil() must be called again with the same msg argument, to process the remaining events in the message. Do not use decode() and decodeUntil() on the same decoder since the two methods advance the state of the decoder differently. Also, you must call decodeUntil() until all bytes have been used up, i.e until it returns false, even if you don’t care about the remaining events of the message.

Parameters:

  • msg – message to be decoded

  • processor – event processor to call when events are decoded

  • timeLimit – sensor time limit up to (but not including) which decoding should happen

  • nextTime – time following the last decoded event. NOT VALID WHEN RETURN VALUE IS FALSE!

Returns:

true if time limit has been reached, i.e. end of msg has not yet been reached.

inline bool decodeUntil(const uint8_t *buf, size_t bufSize, EventProcT *processor, uint64_t timeLimit, uint64_t timeBase, uint64_t *nextTime)

Provides same functionality as decodeUntil(msg, …), but without using a message type. This is helpful when using languages like Python.

Parameters:

  • buf – pointer to first byte of message. Do not advance the pointer!

  • bufSize – number of bytes in event packet. Set to size of message event buffer.

  • processor – event processor to call when events are decoded

  • timeLimit – sensor time limit up to (but not including) which decoding should happen

  • timeBase – time bases for events in packet (may not be used)

  • nextTime – time following the last decoded event. NOT VALID WHEN RETURN VALUE IS FALSE!

Returns:

true if time limit has been reached, i.e. end of msg has not yet been reached.

inline bool summarize(const MsgT &msg, uint64_t *firstTS, uint64_t *lastTS, size_t *numEventsOnOff)

Summarizes message statistics. Use this function to peek into message without getting processing callbacks.

Parameters:

  • msg – message to summarize.

  • firstTS – first timestamp (will not be set if msg does not contain timestamp)

  • lastTS – last timestamp (will not be set if msg does not contain timestamp)

  • numEventsOnOff – number of events in message (must be pointer to array of size 2)

Returns:

true if timestamp has been found (i.e. firstTS and lastTS are valid)

virtual void decode(const uint8_t *buf, size_t bufSize, EventProcT *processor) = 0

decode buffer without using message type. Use this method if the message is not available, e.g. when calling from python.

virtual size_t decodeUntil(const uint8_t *buf, size_t bufSize, EventProcT *processor, uint64_t timeLimit, uint64_t *nextTime) = 0

decode buffer until reaching time limit, without using message type. Use this method if the message is not available, e.g. when calling from python.

virtual bool summarize(const uint8_t *buf, size_t size, uint64_t *firstTS, uint64_t *lastTS, size_t *numEventsOnOff) = 0

See summarize()

virtual void setTimeBase(const uint64_t timeBase) = 0

Sets time base, i.e the reference time to which the event times refer to. For some codecs (like evt3) this has no effect.

Parameters:

timeBase – typically time in nanoseconds since epoch.

virtual bool findFirstSensorTime(const uint8_t *buf, size_t size, uint64_t *firstTS) = 0

Finds first sensor time in event packet. This can be much faster than decoding the entire packet.

Parameters:

  • buf – buffer with event data

  • size – size of buffer with event data (bytes)

  • firstTS – first time stamp (only valid if “true” is returned!)

Returns:

true if sensor time has been found

virtual bool findFirstSensorTime(const MsgT &msg, uint64_t *firstTS) = 0

Finds first sensor time in event packet. This can be much faster than decoding the entire packet.

Parameters:

  • msg – event packet message

  • firstTS – first time stamp (only valid if “true” is returned!)

Returns:

true if sensor time has been found

virtual void setTimeMultiplier(uint32_t mult) = 0

Sets the time multiplier.

Parameters:

mult – Time multiplier. If the sensor time is natively in usec and mult is set to 1000, then the decoded time will be in nanoseconds.

virtual void setGeometry(uint16_t width, uint16_t height) = 0

Sets sensor geometry. Must be called before first call to “decode”. Necessary for sanity checks.

Parameters:

  • width – sensor width in pixels

  • height – sensor height in pixels

virtual uint16_t getWidth() const = 0

Gets sensor width.

Returns:

width of sensor

virtual uint16_t getHeight() const = 0

Gets sensor height.

Returns:

height of sensor

virtual uint32_t getTimeMultiplier() const = 0
virtual bool hasSensorTimeSinceEpoch() const = 0

Protected Attributes

uint16_t width_ = {0}
uint16_t height_ = {0}