CVB++ 14.1
PointCloud Class Reference

A point cloud object. More...

#include <cvb/point_cloud.hpp>

Inherited by DensePointCloud, and SparsePointCloud.

Public Member Functions

PointCloudLayout Layout () const
 Get the layout of the available buffers/planes of the given point cloud. More...
 
class DataType DataType () const
 Gets the DataType of the x,y,z(,w) components of the given PointCloud. More...
 
std::size_t NumPoints () const
 Gets the number of x,y,z(,w) points in the given point cloud. More...
 
ComponentsPointers3D PointComponents () const
 Tries to get the point components from the given point cloud. More...
 
template<class T >
std::size_t Points (Point3D< T > *&points) const
 Gets the 3D points from the given point cloud. More...
 
template<class T >
std::size_t PointsH (Point3DH< T > *&pointsH) const
 Tries to get the 3D points from the given point cloud. More...
 
Cuboid CalculateBoundingBox () const
 Calculates the minimum and maximum extent of the point cloud. More...
 
Point3D< double > CalculateCenterOfGravity () const
 Calculates the center of gravity of the point cloud. More...
 
Matrix3D CalculateCovarianceMatrix () const
 Calculates the covariance matrix of the point cloud. More...
 
Plane3D FitPlane () const
 Fits a plane in the points of the point cloud without cropping it. More...
 
Plane3D FitPlane (const Cuboid &aoi) const
 Fits a plane in the points of the point cloud for a specified area of interest. More...
 
template<class T >
std::shared_ptr< T > Crop (const Cuboid &clipBox) const
 Creates a new point cloud which only consists of the points inside the clip box. More...
 
template<class T >
std::shared_ptr< T > FrustumCrop (const Cuboid &clipBox, Angle theta, Angle phi) const
 Creates a new point cloud which only consists of the points inside the clipBox, where the orientation of the two boundary planes Z=Zmin and Z=Zmax can be modified by angles theta and phi. More...
 
template<class T >
std::shared_ptr< T > PlaneCrop (const Plane3D &plane, const ValueRange< double > &range, CropRange cropRange) const
 Creates a new point cloud where points within or outside a range parallel to given plane are cropped. More...
 
template<class T >
std::shared_ptr< T > PlaneCrop (const Plane3D &plane, double threshold, CropDirection cropBelowAbove=CropDirection::Below) const
 Creates a new point cloud which only consists of the points below or above given plane. More...
 
PointCloudPtr Downsample (DownSampleMode mode, int value) const
 Creates a new point cloud which has several points being removed dependent on the down sample mode and value. More...
 
PointCloudPtr Duplicate () const
 Creates a new point cloud which is a copy this point cloud. More...
 
void Save (const String &fileName) const
 Saves the given point cloud to the file with the given FileName. More...
 
PointCloudPtr Convert (PointCloudFlags flags) const
 Creates a new point cloud, which is a copy from this point cloud, but with possibly different data type and number of components. More...
 
PointCloudPtr Scale (Factors3D factors) const
 Creates a new point cloud with all points being scaled by the given factors. More...
 
PointCloudPtr Transform (const AffineMatrix3D &transformation) const
 Creates a new point cloud with all points being transformed by the given transformation. More...
 
PointCloudPtr Transform (const Matrix3DH &transformation) const
 Creates a new point cloud with all points being transformed by the given transformation. More...
 
void Transform (const AffineMatrix3D &affineTransformation, PointCloud &pointCloud)
 Transforms all points in this point cloud by the given AffineTransformation and stores them in the given point cloud. More...
 
void Transform (const Cvb::Matrix3DH &transformation, PointCloud &pointCloud)
 Transforms all points in this point cloud by the given transformation and stores them in the given point cloud. More...
 
std::unique_ptr< Cvb::ImageRangeMap (ValueRange< double > xRange, ValueRange< double > yRange, Size2D< int > size, double background) const
 Creates a new range map image via linear projection in negative z-direction. More...
 
int PlaneCount () const noexcept
 Gets the number of planes enumerated by this object. More...
 
std::vector< PlanePtrPlanes () const
 Gets all available planes enumerated by this object. More...
 
PlanePtr Plane (int index) const
 Index based plane access. More...
 
size_t MemorySize (PointCloudFlags flags, Cvb::PointCloudFileFormat format) const
 Determines the amount of memory needed for ToMemory. More...
 
