Applications Basic

The output types produced by a capture and the building blocks for visualization, file IO, and basic point-cloud processing. Captures on Camera Basic produce the Frame and Frame2D types documented below. Mirrors the public sample tree at {cpp,csharp,python}/source/Applications/Basic/ and the academy chapter at Point Cloud Tutorial.

        flowchart LR
  subgraph frame [Frame/Frame2D]
    direction TB
    Frame
    frame2DOp(["frame2D()"])
    Frame2D
  end
  subgraph outputs [Outputs]
    PointCloud
    transformOp(["transform()"])
    normalsOp(["normals()"])
    downsampleOp(["downsample()"])
    toUnorganizedOp(["toUnorganizedPointCloud()"])
    UnorganizedPointCloud
    Image
    Visualizer
  end

  pointCloudOp(["pointCloud()"])
  imageRGBAOp(["imageRGBA()"])

  Frame --> pointCloudOp --> PointCloud
  Frame --> frame2DOp --> Frame2D
  Frame2D --> imageRGBAOp --> Image
  PointCloud --> transformOp
  PointCloud --> normalsOp
  PointCloud --> downsampleOp
  PointCloud --> toUnorganizedOp --> UnorganizedPointCloud
  PointCloud -.-> Visualizer
  Image -.-> Visualizer

  classDef zividClass fill:#4A8FA4,stroke:#34323D,color:#FFFFFF
  classDef api fill:#91D2C8,stroke:#4A8FA4,color:#000000
  class Frame,Frame2D,PointCloud,UnorganizedPointCloud,Image,Visualizer zividClass
  class frame2DOp,pointCloudOp,imageRGBAOp,transformOp,normalsOp,downsampleOp,toUnorganizedOp api

Frame (2D + 3D)

The result of a 2D + 3D capture. Owns the point cloud and an optional 2D color frame.

C++

class Frame

A frame captured by a Zivid camera.

Contains the point cloud (stored on compute device memory) as well as calibration data, settings and state used by the API at time of the frame capture. Use Frame::pointCloud() to access point cloud data.

Note that if this Frame object was returned from a call to Camera::capture, then there may still be remaining data transfer and processing going on in the background. When you call a method on the Frame object that requires the capture to be finished, for example Frame::pointCloud(), the method will block until the point cloud is available.

Public Functions

Frame(): Construct a new frame.

explicit Frame(const std::string &fileName): Creates a frame by loading data from a file.

PointCloud pointCloud() const

Get the point cloud.

If the point cloud is not yet available because the capture is still in-progress, then this method will block until the point cloud is available.

The PointCloud instance returned is a handle to the actual point cloud data stored on the compute device memory. See PointCloud for more information.

std::optional<Frame2D> frame2D() const

Get 2D frame from 2D+3D frame.

If the frame is the result of a 2D+3D capture, this method returns the 2D frame contained in the 2D+3D frame. In the case of a 3D-only capture, this method returns an empty std::optional.

If the frame was captured by an SDK version prior to 2.14.0, then this method will return an empty std::optional.

If the 2D frame is not yet available because the capture is still in-progress, then this method will block until acquisition of the entire 2D+3D capture is done. If you need to access the 2D frame before the 3D acquisition has finished, then it is required to do separate 2D and 3D captures.

In a 2D+3D capture, the 2D color image and 3D point cloud may have different resolutions depending on the pixel sampling settings used. The 2D pixel sampling setting determines the resolution of the 2D color image whereas the 3D pixel sampling setting and the resampling setting determines the resolution of the 3D point cloud. The 2D color image returned in this 2D frame will always have the same resolution as the 2D color image that was captured. On the other hand, the point cloud colors will be sampled from the 2D color image to match the resolution of the 3D point cloud. The point cloud colors will always have a 1:1 correspondence with the 3D point cloud resolution. See PointCloud for more information.

CameraState state() const

Get the camera state data at the time of the frame capture.

If the capture is still in-progress, then this method will block until the capture completes.

Settings settings() const

Get the settings used to capture this frame.

This method returns instantly, even if the capture is still in-progress.

FrameInfo info() const

Get information collected at the time of the frame capture.

If the capture is still in-progress, then this method will block until the capture completes.

CameraInfo cameraInfo() const

Get information about the camera used to capture the frame.

This method returns instantly, even if the capture is still in-progress.

void save(const std::string &fileName) const

Save the frame to file.

The file type is determined from the file extension. Supported extensions are .zdf, .ply (ordered), .xyz and .pcd.

If the capture is still in-progress, then this method will block until the capture completes.

This method will copy the necessary point cloud data from the compute device (GPU) memory into host memory (RAM), unless that data has already been copied to host memory by an earlier function call.

This method saves the RGB colors in linear color space for .ply, .xyz and .pcd file formats. This method does not save the normal data in the .ply and .pcd file formats. The points saved in .ply format will contain NaN (invalid) values. For .pcd format, the saved file will contain a header that indicates an unorganized point cloud. However the points will contain NaN (invalid) values as well. Since SDK 2.5, it is possible to export PCD with correct header (organized) by setting Configuration/APIBreakingBugFixes/FileFormats/PCD/UseOrganizedFormat in Config.yml file. See https://support.zivid.com/en/latest/reference-articles/point-cloud-structure-and-output-formats.html#organized-pcd-format

It is recommended to use exportFrame methods to save point cloud to different file formats. exportFrame methods allow customization of the color space of RGB values (linear or sRGB), controlling the layout of the points (organized or unorganized) and saving normal data in the .ply and .pcd file formats. See:

Zivid::Experimental::PointCloudExport::exportFrame(const Zivid::Frame &, const Zivid::Experimental::PointCloudExport::FileFormat::PLY &) Zivid::Experimental::PointCloudExport::exportFrame(const Zivid::Frame &, const Zivid::Experimental::PointCloudExport::FileFormat::XYZ &) Zivid::Experimental::PointCloudExport::exportFrame(const Zivid::Frame &, const Zivid::Experimental::PointCloudExport::FileFormat::PCD &)

Parameters:: fileName – File name to save the frame to

void load(const std::string &fileName)

Load a frame from a .zdf file.

If the file contains a 2D frame, use Frame2D::load instead. Use Zivid::readFrameFileType to determine the frame type without loading. This method will throw an exception if the frame type is not frame.

std::string toString() const

Get string representation of the frame.

If the capture is still in-progress, then this method will block until the capture completes.

Returns:: Frame info as string

Frame clone() const

Returns a clone of the frame.

The clone will include a copy of all of the point cloud data on the compute device memory. This means that the returned frame will not be affected by subsequent modifications on the original frame or 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 frame or point cloud.

void mask(const Mask &mask) const

Applies the given mask to the point cloud in this frame.

Points corresponding to non-zero values in the mask will be set to NaN.

The mask must have the same resolution as the point cloud. This method modifies the point cloud in-place.

Parameters:: mask – The mask to apply to the point cloud

Frame masked(const Mask &mask) const

Returns a new frame with the point cloud masked according to the provided mask.

Points corresponding to non-zero values in the mask will be set to NaN.

The mask must have the same resolution as the point cloud. This method creates a copy of the frame with the masking applied to the point cloud data.

Parameters:: mask – The mask to apply to the point cloud
Returns:: A new frame with the masked point cloud

C#

class Frame

A frame captured by a Zivid camera.

Contains the point cloud (stored on compute device memory) as well as calibration data, settings and state used by the API at time of the frame capture. Use PointCloud to access point cloud data.

Note that if this Frame object was returned from a call to Camera::Capture(Settings^) or Camera::Capture(Settings2D^), then there may still be remaining data transfer and processing going on in the background. When you call a method on the Frame object that requires the capture to be finished, for example Frame::PointCloud(), the method will block until the point cloud is available.

Public Functions

Frame (System::String ^ fileName)

Create a frame by loading data from a file.

Use Zivid::NET::FrameFile to determine the frame type without loading. This method will throw an exception if the frame type is not Frame.

Parameters:: fileName – Name of file in ZDF format

Frame(Zivid::Frame &&cppInstance): Create a .NET frame from a native frame.

void Save (System::String ^ fileName)

Save the frame to file.

The file type is determined from the file extension. Supported extensions are .zdf, .ply (ordered), .xyz and .pcd.

If the capture is still in-progress, then this method will block until the capture completes.

This method will copy the necessary point cloud data from the compute device (GPU) memory into host memory (RAM), unless that data has already been copied to host memory by an earlier function call.

This method saves the RGB colors in linear color space for .ply, .xyz and .pcd file formats. This method does not save the normal data in the .ply and .pcd file formats. The points saved in .ply format will contain NaN (invalid) values. For .pcd format, the saved file will contain a header that indicates an unorganized point cloud. However the points will contain NaN (invalid) values as well. Since SDK 2.5, it is possible to export PCD with correct header (organized) by setting Configuration/APIBreakingBugFixes/FileFormats/PCD/UseOrganizedFormat in Config.yml file. See https://support.zivid.com/en/latest/reference-articles/point-cloud-structure-and-output-formats.html#organized-pcd-format

It is recommended to use ExportFrame methods to save point cloud to different file formats. ExportFrame methods allow customization of the color space of RGB values (linear or sRGB), controlling the layout of the points (organized or unorganized) and saving normal data in the .ply and .pcd file formats. See:

Experimental::PointCloudExport::ExportFrame(Frame ^frame, Experimental::PointCloudExport::FileFormat::PLY ^specification) Experimental::PointCloudExport::ExportFrame(Frame ^frame, Experimental::PointCloudExport::FileFormat::XYZ ^specification) Experimental::PointCloudExport::ExportFrame(Frame ^frame, Experimental::PointCloudExport::FileFormat::PCD ^specification)

Parameters:: fileName – File name to save the frame to

void Load (System::String ^ fileName)

Load a frame from a Zivid data file.

Parameters:: fileName – Filename

Frame ^ Mask (Zivid::NET::Mask ^ mask)

Apply a binary mask to the frame’s point cloud in-place.

The mask indicates which points in the frame’s point cloud should be considered invalid (NaN). The mask must have the same height and width as the point cloud. A value of True/non-zero in the mask indicates that the corresponding point in the point cloud should be set to invalid (NaN). A value of False/zero indicates that the corresponding point should be kept unchanged.

If the capture is still in-progress, then this method will block until the capture completes.

See also

Masked

Parameters:: mask – A binary mask with the same resolution as the frame’s point cloud

Frame ^ Masked (Zivid::NET::Mask ^ mask)

Get a copy of the frame with a binary mask applied to its point cloud.

This method is identical to Mask, except the masked frame is returned as a new Frame instance. The current frame is not modified.

The mask indicates which points in the frame’s point cloud should be considered invalid (NaN). The mask must have the same height and width as the point cloud. A value of True/non-zero in the mask indicates that the corresponding point in the point cloud should be set to invalid (NaN). A value of False/zero indicates that the corresponding point should be kept unchanged.

If the capture is still in-progress, then this method will block until the capture completes.

See also

Mask

Parameters:: mask – A binary mask with the same resolution as the frame’s point cloud

Frame ^ ShallowCopy ()

Returns a shallow copy of the frame.

The copy will share the point cloud data with the original frame. This means that modifications to the point cloud data in the copy will also affect the original frame.

To create a deep copy of the frame, use the Clone method instead.

The copy will not be disposed when the original frame is disposed. Both the original and the copy will need to be disposed separately.

Frame ^ Clone ()

Returns a clone of the frame.

The clone will include a copy of all of the point cloud data on the compute device memory. This means that the returned frame will not be affected by subsequent modifications on the original frame or point cloud.

To create a shallow copy of the frame, use the ShallowCopy method instead.

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 frame or point cloud.

System::String ^ ToString () override

Get string representation of the frame.

If the capture is still in-progress, then this method will block until the capture completes.

Returns:: Frame info as string

Properties

Zivid::NET::PointCloud^ PointCloud

The point cloud.

If the point cloud is not yet available because the capture is still in-progress, accessing this property will block until the point cloud is available.

The PointCloud instance returned is a handle to the actual point cloud data stored on the compute device memory. See PointCloud for more information.

The point cloud returned by this property will be automatically disposed when the parent frame is disposed. If you need to keep the point cloud alive after the parent frame is disposed, then you need to clone the point cloud using the Zivid::NET::PointCloud::Clone method.

Zivid::NET::Frame2D^ Frame2D

Get 2D frame from 2D+3D frame.

If the frame is the result of a 2D+3D capture, this method returns the 2D frame contained in the 2D+3D frame. In the case of a 3D-only capture, this method returns null.

If the frame was captured by an SDK version prior to 2.14.0, then this method will return null.

If the 2D frame is not yet available because the capture is still in-progress, then this method will block until acquisition of the entire 2D+3D capture is done. If you need to access the 2D frame before the 3D acquisition has finished, then it is required to do separate 2D and 3D captures.

In a 2D+3D capture, the 2D color image and 3D point cloud may have different resolutions depending on the pixel sampling settings used. The 2D pixel sampling setting determines the resolution of the 2D color image whereas the 3D pixel sampling setting and the resampling setting determines the resolution of the 3D point cloud. The 2D color image returned in this 2D frame will always have the same resolution as the 2D color image that was captured. On the other hand, the point cloud colors will be sampled from the 2D color image to match the resolution of the 3D point cloud. The point cloud colors will always have a 1:1 correspondence with the 3D point cloud resolution. See PointCloud for more information.

The 2D frame returned by this method will be automatically disposed when the parent 2D+3D frame is disposed. If you need to keep the 2D frame alive after the parent 2D+3D frame is disposed, then you need to clone the 2D frame using the Zivid::NET::Frame2D::Clone method.

FrameInfo^ Info

Additional information associated with the frame.

If the capture is still in-progress, then this method will block until the capture completes.

Settings^ Settings

The camera settings at the time of the frame capture.

This method returns instantly, even if the capture is still in-progress.

CameraState^ State

The camera state data at the time of the frame capture.

If the capture is still in-progress, then this method will block until the capture completes.

Zivid::NET::CameraInfo^ CameraInfo

Information about the camera used to capture the frame.

This method returns instantly, even if the capture is still in-progress.

Python

frame = camera.capture_2d_3d(settings)

PointCloud

The structured (organized) point cloud produced from a 2D + 3D capture.

C++

class PointCloud

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.

Public Types

enum class Downsampling

Option for downsampling.

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

See also

downsample, downsampled

Values:

enumerator by2x2

enumerator by3x3

enumerator by4x4

Public Functions

PointCloud(): Create an empty point cloud.

size_t width() const: Get the width of the point cloud (number of columns)

size_t height() const: Get the height of the point cloud (number of rows)

size_t size() const

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

This is identical to width() * height()

Resolution resolution() const

Get the resolution of the point cloud.

Returns:: Resolution object containing width and height of the point cloud

bool isEmpty() const: Check if the point cloud is empty (contains zero points)

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

Array2D<PointXYZW> 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.

Array2D<PointZ> 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.

Array2D<ColorRGBA> 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 ColorRGBA_SRGB format.

Array2D<ColorBGRA> 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 ColorRGBA_SRGB format.

Array2D<ColorRGBA_SRGB> 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 copyImageRGBA_SRGB. However, the Image provides additional functionality such as saving the image to a file.

The format of each pixel is given by ColorRGBA_SRGB.

This method has been deprecated as of SDK 2.15. The method will be removed in the next SDK major version (SDK 3.0). Prefer to use the new and equivalent method copyColorsRGBA_SRGB.

Array2D<ColorRGBA_SRGB> copyColorsRGBA_SRGB() 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 copyImageRGBA_SRGB. However, the Image provides additional functionality such as saving the image to a file.

The format of each pixel is given by ColorRGBA_SRGB.

Array2D<ColorBGRA_SRGB> copyColorsBGRA_SRGB() const

Array2D of point colors in 8-bit BGRA format in the sRGB color space.

This method copies the BGRA values in the sRGB color space 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 copyImageBGRA_SRGB. However, the Image provides additional functionality such as saving the image to a file.

The format of each pixel is given by ColorBGRA_SRGB.

Image<ColorRGBA> 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 ColorRGBA_SRGB format.

Image<ColorBGRA> 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.

Image<ColorRGBA_SRGB> copyImageSRGB() const

Get point cloud colors as 8-bit RGBA 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 copyColorsRGBA_SRGB. However, the Image provides additional functionality such as saving the image to a file.

The format of each pixel is given by ColorRGBA_SRGB.

This method has been deprecated as of SDK 2.15. The method will be removed in the next SDK major version (SDK 3.0). Prefer to use the new and equivalent method copyImageRGBA_SRGB.

Image<ColorRGBA_SRGB> copyImageRGBA_SRGB() const

Get point cloud colors as 8-bit RGBA 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 copyColorsRGBA_SRGB. However, the Image provides additional functionality such as saving the image to a file.

The format of each pixel is given by ColorRGBA_SRGB.

Image<ColorBGRA_SRGB> copyImageBGRA_SRGB() const

Get point cloud colors as 8-bit BGRA image in the sRGB color space.

This method copies the BGRA values in the sRGB color space 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 copyColorsBGRA_SRGB. However, the Image provides additional functionality such as saving the image to a file.

The format of each pixel is given by ColorBGRA_SRGB.

Array2D<SNR> 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.

Array2D<NormalXYZ> 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.

DeviceArray<PointXYZ> devicePointsXYZ(StreamOrQueue streamOrQueue) const: Get a device buffer containing XYZ point coordinates, synchronized to the user’s stream/queue.

DeviceArray<PointXYZW> devicePointsXYZW(StreamOrQueue streamOrQueue) const: Get a device buffer containing XYZW point coordinates, synchronized to the user’s stream/queue.

DeviceArray<PointZ> devicePointsZ(StreamOrQueue streamOrQueue) const: Get a device buffer containing Z point coordinates, synchronized to the user’s stream/queue.

DeviceArray<SNR> deviceSNRs(StreamOrQueue streamOrQueue) const: Get a device buffer containing SNR values, synchronized to the user’s stream/queue.

