Detailed Description

Implements a point cloud (with contiguous storage), whose main goal is to offer a convenient, synchronized interface to commonly used fields and data types applicable for basic 3D perception.

This is a mix between the philosophy of PCL (templated interface to provide a compile-time open set, run-time closed set) and VTK (non-templated interface to provide a very free form run-time open set).

Definitions:

point - An entry in a point cloud (not exclusively an XYZ point).
feature - Abstract representation of local properties (geometric and non-geometric)
descriptor - Concrete representation of a feature.
field - A feature or descriptor described by the point cloud.

This point cloud class provides the following fields:

xyz - Cartesian XYZ coordinates (float[3]).
descriptor - A descriptor that is run-time defined (float[X]).

Note: "contiguous" here means contiguous in memory. This was chosen to avoid ambiguity between PCL and Eigen, where in PCL "dense" implies that the point cloud corresponds to a cloud with only valid values, and in Eigen "dense" implies contiguous storage.; The accessors / mutators for the point fields of this class returns references to the original Eigen matrices. This implies that they are invalidated whenever memory is reallocated for the values. Given this, minimize the lifetime of these references to be as short as possible. Additionally, algorithms wanting fast access to values should avoid the single point accessors / mutatotrs (e.g. xyz(i), mutable_descriptor(i)) to avoid overhead when accessing a single element (either copying or creating a reference).; The definitions presented here for "feature" and "descriptor" are loosely based on their definitions within PCL and Radu Rusu's dissertation: Rusu, Radu Bogdan. "Semantic 3d object maps for everyday manipulation in human living environments." KI-Künstliche Intelligenz 24.4 (2010): 345-348. This differs from other definitions, such as having "feature" describe geometric quantities and "descriptor" describe non-geometric quantities which is presented in the following survey paper: Pomerleau, François, Francis Colas, and Roland Siegwart. "A review of point cloud registration algorithms for mobile robotics." Foundations and Trends® in Robotics 4.1 (2015): 1-104.

#include <drake/perception/point_cloud.h>

Public Types
using	T = float
	Geometric scalar type. More...

using	C = uint8_t
	Color channel scalar type. More...

using	D = T
	Descriptor scalar type. More...

Public Member Functions
	PointCloud (int new_size=0, pc_flags::Fields fields=pc_flags::kXYZs, bool skip_initialize=false)
	Constructs a point cloud of a given `new_size`, with the prescribed `fields`. More...

	PointCloud (const PointCloud &other)
	Copies another point cloud's fields and data. More...

	PointCloud (PointCloud &&other)
	Takes ownership of another point cloud's data. More...

	PointCloud (const PointCloud &other, pc_flags::Fields copy_fields)
	Copies another point cloud's fields and data. More...

PointCloud &	operator= (const PointCloud &other)

PointCloud &	operator= (PointCloud &&other)

	~PointCloud ()

pc_flags::Fields	fields () const
	Returns the fields provided by this point cloud. More...

int	size () const
	Returns the number of points in this point cloud. More...

void	resize (int new_size, bool skip_initialize=false)
	Conservative resize; will maintain existing data, and initialize new data to their invalid values. More...

PointCloud	VoxelizedDownSample (double voxel_size, Parallelism parallelize=false) const
	Returns a down-sampled point cloud by grouping all xyzs in this cloud into a 3D grid with cells of dimension voxel_size. More...

bool	EstimateNormals (double radius, int num_closest, Parallelism parallelize=false)
	Estimates the normal vectors in `this` by fitting a plane at each point in the cloud using up to `num_closest` points within Euclidean distance `radius` from the point. More...

Geometric Descriptors - XYZs
bool	has_xyzs () const
	Returns if this cloud provides XYZ values. More...

Eigen::Ref< const Matrix3X< T > >	xyzs () const
	Returns access to XYZ values. More...

Eigen::Ref< Matrix3X< T > >	mutable_xyzs ()
	Returns mutable access to XYZ values. More...

