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::Image >	RangeMap (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< PlanePtr >	Planes () 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

Any	exception 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

Any	exception 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

Any	exception 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] flags Flags specifying the kind of point cloud to be created.

Returns: The new point cloud.

Exceptions

Any	exception 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

T	Point cloud type (dense or sparse). Note, that point clouds will have the same type after cropping.

Parameters

[in] clipBox Cuboid defining the bounds for the points to be copied (min/max are inclusive).

Returns: The new point cloud.

Exceptions

Any	exception 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

Any	exception 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]	mode	Downsample strategy.
[in]	value	Every Value-th point will be removed (must be greater than one).

Returns: The new point cloud.

Exceptions

Any	exception 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

Any	exception 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

Any	exception 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] aoi Bounding cuboid to extract points from.

Returns: Newly created Plane object fitted in the points from the point cloud.

Exceptions

Any	exception derived from std::exception including CvbException.

◆ FromComposite()

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

inlinestatic

Creates a point cloud from a composite.

Parameters

[in] object A composite to share.

Returns: A pointer to an object that shares that shares resources with the composite.

Exceptions

Any	exception 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] guard Life time guard for C-API handle.

Returns: The point cloud created from the classic API handle.

Exceptions

Any	exception 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

Point 3D point type.

Parameters

[in]	buffer	Raw pointer to buffer with given size.
[in]	size	Size of buffer.
[in]	format	The data format the buffer is in.

Returns: Point cloud, where buffer is written to.

Exceptions

Any	exception 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]	buffer	Raw pointer to buffer with given size.
[in]	size	Size of buffer.
[in]	flags	Point cloud flags.
[in]	format	The data format the buffer is in.

Returns: Point cloud, where buffer is written to.

Exceptions

Any	exception 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

T	Point cloud type (dense or sparse). Note, that point clouds will have the same type after cropping.

Parameters

[in]	clipBox	Cuboid defining the bounds for the points to be copied (min/max are inclusive).
[in]	theta	Tilt angle of the two Z-boundary planes Z=Zmin and Z=Zmax towards the positive Y-axis.
[in]	phi	Rotation 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

Any	exception 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

Any	exception 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

Point 3D point type.

Parameters

[in] format The data format to be used for the export.

Returns: The size of the buffer.

Exceptions

Any	exception 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]	flags	Point cloud flags.
[in]	format	The data format to be used for the export.

Returns: The size of the buffer.

Exceptions

Any	exception 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

Any	exception derived from std::exception including CvbException.

Examples: Cvb/CppPointCloudCreateAndHandle.

◆ Plane()

PlanePtr Plane ( int index ) const

inline

Index based plane access.

Parameters

[in] index Index of the plane.

Returns: A pointer to the plane.

Exceptions

Any	exception 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

Any	exception 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

T	Point cloud type (dense or sparse). Note, that point clouds will have the same type after cropping.

Parameters

[in]	plane	Points parallel to this plane will be cropped.
[in]	range	Points within or outside this range will be cropped.
[in]	cropRange	Indicates whether points should be cropped within or outside the range.

Returns: Cropped point cloud.

Exceptions

Any	exception 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

T	Point cloud type (dense or sparse). Note, that point clouds will have the same type after cropping.

Parameters

[in]	plane	Points beyond this plane will be cropped.
[in]	threshold	Points 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]	cropBelowAbove	Indicates if points should either be cropped below or above plane (optional, default value: CropDirection::Below).

Returns: Cropped point cloud.

Exceptions

Any	exception 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

Any	exception 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

Any	exception 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] points The variable to be filled with pointer to first point in PointCloud.

Returns: The number of points in PointCloud.

Exceptions

Any	exception 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] pointsH The variable to be filled with pointer to first point in PointCloud.

Returns: The number of points in PointCloud.

Exceptions

Any	exception 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]	xRange	Input window along the x-axis (inclusive).
[in]	yRange	Input window along the y-axis (inclusive).
[in]	size	Target size of RangeMap in pixels (greater or equal to 2x2).
[in]	background	Background value (initialization value for RangeMap).

Returns: The range map image.

Exceptions

Any	exception 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] fileName Complete path where to save the file to.

Exceptions

Any	exception 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] factors Scale factors to be applied to each point.

Returns: The new point cloud.

Exceptions

Any	exception 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

Point 3D point type.

Parameters

[in]	format	The data format to be used for the export.
[in]	size	Size of buffer.
[in]	buffer	Raw pointer to buffer with given size, where memory is written to.

Exceptions

Any	exception 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]	flags	Point cloud flags.
[in]	format	The data format to be used for the export.
[in]	size	Size of buffer.
[in]	buffer	Raw pointer to buffer with given size, where memory is written to.

Exceptions

Any	exception 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]	affineTransformation	Homogeneous 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]	pointCloud	Handle to point cloud were the transformed points are stored in.

Exceptions

Any	exception 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] transformation Homogeneous transformation matrix.

Returns: The new point cloud.

Exceptions

Any	exception 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]	transformation	Homogeneous transformation matrix.
[out]	pointCloud	Handle to point cloud were the transformed points are stored in.

Exceptions

Any	exception 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] transformation Homogeneous transformation matrix.

Returns: The new point cloud.

Exceptions

Any	exception derived from std::exception including CvbException.

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ CalculateBoundingBox()

◆ CalculateCenterOfGravity()

◆ CalculateCovarianceMatrix()

◆ Convert()

◆ Crop()

◆ DataType()

◆ Downsample()

◆ Duplicate()

◆ FitPlane() [1/2]

◆ FitPlane() [2/2]

◆ FromComposite()

◆ FromHandle()

◆ FromMemory() [1/2]

◆ FromMemory() [2/2]

◆ FrustumCrop()

◆ Handle()

◆ Layout()

◆ MemorySize() [1/2]

◆ MemorySize() [2/2]

◆ NumPoints()

◆ Plane()

◆ PlaneCount()

◆ PlaneCrop() [1/2]

◆ PlaneCrop() [2/2]

◆ Planes()

◆ PointComponents()

◆ Points()

◆ PointsH()

◆ RangeMap()

◆ Save()

◆ Scale()

◆ ToMemory() [1/2]

◆ ToMemory() [2/2]

◆ Transform() [1/4]

◆ Transform() [2/4]

◆ Transform() [3/4]

◆ Transform() [4/4]