Point cloud with x, y, z, RGB color and SNR laid out on a 2D grid More...

#include <Zivid/PointCloud.h>

Public Types
enum class	Downsampling { by2x2 , by3x3 , by4x4 }
	Option for downsampling More...

Public Member Functions
ZIVID_CORE_EXPORT	PointCloud ()
	Create an empty point cloud More...

ZIVID_CORE_EXPORT size_t	width () const
	Get the width of the point cloud (number of columns) More...

ZIVID_CORE_EXPORT size_t	height () const
	Get the height of the point cloud (number of rows) More...

ZIVID_CORE_EXPORT size_t	size () const
	Get the size of the point cloud (total number of points) More...

ZIVID_CORE_EXPORT bool	isEmpty () const
	Check if the point cloud is empty (contains zero points) More...

ZIVID_CORE_EXPORT Array2D< PointXYZ >	copyPointsXYZ () const
	Array2D of point coordinates More...

ZIVID_CORE_EXPORT Array2D< PointXYZW >	copyPointsXYZW () const
	Array2D of point coordinates in 4D More...

ZIVID_CORE_EXPORT Array2D< PointZ >	copyPointsZ () const
	Array2D of Z coordinates More...

ZIVID_CORE_EXPORT Array2D< ColorRGBA >	copyColorsRGBA () const
	Array2D of point colors in 8-bit RGBA format More...

ZIVID_CORE_EXPORT Array2D< ColorBGRA >	copyColorsBGRA () const
	Array2D of point colors in 8-bit BGRA format More...

ZIVID_CORE_EXPORT Image< ColorRGBA >	copyImageRGBA () const
	Get point cloud colors as 8-bit RGBA image More...

ZIVID_CORE_EXPORT Image< ColorBGRA >	copyImageBGRA () const
	Get point cloud colors as 8-bit BGRA image More...

ZIVID_CORE_EXPORT Array2D< SNR >	copySNRs () const
	Array2D of SNR values More...

ZIVID_CORE_EXPORT Array2D< NormalXYZ >	copyNormalsXYZ () const
	Array2D of NormalXYZ More...

ZIVID_CORE_EXPORT Array2D< PointXYZColorRGBA >	copyPointsXYZColorsRGBA () const
	Array2D of PointXYZColorRGBA More...

ZIVID_CORE_EXPORT Array2D< PointXYZColorBGRA >	copyPointsXYZColorsBGRA () const
	Array2D of PointXYZColorBGRA More...

template<typename DataFormat >
Array2D< DataFormat >	copyData () const
	Array2D with point cloud data using specified DataFormat More...

template<typename DataFormat >
void	copyData (DataFormat *destination) const
	Copy data in the specified DataFormat to a destination buffer More...

ZIVID_CORE_EXPORT std::string	toString () const
	Get string representation of the point cloud More...

ZIVID_CORE_EXPORT PointCloud &	transform (const Zivid::Matrix4x4 &matrix)
	Transform the point cloud in-place by the given 4x4 transformation matrix More...

ZIVID_CORE_EXPORT PointCloud &	downsample (Downsampling downsampling)
	Downsample the point cloud in-place More...

ZIVID_CORE_EXPORT PointCloud	downsampled (Downsampling downsampling) const
	Get a downsampled point cloud More...

Detailed Description

Point cloud with x, y, z, RGB color and SNR laid out on a 2D grid

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).

Member Enumeration Documentation

◆ Downsampling

enum class Zivid::PointCloud::Downsampling

strong

Option for downsampling

This enumeration defines if 2x2, 3x3 or 4x4 downsampling is performed.

See also: downsample, downsampled

Enumerator
by2x2
by3x3
by4x4

Constructor & Destructor Documentation

◆ PointCloud()

ZIVID_CORE_EXPORT Zivid::PointCloud::PointCloud ( )

Create an empty point cloud

Member Function Documentation

◆ copyColorsBGRA()

ZIVID_CORE_EXPORT Array2D< ColorBGRA > Zivid::PointCloud::copyColorsBGRA ( ) const

Array2D of point colors in 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 Array2D.

The returned Array2D contains the same pixel data as the Image returned by copyImageBGRA. However, the Image provides additional functionality such as saving the image to a file.

The format of each pixel is given by ColorBGRA.

◆ copyColorsRGBA()

ZIVID_CORE_EXPORT Array2D< ColorRGBA > Zivid::PointCloud::copyColorsRGBA ( ) const

Array2D of point colors in 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 Array2D.

The returned Array2D contains the same pixel data as the Image returned by copyImageRGBA. However, the Image provides additional functionality such as saving the image to a file.

The format of each pixel is given by ColorRGBA.

◆ copyData() [1/2]

template<typename DataFormat >

Array2D< DataFormat > Zivid::PointCloud::copyData ( ) const

inline

Array2D 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::PointCloud::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 data is stored sequentially in row major-order. The destination buffer must be large enough to hold PointCloud::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.
PointXYZW: 3D coordinates represented as 4D homogeneous coordinates. Contains 4 floats (x, y, z, w). w is always 1.0. Size per element is 16 bytes.
PointZ: Z coordinate. Contains 1 float z. Size per element is 4 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.
SNR: SNR values, contains one float member value. Size per element is 4 bytes.
NormalXYZ: Normal vectors. Contains 3 floats (x, y, z) packed together. The vectors are normalized. Size per element is 12 bytes.
PointXYZColorRGBA: 3D coordinates and RGBA color. This is a nested type which contains PointXYZ point and ColorRGBA color members. Size per element is 16 bytes.
PointXYZColorBGRA: 3D coordinates and BGRA color. This is a nested type which contains PointXYZ point and ColorBGRA color members. Size per element is 16 bytes.

See also: copyData, copyPointsXYZ, copyPointsXYZW, copyPointsZ, copyColorsRGBA, copySNRs, copyPointsXYZColorsRGBA, copyPointsXYZColorsBGRA

◆ copyImageBGRA()

ZIVID_CORE_EXPORT Image< ColorBGRA > Zivid::PointCloud::copyImageBGRA ( ) const

Get point cloud colors as 8-bit BGRA image

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

The returned Image contains the same pixel data as the Array2D returned by copyColorsBGRA. However, the Image provides additional functionality such as saving the image to a file.

The format of each pixel is given by ColorBGRA.

◆ copyImageRGBA()

ZIVID_CORE_EXPORT Image< ColorRGBA > Zivid::PointCloud::copyImageRGBA ( ) const

Get point cloud colors as 8-bit RGBA image

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

The returned Image contains the same pixel data as the Array2D returned by copyColorsRGBA. However, the Image provides additional functionality such as saving the image to a file.

The format of each pixel is given by ColorRGBA.

◆ copyNormalsXYZ()

ZIVID_CORE_EXPORT Array2D< NormalXYZ > Zivid::PointCloud::copyNormalsXYZ ( ) const

Array2D of NormalXYZ

This method computes the normals of the 3D points and copies the result from compute device memory to host (CPU) system memory (RAM). It returns them as an Array2D of normalized NormalXYZ. Each element in the array contains 3 float members (x, y, z) representing the 3D coordinates.

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

◆ copyPointsXYZ()

ZIVID_CORE_EXPORT Array2D< PointXYZ > Zivid::PointCloud::copyPointsXYZ ( ) const

Array2D of point coordinates

This method copies the 3D point coordinates from compute device memory to host (CPU) system memory (RAM) and returns them as an Array2D of PointXYZ. Each element in the array contains 3 float members (x, y, z) representing the 3D coordinates.

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.

copyPointsXYZW provides an array of points in homogeneous coordinates (Zivid::PointXYZW instead of Zivid::PointXYZ).

◆ copyPointsXYZColorsBGRA()

ZIVID_CORE_EXPORT Array2D< PointXYZColorBGRA > Zivid::PointCloud::copyPointsXYZColorsBGRA ( ) const

Array2D of PointXYZColorBGRA

This method copies the 3D point coordinates and colors from compute device memory to host (CPU) system memory (RAM) and returns them as an Array2D of PointXYZColorBGRA. PointXYZColorBGRA contains point coordinates stored as floats in a PointXYZ, and colors stored as BGRA (8 bits per channel) in a ColorBGRA.

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

◆ copyPointsXYZColorsRGBA()

ZIVID_CORE_EXPORT Array2D< PointXYZColorRGBA > Zivid::PointCloud::copyPointsXYZColorsRGBA ( ) const

Array2D of PointXYZColorRGBA

This method copies the 3D point coordinates and colors from compute device memory to host (CPU) system memory (RAM) and returns them as an Array2D of PointXYZColorRGBA. PointXYZColorRGBA contains point coordinates stored as floats in a PointXYZ, and colors stored as RGBA (8 bits per channel) in a ColorRGBA.

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

◆ copyPointsXYZW()

ZIVID_CORE_EXPORT Array2D< PointXYZW > Zivid::PointCloud::copyPointsXYZW ( ) const

Array2D of point coordinates in 4D