Vector3< T >	xyz (int i) const
	Returns access to an XYZ value. More...

Eigen::Ref< Vector3< T > >	mutable_xyz (int i)
	Returns mutable access to an XYZ value. More...

Geometric Descriptors - Normals
bool	has_normals () const
	Returns if this cloud provides normals. More...

Eigen::Ref< const Matrix3X< T > >	normals () const
	Returns access to normals. More...

Eigen::Ref< Matrix3X< T > >	mutable_normals ()
	Returns mutable access to normals. More...

Vector3< T >	normal (int i) const
	Returns access to a normal. More...

Eigen::Ref< Vector3< T > >	mutable_normal (int i)
	Returns mutable access to a normal. More...

Geometric Descriptors - RGBs
bool	has_rgbs () const
	Returns if this cloud provides RGB colors. More...

Eigen::Ref< const Matrix3X< C > >	rgbs () const
	Returns access to RGB colors. More...

Eigen::Ref< Matrix3X< C > >	mutable_rgbs ()
	Returns mutable access to RGB colors. More...

Vector3< C >	rgb (int i) const
	Returns access to an RGB color. More...

Eigen::Ref< Vector3< C > >	mutable_rgb (int i)
	Returns mutable access to an RGB color. More...

Run-Time Descriptors
bool	has_descriptors () const
	Returns if this point cloud provides descriptor values. More...

bool	has_descriptors (const pc_flags::DescriptorType &descriptor_type) const
	Returns if the point cloud provides a specific descriptor. More...

const pc_flags::DescriptorType &	descriptor_type () const
	Returns the descriptor type. More...

Eigen::Ref< const MatrixX< D > >	descriptors () const
	Returns access to descriptor values. More...

Eigen::Ref< MatrixX< D > >	mutable_descriptors ()
	Returns mutable access to descriptor values. More...

VectorX< D >	descriptor (int i) const
	Returns access to a descriptor value. More...

Eigen::Ref< VectorX< D > >	mutable_descriptor (int i)
	Returns mutable access to a descriptor value. More...

Container Manipulation
void	SetFrom (const PointCloud &other, pc_flags::Fields fields_in=pc_flags::kInherit, bool allow_resize=true)
	Copies all points from another point cloud. More...

void	Expand (int add_size, bool skip_initialization=false)
	Adds `add_size` default-initialized points. More...

Fields
void	SetFields (pc_flags::Fields new_fields, bool skip_initialize=false)
	Updates the point cloud to a given set of fields. More...

bool	HasFields (pc_flags::Fields fields_in) const
	Returns if a point cloud has a given set of fields. More...

void	RequireFields (pc_flags::Fields fields_in) const
	Requires a given set of fields. More...

bool	HasExactFields (pc_flags::Fields fields_in) const
	Returns if a point cloud has exactly a given set of fields. More...

void	RequireExactFields (pc_flags::Fields field_set) const
	Requires the exact given set of fields. More...

Point Cloud Processing
PointCloud	Crop (const Eigen::Ref< const Vector3< T >> &lower_xyz, const Eigen::Ref< const Vector3< T >> &upper_xyz)
	Returns a new point cloud containing only the points in `this` with xyz values within the axis-aligned bounding box defined by `lower_xyz` and `upper_xyz`. More...

void	FlipNormalsTowardPoint (const Eigen::Ref< const Vector3< T >> &p_CP)
	Changes the sign of the normals in `this`, if necessary, so that each normal points toward the point `P` in the frame `C` in which the xyzs of `this` cloud are represented. More...

Static Public Member Functions
static bool	IsDefaultValue (T value)

static bool	IsInvalidValue (T value)

Static Public Attributes
static constexpr T	kDefaultValue = std::numeric_limits<T>::quiet_NaN()
	Represents an invalid or uninitialized value. More...

static constexpr C	kDefaultColor {}

