Provides Reference Frame (i.e., coordinate systemm) transforms. More...

#include <ReferenceFrameFwd.h>

Public Member Functions
	ReferenceFrame ()
	Default constructor. More...

	ReferenceFrame (std::shared_ptr< ReferenceFrameVersion > impl)
	Construct from an existing ReferenceFrameVersion object. More...

template<typename P , typename std::enable_if< supports_transform_to< P >::value, void * >::type = nullptr>
	ReferenceFrame (P &&origin, uint64_t timestamp=-1)
	Constructor from an origin, and optional timestamp. More...

template<typename P , typename std::enable_if< supports_transform_to< P >::value, void * >::type = nullptr>
	ReferenceFrame (const ReferenceFrameType *type, P &&origin, uint64_t timestamp=-1)
	Constructor from a type, an origin, and optional timestamp. More...

template<typename P , typename std::enable_if< supports_transform_to< P >::value, void * >::type = nullptr>
	ReferenceFrame (std::string id, P &&origin, uint64_t timestamp=-1)
	Constructor from a id, an origin, and optional timestamp. More...

template<typename P , typename std::enable_if< supports_transform_to< P >::value, void * >::type = nullptr>
	ReferenceFrame (const ReferenceFrameType *type, std::string id, P &&origin, uint64_t timestamp=-1)
	Constructor from a type, id, an origin, and optional timestamp. More...

uint64_t	expiry (uint64_t age=-1) const
	Sets configuration for all frames of this frames ID. More...

uint64_t	expiry () const
	Return the current expiry for frames of this ID. More...

const std::string &	id () const
	Get the ID string of this frame. More...

ReferenceFrame	interpolate (const ReferenceFrame &other, ReferenceFrame parent, uint64_t time) const
	Interpolate a frame between the given frame; use the given parent. More...

bool	interpolated () const
	Test if frame is interpolated. More...

ReferenceFrame	move (const Position &new_origin) const
	Creates a new ReferenceFrame with modified origin. More...

ReferenceFrame	move (const Position &new_origin, uint64_t timestamp) const
	Creates a new ReferenceFrame with modified origin and timestamp. More...

std::string	name () const
	Returns a human-readable name for the reference frame type. More...

bool	operator!= (const ReferenceFrame &other) const
	Inequality operator. More...

bool	operator< (const ReferenceFrame &other) const

bool	operator<= (const ReferenceFrame &other) const

bool	operator== (const ReferenceFrame &other) const
	Equality operator. More...

bool	operator> (const ReferenceFrame &other) const

bool	operator>= (const ReferenceFrame &other) const

ReferenceFrame	orient (const Orientation &new_origin) const
	Creates a new ReferenceFrame with modified origin. More...

ReferenceFrame	orient (const Orientation &new_origin, uint64_t timestamp) const
	Creates a new ReferenceFrame with modified origin and timestamp. More...

const Pose &	origin () const
	Gets the origin of this Frame. More...

ReferenceFrame	origin_frame () const
	Gets the parent frame (the one the origin is within). More...

ReferenceFrame	pose (const Pose &new_origin) const
	Creates a new ReferenceFrame with modified origin. More...

ReferenceFrame	pose (const Pose &new_origin, uint64_t timestamp) const
	Creates a new ReferenceFrame with modified origin and timestamp. More...

void	save (madara::knowledge::KnowledgeBase &kb, const FrameEvalSettings &settings=FrameEvalSettings::DEFAULT) const
	Save this ReferenceFrame to the knowledge base, The saved frames will be marked with their timestamp for later retrieval. More...

void	save (madara::knowledge::KnowledgeBase &kb, uint64_t expiry, const FrameEvalSettings &settings=FrameEvalSettings::DEFAULT) const
	Save this ReferenceFrame to the knowledge base, The saved frames will be marked with their timestamp for later retrieval. More...

void	save_as (madara::knowledge::KnowledgeBase &kb, const std::string &key, const FrameEvalSettings &settings=FrameEvalSettings::DEFAULT) const
	Save this ReferenceFrame to the knowledge base, with a specific key value. More...

void	save_as (madara::knowledge::KnowledgeBase &kb, const std::string &key, uint64_t expiry, const FrameEvalSettings &settings=FrameEvalSettings::DEFAULT) const
	Save this ReferenceFrame to the knowledge base, with a specific key value. More...

uint64_t	timestamp () const
	Get the timestamp assigned to this frame. More...

