3D machine vision blog - Zivid

SDK 2.5 out now with normals support

Written by John Leonard | 2021-10-20

We’ve just recently released our latest SDK 2.5.0 for our Zivid One+ and Zivid Two 3D color cameras. We wanted to give you an update on some of the new features and supporting material we’ve introduced for developers to make use of in your applications: 

  • API - Obtaining normals data 
  • API - Camera model detection 
  • Zivid Studio - Drag & drop ZDF files 
  • Zivid Studio – Depth map coloring of point cloud 
  • New developer samples 

The support for Normals is undoubtedly the main feature of this SDK release, so let’s take a quick run through what normals are, how they help with scene analysis, and what we have done for the implementation. 

Read full changelog

A quick introduction to normals 

Surface normals, often just called ‘normals’ is the term to describe vectors that are perpendicular to the surface of an object.  Estimation and analysis of the normal vectors on an object’s surface yield important information about the object’s shape and its surface, such as whether it is round, has angular edges, or if there are surface deformations or undulations.  

This information is extremely useful in 3D camera applications such as bin picking and piece picking where the angular vectors of a surface influence the ability to pick accurately. 

Calculation of normals can be a computationally intensive task, and there are various approaches. At Zivid we have implemented a novel solution for obtaining normals data that is highly accurate and executes very quickly and efficiently on a GPU whilst the data is still in the GPU’s memory. This negates the need for transferring the data to the host CPU for the normals to be calculated with a third-party application.  

Use of normals in applications 

Normals data is useful to determine an object’s surface characteristics. Where the surface has changes, such as the curved surface of a cylinder or sphere, or an angular feature such as an edge or corner. They are also used routinely in 3D CAD matching applications, and with this support, we have made this workflow simpler by having everything needed available in our latest SDK. 

Normals information is also useful for correctly identifying small gaps and holes between objects and on surfaces. For example, if we have two boxes closely aligned, we will see the normals start to change at the box corners and this can help us to identify the dark space as a gap, as opposed to say a strip of black tape on the box surface. 

The new CopyNormalsXYZ function allows developers to obtain normals and use them in your application.  

Fig.1 Normals on the surface of a box

Fig.2 Normals on a collection of rectangular blocks 

Other SDK 2.5.0 highlights 

In addition to the new API for obtaining normals data, we have added a few more features for you to make use of.  

  • New Model enumeration to the CameraInfo class. This allows differentiation between the camera models: Zivid One+ Small/Medium/Large, and Zivid Two cameras
  • Zivid Studio has added support for depth map coloring of points in the 3D point cloud 
  • Zivid Studio drag and drop support for ZDF and YML files

Depth map coloring of point cloud in Zivid Studio 

We have added some further visualization capability to Zivid studio with depth map coloring of the point cloud. This feature enables viewing of the 3D point cloud together with depth map coloring for better scene assessment. 

Fig.3 Depth map coloring of point clouds in Zivid Studio. 

Python wrapper catching up 

For developers that prefer to use Python, we have been working hard on synchronizing our Python API with the C++ API. With this release, we have introduced several wrapper functions for key features in our SDK. These are: 

  • Normal vectors
  • Save/Load Settings/Settings2D (and other data models) to/from YML files
  • Engine options (Stripe engine is now available in Python)
  • Tone-mapping options

Going forward, all extensions to Settings and Settings2D added in future SDKs will be automatically available through the Python API. 

Knowledge Base and samples 

We have updated our knowledge base with two new articles on our normals and transform support and code samples to get you started with using them in your applications. 

Sample code:

C++ 

  • CaptureHDRVisNormals - This sample shows how to capture Zivid point clouds with color and normals information. For scenes with a high dynamic range, multiple HDR captures are used. 
  • CaptureHDRPrintNormals – Captures Zivid point clouds, compute them and print a subset 
  • SettingsInfo – This sample queries the point cloud resolution given a Settings object and a CameraInfo object. 
  • AllocateMemoryForPointCloudData – Allocates the appropriate amount of memory before a point cloud capture. 
  • TransformPointCloudViaArucoMarker – This sample shows how to transform a point cloud from camera to ArUco Marker coordinate frame by estimating the marker’s pose from the point cloud. (The ZDF file for this sample can be found under the main instructions for Zivid samples.)
C#

Python 

For details, read full changelog.

We encourage all customers developing for Zivid color 3D cameras to update to this latest SDK as soon as is feasible to do so. 

Happy developing, and all the best from the team at Zivid!