Member Typedef Documentation

◆ C

using C = uint8_t

Color channel scalar type.

◆ D

using D = T

Descriptor scalar type.

◆ T

using T = float

Geometric scalar type.

Constructor & Destructor Documentation

◆ PointCloud() [1/4]

PointCloud	(	int	new_size = `0`,
		pc_flags::Fields	fields = `pc_flags::kXYZs`,
		bool	skip_initialize = `false`
	)

explicit

Constructs a point cloud of a given new_size, with the prescribed fields.

If kDescriptors is one of the fields, then descriptor should be included and should not be kNone.

Parameters

new_size	Size of the point cloud after construction.
fields	Fields that the point cloud contains.
skip_initialize	Do not default-initialize new values.

◆ PointCloud() [2/4]

PointCloud ( const PointCloud & other )

Copies another point cloud's fields and data.

◆ PointCloud() [3/4]

PointCloud ( PointCloud && other )

Takes ownership of another point cloud's data.

◆ PointCloud() [4/4]

PointCloud	(	const PointCloud &	other,
		pc_flags::Fields	copy_fields
	)

Copies another point cloud's fields and data.

Parameters

copy_fields Fields to copy. If this is kInherit, then others fields will be copied. Otherwise, only the specified fields will be copied; the remaining fields in this cloud are left default initialized.

◆ ~PointCloud()

~PointCloud ( )

Member Function Documentation

◆ Crop()

PointCloud Crop	(	const Eigen::Ref< const Vector3< T >> &	lower_xyz,
		const Eigen::Ref< const Vector3< T >> &	upper_xyz
	)

Returns a new point cloud containing only the points in this with xyz values within the axis-aligned bounding box defined by lower_xyz and upper_xyz.

Requires that xyz values are defined.

Precondition: lower_xyz <= upper_xyz (elementwise).

Exceptions

std::exception if has_xyzs() != true.

◆ descriptor()

VectorX<D> descriptor ( int i ) const

Returns access to a descriptor value.

Precondition: has_descriptors() must be true.

◆ descriptor_type()

const pc_flags::DescriptorType& descriptor_type ( ) const

Returns the descriptor type.

◆ descriptors()

Eigen::Ref<const MatrixX<D> > descriptors ( ) const

Returns access to descriptor values.

Precondition: has_descriptors() must be true.

◆ EstimateNormals()

bool EstimateNormals	(	double	radius,
		int	num_closest,
		Parallelism	parallelize = `false`
	)

Estimates the normal vectors in this by fitting a plane at each point in the cloud using up to num_closest points within Euclidean distance radius from the point.

If has_normals() is false, then new normals will be allocated (and has_normals() will become true). Points for which the normals cannot be estimated (because the this has less than two closest points within the radius), will receive normal [NaN, NaN, NaN]. Normals estimated from two closest points will be orthogonal to the vector between those points, but can be arbitrary in the last dimension. parallelize enables OpenMP parallelization.

Returns: true iff all points were assigned normals by having at least three closest points within radius.

Precondition: radius > 0 and num_closest >= 3.

Exceptions

std::exception if has_xyzs() is false.

◆ Expand()

void Expand	(	int	add_size,
		bool	skip_initialization = `false`
	)

Adds add_size default-initialized points.

Parameters

add_size	Number of points to add.
skip_initialization	Do not require that the new values be initialized.

◆ fields()

pc_flags::Fields fields ( ) const

Returns the fields provided by this point cloud.

◆ FlipNormalsTowardPoint()

void FlipNormalsTowardPoint ( const Eigen::Ref< const Vector3< T >> & p_CP )

Changes the sign of the normals in this, if necessary, so that each normal points toward the point P in the frame C in which the xyzs of this cloud are represented.

This can be useful, for instance, when P is the position of the camera used to generate the cloud.

Exceptions

std::exception if has_xyzs() != true or has_normals() != true.

◆ has_descriptors() [1/2]