DeviceArray<NormalXYZ> deviceNormalsXYZ(StreamOrQueue streamOrQueue) const: Get a device buffer containing normal vectors, synchronized to the user’s stream/queue.

template<typename ColorFormat, typename = std::enable_if_t<Detail::SupportedImageDeviceArrayColorFormat<ColorFormat>::value>> DeviceArray<ColorFormat> imageDeviceArray(StreamOrQueue streamOrQueue) const: Get the point cloud color image as a device buffer in the specified format.

template<typename ColorFormat, typename = std::enable_if_t<Detail::SupportedImageDeviceArrayColorFormat<ColorFormat>::value>> void imageDeviceArray(DeviceArrayView<ColorFormat> destinationBuffer, StreamOrQueue streamOrQueue) const

Fill a user-provided DeviceArrayView with the point cloud’s color image in the specified format.

Writes the color image directly into the memory referenced by the view, bypassing the SDK’s internal cache. Throws an exception on shape mismatch. The caller’s stream/queue carries a barrier against the SDK compute on return.

Template Parameters:

ColorFormat – Target color format.

Parameters:

destinationBuffer – Non-owning view over the destination device memory - either created via createDeviceArrayView from a caller-owned pointer, or borrowed from a DeviceArray.
streamOrQueue – User CUDA stream or OpenCL command queue to synchronize the completion of the color conversion on. Either a CUDAStreamPtr or OpenCLCommandQueuePtr, which converts implicitly.

Array2D<PointXYZColorRGBA> 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.

Array2D<PointXYZColorRGBA_SRGB> copyPointsXYZColorsRGBA_SRGB() const

Array2D of PointXYZColorRGBA_SRGB.

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_SRGB. PointXYZColorRGBA_SRGB contains point coordinates stored as floats in a PointXYZ, and colors stored as SRGB (RGBA order with 8 bits per channel in the sRGB color space) in a ColorRGBA_SRGB.

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

Array2D<PointXYZColorBGRA> 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.

Array2D<PointXYZColorBGRA_SRGB> copyPointsXYZColorsBGRA_SRGB() const

Array2D of PointXYZColorBGRA_SRGB.

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_SRGB. PointXYZColorBGRA_SRGB contains point coordinates stored as floats in a PointXYZ, and colors stored in BGRA order (8 bits per channel in the sRGB color space) in a ColorBGRA_SRGB.

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

template<typename DataFormat> inline Array2D<DataFormat> copyData() const

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

template<typename DataFormat> inline void copyData(DataFormat *destination) const

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.
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.
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.
PointXYZColorRGBA_SRGB: 3D coordinates and RGBA color in the sRGB color space. This is a nested type which contains PointXYZ point and ColorRGBA_SRGB 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.
PointXYZColorBGRA_SRGB: 3D coordinates and BGRA color in the sRGB color space. This is a nested type which contains PointXYZ point and ColorBGRA_SRGB color members. Size per element is 16 bytes.

std::string toString() const

Get string representation of the point cloud.

Returns:: Point cloud info as string

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

PointCloud 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 PointCloud instance. The current point cloud is not modified.

Parameters:: matrix – An affine 4x4 matrix

Zivid::Matrix4x4 transformationMatrix() const

Return the current transformation matrix of this point cloud.

Returns the transformation matrix from the camera’s native coordinate system to the current coordinate system. The returned matrix represents the cumulative result of all the transform operations performed on the point cloud. If no transformations have been applied, the identity matrix is returned.

Note: ZDF files saved from SDK 2.14 or earlier did not store the active transformation matrix. This means that for point clouds loaded from .zdf files from SDK 2.14 or earlier, this method will always return the identity matrix even in the case where the point cloud had been transformed prior to saving.

See also

transform

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.

See also

downsampled

Parameters:: downsampling – This enum defines the size of the downsampled point cloud

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.

See also

downsample

Parameters:: downsampling – This enum defines the size of the downsampled point cloud

PointCloud &maskByRegionOfInterest(const Zivid::Settings::RegionOfInterest::Box &roiSettings)

Apply region of interest filtering to the point cloud in-place.

Region of interest filtering is used to mask out points that fall outside a specified 3D box region. Points outside the region are set to invalid (NaN) values, effectively removing them from the point cloud while maintaining the original dimensions and structure.

The filtering is performed on the compute device. The point cloud is modified in-place. Use maskedByRegionOfInterest if you want to apply ROI masking to a new PointCloud instance.

The ROI box must be enabled (roiSettings.isEnabled() == true) for the filtering to be applied.

See also

maskedByRegionOfInterest

Parameters:: roiSettings – The ROI box settings defining the 3D region to preserve

PointCloud maskedByRegionOfInterest(const Zivid::Settings::RegionOfInterest::Box &roiSettings) const

Apply region of interest filtering to a copy of the point cloud.

This method is identical to maskByRegionOfInterest, except that the filtering is performed on a copy of the original point cloud. This method does not modify the original point cloud.

See also

maskByRegionOfInterest

Parameters:: roiSettings – The ROI box settings defining the 3D region to preserve

PointCloud &mask(const Zivid::Mask &mask)

Apply a mask to the point cloud in-place.

This method applies the provided mask to the point cloud. Points corresponding to non-zero values in the mask are set to invalid (NaN) values, effectively removing them from the point cloud while maintaining the original dimensions and structure.

The masking is performed on the compute device. The point cloud is modified in-place. Use masked if you want to apply the mask to a new PointCloud instance.

Parameters:: mask – The mask to apply to the point cloud

PointCloud masked(const Zivid::Mask &mask) const

Get a masked point cloud.

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

Parameters:: mask – The mask to apply to the point cloud

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.

UnorganizedPointCloud toUnorganizedPointCloud() const

Convert to an UnorganizedPointCloud.

The PointCloud class represents an organized point cloud, meaning that it contains 3D data for every pixel (row, col) on the sensor. If 3D data could not be computed for a given pixel, or was removed by a filter, that pixel contains (x,y,z) = (NaN, NaN, NaN) representing an “invalid” point. For some use cases it is more useful to have an unorganized point cloud, which instead contains a linear list of only valid points.

This function efficiently picks out the valid (not-NaN) points from this structured point cloud, and constructs an unorganized point cloud containing the XYZ, Color and SNR from those points only. The resulting unorganized point cloud will have less than (or equal) memory footprint compared to the structured point cloud it comes from, since it will contain fewer (or equal) number of points.

See UnorganizedPointCloud for more information on how to use the return value.

C#

class PointCloud

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 property of the Zivid::NET::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.

Public Types

enum class Downsampling

Option for downsampling.

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

See also

Downsample, Downsampled

Values:

enumerator By2x2

enumerator By3x3

enumerator By4x4

Public Functions

Float3DimArray ^ CopyPointsXYZ ()

Point coordinates (x, y, and z) as a float array of rank 3 with size height * width * 3.

This method copies the point coordinates from compute device memory to host (CPU) system memory (RAM) memory and returns them in a float array. First dimension is row (0 to height-1), second dimension is column (0 to width-1), and third dimension is x/y/z (x=0, y=1, z=2). For example, to get z coordinate of row 100, column 200 on the 2D grid, use index [100, 200, 2].

See also

CopyPointsXYZW

Returns:: Rank 3 float array of XYZ point coordinates

Float3DimArray ^ CopyPointsXYZW ()

Point coordinates as 4D (homogeneous coordinates) as a float array of rank 3 with size height * width * 4.

This method copies the point coordinates (as 4D homogeneous coordinates) from compute device memory to host (CPU) system memory (RAM) and returns them in a float array. Note that W is always set to 1.0. First dimension is row (0 to height-1), second dimension is column (0 to width-1), and third dimension is x/y/z/w (x=0, y=1, z=2, w=3). For example, to get x coordinate of row 50, column 400 on the 2D grid, use index [50, 400, 0].

See also

CopyPointsXYZ

Returns:: Rank 3 float array of XYZW point coordinates

Float2DimArray ^ CopyPointsZ ()

Point Z values as a 2D float array of size height * width.

This method copies the point Z coordinates from compute device memory to host (CPU) system memory (RAM) and returns them in a 2D float array. First dimension is row (0 to height-1), second dimension is column (0 to width-1).

Returns:: Rank 2 float array of point Z coordinates

Float2DimArray ^ CopySNRs ()

Get signal-to-noise ratio (SNR) values as a 2D float array of size height * width.

This method copies the SNR values from compute device memory to host (CPU) system memory (RAM) and returns them as an 2D array. First dimension is row (0 to height-1), second dimension is column (0 to width-1).

Returns:: Rank 2 float array of SNR values

Float3DimArray ^ CopyNormalsXYZ ()

Normal vectors (x, y, and z) as a float array of rank 3 with size height * width * 3.

This method computes the normals of the 3D points and copies the result from compute device memory to host (CPU) system memory (RAM) and returns them in a float array. First dimension is row (0 to height-1), second dimension is column (0 to width-1), and third dimension is x/y/z (x=0, y=1, z=2). For example, to get z value of the normal at row 100, column 200 on the 2D grid, use index [100, 200, 2]. The vectors are normalized.

Returns:: Rank 3 float array of normals

Byte3DimArray ^ CopyColorsRGBA ()

Point colors (RGBA) as a byte array of rank 3 with size height * width * 4.

This method copies the colors from compute device memory to host (CPU) system memory (RAM) and returns them as a byte array. The format of the image will be four channels (R,G,B,A), with 8 bits per channel.

The returned byte array holds the same pixel data as the Zivid::NET::ImageRGBA returned by CopyImageRGBA. However, the Zivid::NET::ImageRGBA provides additional functionality such as saving the image to a file.

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 ColorRGBA_SRGB format.

See also

CopyImageRGBA

Returns:: Rank 3 byte array of RGBA color values

Byte3DimArray ^ CopyColorsBGRA ()

Point colors (BGRA) as a byte array of rank 3 with size height * width * 4.

This method copies the colors from compute device memory to host (CPU) system memory (RAM) and returns them as a byte array. The format of the image will be four channels (B,G,R,A), with 8 bits per channel.

The returned byte array holds the same pixel data as the Zivid::NET::ImageBGRA returned by CopyImageBGRA. However, the Zivid::NET::ImageBGRA provides additional functionality such as saving the image to a file.

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 ColorRGBA_SRGB format.

See also

CopyImageBGRA

Returns:: Rank 3 byte array of BGRA color values

Byte3DimArray ^ CopyColorsSRGB ()

Point colors (RGBA in sRGB color space) as a byte array of rank 3 with size height * width * 4.

This method copies the colors from compute device memory to host (CPU) system memory (RAM) and returns them as a byte array. The format of the image will be four channels (R,G,B,A), with 8 bits per channel.

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 byte array holds the same pixel data as the Zivid::NET::ImageSRGB returned by CopyImageSRGB. However, the Zivid::NET::ImageSRGB provides additional functionality such as saving the image to a file.

This method has been deprecated as of SDK 2.15. The method will be removed in the next SDK major version (SDK 3.0). Prefer to use the new and equivalent method CopyColorsRGBA_SRGB.

See also

CopyImageSRGB

Returns:: Rank 3 byte array of SRGB color values

Byte3DimArray ^ CopyColorsRGBA_SRGB ()

Point colors (RGBA in sRGB color space) as a byte array of rank 3 with size height * width * 4.

This method copies the colors from compute device memory to host (CPU) system memory (RAM) and returns them as a byte array. The format of the image will be four channels (R,G,B,A), with 8 bits per channel.

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 byte array holds the same pixel data as the Zivid::NET::ImageSRGB returned by CopyImageRGBA_SRGB. However, the Zivid::NET::ImageRGBA_SRGB provides additional functionality such as saving the image to a file.

See also

CopyImageRGBA_SRGB

Returns:: Rank 3 byte array of SRGB color values

Byte3DimArray ^ CopyColorsBGRA_SRGB ()

Point colors (BGRA in sRGB color space) as a byte array of rank 3 with size height * width * 4.

This method copies the colors from compute device memory to host (CPU) system memory (RAM) and returns them as a byte array. The format of the image will be four channels (B,G,R,A), with 8 bits per channel.

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 byte array holds the same pixel data as the Zivid::NET::ImageBGRA_SRGB returned by CopyImageBGRA_SRGB. However, the Zivid::NET::ImageBGRA_SRGB provides additional functionality such as saving the image to a file.

See also

CopyImageBGRA_SRGB

Returns:: Rank 3 byte array of BGRA_SRGB color values

Zivid::NET::ImageRGBA ^ CopyImageRGBA ()

Point colors (RGBA) as a 2D image.

This method copies the colors from compute device memory to host (CPU) system memory (RAM) and returns them as an Image. The format of the image will be four channels (R,G,B,A), with 8 bits per channel.

The returned Zivid::NET::ImageRGBA holds the same pixel data as the byte array returned by CopyColorsRGBA. However, the Zivid::NET::ImageRGBA provides additional functionality such as saving the image to a file.

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 ColorRGBA_SRGB format.

See also

CopyColorsRGBA

Returns:: Point colors as 8-bit RGBA image

Zivid::NET::ImageBGRA ^ CopyImageBGRA ()

Point colors (BGRA) as a 2D image.

This method copies the colors from compute device memory to host (CPU) system memory (RAM) and returns them as an Image. The format of the image will be four channels (B,G,R,A), with 8 bits per channel.

The returned Zivid::NET::ImageBGRA holds the same pixel data as the byte array returned by CopyColorsBGRA. However, the Zivid::NET::ImageBGRA provides additional functionality such as saving the image to a file.

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 ColorBGRA_SRGB format.

See also

CopyColorsBGRA

Returns:: Point colors as 8-bit BGRA image

Zivid::NET::ImageSRGB ^ CopyImageSRGB ()

Point colors (RGBA in sRGB color space) as a 2D image.

This method copies the colors from compute device memory to host (CPU) system memory (RAM) and returns them as an Image. The format of the image will be four channels (R,G,B,A), with 8 bits per channel.

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 Zivid::NET::ImageSRGB holds the same pixel data as the byte array returned by CopyColorsSRGB. However, the Zivid::NET::ImageSRGB provides additional functionality such as saving the image to a file.

This method has been deprecated as of SDK 2.15. The method will be removed in the next SDK major version (SDK 3.0). Prefer to use the new and equivalent method CopyImageRGBA_SRGB.

See also

CopyColorsSRGB

Returns:: Point colors as 8-bit SRGB image

Zivid::NET::ImageRGBA_SRGB ^ CopyImageRGBA_SRGB ()

Point colors (RGBA in sRGB color space) as a 2D image.

This method copies the colors from compute device memory to host (CPU) system memory (RAM) and returns them as an Image. The format of the image will be four channels (R,G,B,A), with 8 bits per channel.

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 Zivid::NET::ImageRGBA_SRGB holds the same pixel data as the byte array returned by CopyColorsRGBA_SRGB. However, the Zivid::NET::ImageRGBA_SRGB provides additional functionality such as saving the image to a file.

See also

CopyColorsRGBA_SRGB

Returns:: Point colors as 8-bit SRGB image

Zivid::NET::ImageBGRA_SRGB ^ CopyImageBGRA_SRGB ()

Point colors (BGRA in sRGB color space) as a 2D image.

This method copies the colors from compute device memory to host (CPU) system memory (RAM) and returns them as an Image. The format of the image will be four channels (B,G,R,A), with 8 bits per channel.

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 Zivid::NET::ImageBGRA_SRGB holds the same pixel data as the byte array returned by CopyColorsBGRA_SRGB. However, the Zivid::NET::ImageBGRA_SRGB provides additional functionality such as saving the image to a file.

See also

CopyColorsBGRA_SRGB

Returns:: Point colors as 8-bit BGRA_SRGB image

PointXYZColorRGBA2DimArray ^ CopyPointsXYZColorsRGBA ()

Get PointXYZColorRGBA as an array of rank 2 with size height * width.

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

Returns:: Rank 2 array of PointXYZColorRGBA

PointXYZColorRGBA_SRGB2DimArray ^ CopyPointsXYZColorsRGBA_SRGB ()

Get PointXYZColorRGBA_SRGB as an array of rank 2 with size height * width.

This method copies the 3D point coordinates and colors from compute device memory to host (CPU) system memory (RAM) and returns them as an array of PointXYZColorRGBA_SRGB. PointXYZColorRGBA_SRGB contains point coordinates stored as floats in a PointXYZ, and colors stored as RGBA_SRGB (8 bits per channel in the sRGB color space) in a ColorRGBA_SRGB.

Returns:: Rank 2 array of PointXYZColorRGBA_SRGB

PointXYZColorBGRA2DimArray ^ CopyPointsXYZColorsBGRA ()

Get PointXYZColorBGRA as an array of rank 2 with size height * width.

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

Returns:: Rank 2 array of PointXYZColorBGRA

PointXYZColorBGRA_SRGB2DimArray ^ CopyPointsXYZColorsBGRA_SRGB ()

Get PointXYZColorBGRA_SRGB as an array of rank 2 with size height * width.

This method copies the 3D point coordinates and colors from compute device memory to host (CPU) system memory (RAM) and returns them as an array of PointXYZColorBGRA_SRGB. PointXYZColorBGRA_SRGB contains point coordinates stored as floats in a PointXYZ, and colors stored as BGRA_SRGB (8 bits per channel in the sRGB color space) in a ColorBGRA_SRGB.

Returns:: Rank 2 array of PointXYZColorBGRA_SRGB

System::String ^ ToString () override

Get string representation of the PointCloud.

Returns:: PointCloud as string

PointCloud ^ Transform (Float2DimArray^ matrix)

Transform the point cloud in-place by the given 4x4 transformation matrix, represented as a 2D array.

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 transformation matrix, as a 2D array

PointCloud ^ Transform (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

PointCloud ^ Transformed (Float2DimArray^ matrix)

Transform the point cloud by the given 4x4 transformation matrix, represented as a 2D array.

This method is identical to Transform(Float2DimArray^ matrix), except the transformed point cloud is returned as a new PointCloud instance. The current point cloud is not modified.

Parameters:: matrix – An affine 4x4 matrix

PointCloud ^ Transformed (Matrix4x4^ matrix)

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

This method is identical to Transform(Matrix4x4^ matrix), except the transformed point cloud is returned as a new PointCloud instance. The current point cloud is not modified.

Parameters:: matrix – An affine 4x4 matrix

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.

See also

Downsampled

Parameters:: downsampling – This enum defines the size of the downsampled point cloud

PointCloud ^ Downsampled (Downsampling downsampling)

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.

See also

Downsample

Parameters:: downsampling – This enum defines the size of the downsampled point cloud

PointCloud ^ Mask (Zivid::NET::Mask ^ mask)

Apply a binary mask to the point cloud in-place.

The mask indicates which points in the point cloud should be considered invalid (NaN). The mask must have the same height and width as the point cloud. A value of True/non-zero in the mask indicates that the corresponding point in the point cloud should be set to invalid (NaN). A value of False/zero indicates that the corresponding point should be kept unchanged.

See also

Masked

Parameters:: mask – A binary mask with the same resolution as the point cloud

PointCloud ^ Masked (Zivid::NET::Mask ^ mask)

Get a copy of the point cloud with a binary mask applied.

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

The mask indicates which points in the point cloud should be considered invalid (NaN). The mask must have the same height and width as the point cloud. A value of True/non-zero in the mask indicates that the corresponding point in the point cloud should be set to invalid (NaN). A value of False/zero indicates that the corresponding point should be kept unchanged.

See also

Mask

Parameters:: mask – A binary mask with the same resolution as the point cloud

PointCloud ^ MaskByRegionOfInterest (Zivid::NET::Settings::RegionOfInterestGroup::BoxGroup ^ roiSettings)

Apply a region of interest box mask to the point cloud in-place.

Region of interest masking is used to mask out points that fall outside a specified 3D box region. Points outside the region are set to invalid (NaN) values, effectively removing them from the point cloud while maintaining the original dimensions and structure.

The masking is performed on the compute device. The point cloud is modified in-place. Use MaskedByRegionOfInterest if you want to apply ROI masking to a new PointCloud instance.

The ROI box must be enabled (roiSettings.Enabled == true) for the masking to be applied.

See also

MaskedByRegionOfInterest

Parameters:: roiSettings – The ROI box settings defining the 3D region to preserve

PointCloud ^ MaskedByRegionOfInterest (Zivid::NET::Settings::RegionOfInterestGroup::BoxGroup ^ roiSettings)

Apply region of interest filtering to a copy of the point cloud.

This method is identical to MaskByRegionOfInterest, except that the filtering is performed on a copy of the original point cloud. This method does not modify the original point cloud.

See also

MaskByRegionOfInterest

Parameters:: roiSettings – The ROI box settings defining the 3D region to preserve

PointCloud ^ ShallowCopy ()

Returns a shallow copy of the point cloud.

The copy will share the point cloud data with the original point cloud instance. This means that modifications to the point cloud data in the copy will also affect the original point cloud instance.

To create a deep copy of the point cloud, use the Clone method instead.

The copy will not be disposed when the original point cloud is disposed. Both the original and the copy will need to be disposed separately.

PointCloud ^ Clone ()

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.

To create a shallow copy of the point cloud, use the ShallowCopy method instead.

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.

DeviceArray< PointXYZ > ^ DevicePointsXYZ (StreamOrQueue streamOrQueue): Get a device buffer containing XYZ point coordinates.

DeviceArray< PointXYZW > ^ DevicePointsXYZW (StreamOrQueue streamOrQueue): Get a device buffer containing XYZW point coordinates.

DeviceArray< PointZ > ^ DevicePointsZ (StreamOrQueue streamOrQueue): Get a device buffer containing Z point coordinates.

DeviceArray< SNR > ^ DeviceSNRs (StreamOrQueue streamOrQueue): Get a device buffer containing SNR values.

DeviceArray< NormalXYZ > ^ DeviceNormalsXYZ (StreamOrQueue streamOrQueue)

Get a device buffer containing normal vectors.

Normals are only produced organized; calling ToArray1D on the returned array always throws.

DeviceArray< ColorRGBA > ^ DeviceImageRGBA (StreamOrQueue streamOrQueue): Get a device buffer containing RGBA image data (8 bits per channel, linear)

DeviceArray< ColorBGRA > ^ DeviceImageBGRA (StreamOrQueue streamOrQueue): Get a device buffer containing BGRA image data (8 bits per channel, linear)

DeviceArray< ColorRGBA_SRGB > ^ DeviceImageRGBA_SRGB (StreamOrQueue streamOrQueue): Get a device buffer containing RGBA image data in the sRGB color space.

DeviceArray< ColorBGRA_SRGB > ^ DeviceImageBGRA_SRGB (StreamOrQueue streamOrQueue): Get a device buffer containing BGRA image data in the sRGB color space.

DeviceArray< ColorRGBAf > ^ DeviceImageRGBAf (StreamOrQueue streamOrQueue)

Get a device buffer containing RGBA float image data (32 bits per channel, linear)

RGBAf is only produced organized; calling ToArray1D on the returned array always throws.

UnorganizedPointCloud ^ ToUnorganizedPointCloud ()

Convert to an UnorganizedPointCloud.

The PointCloud class represents an organized point cloud, meaning that it contains 3D data for every pixel (row, col) on the sensor. If 3D data could not be computed for a given pixel, or was removed by a filter, that pixel contains (x,y,z) = (NaN, NaN, NaN) representing an “invalid” point. For some use cases it is more useful to have an unorganized point cloud, which instead contains a linear list of only valid points.

This function efficiently picks out the valid (not-NaN) points from this structured point cloud, and constructs an unorganized point cloud containing the XYZ, Color and SNR from those points only. The resulting unorganized point cloud will have less than (or equal) memory footprint compared to the structured point cloud it comes from, since it will contain fewer (or equal) number of points.

See UnorganizedPointCloud for more information on how to use the return value.

Properties

bool Empty: Check if the point cloud is empty.

size_t Width: Get the width of the point cloud (number of columns)

size_t Height: Get the height of the point cloud (number of rows)

size_t Size

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

This is identical to width() * height()

Matrix4x4^ TransformationMatrix

Return the current transformation matrix of this point cloud.

Returns the transformation matrix from the camera’s native coordinate system to the current coordinate system. The returned matrix represents the cumulative result of all the transform operations performed on the point cloud. If no transformations have been applied, the identity matrix is returned.

Note: ZDF files saved from SDK 2.14 or earlier did not store the active transformation matrix. This means that for point clouds loaded from .zdf files from SDK 2.14 or earlier, this method will always return the identity matrix even in the case where the point cloud had been transformed prior to saving.

Python

See the Capture sample for Python and Point Cloud Tutorial for the typical access patterns. The full Python API is documented in zivid-python.

UnorganizedPointCloud

A flat, contiguous point cloud derived from a structured PointCloud via toUnorganizedPointCloud. Useful for filtering, decimation, and stitching.

C++

class UnorganizedPointCloud

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.

Public Functions

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.

size_t size() const: Get the size of the point cloud (total number of points)

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

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

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

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

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

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.

std::optional<PointXYZ> 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

UnorganizedPointCloud &paintUniformColor(const Zivid::ColorRGBA &color)

Set point cloud colors in-place according to the given value.

Parameters:: color – The RGBA value used to color all points

UnorganizedPointCloud paintedUniformColor(const Zivid::ColorRGBA &color) const

Create a clone of this point cloud with all points colored according to the given value.

Parameters:: color – The RGBA value used to color all points

Array1D<PointXYZ> 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.

Array1D<PointXYZW> copyPointsXYZW() const

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

Array1D<ColorRGBA> 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.

Array1D<ColorBGRA> 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.

Array1D<ColorRGBA_SRGB> 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.

Array1D<ColorBGRA_SRGB> 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.

Array1D<SNR> 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.

DeviceArray<PointXYZ> devicePointsXYZ(StreamOrQueue streamOrQueue) const: Get a device buffer containing XYZ point coordinates, synced to the user’s stream/queue.

DeviceArray<PointXYZW> devicePointsXYZW(StreamOrQueue streamOrQueue) const: Get a device buffer containing XYZW point coordinates, synced to the user’s stream/queue.

DeviceArray<SNR> deviceSNRs(StreamOrQueue streamOrQueue) const: Get a device buffer containing SNR values, synced to the user’s stream/queue.

template<typename ColorFormat, typename = std::enable_if_t<Detail::SupportedImageDeviceArrayColorFormat<ColorFormat>::value>> DeviceArray<ColorFormat> deviceColors(StreamOrQueue streamOrQueue) const: Get a device buffer containing color data in the specified format, synced to the user’s stream/queue.

template<typename DataFormat> inline Array1D<DataFormat> copyData() const

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

template<typename DataFormat> inline void copyData(DataFormat *destination) const

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.
PointXYZW: 3D coordinates in 4D homogeneous coordinates. Contains 4 floats, (x, y, z, w). w is always 1.0. Size per element is 16 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.

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.

std::string toString() const

Get string representation of the point cloud.

Returns:: Point cloud info as string

C#

class UnorganizedPointCloud

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.

Public Functions

UnorganizedPointCloud ^ Extended (UnorganizedPointCloud^ other)

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

UnorganizedPointCloud ^ Extend (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

UnorganizedPointCloud ^ VoxelDownsampled (float voxelSize, int minPointsPerVoxel)

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

UnorganizedPointCloud ^ Transform (Float2DimArray^ matrix)

Transform the point cloud in-place by the given 4x4 transformation matrix, represented as a 2D array.

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

UnorganizedPointCloud ^ Transform (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

UnorganizedPointCloud ^ Transformed (Float2DimArray^ matrix)

Transform the point cloud by the given 4x4 transformation matrix, represented as a 2D array.

This method is identical to Transform(Float2DimArray^ matrix), 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

UnorganizedPointCloud ^ Transformed (Matrix4x4^ matrix)

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

This method is identical to Transform(Matrix4x4^ matrix), 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

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.

System::Nullable<Zivid::NET::PointXYZ> Centroid()

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

Returns:: The centroid of the point cloud as a PointXYZ

UnorganizedPointCloud ^ PaintUniformColor (Zivid::NET::ColorRGBA color)

Set point cloud colors in-place according to the given value.

Parameters:: color – The RGBA value used to color all points

UnorganizedPointCloud ^ PaintedUniformColor (Zivid::NET::ColorRGBA color)

Create a clone of this point cloud with all points colored according to the given value.

Parameters:: color – The RGBA value used to color all points

Float2DimArray ^ CopyPointsXYZ ()

Point coordinates (x, y, and z) as a float array of rank 2 with size Size * 3.

This method copies the point coordinates from compute device memory to host (CPU) system memory (RAM) memory and returns them in a float array. First dimension indexes the points of the point cloud (0 to Size - 1), and the second dimension is x/y/z (x=0, y=1, z=2). For example, to get z coordinate of the point at index 100 in the point cloud, use [100, 2].

See also

CopyPointsXYZW

Returns:: Rank 2 float array of XYZ point coordinates

Float2DimArray ^ CopyPointsXYZW ()

Point coordinates as 4D (homogeneous coordinates) as a float array of rank 2 with size Size * 4.

This method copies the point coordinates (as 4D homogeneous coordinates) from compute device memory to host (CPU) system memory (RAM) and returns them in a float array. Note that W is always set to 1.0. First dimension indexes the points of the point cloud (0 to Size - 1), and second dimension is x/y/z/w (x=0, y=1, z=2, w=3). For example, to get x coordinate of the point at index 50 in the point cloud, use [50, 0].

See also

CopyPointsXYZ

Returns:: Rank 2 float array of XYZW point coordinates

Byte2DimArray ^ CopyColorsRGBA ()

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 a byte array of rank 2. First dimension indexes the points of the point cloud (0 to Size - 1), and second dimension is the color channels (r=0, g=1, b=2, a=3).

The length of the returned array’s first dimension will match the Size property.

Returns:: Rank 2 byte array of RGBA color values

Byte2DimArray ^ CopyColorsBGRA ()

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 a byte array of rank 2. First dimension indexes the points of the point cloud (0 to Size - 1), and second dimension is the color channels (b=0, g=1, r=2, a=3).

The length of the returned array’s first dimension will match the Size property.

Returns:: Rank 2 byte array of BGRA color values

Byte2DimArray ^ CopyColorsRGBA_SRGB ()

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 a byte array of rank 2. First dimension indexes the points of the point cloud (0 to Size - 1), and second dimension is the color channels (r=0, g=1, b=2, a=3).

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.

Returns:: Rank 2 byte array of RGBA_SRGB color values

Byte2DimArray ^ CopyColorsBGRA_SRGB ()

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 a byte array of rank 2. First dimension indexes the points of the point cloud (0 to Size - 1), and second dimension is the color channels (b=0, g=1, r=2, a=3).

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.

Returns:: Rank 2 byte array of BGRA_SRGB color values

Float1DimArray ^ CopySNRs ()

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 a float array.

The length of the returned array will match the Size property.

Returns:: Float array of SNR values

UnorganizedPointCloud ^ ShallowCopy ()

Returns a shallow copy of the point cloud.

The copy will share the point cloud data with the original point cloud instance. This means that modifications to the point cloud data in the copy will also affect the original point cloud instance.

To create a deep copy of the point cloud, use the Clone method instead.

The copy will not be disposed when the original point cloud is disposed. Both the original and the copy will need to be disposed separately.

UnorganizedPointCloud ^ Clone ()

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.

To create a shallow copy of the point cloud, use the ShallowCopy method instead.

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.

DeviceArray< PointXYZ > ^ DevicePointsXYZ (StreamOrQueue streamOrQueue): Get a device buffer containing XYZ point coordinates.

DeviceArray< PointXYZW > ^ DevicePointsXYZW (StreamOrQueue streamOrQueue): Get a device buffer containing XYZW point coordinates.

DeviceArray< SNR > ^ DeviceSNRs (StreamOrQueue streamOrQueue): Get a device buffer containing SNR values.

DeviceArray< ColorRGBA > ^ DeviceColorsRGBA (StreamOrQueue streamOrQueue): Get a device buffer containing RGBA color data (8 bits per channel, linear)

DeviceArray< ColorBGRA > ^ DeviceColorsBGRA (StreamOrQueue streamOrQueue): Get a device buffer containing BGRA color data (8 bits per channel, linear)

DeviceArray< ColorRGBA_SRGB > ^ DeviceColorsRGBA_SRGB (StreamOrQueue streamOrQueue): Get a device buffer containing RGBA color data in the sRGB color space.

DeviceArray< ColorBGRA_SRGB > ^ DeviceColorsBGRA_SRGB (StreamOrQueue streamOrQueue): Get a device buffer containing BGRA color data in the sRGB color space.

DeviceArray< ColorRGBAf > ^ DeviceColorsRGBAf (StreamOrQueue streamOrQueue): Get a device buffer containing RGBA float color data (32 bits per channel, linear)

Python

The Python API exposes zivid.UnorganizedPointCloud. See zivid-python for the full reference.

Frame2D

The result of a pure 2D capture.

C++

class Frame2D

A 2D frame captured by a Zivid camera.

Contains a 2D image as well as metadata, settings and state of the API at the time of capture.

Note that if this Frame2D object was returned from a call to Camera::capture, then there may still be remaining data transfer and processing going on in the background. When you call a method on the Frame2D object that requires the capture to be finished, for example Frame2D::imageRGBA(), the method will block until the image is available.

The images are not corrected for lens distortion. If your application relies on the geometry of the image, you can undistort it using the camera intrinsics.

Public Functions

Frame2D(): Construct a new empty 2d frame.

Image<ColorRGBA> imageRGBA() const

Get color (RGBA) image from the frame.

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 ColorRGBA_SRGB format.

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

Image<ColorBGRA> imageBGRA() const

Get color (BGRA) image from the frame.

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 ColorRGBA_SRGB format.

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

Image<ColorRGBA_SRGB> imageSRGB() const

Get color (RGBA in the sRGB color space) image from the frame.

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 format of each pixel is given by ColorRGBA_SRGB. If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

This method has been deprecated as of SDK 2.15. The method will be removed in the next SDK major version (SDK 3.0). Prefer to use the new and equivalent method imageRGBA_SRGB.

Image<ColorRGBA_SRGB> imageRGBA_SRGB() const

Get color (RGBA in the sRGB color space) image from the frame.

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 format of each pixel is given by ColorRGBA_SRGB.

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

Image<ColorBGRA_SRGB> imageBGRA_SRGB() const

Get color (BGRA in the sRGB color space) image from the frame.

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 format of each pixel is given by ColorBGRA_SRGB.

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

Image<ColorRGB> imageRGB() const

Get color (RGB, 3-channel, no alpha) image from the frame.

The format of each pixel is given by ColorRGB. Identical to imageRGBA but skips the alpha channel for ~25% bandwidth savings.

Image<ColorRGB_SRGB> imageRGB_SRGB() const: Get color (RGB in the sRGB color space, 3-channel, no alpha) image from the frame.

Image<ColorBGR> imageBGR() const: Get color (BGR, 3-channel, no alpha) image from the frame.

Image<ColorBGR_SRGB> imageBGR_SRGB() const: Get color (BGR in the sRGB color space, 3-channel, no alpha) image from the frame.

Image<ColorGray8> imageGray8() const

Get 8-bit single-channel grayscale image from the frame.

The format of each pixel is given by ColorGray8. The intensity is the average of the linear red, green and blue channels (or, on monochrome sensors, the sensor intensity directly).

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

Image<ColorGray16> imageGray16() const

Get 16-bit single-channel grayscale image from the frame.

The format of each pixel is given by ColorGray16. Compared to ColorGray8 it preserves more of the dynamic range.

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

template<typename ColorFormat, typename = std::enable_if_t<Detail::SupportedImageDeviceArrayColorFormat<ColorFormat>::value>> DeviceArray<ColorFormat> imageDeviceArray(StreamOrQueue streamOrQueue) const

Get a GPU device buffer of the image in the specified format.

This method provides access to the image data on the GPU. If the requested format matches the internal format, the buffer is returned directly without conversion. Otherwise, a format conversion is performed on the GPU.

The buffer is reference-counted and holds a reference to the underlying device memory, ensuring it remains valid for the lifetime of the buffer object. The buffer can be safely copied, and all copies will share ownership of the underlying device memory. The device memory is automatically released when the last reference is destroyed.

The device pointer obtained from the buffer can be used with GPU compute frameworks (such as CUDA), passed to GPU-aware libraries (like cuDNN or GStreamer CUDA elements), or used for zero-copy interop with other GPU frameworks.

If the image is not yet available because the capture is still in progress, then this method will block until the image is available.

Example usage:

// Get buffer in RGBA8 format, synchronized on the user's CUDA stream.
auto rgba8Buffer = frame2d.imageDeviceArray<ColorRGBA>(CUDAStreamPtr{ stream });
auto image = Zivid::toImage(rgba8Buffer); // Image<ColorRGBA>

// OpenCL callers pass OpenCLCommandQueuePtr instead; implicit conversion picks the right backend.
auto floatBuffer = frame2d.imageDeviceArray<ColorRGBAf>(OpenCLCommandQueuePtr{ queue });

Template Parameters:: ColorFormat – Target color format (ColorRGBA, ColorRGBA_SRGB, ColorBGRA, ColorBGRA_SRGB, or ColorRGBAf)
Returns:: DeviceArray containing the image in the requested format

template<typename ColorFormat, typename = std::enable_if_t<Detail::SupportedImageDeviceArrayColorFormat<ColorFormat>::value>> void imageDeviceArray(DeviceArrayView<ColorFormat> destinationBuffer, StreamOrQueue streamOrQueue) const

Fill a user-provided DeviceArrayView with the image in the specified format.

Writes the frame’s image directly into the memory referenced by the view, bypassing the SDK’s internal cache. Throws an exception if the view shape does not match the frame dimensions. The caller’s stream/queue carries a barrier against the SDK compute on return, so consumer work can be enqueued on the same stream immediately.

Template Parameters:

ColorFormat – Target color format (ColorRGBA, ColorRGBA_SRGB, ColorBGRA, ColorBGRA_SRGB, or ColorRGBAf).

Parameters:

destinationBuffer – Non-owning view over the destination device memory, typically constructed via createDeviceArrayView from a caller-owned pointer, or borrowed implicitly from a DeviceArray.
streamOrQueue – User CUDA stream or OpenCL command queue to synchronize the completion of the color conversion on. Pass either a CUDAStreamPtr or OpenCLCommandQueuePtr; conversion is implicit.

Settings2D settings() const

Get the settings used to capture this frame.

This method returns instantly, even if the capture is still in-progress.

CameraState state() const

Get the camera state data at the time of the capture.

If the capture is still in-progress, then this method will block until the capture completes.

FrameInfo info() const

Get information collected at the time of the capture.

If the capture is still in-progress, then this method will block until the capture completes.

CameraInfo cameraInfo() const

Get information about the camera used to capture the frame.

This method returns instantly, even if the capture is still in-progress.

std::string toString() const

Get string representation of the frame.

If the capture is still in-progress, then this method will block until the capture completes.

Returns:: Frame info as string

Frame2D clone() const

Returns a clone of the frame.

The clone will include a copy of all of the frame data.

This function incurs a performance cost due to the copying of the data. When performance is important we recommend to avoid using this method, and instead modify the existing frame.

void save(const std::string &fileName) const

Save the frame to a .zdf file.

Parameters:: fileName – Path to the output .zdf file

void load(const std::string &fileName)

Load a frame from a .zdf file.

Use Zivid::readFrameFileType to determine the frame type without loading. This method will throw an exception if the frame type is not frame2D.

Parameters:: fileName – Path to the .zdf file to load

explicit Frame2D(const std::string &fileName)

Construct a Frame2D by loading from a .zdf file.

Parameters:: fileName – Path to the .zdf file to load

C#

class Frame2D

A 2D frame captured by a Zivid camera.

Contains a 2D image as well as metadata, settings and state of the API at the time of capture.

Note that if this Frame2D object was returned from a call to Camera::Capture(Settings^) or Camera::Capture(Settings2D^), then there may still be remaining data transfer and processing going on in the background. When you call a method on Frame2D that requires the capture to be finished, for example Frame2D::ImageRGBA(), the method will block until the image is available.

The images are not corrected for lens distortion. If your application relies on the geometry of the image, you can undistort it using the camera intrinsics.

Public Functions

Frame2D(const Zivid::Frame2D frame)

Create a 2D frame using a native 2D frame.

Parameters:: frame – Native Zivid::Frame2D object

Frame2D (System::String ^ fileName)

Load a 2D frame from a .zdf file.

Use Zivid::NET::FrameFile to determine the frame type without loading. This method will throw an exception if the frame type is not Frame2D.

Parameters:: fileName – Path to the .zdf file to load

void Save (System::String ^ fileName)

Save the 2D frame to a .zdf file.

Parameters:: fileName – Path to the output .zdf file

void Load (System::String ^ fileName)

Load a 2D frame from a .zdf file.

Parameters:: fileName – Path to the .zdf file to load

Zivid::NET::ImageRGBA ^ ImageRGBA ()

Get the associated 2D color image in 8-bit RGBA format.

The format of the image will be four channels (R,G,B,A), with 8 bits per channel. The image can be converted to an array using Zivid::NET::ImageRGBA::ToArray() or Zivid::NET::ImageRGBA::ToByteArray().

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 ColorRGBA_SRGB format.

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

Returns:: The associated 2D color image

Zivid::NET::ImageBGRA ^ ImageBGRA ()

Get the associated 2D color image in 8-bit BGRA format.

The format of the image will be four channels (B,G,R,A), with 8 bits per channel. The image can be converted to an array using Zivid::NET::ImageBGRA::ToArray() or Zivid::NET::ImageBGRA::ToByteArray().

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 ColorRGBA_SRGB format.

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

Returns:: The associated 2D color image

Zivid::NET::ImageSRGB ^ ImageSRGB ()

Get the associated 2D color image in the sRGB color space in 8-bit RGBA format.

The format of the image will be four channels (R,G,B,A), with 8 bits per channel. The image can be converted to an array using Zivid::NET::ImageSRGB::ToArray() or Zivid::NET::ImageSRGB::ToByteArray().

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.

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

This method has been deprecated as of SDK 2.15. The method will be removed in the next SDK major version (SDK 3.0). Prefer to use the new and equivalent method ImageRGBA_SRGB.

Returns:: The associated 2D color image

Zivid::NET::ImageRGBA_SRGB ^ ImageRGBA_SRGB ()

Get the associated 2D color image in the sRGB color space in 8-bit RGBA format.

The format of the image will be four channels (R,G,B,A), with 8 bits per channel. The image can be converted to an array using Zivid::NET::ImageRGBA_SRGB::ToArray() or Zivid::NET::ImageRGBA_SRGB::ToByteArray().

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.

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

Returns:: The associated 2D color image

Zivid::NET::ImageBGRA_SRGB ^ ImageBGRA_SRGB ()

Get the associated 2D color image in the sRGB color space in 8-bit BGRA format.

The format of the image will be four channels (B,G,R,A), with 8 bits per channel. The image can be converted to an array using Zivid::NET::ImageBGRA_SRGB::ToArray() or Zivid::NET::ImageBGRA_SRGB::ToByteArray().

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.

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

Returns:: The associated 2D color image

DeviceArray< ColorRGBA > ^ ImageDeviceArrayRGBA (StreamOrQueue streamOrQueue)

Get a device buffer containing RGBA image data (8 bits per channel, linear)

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

DeviceArray< ColorBGRA > ^ ImageDeviceArrayBGRA (StreamOrQueue streamOrQueue)

Get a device buffer containing BGRA image data (8 bits per channel, linear)

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

DeviceArray< ColorRGBA_SRGB > ^ ImageDeviceArrayRGBA_SRGB (StreamOrQueue streamOrQueue)

Get a device buffer containing RGBA image data in the sRGB color space (8 bits per channel)

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

DeviceArray< ColorBGRA_SRGB > ^ ImageDeviceArrayBGRA_SRGB (StreamOrQueue streamOrQueue)

Get a device buffer containing BGRA image data in the sRGB color space (8 bits per channel)

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

DeviceArray< ColorRGBAf > ^ ImageDeviceArrayRGBAf (StreamOrQueue streamOrQueue)

Get a device buffer containing RGBA float image data (32 bits per channel, linear)

If the image is not yet available because the capture is still in-progress, then this method will block until the image is available.

RGBAf is only produced organized; calling ToArray1D on the returned array always throws.

Frame2D ^ ShallowCopy ()

Returns a shallow copy of the frame.

The copy will share the image data with the original frame.

To create a deep copy of the frame, use the Clone method instead.

The copy will not be disposed when the original frame is disposed. Both the original and the copy will need to be disposed separately.

Frame2D ^ Clone ()

Returns a clone of the frame.

The clone will include a copy of all of the frame data.

To create a shallow copy of the frame, use the ShallowCopy method instead.

This function incurs a performance cost due to the copying of the data. When performance is important we recommend to avoid using this method, and instead modify the existing frame.

System::String ^ ToString () override

Get string representation of the frame.

If the capture is still in-progress, then this method will block until the capture completes.

Returns:: Frame info as string

Properties

FrameInfo^ Info

Get information collected at the time of the capture.

If the capture is still in-progress, then this method will block until the capture completes.

Settings2D^ Settings

Get the settings used to capture this frame.

This method returns instantly, even if the capture is still in-progress.

CameraState^ State

Get the camera state data at the time of the capture.

If the capture is still in-progress, then this method will block until the capture completes.

Zivid::NET::CameraInfo^ CameraInfo

Get information about the camera used to capture the frame.

This method returns instantly, even if the capture is still in-progress.

Python

image_rgba = frame.frame_2d().image_rgba_srgb()

Image

A 2D image (color or projection target).

C++

template<class PixelFormat> class Image : public Zivid::Array2D<PixelFormat>

A 2-dimensional image.

The type of each pixel in the image is given by template parameter PixelFormat. Currently the supported PixelFormats are ColorRGBA, ColorBGRA, ColorRGBA_SRGB and ColorBGRA_SRGB.

Public Functions

Image() = default: Create an empty image.

template<typename Iterator> inline Image(const Resolution &resolution, Iterator beginIt, Iterator endIt): Create an image from a buffer of elements by copy.

inline Image(const Resolution &resolution, const unsigned char *begin, const unsigned char *end)

Create an image from an unsigned char byte buffer.

Copies the buffer without taking ownership. The byte size of the buffer (i.e., end - begin) must be equal to the byte size of the image (i.e., resolution.size() * sizeof(PixelFormat)). Otherwise, an exception will be thrown. The layout of the buffer must match the memory layout of PixelFormat, and the elements must be stored in row-major order; the input buffer will be copied as-is.

Parameters:

resolution – The resolution of the image (i.e., width and height)
begin – A pointer to the first element in the buffer
end – A pointer to the element following the last element in the buffer. See https://en.cppreference.com/w/cpp/iterator/end.

inline explicit Image(const std::string &fileName)

Load an image from a file.

The supported file types are PNG (.png), JPEG (.jpg, .jpeg) and BMP (.bmp). This method will throw an exception if failing to load the provided fileName.

inline Resolution resolution() const: Get the resolution of the image.

inline void save(const std::string &fileName) const

Save the image to a file.

The supported file types are PNG (.png), JPEG (.jpg, .jpeg) and BMP (.bmp). This method will throw an exception if failing to save to the provided fileName.

C#

Warning

doxygenclass: Cannot find class “Image” in doxygen xml output for project “Camera C#” from directory: /host_dir/documentation/build/ci/build/documentation/doxygen/camera-sdk-csharp/xml

Python

image_file = "ImageRGBA.png"
print(f"Saving 2D color image (sRGB color space) to file: {image_file}")
image_rgba.save(image_file)

Visualizer

Lightweight visualizer used in many of the public samples to display point clouds and 2D images.

C++

class Visualizer

Simple visualizer component for point clouds.

Public Functions

ZIVID_VISUALIZATION_EXPORT Visualizer(): Constructor.

ZIVID_VISUALIZATION_EXPORT void show (): Show the visualization window.

ZIVID_VISUALIZATION_EXPORT void hide (): Hide the visualization window.

ZIVID_VISUALIZATION_EXPORT int run (): Run the event loop. Should be called to allow interaction with the point cloud.

ZIVID_VISUALIZATION_EXPORT void close (): Stop the event loop and close the window. The object goes back to idle state.

ZIVID_VISUALIZATION_EXPORT void resize (int width, int height): Resize the window to specified height and width.

ZIVID_VISUALIZATION_EXPORT void resetToFit ()

Reset the view so that the point cloud will fit in the window.

The view will be reset to the default view, which is looking at the point cloud along the Z axis in the positive direction.

ZIVID_VISUALIZATION_EXPORT void showFullScreen (): Show the window in full screen mode.

ZIVID_VISUALIZATION_EXPORT void showMaximized (): Show the window in maximized mode.

ZIVID_VISUALIZATION_EXPORT void setWindowTitle (std::string title): Set the window title.

ZIVID_VISUALIZATION_EXPORT void show (const PointCloud &cloud): Show a point cloud.

ZIVID_VISUALIZATION_EXPORT void show (const UnorganizedPointCloud &cloud)

Show an unorganized point cloud.

Meshing is not supported when showing an unorganized point cloud. This method will throw an exception if meshing is enabled.

If the point cloud is transformed, then it may be necessary to call resetToFit() to reset the view such that the point cloud becomes visible.

ZIVID_VISUALIZATION_EXPORT void show (const Frame &frame): Show a frame.

ZIVID_VISUALIZATION_EXPORT void show (const Frame2D &frame)

Show a 2D frame.

Displays the 2D frame as a 2D texture. This replaces any currently displayed content. The image will be shown at its native resolution, centered in the window.

ZIVID_VISUALIZATION_EXPORT void show (const Stereo::Frame2D &stereoFrame)

Show a stereo 2D frame.

Displays the stereo 2D frame as two 2D textures side by side. This replaces any currently displayed content. The left and right images will be shown at their native resolution, centered in the window.

ZIVID_VISUALIZATION_EXPORT void show (const Sensor::Frame2D &frame)

Show a sensor capture 2D frame.

Displays the 2D frame as a 2D texture. This replaces any currently displayed content. The image will be shown at its native resolution, centered in the window.

ZIVID_VISUALIZATION_EXPORT void setColorsEnabled (bool enabled): Enable or disable coloring of the points with their accompanying RGB colors.

ZIVID_VISUALIZATION_EXPORT bool colorsEnabled () const: Whether coloring of the points with their accompanying RGB colors is enabled.

ZIVID_VISUALIZATION_EXPORT void setMeshingEnabled (bool enabled)

Enable or disable meshing.

Meshing is not supported when showing an unorganized point cloud. An exception will be thrown if setMeshingEnabled(true) is called while an unorganized point cloud is being shown.

ZIVID_VISUALIZATION_EXPORT bool isMeshingEnabled () const: Whether meshing is enabled.

ZIVID_VISUALIZATION_EXPORT void setAxisIndicatorEnabled (bool enabled): Enable or disable the axis indicator.

ZIVID_VISUALIZATION_EXPORT bool isAxisIndicatorEnabled () const: Whether the axis indicator is enabled.

Public Static Functions

static ZIVID_VISUALIZATION_EXPORT std::string toString (): String representation of the Visualizer.

C#

class Visualizer

Simple point cloud visualizer for console applications.

This visualization component creates a window with a VisualizerControl in it.

The Visualizer’s Dispose method should be called to ensure that all resources allocated by the Visualizer are released.

It is not allowed to have more than one Visualizer on the same thread at a time. You must call the aforementioned Dispose method on the Visualizer before you can create another Visualizer on the same thread.

See also

VisualizerControl

Public Functions

Visualizer(): Construct a new Visualizer object.

void Show(): Ensure the visualization window is visible.

void Hide(): Hide the visualizaton window.

void ShowFullScreen(): Show the visualization window in full screen mode.

void ShowMaximized(): Show the visualization window in maximized mode.

void Run()

Start interacting with the window.

This function will block until the window is closed.

void ResetToFit()

Reset the camera parameters such that the point cloud fits within the window.

The view will be reset to the default view, which is looking at the point cloud along the Z axis in the positive direction.

void Resize(int w, int h)

Resize the window to a given size.

Parameters:

w – Desired width
h – Desired height

void Show (PointCloud ^ cloud)

Show a point cloud.

See also

Show(Frame ^)

Parameters:: cloud – A point cloud

void Show (UnorganizedPointCloud ^ cloud)

Show an unorganized point cloud.

See also

Show(Frame ^)

Meshing is not supported when showing an unorganized point cloud. This method will throw an exception if meshing is enabled.

If the point cloud is transformed, then it may be necessary to call ResetToFit() to reset the view such that the point cloud becomes visible.

Parameters:: cloud – A point cloud

void Show (Frame ^ frame)

Show a point cloud contained in a frame.

See also

Show(PointCloud ^)

Parameters:: frame – A frame

Properties

System::String^ WindowTitle: Title of the window.

bool^ ColorsEnabled: Enable or disable coloring of the points with their accompanying RGB colors.

bool^ MeshingEnabled: Enable or disable meshing.

bool^ AxisIndicatorEnabled: Enable or disable the axis indicator.

Python

The Python API exposes zivid.Visualizer. See zivid-python for the full reference and the Visualization Tutorial.

See also