cpp-extra-samples

This repository contains C++ code samples for Zivid.

Check out our tutorial on configuring and building these samples on Ubuntu.

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

  • Basic (quick tutorial / complete tutorial)
    • Capture - This example shows how to acquire images from the Zivid camera.
    • Capture2D - This example shows how to acquire only 2D images from the Zivid camera.
    • CaptureAssistant - This example shows how to use Capture Assistant to acquire HDR images from the Zivid camera.
    • CaptureFromFile - This example shows how to acquire HDR images from file. This example can be used without access to a physical camera.
    • CaptureHDR - This example shows how to acquire HDR images from the Zivid camera.
    • CaptureHDRCompleteSettings - This example shows how to acquire an HDR image from the Zivid camera with fully configured settings for each frame.
    • CaptureHDRLoop - This example shows how to acquire HDR images from the Zivid camera in a loop, with settings from .yml files.
  • InfoUtilOther
    • CameraUserData - This example shows how to store user data on the Zivid camera.
    • GetCameraIntrinsics - This example shows how to get camera intrinsics from the Zivid camera.
    • FirmwareUpdater - This example shows how to use Zivid APIs to update the firmware on the Zivid camera.

• Applications

  • Basic
    • Visualization
      • CaptureFromFileVis3D - This example shows how capture a Zivid point cloud from file, and visualize it.
      • CaptureVis3D - This example shows how to capture a Zivid point cloud, and visualize it.
      • CaptureLiveVis3D - This example shows how to continuosly capture a Zivid point cloud, and visualize it.
      • CaptureWritePCLVis3D - This example shows how capture a Zivid point cloud, save it to a .PCD file format, and visualize it.
      • ReadPCLVis3D - This example shows how to read a PCL point cloud and visualize it.
    • FileFormats
      • ReadIterateZDF - This example shows how to import a Zivid point cloud from a .ZDF file, iterate through, and extract individual points.
  • Advanced
    • HandEyeCalibration
      • HandEyeCalibration - This samples shows how to perform a complete Hand Eye calibration
      • UtilizeEyeInHandCalibration - Transform a 3D point from camera frame to robot base frame using hand-eye calibration matrix.
      • PoseConversions - Convert to/from Transformation Matrix (Rotation Matrix + Translation Vector)
    • Downsample - This example shows how to import a Zivid point cloud from a .ZDF file and downsample it.
      • Dependencies:
        • Eigen version 3.3.7 or newer
    • CaptureUndistortRGB - Use Zivid camera intrinsics to undistort an RGB image. This example will prompt the user for whether to capture a 2D or a 3D image. In both instances it will operate on a 2D image. However, in the 3D case it will extract 2D image from a ZDF point cloud. The 2D variant is faster.
      • Dependencies:
        • OpenCV version 4.0.1 or newer
    • CreateDepthMap - Import a ZDF point cloud and convert it to OpenCV format, then extract and visualize depth map.
      • Dependencies:
        • OpenCV version 4.0.1 or newer

Instructions

Install Zivid Software. Note: The version tested with Zivid cameras is 1.8.0.

Windows

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

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

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

Configure the sample solution with CMake, open it in Visual Studio, build it, run it. If you are uncertain about doing this, check out our tutorial for configuring C++ Extra Samples with CMake and building them using 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 commands:

git clone https://github.com/zivid/cpp-extra-samples
cd cpp-extra-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 or PCL. 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.

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.

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

./CaptureFromFileVis3D

Support

If you need assistance with using Zivid cameras, visit our Knowledge Base or contact us at customersuccess@zivid.com.

Licence

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 <unixy-repo-path>:/host -w /host/continuous-integration/linux ubuntu:18.04

Where <unixy-repo-path> is the unixy path to the repo on your computer. On Linux, use $PWD for this. On Windows you need to translate the windowsy path to a unixy one (e.g. /c/Users/alice/Documents/cpp-extra-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.