bool has_descriptors ( ) const

Returns if this point cloud provides descriptor values.

◆ has_descriptors() [2/2]

bool has_descriptors ( const pc_flags::DescriptorType & descriptor_type ) const

Returns if the point cloud provides a specific descriptor.

◆ has_normals()

bool has_normals ( ) const

Returns if this cloud provides normals.

◆ has_rgbs()

bool has_rgbs ( ) const

Returns if this cloud provides RGB colors.

◆ has_xyzs()

bool has_xyzs ( ) const

Returns if this cloud provides XYZ values.

◆ HasExactFields()

bool HasExactFields ( pc_flags::Fields fields_in ) const

Returns if a point cloud has exactly a given set of fields.

See also: HasFields for preconditions.

◆ HasFields()

bool HasFields ( pc_flags::Fields fields_in ) const

Returns if a point cloud has a given set of fields.

◆ IsDefaultValue()

static bool IsDefaultValue ( T value )

static

◆ IsInvalidValue()

static bool IsInvalidValue ( T value )

static

◆ mutable_descriptor()

Eigen::Ref<VectorX<D> > mutable_descriptor ( int i )

Returns mutable access to a descriptor value.

Precondition: has_descriptors() must be true.

◆ mutable_descriptors()

Eigen::Ref<MatrixX<D> > mutable_descriptors ( )

Returns mutable access to descriptor values.

Precondition: has_descriptors() must be true.

◆ mutable_normal()

Eigen::Ref<Vector3<T> > mutable_normal ( int i )

Returns mutable access to a normal.

Precondition: has_normals() must be true.

◆ mutable_normals()

Eigen::Ref<Matrix3X<T> > mutable_normals ( )

Returns mutable access to normals.

Precondition: has_normals() must be true.

◆ mutable_rgb()

Eigen::Ref<Vector3<C> > mutable_rgb ( int i )

Returns mutable access to an RGB color.

Precondition: has_rgbs() must be true.

◆ mutable_rgbs()

Eigen::Ref<Matrix3X<C> > mutable_rgbs ( )

Returns mutable access to RGB colors.

Precondition: has_rgbs() must be true.

◆ mutable_xyz()

Eigen::Ref<Vector3<T> > mutable_xyz ( int i )

Returns mutable access to an XYZ value.

Precondition: has_xyzs() must be true.

◆ mutable_xyzs()

Eigen::Ref<Matrix3X<T> > mutable_xyzs ( )

Returns mutable access to XYZ values.

Precondition: has_xyzs() must be true.

◆ normal()

Vector3<T> normal ( int i ) const

Returns access to a normal.

Precondition: has_normals() must be true.

◆ normals()

Eigen::Ref<const Matrix3X<T> > normals ( ) const

Returns access to normals.

Precondition: has_normals() must be true.

◆ operator=() [1/2]

PointCloud& operator= ( const PointCloud & other )

◆ operator=() [2/2]

PointCloud& operator= ( PointCloud && other )

◆ RequireExactFields()

void RequireExactFields ( pc_flags::Fields field_set ) const

Requires the exact given set of fields.

See also: HasFields for preconditions.

Exceptions

std::exception if this point cloud does not have exactly these fields.

◆ RequireFields()

void RequireFields ( pc_flags::Fields fields_in ) const

Requires a given set of fields.

See also: HasFields for preconditions.

Exceptions

std::exception if this point cloud does not have these fields.

◆ resize()

void resize	(	int	new_size,
		bool	skip_initialize = `false`
	)

Conservative resize; will maintain existing data, and initialize new data to their invalid values.

Parameters

new_size	The new size of the value. If less than the present `size()`, then the values will be truncated. If greater than the present `size()`, then the new values will be uninitialized if `skip_initialize` is not true.
skip_initialize	Do not default-initialize new values.

◆ rgb()

Vector3<C> rgb ( int i ) const

Returns access to an RGB color.

Precondition: has_rgbs() must be true.

◆ rgbs()

Eigen::Ref<const Matrix3X<C> > rgbs ( ) const

Returns access to RGB colors.

Precondition: has_rgbs() must be true.

◆ SetFields()

void SetFields	(	pc_flags::Fields	new_fields,
		bool	skip_initialize = `false`
	)

Updates the point cloud to a given set of fields.

In the case of introducing a new field, its container will be allocated with the current size and default initialized. The data for all retained fields will remain unchanged.

Parameters

new_fields	New fields to set to.
skip_initialize	Do not default-initialize new values.

◆ SetFrom()

void SetFrom	(	const PointCloud &	other,
		pc_flags::Fields	fields_in = `pc_flags::kInherit`,
		bool	allow_resize = `true`
	)

Copies all points from another point cloud.

Parameters

other	Other point cloud.
fields_in	Fields to copy. If this is `kInherit`, then `other`s fields will be copied. Otherwise, both clouds must support the fields indicated this parameter.
allow_resize	Permit resizing to the other cloud's size.

◆ size()

int size ( ) const

Returns the number of points in this point cloud.

◆ VoxelizedDownSample()

PointCloud VoxelizedDownSample	(	double	voxel_size,
		Parallelism	parallelize = `false`
	)		const

Returns a down-sampled point cloud by grouping all xyzs in this cloud into a 3D grid with cells of dimension voxel_size.

Each occupied voxel will result in one point in the downsampled cloud, with a location corresponding to the centroid of the points in that voxel. Points with non-finite xyz values are ignored. All other fields (e.g. rgbs, normals, and descriptors) with finite values will also be averaged across the points in a voxel. parallelize enables OpenMP parallelization. Equivalent to Open3d's voxel_down_sample or PCL's VoxelGrid filter.

Exceptions

std::exception	if has_xyzs() is false.
std::exception	if voxel_size <= 0.

◆ xyz()

Vector3<T> xyz ( int i ) const

Returns access to an XYZ value.

Precondition: has_xyzs() must be true.

◆ xyzs()

Eigen::Ref<const Matrix3X<T> > xyzs ( ) const

Returns access to XYZ values.

Precondition: has_xyzs() must be true.

Member Data Documentation

◆ kDefaultColor

constexpr C kDefaultColor {}

static

◆ kDefaultValue

constexpr T kDefaultValue = std::numeric_limits<T>::quiet_NaN()

static

Represents an invalid or uninitialized value.

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

drake/perception/point_cloud.h

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Member Typedef Documentation

◆ C

◆ D

◆ T

Constructor & Destructor Documentation

◆ PointCloud() [1/4]

◆ PointCloud() [2/4]

◆ PointCloud() [3/4]

◆ PointCloud() [4/4]

◆ ~PointCloud()

Member Function Documentation

◆ Crop()

◆ descriptor()

◆ descriptor_type()

◆ descriptors()

◆ EstimateNormals()

◆ Expand()

◆ fields()

◆ FlipNormalsTowardPoint()

◆ has_descriptors() [1/2]

◆ has_descriptors() [2/2]

◆ has_normals()

◆ has_rgbs()

◆ has_xyzs()

◆ HasExactFields()

◆ HasFields()

◆ IsDefaultValue()

◆ IsInvalidValue()

◆ mutable_descriptor()

◆ mutable_descriptors()

◆ mutable_normal()

◆ mutable_normals()

◆ mutable_rgb()

◆ mutable_rgbs()

◆ mutable_xyz()

◆ mutable_xyzs()

◆ normal()

◆ normals()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ RequireExactFields()

◆ RequireFields()

◆ resize()

◆ rgb()

◆ rgbs()

◆ SetFields()

◆ SetFrom()

◆ size()

◆ VoxelizedDownSample()

◆ xyz()

◆ xyzs()

Member Data Documentation

◆ kDefaultColor

◆ kDefaultValue