template<class Point >
size_t MemorySize (Cvb::PointCloudFileFormat format) const
 Determines the amount of memory needed for ToMemory. More...
 
void ToMemory (PointCloudFlags flags, Cvb::PointCloudFileFormat format, size_t size, void *buffer) const
 Saves the point cloud to the memory in the given format. More...
 
template<class Point >
void ToMemory (Cvb::PointCloudFileFormat format, size_t size, std::uint8_t *buffer) const
 Saves the point cloud to the memory in the given format. More...
 
void * Handle () const noexcept
 Returns C-API style handle to Node Object. More...
 

Static Public Member Functions

static PointCloudPtr FromHandle (HandleGuard< PointCloud > &&guard)
 Creates a point cloud from a classic API handle. More...
 
template<class T >
static std::shared_ptr< T > FromComposite (CompositePtr object)
 Creates a point cloud from a composite. More...
 
static PointCloudPtr FromMemory (void *buffer, size_t size, PointCloudFlags flags, Cvb::PointCloudFileFormat format)
 Creates a point cloud reading memory from buffer. More...
 
template<class Point >
static PointCloudPtr FromMemory (void *buffer, size_t size, Cvb::PointCloudFileFormat format)
 Creates a point cloud reading memory from buffer. More...
 

Detailed Description

A point cloud object.

At its core the point cloud is a collection of 3D points (x, y, z and optionally w).

Examples
Cvb/CppPointCloudCreateCalibrated.

Member Function Documentation

◆ CalculateBoundingBox()

Cuboid CalculateBoundingBox ( ) const
inline

Calculates the minimum and maximum extent of the point cloud.

Returns
The variable to receive the extent.
Exceptions
Anyexception derived from std::exception including CvbException.
Examples
Cvb/CppPointCloudCreateCalibrated.

◆ CalculateCenterOfGravity()

Point3D< double > CalculateCenterOfGravity ( ) const
inline

Calculates the center of gravity of the point cloud.

Returns
The variable to receive the extent.
Exceptions
Anyexception derived from std::exception including CvbException.
Examples
Cvb/CppPointCloudCreateCalibrated.

◆ CalculateCovarianceMatrix()

Matrix3D CalculateCovarianceMatrix ( ) const
inline

Calculates the covariance matrix of the point cloud.

Returns
The covariance Matrix to be filled.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ Convert()

PointCloudPtr Convert ( PointCloudFlags  flags) const
inline

Creates a new point cloud, which is a copy from this point cloud, but with possibly different data type and number of components.

Parameters
[in]flagsFlags specifying the kind of point cloud to be created.
Returns
The new point cloud.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ Crop()

std::shared_ptr< T > Crop ( const Cuboid clipBox) const
inline

Creates a new point cloud which only consists of the points inside the clip box.

Template Parameters
TPoint cloud type (dense or sparse). Note, that point clouds will have the same type after cropping.
Parameters
[in]clipBoxCuboid defining the bounds for the points to be copied (min/max are inclusive).
Returns
The new point cloud.
Exceptions
Anyexception derived from std::exception including CvbException.
Examples
Cvb/CppPointCloudCreateCalibrated.

◆ DataType()

class DataType DataType ( ) const
inline

Gets the DataType of the x,y,z(,w) components of the given PointCloud.

Returns
The DataType of the x,y,z(,w) components of the PointCloud points.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ Downsample()

PointCloudPtr Downsample ( DownSampleMode  mode,
int  value 
) const
inline

Creates a new point cloud which has several points being removed dependent on the down sample mode and value.

Parameters
[in]modeDownsample strategy.
[in]valueEvery Value-th point will be removed (must be greater than one).
Returns
The new point cloud.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ Duplicate()

PointCloudPtr Duplicate ( ) const
inline

Creates a new point cloud which is a copy this point cloud.

Attention
The duplicated point cloud may have a different point cloud layout.
Returns
The new point cloud.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ FitPlane() [1/2]

Plane3D FitPlane ( ) const
inline

Fits a plane in the points of the point cloud without cropping it.

Note
Also fits a plane in points lying on one line, thus make sure that the points really span a plane.
Returns
Newly created Plane object fitted in the points from the point cloud.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ FitPlane() [2/2]

Plane3D FitPlane ( const Cuboid aoi) const
inline

Fits a plane in the points of the point cloud for a specified area of interest.

Note
Also fits a plane in points lying on one line, thus make sure that the points really span a plane.
Parameters
[in]aoiBounding cuboid to extract points from.
Returns
Newly created Plane object fitted in the points from the point cloud.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ FromComposite()

std::shared_ptr< T > FromComposite ( CompositePtr  object)
inlinestatic

Creates a point cloud from a composite.

Parameters
[in]objectA composite to share.
Returns
A pointer to an object that shares that shares resources with the composite.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ FromHandle()

CVB_BEGIN_INLINE_NS PointCloudPtr FromHandle ( HandleGuard< PointCloud > &&  guard)
inlinestatic

Creates a point cloud from a classic API handle.

Parameters
[in]guardLife time guard for C-API handle.
Returns
The point cloud created from the classic API handle.
Exceptions
Anyexception derived from std::exception including CvbException.

The point cloud takes ownership of the handle, so you must share it before using this function.

◆ FromMemory() [1/2]

static PointCloudPtr FromMemory ( void *  buffer,
size_t  size,
Cvb::PointCloudFileFormat  format 
)
inlinestatic

Creates a point cloud reading memory from buffer.

The following data formats are supported:

Name Extension(s)
Polygon File Format ply
Wavefront OBJ obj
Stereo Lithography stl
ASCII asc, pts, txt, xyz
Template Parameters
Point3D point type.
Parameters
[in]bufferRaw pointer to buffer with given size.
[in]sizeSize of buffer.
[in]formatThe data format the buffer is in.
Returns
Point cloud, where buffer is written to.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ FromMemory() [2/2]

PointCloudPtr FromMemory ( void *  buffer,
size_t  size,
PointCloudFlags  flags,
Cvb::PointCloudFileFormat  format 
)
inlinestatic

Creates a point cloud reading memory from buffer.

The following data formats are supported:

Name Extension(s)
Polygon File Format ply
Wavefront OBJ obj
Stereo Lithography stl
ASCII asc, pts, txt, xyz
Parameters
[in]bufferRaw pointer to buffer with given size.
[in]sizeSize of buffer.
[in]flagsPoint cloud flags.
[in]formatThe data format the buffer is in.
Returns
Point cloud, where buffer is written to.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ FrustumCrop()

std::shared_ptr< T > FrustumCrop ( const Cuboid clipBox,
Angle  theta,
Angle  phi 
) const
inline

Creates a new point cloud which only consists of the points inside the clipBox, where the orientation of the two boundary planes Z=Zmin and Z=Zmax can be modified by angles theta and phi.

For theta, phi = 0,0 the function will give the same result as Crop(). Angle theta tilts the two Z-boundary planes towards the (positive) Y-axis. Additionally, phi rotates the tilted Z-boundary planes around the Z-axis (for theta=0, phi will have no effect, because it is then just an inplane-rotation). The two Z-boundary planes will stay parallel, but no longer necessarily orthogonal to the lateral boundary planes. Note, that only the Z-boundaries are tilted and not the whole bounding box, i.e. X- and Y-boundaries will stay the same.

Template Parameters
TPoint cloud type (dense or sparse). Note, that point clouds will have the same type after cropping.
Parameters
[in]clipBoxCuboid defining the bounds for the points to be copied (min/max are inclusive).
[in]thetaTilt angle of the two Z-boundary planes Z=Zmin and Z=Zmax towards the positive Y-axis.
[in]phiRotation angle of the tilted Z-boundary planes around the Z-axis. If Theta = 0, Phi will have no effect.
Returns
The new point cloud.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ Handle()

void * Handle ( ) const
inlinenoexcept

Returns C-API style handle to Node Object.

Returns
C-API handle

◆ Layout()

PointCloudLayout Layout ( ) const
inline

Get the layout of the available buffers/planes of the given point cloud.

Returns
The PointCloudLayout of PointCloud.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ MemorySize() [1/2]

size_t MemorySize ( Cvb::PointCloudFileFormat  format) const
inline

Determines the amount of memory needed for ToMemory.

The data format to be used is determined by the format. The following file formats are supported:

Name Extension(s)
Polygon File Format ply
Wavefront OBJ obj
Stereo Lithography stl
ASCII asc, pts, txt, xyz
Template Parameters
Point3D point type.
Parameters
[in]formatThe data format to be used for the export.
Returns
The size of the buffer.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ MemorySize() [2/2]

size_t MemorySize ( PointCloudFlags  flags,
Cvb::PointCloudFileFormat  format 
) const
inline

Determines the amount of memory needed for ToMemory.

The data format to be used is determined by the format. The following file formats are supported:

Name Extension(s)
Polygon File Format ply
Wavefront OBJ obj
Stereo Lithography stl
ASCII asc, pts, txt, xyz
Parameters
[in]flagsPoint cloud flags.
[in]formatThe data format to be used for the export.
Returns
The size of the buffer.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ NumPoints()

std::size_t NumPoints ( ) const
inline

Gets the number of x,y,z(,w) points in the given point cloud.

Returns
The number of points in the PointCloud.
Exceptions
Anyexception derived from std::exception including CvbException.
Examples
Cvb/CppPointCloudCreateAndHandle.

◆ Plane()

PlanePtr Plane ( int  index) const
inline

Index based plane access.

Parameters
[in]indexIndex of the plane.
Returns
A pointer to the plane.
Exceptions
Anyexception derived from std::exception including CvbException.

If the plane does not exist the access will throw.

◆ PlaneCount()

int PlaneCount ( ) const
inlinenoexcept

Gets the number of planes enumerated by this object.

Returns
Number of planes.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ PlaneCrop() [1/2]

std::shared_ptr< T > PlaneCrop ( const Plane3D plane,
const ValueRange< double > &  range,
CropRange  cropRange 
) const
inline

Creates a new point cloud where points within or outside a range parallel to given plane are cropped.

The plane is defined by the hessian normal form:

Points are cropped within or outside a range parallel to the given plane. The range is defined by range. Note, that Range.Max and Range.Min are applied along normal direction.

In order to define a range around the plane, maximum and minimum range have to be positive and negative respectively.

If the input point cloud is dense, cropped points are set non-confident. Lines and columns at the borders containing only non-confident points are removed. If the input point cloud is dense and does not contain a confidence plane, a confidence plane will be added to the cropped point cloud.

Template Parameters
TPoint cloud type (dense or sparse). Note, that point clouds will have the same type after cropping.
Parameters
[in]planePoints parallel to this plane will be cropped.
[in]rangePoints within or outside this range will be cropped.
[in]cropRangeIndicates whether points should be cropped within or outside the range.
Returns
Cropped point cloud.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ PlaneCrop() [2/2]

std::shared_ptr< T > PlaneCrop ( const Plane3D plane,
double  threshold,
CropDirection  cropBelowAbove = CropDirection::Below 
) const
inline

Creates a new point cloud which only consists of the points below or above given plane.

The plane is defined by the hessian normal form:

Above plane means all points with z values greater than the plane are cropped. It makes no difference in which direction the given normal points. The normal is always converted, so that it points up (positive z value). Note, if Normal.Z equals 0, "below" and "above" is undefined and thus no cropping is done. Instead the input point cloud will be duplicated.

If the input point cloud is dense, points beyond the plane are set non-confident. Lines and columns at the borders containing only non-confident points are removed. If the input point cloud is dense and does not contain a confidence plane, a confidence plane will be added to the cropped point cloud.

Template Parameters
TPoint cloud type (dense or sparse). Note, that point clouds will have the same type after cropping.
Parameters
[in]planePoints beyond this plane will be cropped.
[in]thresholdPoints below plane plus this value and points above plane minus this value are cropped respectively. This threshold should be set, if plane is calculated via FitPlane(). It ensures, that all points beyond this plane plus noise are cropped.
[in]cropBelowAboveIndicates if points should either be cropped below or above plane (optional, default value: CropDirection::Below).
Returns
Cropped point cloud.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ Planes()

std::vector< PlanePtr > Planes ( ) const
inline

Gets all available planes enumerated by this object.

Returns
Vector of planes.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ PointComponents()

ComponentsPointers3D PointComponents ( ) const
inline

Tries to get the point components from the given point cloud.

Returns
A struct with pointers to the cloud's components.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ Points()

std::size_t Points ( Point3D< T > *&  points) const
inline

Gets the 3D points from the given point cloud.

Parameters
[in]pointsThe variable to be filled with pointer to first point in PointCloud.
Returns
The number of points in PointCloud.
Exceptions
Anyexception derived from std::exception including CvbException.
Examples
Cvb/CppPointCloudCreateAndHandle.

◆ PointsH()

std::size_t PointsH ( Point3DH< T > *&  pointsH) const
inline

Tries to get the 3D points from the given point cloud.

Parameters
[in]pointsHThe variable to be filled with pointer to first point in PointCloud.
Returns
The number of points in PointCloud.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ RangeMap()

std::unique_ptr< Cvb::Image > RangeMap ( ValueRange< double >  xRange,
ValueRange< double >  yRange,
Size2D< int >  size,
double  background 
) const
inline

Creates a new range map image via linear projection in negative z-direction.

Parameters
[in]xRangeInput window along the x-axis (inclusive).
[in]yRangeInput window along the y-axis (inclusive).
[in]sizeTarget size of RangeMap in pixels (greater or equal to 2x2).
[in]backgroundBackground value (initialization value for RangeMap).
Returns
The range map image.
Exceptions
Anyexception derived from std::exception including CvbException.
See also
FillGaps

◆ Save()

void Save ( const String fileName) const
inline

Saves the given point cloud to the file with the given FileName.

Parameters
[in]fileNameComplete path where to save the file to.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ Scale()

PointCloudPtr Scale ( Factors3D  factors) const
inline

Creates a new point cloud with all points being scaled by the given factors.

Parameters
[in]factorsScale factors to be applied to each point.
Returns
The new point cloud.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ ToMemory() [1/2]

void ToMemory ( Cvb::PointCloudFileFormat  format,
size_t  size,
std::uint8_t buffer 
) const
inline

Saves the point cloud to the memory in the given format.

The data format to be used is determined by the format. The following file formats are supported:

Name Extension(s)
Polygon File Format ply
Wavefront OBJ obj
Stereo Lithography stl
ASCII asc, pts, txt, xyz
Note
Exporting polygon information is only supported for ply, obj and stl. For the other formats this function only saves the point (or vertex) data. Applications expecting polygon information will fail to load the saved files.

Stereo Lithography (STL) is only supported if polygon information is present.

Template Parameters
Point3D point type.
Parameters
[in]formatThe data format to be used for the export.
[in]sizeSize of buffer.
[in]bufferRaw pointer to buffer with given size, where memory is written to.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ ToMemory() [2/2]

void ToMemory ( PointCloudFlags  flags,
Cvb::PointCloudFileFormat  format,
size_t  size,
void *  buffer 
) const
inline

Saves the point cloud to the memory in the given format.

The data format to be used is determined by the format. The following file formats are supported:

Name Extension(s)
Polygon File Format ply
Wavefront OBJ obj
Stereo Lithography stl
ASCII asc, pts, txt, xyz
Note
Exporting polygon information is only supported for ply, obj and stl. For the other formats this function only saves the point (or vertex) data. Applications expecting polygon information will fail to load the saved files.

Stereo Lithography (STL) is only supported if polygon information is present.

Parameters
[in]flagsPoint cloud flags.
[in]formatThe data format to be used for the export.
[in]sizeSize of buffer.
[in]bufferRaw pointer to buffer with given size, where memory is written to.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ Transform() [1/4]

void Transform ( const AffineMatrix3D affineTransformation,
PointCloud pointCloud 
)
inline

Transforms all points in this point cloud by the given AffineTransformation and stores them in the given point cloud.

Parameters
[in]affineTransformationHomogeneous transformation matrix. AffineMatrix3D is a compact version of CVC3DMatrixH with the last row being { 0, 0, 0, 1 }. So no perspective transformation is possible, but translation, rotation and scaling is.
[out]pointCloudHandle to point cloud were the transformed points are stored in.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ Transform() [2/4]

PointCloudPtr Transform ( const AffineMatrix3D transformation) const
inline

Creates a new point cloud with all points being transformed by the given transformation.

Parameters
[in]transformationHomogeneous transformation matrix.
Returns
The new point cloud.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ Transform() [3/4]

void Transform ( const Cvb::Matrix3DH transformation,
PointCloud pointCloud 
)
inline

Transforms all points in this point cloud by the given transformation and stores them in the given point cloud.

Parameters
[in]transformationHomogeneous transformation matrix.
[out]pointCloudHandle to point cloud were the transformed points are stored in.
Exceptions
Anyexception derived from std::exception including CvbException.

◆ Transform() [4/4]

PointCloudPtr Transform ( const Matrix3DH transformation) const
inline

Creates a new point cloud with all points being transformed by the given transformation.

Parameters
[in]transformationHomogeneous transformation matrix.
Returns
The new point cloud.
Exceptions
Anyexception derived from std::exception including CvbException.