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). You may construct one PointCloud which will contain different sets of data, but you cannot change the contained data types after construction. However, you can mutate the data contained within the structure and resize the cloud.

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 invalid 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, bool 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, bool 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

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

Vector3< Txyz (int i) const

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

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

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

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

Vector3< Tnormal (int i) const

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

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

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

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

Vector3< Crgb (int i) const

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

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

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

VectorX< Ddescriptor (int i) const

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

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
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 {}

## ◆ C

 using C = uint8_t

Color channel scalar type.

## ◆ D

 using D = T

Descriptor scalar type.

## ◆ T

 using T = float

Geometric scalar type.

## ◆ 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 ( )

## ◆ 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 descriptor ( int i ) const

Precondition
has_descriptors() must be true.

## ◆ descriptor_type()

 const pc_flags::DescriptorType& descriptor_type ( ) const

Returns the descriptor type.

## ◆ descriptors()

 Eigen::Ref > descriptors ( ) const

Precondition
has_descriptors() must be true.

## ◆ EstimateNormals()

 bool EstimateNormals ( double radius, int num_closest, bool 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.

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 > mutable_descriptor ( int i )

Precondition
has_descriptors() must be true.

## ◆ mutable_descriptors()

 Eigen::Ref > mutable_descriptors ( )

Precondition
has_descriptors() must be true.

## ◆ mutable_normal()

 Eigen::Ref > mutable_normal ( int i )

Precondition
has_normals() must be true.

## ◆ mutable_normals()

 Eigen::Ref > mutable_normals ( )

Precondition
has_normals() must be true.

## ◆ mutable_rgb()

 Eigen::Ref > mutable_rgb ( int i )

Precondition
has_rgbs() must be true.

## ◆ mutable_rgbs()

 Eigen::Ref > mutable_rgbs ( )

Precondition
has_rgbs() must be true.

## ◆ mutable_xyz()

 Eigen::Ref > mutable_xyz ( int i )

Precondition
has_xyzs() must be true.

## ◆ mutable_xyzs()

 Eigen::Ref > mutable_xyzs ( )

Precondition
has_xyzs() must be true.

## ◆ normal()

 Vector3 normal ( int i ) const

Precondition
has_normals() must be true.

## ◆ normals()

 Eigen::Ref > normals ( ) const

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.

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.

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 rgb ( int i ) const

Precondition
has_rgbs() must be true.

## ◆ rgbs()

 Eigen::Ref > rgbs ( ) const

Precondition
has_rgbs() must be true.

## ◆ 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 both clouds must have the exact same fields. 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, bool 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 xyz ( int i ) const

Precondition
has_xyzs() must be true.

## ◆ xyzs()

 Eigen::Ref > xyzs ( ) const

Precondition
has_xyzs() must be true.

## ◆ kDefaultColor

 constexpr C kDefaultColor {}
static

## ◆ kDefaultValue

 constexpr T kDefaultValue = std::numeric_limits::quiet_NaN()
static

Represents an invalid or uninitialized value.

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