Point Cloud Structure and Output Formats

Organized point cloud

Zivid outputs an organized point cloud. This means that the point cloud is laid out as a 2D array of points that resembles an image-like structure. An unorganized point cloud is generally stored as a list of points in a 1D array. In both cases, the XYZ data are provided for each point as well as the RGB values.

There are several advantages to this structure.

  • Algorithms designed for unorganized point clouds work on organized as well because a 2D array can be interpreted as a 1D array. This is not always true the other way around.

  • Ordered point clouds have a 1:1 correlation between pixels in the 2D images (color and depth) and 3D points in the point cloud. This means that the neighboring pixels in the image are the neighboring points in the point cloud. This enables 2D operations and algorithms to be applied to the 2D image, while the result can be applied directly to the point cloud. For example, for object detection and segmentation, one can segment the 2D image and directly extract the 3D points from the desired pixels.

  • The orderliness of points speeds up computation and lowers the cost of certain algorithms, especially operations using neighboring points.

Zivid point cloud

Different Zivid camera models use sensors with different resolutions to capture point clouds of a scene.

Camera

Megapixels (MP)

Resolution

Zivid 2+

5

2448 x 2048

Zivid 2

2.3

1944 x 1200

There are multiple ways to get the resolution from the SDK.

Go to source

source

const auto cameraInfo = camera.info();

auto defaultSettings = Zivid::Experimental::SettingsInfo::defaultValue<Zivid::Settings>(cameraInfo);
defaultSettings.acquisitions().emplaceBack(
    Zivid::Experimental::SettingsInfo::defaultValue<Zivid::Settings::Acquisition>(cameraInfo));

std::cout << "Camera resolution for default settings:" << std::endl;
const auto resolution = Zivid::Experimental::SettingsInfo::resolution(cameraInfo, defaultSettings);
std::cout << "Height: " << resolution.height() << std::endl;
std::cout << "Width: " << resolution.width() << std::endl;

std::cout << "Point cloud (GPU memory) resolution:" << std::endl;
const auto pointCloud = camera.capture(defaultSettings).pointCloud();
std::cout << "Height: " << pointCloud.height() << std::endl;
std::cout << "Width: " << pointCloud.width() << std::endl;

std::cout << "Point cloud (CPU memory) resolution:" << std::endl;
const auto data = pointCloud.copyPointsXYZColorsRGBA();
std::cout << "Height: " << data.height() << std::endl;
std::cout << "Width: " << data.width() << std::endl;

The generated point cloud consists of 5 million points. Since there is a 1:1 correlation between pixels and points, it is possible to obtain XYZ (mm), RGB (8-bit), and SNR for every pixel, where SNR is the Signal-to-Noise Ratio. Internally on the GPU the 3D coordinates, color values, and SNR values are stored as separate 2D arrays of size 2448 x 2048. On the user’s side (CPU memory) the data can be stored in different formats, depending on how it is requested. See Point Cloud Tutorial for a detailed explanation.

The generated point cloud consists of 2.3 million points. Since there is a 1:1 correlation between pixels and points, it is possible to obtain XYZ (mm), RGB (8-bit), and SNR for every pixel, where SNR is the Signal-to-Noise Ratio. Internally on the GPU the 3D coordinates, color values, and SNR values are stored as separate 2D arrays of size 1944 x 1200. On the user’s side (CPU memory) the data can be stored in different formats, depending on how it is requested. See Point Cloud Tutorial for a detailed explanation.

Structured point cloud

Color image and depth map can be directly extracted from a Zivid point cloud. Examples of how to do this are shown in our GitHub repository.

Zivid output formats

From Zivid Studio, you can save the point cloud in Zivid Data File (*.zdf). In addition, you can export the point cloud (File → Export) in the following formats:

  • PLY file - Unordered points (*.ply)

  • PLY file - Ordered points (*.ply)

  • ASCII points (*.xyz)

  • Point Cloud Data File - Unordered points (*.pcd). Can be configured to be stored as ordered points, see Organized PCD format for a tutorial on how to export PCD as organized points.

Zivid studio export options

The Zivid Data File (*.zdf) is the native Zivid file format. If you are using the API, you can loop over the point cloud and save the X, Y, Z, R, G, B, and SNR data in whichever format you prefer. Check out our Samples to see how to read or convert Zivid data using C++, C#, Python, and MATLAB.

Tip

The easiest way to view a Zivid point cloud is to copy the ZDF file to your PC and use Zivid Studio. Alternatively, you could use the API to convert ZDF to PLY (or use our Python script) and use a 3D viewer, e.g. MeshLab or CloudCompare.

ASCII points (*.xyz)

ASCII characters are used to store cartesian coordinates. XYZ are separated with white space. In our version, RGB values are also added for each point. Each new point is separated by the newline character. This file can be viewed in a regular text editor.

PLY file (*.ply)

PLY is a file format developed at Stanford. Learn more about PLY.

Point Cloud Data file (*.pcd)

PCD is a file format native to Point Cloud Library. Learn more about PCD.

Organized PCD format

The Zivid SDK stores the ordered point cloud with a header that indicates an unordered point cloud. Since SDK 2.5, it is possible to configure the SDK with the Config.yml file to export PCD with the correct header that indicates an ordered point cloud. If the file already exists and its located in %LOCALAPPDATA%\Zivid\API for Windows or "${XDG_CONFIG_HOME-$HOME/.config}"/Zivid/API for Ubuntu, update Configuration/APIBreakingBugFixes/FileFormats/PCD/UseOrganizedFormat.

If the file does not exist:

  1. Download the Config.yml file.

    The config file contains the following information:

    __version__:
        serializer: 1
        data: 12
    Configuration:
        APIBreakingBugFixes:
            FileFormats:
                PCD:
                    UseOrganizedFormat: yes
    
  2. Place the config file in the following directory:

    mkdir %LOCALAPPDATA%\Zivid\API
    move %HOMEPATH%\Downloads\Config.yml %LOCALAPPDATA%\Zivid\API\
    
    mkdir --parents "${XDG_CONFIG_HOME-$HOME/.config}"/Zivid/API
    mv ~/Downloads/Config.yml "${XDG_CONFIG_HOME-$HOME/.config}"/Zivid/API/
    

    Caution

    Any existing Config file will be overwritten.

Hint

This workaround also applies to exports to PCD from Zivid Studio.

Caution

Zivid configuration files must use .yml file extension ( not .yaml).