 |
Zivid C++ API 2.14.0+e4a0c4a9-1
|
|
Zivid C++ API 2.14.0+e4a0c4a9-1
|
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. | |
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).
If this point cloud is the result of a 2D+3D capture, then the point cloud RGB colors will be set from the captured 2D color image. If different pixel sampling (resolution) settings for 2D and 3D were used, or if the point cloud is upsampled or downsampled, then the RGB colors will be resampled to correspond 1:1 with the 3D point cloud resolution. To get the original resolution 2D color image from the 2D+3D capture, see the frame2D method of the Frame class.
If this point cloud is the result of a 3D-only capture, then the RGB colors will be set to a uniform default color.
|
strong |
Option for downsampling.
This enumeration defines if 2x2, 3x3 or 4x4 downsampling is performed.
| Enumerator | |
|---|---|
| by2x2 | |
| by3x3 | |
| by4x4 | |
| ZIVID_CORE_EXPORT Zivid::PointCloud::PointCloud | ( | ) |
Create an empty point cloud.
| 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.
| 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.
| 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.
| 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 color space 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.
|
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).
|
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:
x, y, z) packed together. Size per element is 12 bytes. x, y, z, w). w is always 1.0. Size per element is 16 bytes. z. Size per element is 4 bytes. r, g, b and a. a is always 255. Size per element 4 bytes. b, g, r and a. a is always 255. Size per element 4 bytes. r, g, b and a. a is always 255. Size per element 4 bytes. value. Size per element is 4 bytes. x, y, z) packed together. The vectors are normalized. Size per element is 12 bytes. point and ColorRGBA color members. Size per element is 16 bytes. point and ColorBGRA color members. Size per element is 16 bytes. | 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.
| 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.
| 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 color space 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.
| ZIVID_CORE_EXPORT Array2D< NormalXYZ > Zivid::PointCloud::copyNormalsXYZ | ( | ) | const |
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.
| 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).
| ZIVID_CORE_EXPORT Array2D< PointXYZColorBGRA > Zivid::PointCloud::copyPointsXYZColorsBGRA | ( | ) | const |
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.
| ZIVID_CORE_EXPORT Array2D< PointXYZColorRGBA > Zivid::PointCloud::copyPointsXYZColorsRGBA | ( | ) | const |
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.
| 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.
| 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.
| ZIVID_CORE_EXPORT Array2D< SNR > Zivid::PointCloud::copySNRs | ( | ) | const |
| 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.
As an alternative to using this method, downsampling may also be specified up-front when capturing by using Settings::Processing::Resampling.
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.
| downsampling | This enum defines the size of the downsampled point cloud |
| 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.
| downsampling | This enum defines the size of the downsampled point cloud |
| ZIVID_CORE_EXPORT size_t Zivid::PointCloud::height | ( | ) | const |
Get the height of the point cloud (number of rows)
| ZIVID_CORE_EXPORT bool Zivid::PointCloud::isEmpty | ( | ) | const |
Check if the point cloud is empty (contains zero points)
| ZIVID_CORE_EXPORT size_t Zivid::PointCloud::size | ( | ) | const |
| ZIVID_CORE_EXPORT std::string Zivid::PointCloud::toString | ( | ) | const |
Get string representation of the point cloud.
| 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].
| matrix | An affine 4x4 matrix |
| ZIVID_CORE_EXPORT size_t Zivid::PointCloud::width | ( | ) | const |
Get the width of the point cloud (number of columns)
1.12.0