2D Image Capture Process

The 2D capture API returns when the acquisition is done.

C++

const auto frame2D = camera.capture2D(settings);

C#

using (var frame2D = camera.Capture2D(settings))

Python

frame_2d = camera.capture_2d(settings)

The method to get the image from the Frame2D object returns after the 2D image is available in CPU memory. This function call blocks until processing and copying are finished. The image object holds a handle to the image data in CPU memory.

Tip

Use recommended hardware to minimize 2D image processing time.

C++

const auto imageSRGB = frame2D.imageRGBA_SRGB();

C#

var imageSRGB = frame2D.ImageRGBA_SRGB();

Python

image_srgb = frame_2d.image_rgba_srgb()

It is possible to get the image in different color spaces, as linear RGB (BGRA and RGBA) and sRGB (SRGB). For more information, see 2D Color Spaces, Lens Distortion, and Output Formats.

Note

In C++ and C#, class Image inherits from Array2D and provides, in addition, a method to save the image in PNG file format.

When the image is available on the CPU memory, we can utilize it in our machine vision application or save it to disk.

C++

const auto imageFile = "ImageRGBA_sRGB.png";
std::cout << "Saving 2D color image (sRGB color space) to file: " << imageFile << std::endl;
imageSRGB.save(imageFile);

C#

var imageFile = "ImageRGBA_sRGB.png";
Console.WriteLine($"Saving 2D color image (sRGB color space) to file: {imageFile}");
imageSRGB.Save(imageFile);

Python

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

Tip

For optimized timing, move the robot or move the objects in the scene after the 2D capture API returns. This has to happen before or at the same time when calling the API to get the image from the Frame2D object.

A 2D frame can be saved to a .zdf file and later loaded back into memory. This is primarily useful when diagnostics are enabled, to share the raw frame data with Zivid support for more thorough troubleshooting.

C++

const auto dataFile2D = "Frame2D.zdf";
std::cout << "Saving 2D frame to file: " << dataFile2D << std::endl;
frame2D.save(dataFile2D);

C#

var dataFile2D = "Frame2D.zdf";
Console.WriteLine("Saving 2D frame to file: " + dataFile2D);
frame2D.Save(dataFile2D);

Python

data_file_2d = "Frame2D.zdf"
print(f"Saving 2D frame to file: {data_file_2d}")
frame_2d.save(data_file_2d)

The saved file can be loaded using the Frame2D constructor that takes a file path.

C++

std::cout << "Loading 2D frame from file: " << dataFile2D << std::endl;
const auto loadedFrame2D = Zivid::Frame2D{ dataFile2D };

C#

Console.WriteLine("Loading 2D frame from file: " + dataFile2D);
using (var loadedFrame2D = new Zivid.NET.Frame2D(dataFile2D))

Python

print(f"Loading 2D frame from file: {data_file_2d}")
loaded_frame_2d = zivid.Frame2D(data_file_2d)

The readFrameFileType function returns whether a .zdf file contains a 3D Frame or a Frame2D. This is useful when a file path is given as input and the type is not known in advance.

C++

const auto frameFileType2D = Zivid::readFrameFileType(dataFile2D);
std::cout << "Frame file type: " << (frameFileType2D == Zivid::FrameFileType::frame2D ? "Frame2D" : "Frame")
          << std::endl;

C#

var frameFileType2D = Zivid.NET.FrameFile.ReadFrameFileType(dataFile2D);
Console.WriteLine("Frame file type: " + frameFileType2D);

Python

frame_file_type_2d = zivid.read_frame_file_type(data_file_2d)
print(f"Frame file type: {frame_file_type_2d}")

Version History

SDK	Changes
2.18.0	Added support for saving and loading Frame2D to and from .zdf files, and `readFrameFileType` to identify the frame type in a file.
2.12.0	2D acquisition time on Zivid 2+ is reduced by up to 50%.
2.11.0	Added support for SRGB color space.
2.9.0	Capture function returns when the acquisition is done and improved capture speed.
2.8.0	Improved capture speed of Zivid 2.