Skip to content

Code samples for the usage of a Zivid 3D camera in C++

License

Notifications You must be signed in to change notification settings

zivid/zivid-cpp-samples

Repository files navigation

C++ samples

This repository contains cpp code samples for Zivid SDK v2.14.0. For tested compatibility with earlier SDK versions, please check out accompanying releases.

image


Contents: Tutorials | Samples | Installation | Support | License | Development


Tutorials list

Samples list

There are two main categories of samples: Camera and Applications. The samples in the Camera category focus only on how to use the camera. The samples in the Applications category use the output generated by the camera, such as the 3D point cloud, a 2D image or other data from the camera. These samples shows how the data from the camera can be used.

  • Camera
  • Applications
    • Basic
      • Visualization
        • CaptureFromFileCameraVis3D - Capture point clouds, with color, with the Zivid file camera and visualize them.
        • CaptureHDRVisNormals - Capture Zivid point clouds, with color and normals, and visualize it in 3D and as a normal map.
        • CaptureVis3D - Capture point clouds, with color, from the Zivid camera, and visualize it.
        • CaptureWritePCLVis3D - Capture point clouds, with color, from the Zivid camera, save it to PCD file format, and visualize it.
        • ProjectImageStartAndStop - Start the Image Projection and Stop it.
        • ReadAndProjectImage - Read a 2D image from file and project it using the camera projector.
        • ReadPCLVis3D - Read point cloud from PCL file and visualize it.
      • FileFormats
        • ReadIterateZDF - Read point cloud data from a ZDF file, iterate through it, and extract individual points.
    • Advanced
      • CaptureUndistort2D - Use camera intrinsics to undistort a 2D image.
      • CreateDepthMap - Convert point cloud from a ZDF file to OpenCV format, extract depth map and visualize it.
      • Downsample - Downsample point cloud from a ZDF file.
      • GammaCorrection - Capture 2D image with gamma correction.
      • HandEyeCalibration - Perform Hand-Eye calibration.
      • MaskPointCloud - Mask point cloud from a ZDF file and convert to PCL format, extract depth map and visualize it.
      • ProjectAndFindMarker - Show a marker using the projector, capture a set of 2D images to find the marker coordinates (2D and 3D).
      • ReprojectPoints - Illuminate checkerboard (Zivid Calibration Board) corners by getting checkerboard pose
      • ROIBoxViaArucoMarker - Filter the point cloud based on a ROI box given relative to the ArUco marker on a Zivid Calibration Board.
      • ROIBoxViaCheckerboard - Filter the point cloud based on a ROI box given relative to the Zivid Calibration Board.
      • TransformPointCloudFromMillimetersToMeters - Transform point cloud data from millimeters to meters.
      • TransformPointCloudViaArucoMarker - Transform a point cloud from camera to ArUco marker coordinate frame by estimating the marker's pose from the point cloud.
      • TransformPointCloudViaCheckerboard - Transform a point cloud from camera to checkerboard (Zivid Calibration Board) coordinate frame by getting checkerboard pose from the API.
      • HandEyeCalibration
        • PoseConversions - Convert to/from Transformation Matrix (Rotation Matrix
          • Translation Vector)
        • UtilizeHandEyeCalibration - Transform single data point or entire point cloud from camera to robot base reference frame using Hand-Eye calibration
      • MultiCamera
        • MultiCameraCalibration - Use captures of a calibration object to generate transformation matrices to a single coordinate frame, from connected cameras.
        • MultiCameraCalibrationFromZDF - Use captures of a calibration object to generate transformation matrices to a single coordinate frame, from a ZDF files.
        • StitchByTransformation - Use transformation matrices from Multi-Camera calibration to transform point clouds into single coordinate frame, from connected cameras.
        • StitchByTransformationFromZDF - Use transformation matrices from Multi-Camera calibration to transform point clouds into single coordinate frame, from a ZDF files.

Installation

  1. Install Zivid Software
  2. Download Zivid Sample Data

Windows

Launch the Command Prompt by pressing Win + R keys on the keyboard, then type cmd and press Enter.

Navigate to a location where you want to clone the repository, then run to following command:

git clone https://github.com/zivid/zivid-cpp-samples

Configure the sample solution with CMake, open it in Visual Studio, build it, run it. For more information see Configure C++ Samples With CMake and Build Them in Visual Studio in Windows.

Ubuntu

Open the Terminal by pressing Ctrl + Alt + T keys on the keyboard.

Navigate to a location where you want to clone the repository, then run to following command:

git clone https://github.com/zivid/zivid-cpp-samples
cd zivid-cpp-samples

Build the project:

mkdir build
cd build
cmake <options, see below> ../source
make -j

Some of the samples depend on external libraries, in particular Eigen 3, OpenCV, PCL, or HALCON. If you don't want to install those, you can disable the samples depending on them by passing the following options, respectively, to cmake: -DUSE_EIGEN3=OFF, -DUSE_OPENCV=OFF, -DUSE_PCL=OFF, -DUSE_HALCON=OFF.

If you do want to use them:

  • Eigen 3: Set -DEIGEN3_INCLUDE_DIR=<path> where <path> is the root directory of your Eigen3 installation (the folder containing Eigen/Core, Eigen/Dense etc.)
  • PCL and OpenCV: If a recent enough version is installed on your system, these should just work. If not, set -DPCL_DIR=<path> / -DOpenCV_DIR=<path> where <path> is the directory containing PCLConfig.cmake and OpenCVConfig.cmake, respectively.
  • HALCON: If a recent enough version is installed on your system, these should just work.

The samples can now be run from the build directory, for instance like this:

./CaptureFromFileCameraVis3D

HALCON

If you want to use Zivid in HALCON, we provide a GenICam GenTL producer that comes with the Zivid Software.

Zivid and HALCON are compatible with Windows 10 and 11, and Ubuntu 20.04, 22.04, 24.04.


Note:

Support for Ubuntu 18.04 is removed since SDK 2.10.


To set up and use Zivid in one of these operating systems, please follow their respective instructions on the following pages:

The following HALCON versions have been tested and confirmed to work with Zivid cameras:

  • 19.05 Progress, 20.05 Progress, 21.11 Progress

We recommend using one of the HALCON versions we have tested.

Support

For more information about the Zivid cameras, please visit our Knowledge Base. If you run into any issues please check out Troubleshooting.

License

Zivid Samples are distributed under the BSD license.

Development

To run continuous integration locally, use Docker. With Docker installed, run this command:

docker run -it -v <unix-style-repo-path>:/host -w /host/continuous-integration/linux ubuntu:20.04

Where <unix-style-repo-path> is the unix-style path to the repo on your computer. On Linux, use $PWD for this. On Windows you need to translate the windows-style path to a unix-style one (e.g. /c/Users/alice/Documents/zivid-cpp-samples).

Now run ./setup.sh to install dependencies. Once setup has completed, you can run ./lint.sh && ./build.sh repeatedly to check your code.


Tip:

If your build hangs, try to increase the memory available to Docker.