ReferenceFrame	timestamp (uint64_t) const
	Clone the this frame, but with new timestamp. More...

const ReferenceFrameType *	type () const
	Retrieve the frame type object for this frame. More...

bool	valid () const
	Test whether this frame is valid. More...

Static Public Member Functions
static uint64_t	default_expiry (uint64_t age)
	Set the default expiry value for new frames IDs. More...

static uint64_t	default_expiry ()
	Return the default expiry for new frame IDs. More...

static const std::string &	default_prefix ()
	Return the default prefix for load/save operations. More...

static ReferenceFrame	load (madara::knowledge::KnowledgeBase &kb, const std::string &id, uint64_t timestamp=-1, const FrameEvalSettings &settings=FrameEvalSettings::DEFAULT)
	Load a single ReferenceFrame, by ID. More...

template<typename InputIterator >
static std::vector< ReferenceFrame >	load_tree (madara::knowledge::KnowledgeBase &kb, InputIterator begin, InputIterator end, uint64_t timestamp=-1, const FrameEvalSettings &settings=FrameEvalSettings::DEFAULT)
	Load ReferenceFrames, by ID, and their common ancestors. More...

template<typename Container >
static std::vector< ReferenceFrame >	load_tree (madara::knowledge::KnowledgeBase &kb, const Container &ids, uint64_t timestamp=-1, const FrameEvalSettings &settings=FrameEvalSettings::DEFAULT)
	Load ReferenceFrames, by ID, and their common ancestors. More...

Private Attributes
std::shared_ptr< ReferenceFrameVersion >	impl_

Friends
class	ReferenceFrameVersion

Detailed Description

Provides Reference Frame (i.e., coordinate systemm) transforms.

A ReferenceFrame has:

a type: either GPS or Cartesian (the default). Others may be implemented in the future.
an ID: some string that should be unique within each knowledge base. By default, a random GUID will be generated if none is given when constructing a ReferenceFrame. The ID should be unique per platform, across all KnowledgeBases that platform might use. The same ID saved to different KnowledgeBase objects will be assumed to represent the same frame, interchangeably.
a timestamp: a timestamp representing at what time the transform was measured or derived. No units are assumed by GAMS, but interpolation assumes that timestamps progress linearly with respect to real time, and monotonically. A -1, the default if none is given, is treated as "always correct" at all times.
an origin: a Pose in another frame which is the location and of this frame's origin with respect to that frame.

ReferenceFrame objects are immutable. "Setters" like timestamp() and pose() return a new ReferenceFrame object modified accordingly.

If you use gps_frame() or default_frame(), and wish to save any frames which involve them as ancestors, ensure you save them to any KnowledgeBase you will be saving such frames to.

ReferenceFrames get saved to KnowledgeBases under the ".gams.frames" prefix. Do not modify keys under this prefix directly.

ReferenceFrame objects are ref-counted proxies for an underlying object. As such, they are cheap and safe to pass and return by value.

Definition at line 162 of file ReferenceFrameFwd.h.

Constructor & Destructor Documentation

gams::pose::ReferenceFrame::ReferenceFrame ( )

inline

Default constructor.

This frame's valid() will return false. Calling any other method is undefined behavior.

If a frame has a Pose as origin with an invalid frame, it will be treated as a parent-less frame.

Definition at line 175 of file ReferenceFrameFwd.h.

gams::pose::ReferenceFrame::ReferenceFrame ( std::shared_ptr< ReferenceFrameVersion > impl )

inline

Construct from an existing ReferenceFrameVersion object.

In general, you should not be constructing ReferenceFrameVersion objects directly. Use the other constructors of this class.

Parameters

impl	a shared_ptr to construct with. This object will act as a proxy for the pointed-to object.

Definition at line 185 of file ReferenceFrameFwd.h.

template<typename P , typename std::enable_if< supports_transform_to< P >::value, void * >::type = nullptr>

gams::pose::ReferenceFrame::ReferenceFrame	(	P &&	origin,
		uint64_t	timestamp = `-1`
	)

inlineexplicit

Constructor from an origin, and optional timestamp.

Will be constructed with Cartesian type, and a random id.

Template Parameters

P	a Pose or StampedPose

Parameters

origin	the origin of this frame, relative to another frame.
timestamp	the timestamp of this frame. By default, will be treated as "always most current".

Definition at line 200 of file ReferenceFrameFwd.h.

template<typename P , typename std::enable_if< supports_transform_to< P >::value, void * >::type = nullptr>

gams::pose::ReferenceFrame::ReferenceFrame	(	const ReferenceFrameType *	type,
		P &&	origin,
		uint64_t	timestamp = `-1`
	)

inline

Constructor from a type, an origin, and optional timestamp.

Will be constructed with a random id.

Template Parameters

P	a Pose or StampedPose

Parameters

type	a pointer to a ReferenceFrameType struct; typically, either Cartesian, or GPS.
origin	the origin of this frame, relative to another frame.
timestamp	the timestamp of this frame. By default, will be treated as "always most current".

Definition at line 220 of file ReferenceFrameFwd.h.

template<typename P , typename std::enable_if< supports_transform_to< P >::value, void * >::type = nullptr>

gams::pose::ReferenceFrame::ReferenceFrame	(	std::string	id,
		P &&	origin,
		uint64_t	timestamp = `-1`
	)

inline

Constructor from a id, an origin, and optional timestamp.

Will be constructed with Cartesian type.

Template Parameters

P	a Pose or StampedPose

Parameters

id	a string identifier for this frame.
origin	the origin of this frame, relative to another frame.
timestamp	the timestamp of this frame. By default, will be treated as "always most current".

Definition at line 240 of file ReferenceFrameFwd.h.

template<typename P , typename std::enable_if< supports_transform_to< P >::value, void * >::type = nullptr>

gams::pose::ReferenceFrame::ReferenceFrame	(	const ReferenceFrameType *	type,
		std::string	id,
		P &&	origin,
		uint64_t	timestamp = `-1`
	)

inline

Constructor from a type, id, an origin, and optional timestamp.

Template Parameters

P	a Pose or StampedPose

Parameters

type	a pointer to a ReferenceFrameType struct; typically, either Cartesian, or GPS.
id	a string identifier for this frame.
origin	the origin of this frame, relative to another frame.
timestamp	the timestamp of this frame. By default, will be treated as "always most current".

Definition at line 261 of file ReferenceFrameFwd.h.

Member Function Documentation

static uint64_t gams::pose::ReferenceFrame::default_expiry ( uint64_t age )

static

Set the default expiry value for new frames IDs.

Setting this will not change any already created frame IDs.

If a frame newer than its expiry is saved, saved frames expire of the same ID older than this duration into the past from the timestamp of the new frame.

Expired frames are deleted from the KnowledgeBase.

Set to -1 (the default) to never expire frames.

Note: if a timestamp -1 frame is saved and this is not -1, all other frames will expire immediately.

Returns: previous default expiry

static uint64_t gams::pose::ReferenceFrame::default_expiry ( )

static

Return the default expiry for new frame IDs.

static const std::string& gams::pose::ReferenceFrame::default_prefix ( )

static

Return the default prefix for load/save operations.

Returns: std::string holding ".gams.frames"

uint64_t gams::pose::ReferenceFrame::expiry ( uint64_t age = -1 ) const

Sets configuration for all frames of this frames ID.

If a frame newer than this time is saved, expire saved frames of the same ID older than this duration into the past from the timestamp of the new frame.

Expired frames are deleted from the KnowledgeBase.

Set to -1 (the default) to never expire frames.

Note: if a timestamp -1 frame is saved and this is not -1, all other frames will expire immediately.

Returns: previous expiry

uint64_t gams::pose::ReferenceFrame::expiry ( ) const

Return the current expiry for frames of this ID.

const std::string& gams::pose::ReferenceFrame::id ( ) const

Get the ID string of this frame.

By default, frames generate a random GUID as their ID

ReferenceFrame gams::pose::ReferenceFrame::interpolate	(	const ReferenceFrame &	other,
		ReferenceFrame	parent,
		uint64_t	time
	)		const

Interpolate a frame between the given frame; use the given parent.

Note: no sanity checking is done. Ensure that parent has a compatible timestamp, and that this and other are the same frame at different times. Users should generally not call this directly. Use load() or load_tree() instead.

Parameters

other	the other frame to interpolate towards.
parent	the parent the returned frame will have.
time	the timestamp to interpolate at.

Returns: the interpolated frame.

bool gams::pose::ReferenceFrame::interpolated ( ) const

Test if frame is interpolated.

true if this frame was interpolated from two stored frames, false otherwise