This method copies the point coordinates from compute device memory to host (CPU) system memory (RAM) memory and returns them as an Array2D of PointXYZW. The points are returned as 4D homogeneous coordinates. Each element in the array contains 4 float members (x, y, z, w). x, y and z represent the 3D coordinate of the point. w is always set to 1.0.

Storing the point coordinates in 4D can be useful in some scenarios. For example if the points are to be passed to a different library which expects 4 floats for point coordinates.

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

See copyPointsXYZ if you need points in 3D.

◆ copyPointsZ()

ZIVID_CORE_EXPORT Array2D< PointZ > Zivid::PointCloud::copyPointsZ ( ) const

Array2D of Z coordinates

This method copies the point Z coordinates from compute device memory to host (CPU) system memory (RAM) and returns them as an Array2D of PointZ.

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

◆ copySNRs()

ZIVID_CORE_EXPORT Array2D< SNR > Zivid::PointCloud::copySNRs ( ) const

Array2D of SNR values

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

◆ downsample()

ZIVID_CORE_EXPORT PointCloud & Zivid::PointCloud::downsample ( Downsampling downsampling )

Downsample the point cloud in-place

Downsampling is used to reduce the number of points in the point cloud. Downsampling is performed by combining a 2x2, 3x3 or 4x4 region of pixels in the original point cloud to one pixel in the new point cloud. A downsampling factor of 2x2 will reduce width and height each to half, and thus the overall number of points to 1/4. 3x3 downsampling reduces width and height each to 1/3, and the overall number of points to 1/9, and so on.

X, Y and Z coordinates are downsampled by computing the SNR^2 weighted average of each point in the corresponding NxN region in the original point cloud, ignoring invalid (NaN) points. Color is downsampled by computing the average value for each color channel in the NxN region. SNR value is downsampled by computing the square root of the sum of SNR^2 of each valid (non-NaN) point in the NxN region. If all points in the NxN region are invalid (NaN), the downsampled SNR is set to the max SNR in the region.

Downsampling is performed on the compute device. The point cloud is modified in-place. Use downsampled if you want to downsample to a new PointCloud instance. Downsampling can be repeated multiple times to further reduce the size of the point cloud, if desired.

Note that the width or height of the point cloud is not required to divide evenly by the downsampling factor (2, 3 or 4). The new width and height equals the original width and height divided by the downsampling factor, rounded down. In this case the remaining columns at the right and/or rows at the bottom of the original point cloud are ignored.

Parameters

downsampling This enum defines the size of the downsampled point cloud

See also: downsampled

◆ downsampled()

ZIVID_CORE_EXPORT PointCloud Zivid::PointCloud::downsampled ( Downsampling downsampling ) const

Get a downsampled point cloud

This method is identical to downsample, except the downsampled point cloud is returned as a new PointCloud instance. The current point cloud is not modified.

Parameters

downsampling This enum defines the size of the downsampled point cloud

See also: downsample

◆ height()

ZIVID_CORE_EXPORT size_t Zivid::PointCloud::height ( ) const

Get the height of the point cloud (number of rows)

◆ isEmpty()

ZIVID_CORE_EXPORT bool Zivid::PointCloud::isEmpty ( ) const

Check if the point cloud is empty (contains zero points)

◆ size()

ZIVID_CORE_EXPORT size_t Zivid::PointCloud::size ( ) const

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

This is identical to width() * height()

◆ toString()

ZIVID_CORE_EXPORT std::string Zivid::PointCloud::toString ( ) const

Get string representation of the point cloud

Returns: Point cloud info as string

◆ transform()

ZIVID_CORE_EXPORT PointCloud & Zivid::PointCloud::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

◆ width()

ZIVID_CORE_EXPORT size_t Zivid::PointCloud::width ( ) const

Get the width of the point cloud (number of columns)

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

Zivid/PointCloud.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Downsampling

Constructor & Destructor Documentation

◆ PointCloud()

Member Function Documentation

◆ copyColorsBGRA()

◆ copyColorsRGBA()

◆ copyData() [1/2]

◆ copyData() [2/2]

◆ copyImageBGRA()

◆ copyImageRGBA()

◆ copyNormalsXYZ()

◆ copyPointsXYZ()

◆ copyPointsXYZColorsBGRA()

◆ copyPointsXYZColorsRGBA()

◆ copyPointsXYZW()

◆ copyPointsZ()

◆ copySNRs()

◆ downsample()

◆ downsampled()

◆ height()

◆ isEmpty()

◆ size()

◆ toString()

◆ transform()

◆ width()