Detailed Description

A mask on the degrees of freedom (dofs) of a MultibodyPlant instance, partitioning the plant's dofs into "selected" and "unselected" dofs.

A DofMask has two measures: its "size" and its "count". The size is the number of dofs it can mask in total (the selected and unselected dofs together). It must be equal to the number of dofs contained in a MultibodyPlant instance (its qs). The interpretation of a DofMask's indices come from the plant's ordering of its own dofs and their indices. A DofMask instance's valid index values lie in the range [0, size()). The count of the DofMask is the number of selected dofs.

Currently, DofMask is only compatible with MultibodyPlant instances where the generalized velocities are the same as the time derivatives of the generalized positions. Or, in other words, vᵢ = q̇ᵢ. This property holds for all single-dof joints but is not generally true for all joints (e.g., floating joints or roll-pitch-yaw ball joints).

#include <drake/planning/dof_mask.h>

Public Member Functions
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
	DofMask (const DofMask &)=default

DofMask &	operator= (const DofMask &)=default

	DofMask (DofMask &&)=default

DofMask &	operator= (DofMask &&)=default

Constructors
There are a number of constructors available. Using these constructors puts the burden on the caller to know what the appropriate size is and what the interpretation of the indices is. If used in conjunction with a MultibodyPlant instance, the caller must guarantee that the DofMask is constructed to a compatible size with the plant.
	DofMask ()
	Default constructor; creates a mask with no dofs (size() = count() = 0 ). More...

	DofMask (int size, bool value)
	Full/empty constructor. More...

	DofMask (std::initializer_list< bool > values)
	Constructs a DofMask from an initializer list of bool. More...

	DofMask (std::vector< bool > values)
	Constructs a DofMask from a vector of bool. More...

Introspection
int	size () const
	Reports this DofMask instance's total number of indexable dofs. More...

int	count () const
	Reports this DofMask instance's number of selected dofs. More...

std::vector< multibody::JointIndex >	GetJoints (const multibody::MultibodyPlant< double > &plant) const
	Creates a collection of all of the joints implied by the selected dofs in `this`. More...

bool	operator== (const DofMask &o) const
	Note: `o.size()` may be different from `this->size()`. More...

bool	operator[] (int index) const

std::string	to_string () const
	The string representation of the mask – it encodes the full mask size clearly indicating which dofs are selected and which are unselected. More...

Combining masks
We can think of the masks as sets – the iᵗʰ dof is in the set if it's selected. Therefore, we can apply set operations to create new masks from existing masks. Each operation creates a new DofMask. The parameter for these methods, when present, must have the same size() as `this->size()`.
DofMask	Complement () const
	Returns a new mask such that its selected dofs are `this` mask's unselected dofs and vice versa. More...

DofMask	Union (const DofMask &other) const
	Creates the union of `this` and `other`. More...

DofMask	Intersect (const DofMask &other) const
	Creates the intersection of `this` and `other`. More...

DofMask	Subtract (const DofMask &other) const
	Creates the set difference of `this` and `other`. More...

Scattering and gathering
These functions allow the mask to selectively write dof-specific values into a full state vector or read dof-specific values from a full state vector into a compact, selected-dofs-only vector. Only the selected dofs in a DofMask instance participate in the operation.
void	GetFromArray (const Eigen::Ref< const Eigen::VectorXd > &full_vec, drake::EigenPtr< Eigen::VectorXd > output) const
	Gets a subset of the values in `full_vec` and writes them to `output`. More...

Eigen::VectorXd	GetFromArray (const Eigen::Ref< const Eigen::VectorXd > &full_vec) const
	Overload for GetFromArray() which returns the read values in a new vector instead of writing to an output argument. More...

void	GetColumnsFromMatrix (const Eigen::Ref< const Eigen::MatrixXd > &full_mat, drake::EigenPtr< Eigen::MatrixXd > output) const
	Gets a subset of the columns of `full_mat` and writes them to `output`. More...

Eigen::MatrixXd	GetColumnsFromMatrix (const Eigen::Ref< const Eigen::MatrixXd > &full_mat) const
	Overload for GetColumnsFromMatrix() which returns the read values in a new matrix instead of writing to an output argument. More...

void	SetInArray (const Eigen::Ref< const Eigen::VectorXd > &vec, drake::EigenPtr< Eigen::VectorXd > output) const
	Sets the values given in `vec` into `output`. More...

std::vector< int >	GetSelectedToFullIndex () const
	If we have q_selected = dof_mask.GetFromArray(q_full), then this function returns a mapping from q_selected index to q_full index, such that q_selected[i] is the same as q_full[dof_mask.GetSelectedToFullIndex()[i]]. More...

std::vector< std::optional< int > >	GetFullToSelectedIndex () const
	The inverse mapping of GetSelectedToFullIndex(). More...

Static Public Member Functions
Factory methods
These factory methods construct DofMask instances from a MultibodyPlant. Which dofs are marked as "selected" depends on the particular factory method.
static DofMask	MakeFromModel (const multibody::MultibodyPlant< double > &plant, multibody::ModelInstanceIndex model_index)
	Creates the DofMask associated with a model instance (indicated by `model_index`) in `plant`. More...

static DofMask	MakeFromModel (const multibody::MultibodyPlant< double > &plant, const std::string &model_name)
	Creates the DofMask associated with the model instance (named by `model_name`) in `plant`. More...

Constructor & Destructor Documentation

◆ DofMask() [1/6]

DofMask ( const DofMask & )

default

◆ DofMask() [2/6]

DofMask ( DofMask && )

default

◆ DofMask() [3/6]

DofMask ( )

Default constructor; creates a mask with no dofs (size() = count() = 0 ).

◆ DofMask() [4/6]

DofMask	(	int	size,
		bool	value
	)

Full/empty constructor.

This allows for construction of a mask with the given size where all dofs are either selected (value = true) or unselected.

Precondition: size >= 0

◆ DofMask() [5/6]

DofMask ( std::initializer_list< bool > values )

Constructs a DofMask from an initializer list of bool.

◆ DofMask() [6/6]

DofMask ( std::vector< bool > values )

Constructs a DofMask from a vector of bool.

Member Function Documentation

◆ Complement()

DofMask Complement ( ) const

Returns a new mask such that its selected dofs are this mask's unselected dofs and vice versa.

◆ count()

int count ( ) const

Reports this DofMask instance's number of selected dofs.

◆ GetColumnsFromMatrix() [1/2]

void GetColumnsFromMatrix	(	const Eigen::Ref< const Eigen::MatrixXd > &	full_mat,
		drake::EigenPtr< Eigen::MatrixXd >	output
	)		const

Gets a subset of the columns of full_mat and writes them to output.

Similar to GetFromArray(), but instead of single scalar values, whole columns are read from full_mat and written to output.

Precondition: output is not null.; output.cols() == count().; full_mat.cols() == size().; full_mat.rows() = output->rows().

◆ GetColumnsFromMatrix() [2/2]

Eigen::MatrixXd GetColumnsFromMatrix ( const Eigen::Ref< const Eigen::MatrixXd > & full_mat ) const

Overload for GetColumnsFromMatrix() which returns the read values in a new matrix instead of writing to an output argument.

Precondition: full_mat.cols() == size().

◆ GetFromArray() [1/2]

void GetFromArray	(	const Eigen::Ref< const Eigen::VectorXd > &	full_vec,
		drake::EigenPtr< Eigen::VectorXd >	output
	)		const

Gets a subset of the values in full_vec and writes them to output.

The values read from full_vec associated with the selected dofs in this are written into output with the same relative ordering as they appear in full_vec.

For example:

 {c++}
// A mask into five total dofs, with indices 0, 1, & 4 selected.
const DofMask mask({true, true, false, false, true});
const auto full_vec = (VectorX(5) << 0, 10, 20, 30, 40).finished();
VectorX selected(mask.count());
mask.GetFromArray(full_vec, &selected);
// Print out the vector: [0, 10, 40].
std::cout << selected.transpose() << "\n";

Precondition: full_vec.size() == size().; output is not null.; output.size() == count().

◆ GetFromArray() [2/2]

Eigen::VectorXd GetFromArray ( const Eigen::Ref< const Eigen::VectorXd > & full_vec ) const

Overload for GetFromArray() which returns the read values in a new vector instead of writing to an output argument.

Precondition: full_vec.size() == size().

◆ GetFullToSelectedIndex()

std::vector<std::optional<int> > GetFullToSelectedIndex ( ) const

The inverse mapping of GetSelectedToFullIndex().

If we have q_selected = dof_mask.GetFromArray(q_full), the this function returns the mapping from q_full index to q_selected index. Namely if dof_mask[i] is true, namely q_full[i] is selected, then q_selected[*dof_mask.GetFullToSelectedIndex()[i]] is the same as q_full[i]; if dof_mask[i] is false, then dof_mask.GetFullToSelectedIndex()[i] is nullopt.

◆ GetJoints()

std::vector<multibody::JointIndex> GetJoints ( const multibody::MultibodyPlant< double > & plant ) const

Creates a collection of all of the joints implied by the selected dofs in this.

The returned joint indices are reported in increasing order.

Precondition: plant is compatible with DofMask.; plant.num_positions() == size().

◆ GetSelectedToFullIndex()

std::vector<int> GetSelectedToFullIndex ( ) const

If we have q_selected = dof_mask.GetFromArray(q_full), then this function returns a mapping from q_selected index to q_full index, such that q_selected[i] is the same as q_full[dof_mask.GetSelectedToFullIndex()[i]].

◆ Intersect()

DofMask Intersect ( const DofMask & other ) const

Creates the intersection of this and other.

The result includes all selected dofs that are in both this and other.

Precondition: size() == other.size().

◆ MakeFromModel() [1/2]

static DofMask MakeFromModel	(	const multibody::MultibodyPlant< double > &	plant,
		multibody::ModelInstanceIndex	model_index
	)

static

Creates the DofMask associated with a model instance (indicated by model_index) in plant.

Exceptions

std::exception if plant doesn't satisfy the compatibility requirements for DofMask.

◆ MakeFromModel() [2/2]

static DofMask MakeFromModel	(	const multibody::MultibodyPlant< double > &	plant,
		const std::string &	model_name
	)

static

Creates the DofMask associated with the model instance (named by model_name) in plant.

Exceptions

std::exception if plant doesn't satisfy the compatibility requirements for DofMask.

◆ operator=() [1/2]

DofMask& operator= ( DofMask && )

default

◆ operator=() [2/2]

DofMask& operator= ( const DofMask & )

default

◆ operator==()

bool operator== ( const DofMask & o ) const

Note: o.size() may be different from this->size().

They will, by definition report as not equal.

◆ operator[]()

bool operator[] ( int index ) const

Precondition: index is in the range [0, size()).

◆ SetInArray()

void SetInArray	(	const Eigen::Ref< const Eigen::VectorXd > &	vec,
		drake::EigenPtr< Eigen::VectorXd >	output
	)		const

Sets the values given in vec into output.

This is the inverse of GetFromArray(). vec contains count() values and the iᵗʰ value in vec is written to output at the index corresponding to the iᵗʰ selected dof in this. Entries in output which correspond to the unselected dofs will remain unchanged.

For example:

 {c++}
// A mask into five total dofs, with indices 0, 1, & 4 selected.
const DofMask mask({true, true, false, false, true});
const auto dof_vec = (VectorX(3) << -10, -20, -30).finished();
auto full_vec = (VectorX(5) << 0, 1, 2, 3, 4).finished();
mask.SetInArray(dof_vec, &full_vec);
// Print out the vector: [-10, -20, 2, 3, -30].
std::cout << full_vec.transpose() << "\n";

Precondition: vec.size() = this->count().; output is not null.; output.size() == size().

◆ size()

int size ( ) const

Reports this DofMask instance's total number of indexable dofs.

◆ Subtract()

DofMask Subtract ( const DofMask & other ) const

Creates the set difference of this and other.

The result includes only those selected dofs in this that are not in other.

Precondition: size() == other.size().

◆ to_string()

std::string to_string ( ) const

The string representation of the mask – it encodes the full mask size clearly indicating which dofs are selected and which are unselected.

The exact format is not guaranteed to remain fixed, but always clear.

◆ Union()

DofMask Union ( const DofMask & other ) const

Creates the union of this and other.

The result includes all selected dofs in either this or other.

Precondition: size() == other.size().

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

drake/planning/dof_mask.h

Detailed Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

◆ DofMask() [1/6]

◆ DofMask() [2/6]

◆ DofMask() [3/6]

◆ DofMask() [4/6]

◆ DofMask() [5/6]

◆ DofMask() [6/6]

Member Function Documentation

◆ Complement()

◆ count()

◆ GetColumnsFromMatrix() [1/2]

◆ GetColumnsFromMatrix() [2/2]

◆ GetFromArray() [1/2]

◆ GetFromArray() [2/2]

◆ GetFullToSelectedIndex()

◆ GetJoints()

◆ GetSelectedToFullIndex()

◆ Intersect()

◆ MakeFromModel() [1/2]

◆ MakeFromModel() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ operator[]()

◆ SetInArray()

◆ size()

◆ Subtract()

◆ to_string()

◆ Union()