static ReferenceFrame gams::pose::ReferenceFrame::load	(	madara::knowledge::KnowledgeBase &	kb,
		const std::string &	id,
		uint64_t	timestamp = `-1`,
		const FrameEvalSettings &	settings = `FrameEvalSettings::DEFAULT`
	)

static

Load a single ReferenceFrame, by ID.

Parameters

id	the ID of the frame to load
timestamp	if -1, gets the latest frame (no interpolation) Otherwise, gets the frame at a specified timestamp, interpolated necessary.

Returns: the imported ReferenceFrame, or an invalid frame if none exists.

template<typename InputIterator >

static std::vector<ReferenceFrame> gams::pose::ReferenceFrame::load_tree	(	madara::knowledge::KnowledgeBase &	kb,
		InputIterator	begin,
		InputIterator	end,
		uint64_t	timestamp = `-1`,
		const FrameEvalSettings &	settings = `FrameEvalSettings::DEFAULT`
	)

static

Load ReferenceFrames, by ID, and their common ancestors.

Will interpolate frames to ensure the returned frames all have a common timestamp.

Template Parameters

an	InputIterator, of item type std::string

Parameters

begin	beginning iterator
end	ending iterator
timestamp	if -1, the latest possible tree will be returned. Otherwise, the specified timestamp will be returned.

Returns: a vector of ReferenceFrames, each corresponding to the input IDs, in the same order. If the timestamp specified cannot be satisfied, returns an empty vector.

template<typename Container >

static std::vector<ReferenceFrame> gams::pose::ReferenceFrame::load_tree	(	madara::knowledge::KnowledgeBase &	kb,
		const Container &	ids,
		uint64_t	timestamp = `-1`,
		const FrameEvalSettings &	settings = `FrameEvalSettings::DEFAULT`
	)

static

Load ReferenceFrames, by ID, and their common ancestors.

Will interpolate frames to ensure the returned frames all have a common timestamp.

Template Parameters

a	Container, supporting cbegin() and cend(), of item type std::string

Parameters

ids	a Container of ids
timestamp	if -1, the latest possible tree will be returned. Otherwise, the specified timestamp will be returned.

Returns: a vector of ReferenceFrames, each corresponding to the input IDs, in the same order. If the timestamp specified cannot be satisfied, returns an empty vector.

ReferenceFrame gams::pose::ReferenceFrame::move ( const Position & new_origin ) const

Creates a new ReferenceFrame with modified origin.

Parameters

new_origin the new origin

Returns: the new ReferenceFrame with new origin

ReferenceFrame gams::pose::ReferenceFrame::move	(	const Position &	new_origin,
		uint64_t	timestamp
	)		const

Creates a new ReferenceFrame with modified origin and timestamp.

Parameters

new_origin	the new origin
timestamp	the new timestamp

Returns: the new ReferenceFrame with new origin and timestamp

std::string gams::pose::ReferenceFrame::name ( ) const

Returns a human-readable name for the reference frame type.

Returns: the name reference frame type (e.g., GPS, Cartesian)

bool gams::pose::ReferenceFrame::operator!= ( const ReferenceFrame & other ) const

Inequality operator.

Parameters

other the frame to compare to.

Returns: false if both frames are the same object (i.e., same address). Otherwise, frames are not considered equal (returns true).

bool gams::pose::ReferenceFrame::operator< ( const ReferenceFrame & other ) const

inline

Definition at line 361 of file ReferenceFrameFwd.h.

bool gams::pose::ReferenceFrame::operator<= ( const ReferenceFrame & other ) const

inline

Definition at line 366 of file ReferenceFrameFwd.h.

bool gams::pose::ReferenceFrame::operator== ( const ReferenceFrame & other ) const

Equality operator.

Parameters

other the frame to compare to.

Returns: true if both frames are the same object (i.e., same address). Otherwise, frames are not considered equal (returns false).

bool gams::pose::ReferenceFrame::operator> ( const ReferenceFrame & other ) const

inline

Definition at line 371 of file ReferenceFrameFwd.h.

bool gams::pose::ReferenceFrame::operator>= ( const ReferenceFrame & other ) const

inline

Definition at line 376 of file ReferenceFrameFwd.h.

ReferenceFrame gams::pose::ReferenceFrame::orient ( const Orientation & new_origin ) const

Creates a new ReferenceFrame with modified origin.

Parameters

new_origin the new origin

