Drake
Drake C++ Documentation
PointCloud Class Referencefinal

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...
 
PointCloudoperator= (const PointCloud &other)
 
PointCloudoperator= (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< Txyz (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< Tnormal (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< Crgb (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::DescriptorTypedescriptor_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< Ddescriptor (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_sizeSize of the point cloud after construction.
fieldsFields that the point cloud contains.
skip_initializeDo 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_fieldsFields 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::exceptionif 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::exceptionif has_xyzs() is false.

◆ Expand()

void Expand ( int  add_size,
bool  skip_initialization = false 
)

Adds add_size default-initialized points.

Parameters
add_sizeNumber of points to add.
skip_initializationDo 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::exceptionif 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::exceptionif 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::exceptionif 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_sizeThe 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_initializeDo 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_fieldsNew fields to set to.
skip_initializeDo 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
otherOther point cloud.
fields_inFields to copy. If this is kInherit, then others fields will be copied. Otherwise, both clouds must support the fields indicated this parameter.
allow_resizePermit 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::exceptionif has_xyzs() is false.
std::exceptionif 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: