Zivid::UnorganizedPointCloud Class Reference

Point cloud with x, y, z, RGB color and SNR laid out as a linear list of only valid points. More...

#include <Zivid/UnorganizedPointCloud.h>

Public Member Functions
ZIVID_CORE_EXPORT	UnorganizedPointCloud ()
	Create an empty point cloud.
ZIVID_CORE_EXPORT size_t	size () const
	Get the size of the point cloud (total number of points)
ZIVID_CORE_EXPORT UnorganizedPointCloud	extended (const UnorganizedPointCloud &other) const
	Create a new point cloud containing the combined data of this point cloud and another.
ZIVID_CORE_EXPORT UnorganizedPointCloud &	extend (const UnorganizedPointCloud &other)
	Extend this point cloud in-place by adding the points from another point cloud.
ZIVID_CORE_EXPORT UnorganizedPointCloud	voxelDownsampled (float voxelSize, int minPointsPerVoxel) const
	Create a new point cloud that is a voxel downsampling of this point cloud.
ZIVID_CORE_EXPORT UnorganizedPointCloud &	transform (const Zivid::Matrix4x4 &matrix)
	Transform the point cloud in-place by the given 4x4 transformation matrix.
ZIVID_CORE_EXPORT UnorganizedPointCloud	transformed (const Zivid::Matrix4x4 &matrix) const
	Transform the point cloud by the given 4x4 transformation matrix.
ZIVID_CORE_EXPORT UnorganizedPointCloud &	center ()
	Translate the point cloud in-place so that its centroid lands at the origin (0,0,0)
ZIVID_CORE_EXPORT std::optional< PointXYZ >	centroid () const
	Get the centroid of the point cloud, i.e. average of all XYZ point positions.
ZIVID_CORE_EXPORT Array1D< PointXYZ >	copyPointsXYZ () const
	Get the XYZ data of every point.
ZIVID_CORE_EXPORT Array1D< ColorRGBA >	copyColorsRGBA () const
	Get the color data of every point on 8-bit RGBA format.
ZIVID_CORE_EXPORT Array1D< ColorBGRA >	copyColorsBGRA () const
	Get the color data of every point on 8-bit BGRA format.
ZIVID_CORE_EXPORT Array1D< ColorRGBA_SRGB >	copyColorsRGBA_SRGB () const
	Get the color data of every point on 8-bit RGBA format in the sRGB color space.
ZIVID_CORE_EXPORT Array1D< ColorBGRA_SRGB >	copyColorsBGRA_SRGB () const
	Get the color data of every point on 8-bit BGRA format in the sRGB color space.
ZIVID_CORE_EXPORT Array1D< SNR >	copySNRs () const
	Get the SNR data of every point.
template<typename DataFormat >
Array1D< DataFormat >	copyData () const
	Array1D with point cloud data using specified DataFormat.
template<typename DataFormat >
void	copyData (DataFormat *destination) const
	Copy data in the specified DataFormat to a destination buffer.
ZIVID_CORE_EXPORT UnorganizedPointCloud	clone () const
	Returns a clone of the point cloud. The clone will include a copy of all of the point cloud data on the compute device memory. This means that the returned point cloud will not be affected by subsequent modifications (such as transform) on the original point cloud.
ZIVID_CORE_EXPORT std::string	toString () const
	Get string representation of the point cloud.

Detailed Description

Point cloud with x, y, z, RGB color and SNR laid out as a linear list of only valid points.

An instance of this class is a handle to a point cloud stored on the compute device memory. This class provides several methods to copy point cloud data from the compute device memory to host (CPU) system memory (RAM).

This point cloud contains only valid points, meaning that the XYZ values are never NaN.

Constructor & Destructor Documentation

UnorganizedPointCloud()

ZIVID_CORE_EXPORT Zivid::UnorganizedPointCloud::UnorganizedPointCloud

(

)

Create an empty point cloud.

This constructor creates a point cloud with size zero, i.e. no points. An empty point cloud can be useful for combining points from several other points clouds.

Member Function Documentation

center()

ZIVID_CORE_EXPORT UnorganizedPointCloud & Zivid::UnorganizedPointCloud::center

(

)

Translate the point cloud in-place so that its centroid lands at the origin (0,0,0)

If the point cloud has zero points, this method throws an exception.

centroid()

ZIVID_CORE_EXPORT std::optional< PointXYZ > Zivid::UnorganizedPointCloud::centroid

(

)

const

Get the centroid of the point cloud, i.e. average of all XYZ point positions.

If the point cloud has zero points, this method returns an empty std::optional.

Returns

The centroid as an optional PointXYZ

clone()

ZIVID_CORE_EXPORT UnorganizedPointCloud Zivid::UnorganizedPointCloud::clone

(

)

const

Returns a clone of the point cloud. The clone will include a copy of all of the point cloud data on the compute device memory. This means that the returned point cloud will not be affected by subsequent modifications (such as transform) on the original point cloud.

This function incurs a performance cost due to the copying of the compute device memory. When performance is important we recommend to avoid using this method, and instead modify the existing point cloud.

copyColorsBGRA()

ZIVID_CORE_EXPORT Array1D< ColorBGRA > Zivid::UnorganizedPointCloud::copyColorsBGRA

(

)

const

Get the color data of every point on 8-bit BGRA format.

This method copies the BGRA values from compute device memory to host (CPU) system memory (RAM) and returns them as an Array1D of ColorBGRA.

The length of the returned array will match the size method.

If you already have a buffer, you can copy data directly from compute device memory to your destination buffer using copyData with template parameter ColorBGRA.

copyColorsBGRA_SRGB()

ZIVID_CORE_EXPORT Array1D< ColorBGRA_SRGB > Zivid::UnorganizedPointCloud::copyColorsBGRA_SRGB

(

)

const

Get the color data of every point on 8-bit BGRA format in the sRGB color space.

This method copies the sRGB values from compute device memory to host (CPU) system memory (RAM) and returns them as an Array1D of ColorBGRA_SRGB.

The sRGB color space is suitable for showing an image on a display for human viewing. It is easier to see details in darker areas of an image in sRGB than in linear RGB, as more of the dynamic range is dedicated to darker colors. This color space is assumed by default by most monitors and should be used when displaying an image.

copyColorsRGBA()

ZIVID_CORE_EXPORT Array1D< ColorRGBA > Zivid::UnorganizedPointCloud::copyColorsRGBA

(

)

const

Get the color data of every point on 8-bit RGBA format.

This method copies the RGBA values from compute device memory to host (CPU) system memory (RAM) and returns them as an Array1D of ColorRGBA.

The length of the returned array will match the size method.

If you already have a buffer, you can copy data directly from compute device memory to your destination buffer using copyData with template parameter ColorRGBA.

copyColorsRGBA_SRGB()

ZIVID_CORE_EXPORT Array1D< ColorRGBA_SRGB > Zivid::UnorganizedPointCloud::copyColorsRGBA_SRGB

(

)

const

Get the color data of every point on 8-bit RGBA format in the sRGB color space.

This method copies the sRGB values from compute device memory to host (CPU) system memory (RAM) and returns them as an Array1D of ColorRGBA_SRGB.

The sRGB color space is suitable for showing an image on a display for human viewing. It is easier to see details in darker areas of an image in sRGB than in linear RGB, as more of the dynamic range is dedicated to darker colors. This color space is assumed by default by most monitors and should be used when displaying an image.

copyData() [1/2]

template<typename DataFormat >

Array1D< DataFormat > Zivid::UnorganizedPointCloud::copyData ( ) const

inline

Array1D with point cloud data using specified DataFormat.

The template parameter DataFormat specifies which point cloud data fields are included in the array. This is a convenience function that can be used for generic template programming. Calling this method with template parameter PointXYZ, for example, is equivalent to calling the copyPointsXYZ member function.

If you already have a buffer, you can copy data directly from compute device memory to your destination buffer using copyData(DataFormat *destination). For more information about the available DataFormat types, see copyData(DataFormat *destination).

copyData() [2/2]

template<typename DataFormat >

void Zivid::UnorganizedPointCloud::copyData ( DataFormat * destination ) const

inline

Copy data in the specified DataFormat to a destination buffer.

Transfers point cloud data from the compute device to a provided output buffer on the host (CPU) system memory (RAM). The template parameter DataFormat defines the layout of the data and which data fields are included.

This method is the most efficient way to copy point cloud data from the compute device if you need to store it to your own buffer. The destination buffer must be large enough to hold UnorganizedPointCloud::size() * sizeof(DataFormat) bytes of data. Providing a buffer which is too small results in undefined behavior.

Available data formats:

• PointXYZ: 3D coordinates. Contains 3 floats (x, y, z) packed together. Size per element is 12 bytes.
• ColorRGBA: RGBA colors. Contains 4 uint8_t r, g, b and a. a is always 255. Size per element 4 bytes.
• ColorBGRA: BGRA colors. Contains 4 uint8_t b, g, r and a. a is always 255. Size per element 4 bytes.
• ColorRGBA_SRGB: RGBA colors in the sRGB color space. Contains 4 uint8_t r, g, b and a. a is always 255. Size per element 4 bytes.
• ColorBGRA_SRGB: BGRA colors in the sRGB color space. Contains 4 uint8_t b, g, r and a. a is always 255. Size per element 4 bytes.
• SNR: SNR values, contains one float member value. Size per element is 4 bytes.

See also

copyPointsXYZ, copyColorsRGBA, copyColorsBGRA, copyColorsRGBA_SRGB, copyColorsBGRA_SRGB, copySNRs

copyPointsXYZ()

ZIVID_CORE_EXPORT Array1D< PointXYZ > Zivid::UnorganizedPointCloud::copyPointsXYZ

(

)

const

Get the XYZ data of every point.

This method copies the 3D point coordinates from compute device memory to host (CPU) system memory (RAM) and returns them as an Array1D of PointXYZ.

The length of the returned array will match the size method.

If you already have a buffer, you can copy data directly from compute device memory to your destination buffer using copyData with template parameter PointXYZ.

copySNRs()

ZIVID_CORE_EXPORT Array1D< SNR > Zivid::UnorganizedPointCloud::copySNRs

(

)

const

Get the SNR data of every point.

This method copies the signal-to-noise ratios from compute device memory to host (CPU) system memory (RAM) and returns them as an Array1D of SNR.

The length of the returned array will match the size method.

If you already have a buffer, you can copy data directly from compute device memory to your destination buffer using copyData with template parameter SNR.

extend()

ZIVID_CORE_EXPORT UnorganizedPointCloud & Zivid::UnorganizedPointCloud::extend

(

const UnorganizedPointCloud &

other

)

Extend this point cloud in-place by adding the points from another point cloud.

Parameters

other

The other point cloud to copy data from

extended()

ZIVID_CORE_EXPORT UnorganizedPointCloud Zivid::UnorganizedPointCloud::extended

(

const UnorganizedPointCloud &

other

)

const

Create a new point cloud containing the combined data of this point cloud and another.

Parameters

other

The other point cloud to copy data from

Returns

A new point cloud containing the combined data

size()

ZIVID_CORE_EXPORT size_t Zivid::UnorganizedPointCloud::size

(

)

const

Get the size of the point cloud (total number of points)

toString()

ZIVID_CORE_EXPORT std::string Zivid::UnorganizedPointCloud::toString

(

)

const

Get string representation of the point cloud.

Returns

Point cloud info as string

transform()

ZIVID_CORE_EXPORT UnorganizedPointCloud & Zivid::UnorganizedPointCloud::transform

(

const Zivid::Matrix4x4 &

matrix

)

Transform the point cloud in-place by the given 4x4 transformation matrix.

The transform matrix must be affine. In other words, the last row of the matrix must be [0, 0, 0, 1].

Parameters

matrix

An affine 4x4 matrix

transformed()

ZIVID_CORE_EXPORT UnorganizedPointCloud Zivid::UnorganizedPointCloud::transformed

(

const Zivid::Matrix4x4 &

matrix

)

const

Transform the point cloud by the given 4x4 transformation matrix.

This method is identical to transform, except the transformed point cloud is returned as a new UnorganizedPointCloud instance. The current point cloud is not modified.

Parameters

matrix

An affine 4x4 matrix

voxelDownsampled()

ZIVID_CORE_EXPORT UnorganizedPointCloud Zivid::UnorganizedPointCloud::voxelDownsampled	(	float	voxelSize,
		int	minPointsPerVoxel ) const

Create a new point cloud that is a voxel downsampling of this point cloud.

Voxel downsampling subdivides 3D space into a grid of cubic voxels with a given size. If a given voxel contains a number of points at or above the given limit, all those source points are replaced with a single point with the following properties:

• Position (XYZ) is an SNR-weighted average of the source points' positions, i.e. a high-confidence source point will have a greater influence on the resulting position than a low-confidence one.
• Color (RGBA) is the average of the source points' colors.
• Signal-to-noise ratio (SNR) is sqrt(sum(SNR^2)) of the source points' SNR values, i.e. the SNR of a new point will increase with both the number and the confidence of the source points that were used to compute its position.

Using minPointsPerVoxel > 1 is particularly useful for removing noise and artifacts from unorganized point clouds that are a combination of structured point clouds captured from different angles. This is because a given artifact is most likely only present in one of the captures, and minPointsPerVoxel can be used to only fill voxels that both captures "agree" on.

Parameters

voxelSize	The size of the voxel cubes (must be greater than 0.0)
minPointsPerVoxel	The minimum number of points required to fill a voxel (must be 1 or greater)

Returns

A new point cloud containing the voxel downsampled data

---

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

• Zivid/UnorganizedPointCloud.h