Zivid::PointCloud Class Reference

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.
ZIVID_CORE_EXPORT size_t	width () const
	Get the width of the point cloud (number of columns)
ZIVID_CORE_EXPORT size_t	height () const
	Get the height of the point cloud (number of rows)
ZIVID_CORE_EXPORT size_t	size () const
	Get the size of the point cloud (total number of points)
ZIVID_CORE_EXPORT bool	isEmpty () const
	Check if the point cloud is empty (contains zero points)
ZIVID_CORE_EXPORT Array2D< PointXYZ >	copyPointsXYZ () const
	Array2D of point coordinates.
ZIVID_CORE_EXPORT Array2D< PointXYZW >	copyPointsXYZW () const
	Array2D of point coordinates in 4D.
ZIVID_CORE_EXPORT Array2D< PointZ >	copyPointsZ () const
	Array2D of Z coordinates.
ZIVID_CORE_EXPORT Array2D< ColorRGBA >	copyColorsRGBA () const
	Array2D of point colors in 8-bit RGBA format.
ZIVID_CORE_EXPORT Array2D< ColorBGRA >	copyColorsBGRA () const
	Array2D of point colors in 8-bit BGRA format.
ZIVID_CORE_EXPORT Array2D< ColorSRGB >	copyColorsSRGB () const
	Array2D of point colors in 8-bit RGBA format in the sRGB color space.
ZIVID_CORE_EXPORT Image< ColorRGBA >	copyImageRGBA () const
	Get point cloud colors as 8-bit RGBA image.
ZIVID_CORE_EXPORT Image< ColorBGRA >	copyImageBGRA () const
	Get point cloud colors as 8-bit BGRA image.
ZIVID_CORE_EXPORT Image< ColorSRGB >	copyImageSRGB () const
	Get point cloud colors as 8-bit RGB image in the sRGB color space.
ZIVID_CORE_EXPORT Array2D< SNR >	copySNRs () const
	Array2D of SNR values.
ZIVID_CORE_EXPORT Array2D< NormalXYZ >	copyNormalsXYZ () const
	Array2D of NormalXYZ.
ZIVID_CORE_EXPORT Array2D< PointXYZColorRGBA >	copyPointsXYZColorsRGBA () const
	Array2D of PointXYZColorRGBA.
ZIVID_CORE_EXPORT Array2D< PointXYZColorBGRA >	copyPointsXYZColorsBGRA () const
	Array2D of PointXYZColorBGRA.
template<typename DataFormat >
Array2D< DataFormat >	copyData () const
	Array2D 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 std::string	toString () const
	Get string representation of the point cloud.
ZIVID_CORE_EXPORT PointCloud &	transform (const Zivid::Matrix4x4 &matrix)
	Transform the point cloud in-place by the given 4x4 transformation matrix.
ZIVID_CORE_EXPORT PointCloud &	downsample (Downsampling downsampling)
	Downsample the point cloud in-place.
ZIVID_CORE_EXPORT PointCloud	downsampled (Downsampling downsampling) const
	Get a downsampled point cloud.
ZIVID_CORE_EXPORT PointCloud	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 or downsample) on the original point cloud.

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

clone()

ZIVID_CORE_EXPORT PointCloud Zivid::PointCloud::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 or downsample) 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 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.

This format holds linear color values, which are suitable as input to computer vision algorithms. For showing colors on a display for viewing, consider using the ColorSRGB format.

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.

This format holds linear color values, which are suitable as input to computer vision algorithms. For showing colors on a display for viewing, consider using the ColorSRGB format.

copyColorsSRGB()

ZIVID_CORE_EXPORT Array2D< ColorSRGB > Zivid::PointCloud::copyColorsSRGB

(

)

const

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

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 format is assumed by default by most monitors and should be used when displaying an image.

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

The format of each pixel is given by ColorSRGB.

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.
• ColorSRGB: 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.
• 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.

This format holds linear color values, which are suitable as input to computer vision algorithms. For showing colors on a display for viewing, consider using the ColorSRGB format.

copyImageSRGB()

ZIVID_CORE_EXPORT Image< ColorSRGB > Zivid::PointCloud::copyImageSRGB

(

)

const

Get point cloud colors as 8-bit RGB image 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 Image.

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 format is assumed by default by most monitors and should be used when displaying an image.

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

The format of each pixel is given by ColorSRGB.

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