Returns: the new ReferenceFrame with new origin

ReferenceFrame gams::pose::ReferenceFrame::orient	(	const Orientation &	new_origin,
		uint64_t	timestamp
	)		const

Creates a new ReferenceFrame with modified origin and timestamp.

Parameters

new_origin	the new origin
timestamp	the new timestamp

Returns: the new ReferenceFrame with new origin and timestamp

const Pose& gams::pose::ReferenceFrame::origin ( ) const

Gets the origin of this Frame.

Returns: the Pose which is the origin within this frame's parent, or, a Pose within this own frame, with all zeros for coordinates, if this frame has no parent.

ReferenceFrame gams::pose::ReferenceFrame::origin_frame ( ) const

Gets the parent frame (the one the origin is within).

Will be *this if no parent frame.

ReferenceFrame gams::pose::ReferenceFrame::pose ( const Pose & new_origin ) const

Creates a new ReferenceFrame with modified origin.

Parameters

new_origin the new origin

Returns: the new ReferenceFrame with new origin

ReferenceFrame gams::pose::ReferenceFrame::pose	(	const Pose &	new_origin,
		uint64_t	timestamp
	)		const

Creates a new ReferenceFrame with modified origin and timestamp.

Parameters

new_origin	the new origin
timestamp	the new timestamp

Returns: the new ReferenceFrame with new origin and timestamp

void gams::pose::ReferenceFrame::save	(	madara::knowledge::KnowledgeBase &	kb,
		const FrameEvalSettings &	settings = `FrameEvalSettings::DEFAULT`
	)		const

Save this ReferenceFrame to the knowledge base, The saved frames will be marked with their timestamp for later retrieval.

If timestamp is -1, it will always be treated as the most recent frame.

Parameters

kb	the KnowledgeBase to store into

void gams::pose::ReferenceFrame::save	(	madara::knowledge::KnowledgeBase &	kb,
		uint64_t	expiry,
		const FrameEvalSettings &	settings = `FrameEvalSettings::DEFAULT`
	)		const

Save this ReferenceFrame to the knowledge base, The saved frames will be marked with their timestamp for later retrieval.

If timestamp is -1, it will always be treated as the most recent frame.

Parameters

kb	the KnowledgeBase to store into
expiry	use this expiry time instead of the one set on this ID

void gams::pose::ReferenceFrame::save_as	(	madara::knowledge::KnowledgeBase &	kb,
		const std::string &	key,
		const FrameEvalSettings &	settings = `FrameEvalSettings::DEFAULT`
	)		const

Save this ReferenceFrame to the knowledge base, with a specific key value.

Parameters

kb	the KnowledgeBase to save to
key	a key prefix to save with

void gams::pose::ReferenceFrame::save_as	(	madara::knowledge::KnowledgeBase &	kb,
		const std::string &	key,
		uint64_t	expiry,
		const FrameEvalSettings &	settings = `FrameEvalSettings::DEFAULT`
	)		const

Save this ReferenceFrame to the knowledge base, with a specific key value.

Parameters

kb	the KnowledgeBase to save to
key	a key prefix to save with
expiry	use this expiry time instead of the one set on this ID

uint64_t gams::pose::ReferenceFrame::timestamp ( ) const

Get the timestamp assigned to this frame.

Returns: the timestamp

ReferenceFrame gams::pose::ReferenceFrame::timestamp ( uint64_t ) const

Clone the this frame, but with new timestamp.

Returns: the new frame object

const ReferenceFrameType* gams::pose::ReferenceFrame::type ( ) const

Retrieve the frame type object for this frame.

Mostly useful for comparing to the pose::Cartesian or pose::GPS instances to test what kind of frame this is.

Returns: a pointer to this frames ReferenceFrameType

bool gams::pose::ReferenceFrame::valid ( ) const

inline

Test whether this frame is valid.

If not, all other methods will have undefined behavior.

Returns: true if valid, false otherwise.

Definition at line 275 of file ReferenceFrameFwd.h.

Friends And Related Function Documentation

friend class ReferenceFrameVersion

friend

Definition at line 599 of file ReferenceFrameFwd.h.

Member Data Documentation

std::shared_ptr<ReferenceFrameVersion> gams::pose::ReferenceFrame::impl_

private

Definition at line 165 of file ReferenceFrameFwd.h.

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

src/gams/pose/ReferenceFrameFwd.h

Public Member Functions

Static Public Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation