gtsam::Values Class Reference

Detailed Description

A non-templated config holding any types of Manifold-group elements.

A values structure is a map from keys to values. It is used to specify the value of a bunch of variables in a factor graph. A Values is a values structure which can hold variables that are elements on manifolds, not just vectors. It then, as a whole, implements a aggregate type which is also a manifold element, and hence supports operations dim, retract, and localCoordinates.

Public Member Functions
void	insert (Key j, const Value &val)
	Add a variable with the given j, throws KeyAlreadyExists<J> if j is already present.
void	insert (const Values &values)
	Add a set of variables, throws KeyAlreadyExists<J> if a key is already present.
template<typename ValueType>
void	insert (Key j, const ValueType &val)
	Templated version to add a variable with the given j, throws KeyAlreadyExists<J> if j is already present.
template<typename UnaryOp, typename ValueType>
void	insert (Key j, const Eigen::CwiseUnaryOp< UnaryOp, const ValueType > &val)
	Partial specialization that allows passing a unary Eigen expression for val.
template<typename BinaryOp, typename ValueType1, typename ValueType2>
void	insert (Key j, const Eigen::CwiseBinaryOp< BinaryOp, const ValueType1, const ValueType2 > &val)
	Partial specialization that allows passing a binary Eigen expression for val.
void	insertDouble (Key j, double c)
	version for double
void	insertPoint3 (Key j, const Vector3 &point3)
	Insert a fixed-size 3-vector without Python overload ambiguity.
void	update (Key j, const Value &val)
	single element change of existing element
template<typename T>
void	update (Key j, const T &val)
	Templated version to update a variable with the given j, throws KeyDoesNotExist<J> if j is not present.
template<typename UnaryOp, typename ValueType>
void	update (Key j, const Eigen::CwiseUnaryOp< UnaryOp, const ValueType > &val)
	Partial specialization that allows passing a unary Eigen expression for val, similar to the partial specialization for insert.
template<typename BinaryOp, typename ValueType1, typename ValueType2>
void	update (Key j, const Eigen::CwiseBinaryOp< BinaryOp, const ValueType1, const ValueType2 > &val)
	Partial specialization that allows passing a binary Eigen expression for val, similar to the partial specialization for insert.
void	update (const Values &values)
	update the current available values without adding new ones
void	insert_or_assign (Key j, const Value &val)
	If key j exists, update value, else perform an insert.
void	insert_or_assign (const Values &values)
	Update a set of variables.
template<typename ValueType>
void	insert_or_assign (Key j, const ValueType &val)
	Templated version to insert_or_assign a variable with the given j.
template<typename UnaryOp, typename ValueType>
void	insert_or_assign (Key j, const Eigen::CwiseUnaryOp< UnaryOp, const ValueType > &val)
	Partial specialization that allows passing a unary Eigen expression for val, similar to the partial specialization for insert.
template<typename BinaryOp, typename ValueType1, typename ValueType2>
void	insert_or_assign (Key j, const Eigen::CwiseBinaryOp< BinaryOp, const ValueType1, const ValueType2 > &val)
	Partial specialization that allows passing a binary Eigen expression for val, similar to the partial specialization for insert.
void	erase (Key j)
	Remove a variable from the config, throws KeyDoesNotExist<J> if j is not present.
KeyVector	keys () const
	Returns a vector of keys in the config.
KeySet	keySet () const
	Returns a set of keys in the config.
Values	extract (const KeyVector &keys) const
	Returns a new Values holding copies of the values at the given keys, whatever their types.
Values &	operator= (const Values &rhs)
	Replace all keys and variables.
void	swap (Values &other)
	Swap the contents of two Values without copying data.
void	clear ()
	Remove all variables from the config.
size_t	dim () const
	Compute the total dimensionality of all values ( \( O(n) \)).
std::map< Key, size_t >	dims () const
	Return all dimensions in a map ( \( O(n log n) \)).
VectorValues	zeroVectors () const
	Return a VectorValues of zero vectors for each variable in this Values.
template<class ValueType>
size_t	count () const
template<class ValueType>
std::map< Key, ValueType >	extract (const std::function< bool(Key)> &filterFcn=&_truePredicate< Key >) const
	Extract a subset of values of the given type ValueType.
template<typename ValueType>
void	update (Key j, const ValueType &val)
Constructors
	Values ()=default
	Default constructor creates an empty Values class.
	Values (const Values &other)
	Copy constructor duplicates all keys and values.
	Values (Values &&other)
	Move constructor.
	Values (std::initializer_list< ConstKeyValuePair > init)
	Constructor from initializer list.
	Values (const Values &other, const VectorValues &delta)
	Construct from a Values and an update vector: identical to other.retract(delta).
Testable
void	print (const std::string &str="", const KeyFormatter &keyFormatter=DefaultKeyFormatter) const
	print method for testing and debugging
bool	equals (const Values &other, double tol=1e-9) const
	Test whether the sets of keys and values are identical.
Standard Interface
template<typename ValueType>
const ValueType	at (Key j) const
	Retrieve a variable by key j.
template<typename ValueType>
const ValueType &	atRef (Key j) const
	Retrieve a variable by key j without copying.
double	atDouble (size_t key) const
	version for double
const Value &	at (Key j) const
	Retrieve a variable by key j.
bool	exists (Key j) const
	Check if a value exists with key j.
template<typename ValueType>
const ValueType *	exists (Key j) const
	Check if a value with key j exists, returns a pointer to the const version of the value Value if the key does exist, or nullptr if it does not exist.
size_t	size () const
	The number of variables in this config.
bool	empty () const
	whether the config is empty
Iterator
deref_iterator	begin () const
deref_iterator	end () const
deref_iterator	find (Key j) const
	Find an element by key, returning an iterator, or end() if the key was not found.
deref_iterator	lower_bound (Key j) const
	Find the element greater than or equal to the specified key.
deref_iterator	upper_bound (Key j) const
	Find the lowest-ordered element greater than the specified key.
Manifold Operations
Values	retract (const VectorValues &delta) const
	Add a delta config to current config and returns a new config.
Values	retract (const VectorValues &delta, const KeyVector &keys) const
	Retract only the named keys, returning a Values holding just those.
void	retractMasked (const VectorValues &delta, const KeySet &mask)
	Retract, but only for Keys appearing in mask.
VectorValues	localCoordinates (const Values &cp) const
	Get a delta config about a linearization point c0 (*this).

Public Types
typedef std::shared_ptr< Values >	shared_ptr
	A shared_ptr to this class.
typedef std::shared_ptr< const Values >	const_shared_ptr
	A const shared_ptr to this class.
typedef KeyValuePair	value_type

Classes
struct	KeyValuePair
	A key-value pair, which you get by dereferencing iterators. More...
struct	ConstKeyValuePair
	A key-value pair, which you get by dereferencing iterators. More...
struct	deref_iterator

Friends
class	NonlinearMultifrontalSolver

Constructor & Destructor Documentation

Values()

Values::Values

(

std::initializer_list< ConstKeyValuePair >

init

)

Constructor from initializer list.

Example usage:

Values v = {{k1, genericValue(pose1)}, {k2, genericValue(point2)}};

Member Function Documentation

at() [1/2]

const Value & Values::at

(

Key

j

)

const

Retrieve a variable by key j.

This version returns a reference to the base Value class, and needs to be casted before use.

Parameters

j	Retrieve the value associated with this key

Returns

A const reference to the stored value

at() [2/2]

template<typename ValueType>

const ValueType Values::at

(

Key

j

)

const

Retrieve a variable by key j.

The type of the value associated with this key is supplied as a template argument to this function.

Parameters

j	Retrieve the value associated with this key

Template Parameters

ValueType

The type of the value stored with this key, this method Throws DynamicValuesIncorrectType if this requested type is not correct. Dynamic matrices/vectors can be retrieved as fixed-size, but not vice-versa.

Returns

The stored value

atRef()

template<typename ValueType>

const ValueType & Values::atRef

(

Key

j

)

const

Retrieve a variable by key j without copying.

This is a fast path that assumes the stored type matches ValueType; in debug builds it asserts on mismatch.

exists() [1/2]

template<typename ValueType>

const ValueType * Values::exists

(

Key

j

)

const

Check if a value with key j exists, returns a pointer to the const version of the value Value if the key does exist, or nullptr if it does not exist.

Throws DynamicValuesIncorrectType if the value type associated with the requested key does not match the stored value type.

exists() [2/2]

bool Values::exists

(

Key

j

)

const

Check if a value exists with key j.

See exists<>(Key j) and exists(const TypedKey& j) for versions that return the value if it exists.

extract() [1/2]

Values Values::extract

(

const KeyVector &

keys

)

const

Returns a new Values holding copies of the values at the given keys, whatever their types.

Complements the typed extract<ValueType>(), which returns a map of one type; this one keeps the result a Values, so it can be fed straight back into a factor graph, optimizer, or smoother.

Parameters

keys	The keys to copy; must be unique.

Exceptions

ValuesKeyDoesNotExist

if a key is not present.

extract() [2/2]

template<class ValueType>

std::map< Key, ValueType > Values::extract

(

const std::function< bool(Key)> &

filterFcn = &_truePredicate<Key>

)

const

Extract a subset of values of the given type ValueType.

In this templated version, only key-value pairs whose value matches the template argument ValueType and whose key causes the function argument filterFcn to return true are visited when iterating over the filtered view. This replaces the fancier but very boost-dependent filter methods that were previously available up to GTSAM 4.2.

Template Parameters

ValueType

The type that the value in a key-value pair must match to be included in the filtered view. Currently, base classes are not resolved so the type must match exactly, except if ValueType = Value, in which case no type filtering is done.

Parameters

filterFcn

The function that determines which key-value pairs are included in the filtered view, for which this function returns true on their keys (default: always return true so that filter() only filters by type, matching ValueType).

Returns

An Eigen aligned map on Key with the filtered values.

insert() [1/2]

template<typename BinaryOp, typename ValueType1, typename ValueType2>

void Values::insert	(	Key	j,
		const Eigen::CwiseBinaryOp< BinaryOp, const ValueType1, const ValueType2 > &	val )

Partial specialization that allows passing a binary Eigen expression for val.

A binary expression is an expression such as a + b, where a and b are valid Vector or Matrix types of compatible size. The typical usage is for types Point2 (i.e. Eigen::Vector2d) or Point3 (i.e. Eigen::Vector3d). For example, together with the partial specialization for binary operators, a user may call insert(j, 2*a + M*b - c), where M is an appropriately sized matrix (such as a rotation matrix). Thus, it isn't necessary to explicitly evaluate the Eigen expression, as in insert(j, (2*a + M*b - c).eval()), nor is it necessary to first assign the expression to a separate variable.

insert() [2/2]

template<typename UnaryOp, typename ValueType>

void Values::insert	(	Key	j,
		const Eigen::CwiseUnaryOp< UnaryOp, const ValueType > &	val )

Partial specialization that allows passing a unary Eigen expression for val.

A unary expression is an expression such as 2*a or -a, where a is a valid Vector or Matrix type. The typical usage is for types Point2 (i.e. Eigen::Vector2d) or Point3 (i.e. Eigen::Vector3d). For example, together with the partial specialization for binary operators, a user may call insert(j, 2*a + M*b - c), where M is an appropriately sized matrix (such as a rotation matrix). Thus, it isn't necessary to explicitly evaluate the Eigen expression, as in insert(j, (2*a + M*b - c).eval()), nor is it necessary to first assign the expression to a separate variable.

insert_or_assign()

void Values::insert_or_assign

(

const Values &

values

)

Update a set of variables.

If any variable key does not exist, then perform an insert.

keys()

KeyVector Values::keys

(

)

const

Returns a vector of keys in the config.

Note: by construction, the list is ordered

retract()

Values Values::retract	(	const VectorValues &	delta,
		const KeyVector &	keys ) const

Retract only the named keys, returning a Values holding just those.

Complements retract(delta), which retracts every variable. As in retract(delta), a requested key with no entry in delta is copied unchanged rather than treated as an error.

Parameters

delta	The delta vector in the tangent space of this Values.
keys	The keys to retract; must be unique.

Exceptions

ValuesKeyDoesNotExist	if a key is not in this Values.
ValuesKeyAlreadyExists	if a key is repeated.

retractMasked()

void Values::retractMasked	(	const VectorValues &	delta,
		const KeySet &	mask )

Retract, but only for Keys appearing in mask.

In-place.

Parameters

mask	Mask on Keys where to apply retract.

update()

template<typename T>

void gtsam::Values::update	(	Key	j,
		const T &	val )

Templated version to update a variable with the given j, throws KeyDoesNotExist<J> if j is not present.

If no chart is specified, the DefaultChart<ValueType> is used.

---

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

• /tmp/gtsam-4.3.0-doxygen.rsXPUS/source/gtsam/nonlinear/Values.h
• /tmp/gtsam-4.3.0-doxygen.rsXPUS/source/gtsam/nonlinear/Values-inl.h
• /tmp/gtsam-4.3.0-doxygen.rsXPUS/source/gtsam/nonlinear/Values.cpp