Capture Tutorial¶

Introduction
Initialize
Connect
- Connect - Specific Camera
- Connect - File Camera
Configure
Capture
- Capture2D
Save
- Save 2D
Conclusion

Introduction ¶

This tutorial describes how to use the Zivid SDK to capture point clouds and 2D images.

For Python and Matlab see:

Prerequisites

You should have installed Zivid SDK and C++ samples.

Initialize ¶

Before calling any of the APIs in the Zivid SDK, we have to start up the Zivid Application. This is done through a simple instantiation of the application.

Zivid::Application zivid;

var zivid = new Zivid.NET.Application();

Connect ¶

Now we can connect to the camera.

auto camera = zivid.connectCamera();

var camera = zivid.ConnectCamera();

Sometimes multiple cameras are connected to the same computer, but it might be necessary to work with a specific camera in the code. This can be done by providing the serial number of the wanted camera.

auto camera = zivid.connectCamera(Zivid::CameraInfo::SerialNumber{ "2020C0DE" });

var camera = zivid.ConnectCamera(new Zivid.NET.CameraInfo.SerialNumber("2020C0DE"));

Note

The serial number of your camera is shown in the Zivid Studio.

You may also list all cameras connected to the computer, and view their serial numbers through

std::cout << "Finding cameras" << std::endl;
Zivid::Application zivid;
auto cameras = zivid.cameras();
if(cameras.size() < 2)
{
    throw std::runtime_error("At least two cameras need to be connected");
}
std::cout << "Number of cameras found: " << cameras.size() << std::endl;
for(auto &camera : cameras)
{
    std::cout << "Connecting to camera: " << camera.info().serialNumber() << std::endl;
    camera.connect();
}

var cameras = zivid.Cameras;
Console.WriteLine("Number of cameras found: {0}", cameras.Count);
foreach(var camera in cameras)
{
    Console.WriteLine("Connecting to camera: {0}", camera.Info.SerialNumber);
    camera.Connect();
}

Connect - File Camera ¶

You may want to experiment with the SDK, without access to a physical camera. Minor changes are required to keep the sample working.

const auto fileCamera = std::string(ZIVID_SAMPLE_DATA_DIR) + "/FileCameraZividOne.zfc";
auto camera = zivid.createFileCamera(fileCamera);

var fileCamera = Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData)
                 + "/Zivid/FileCameraZividOne.zfc";
var camera = zivid.CreateFileCamera(fileCamera);

Note

The quality of the point cloud you get from FileCameraZividOne.zfc is not representative of the Zivid 3D cameras.

Configure ¶

As with all cameras there are settings that can be configured. These may be set manually, or you use our Capture Assistant.

Capture Assistant ¶

It can be difficult to know what settings to configure. Luckily we have the Capture Assistant. This is available in the Zivid SDK to help configure camera settings.

const auto suggestSettingsParameters = Zivid::CaptureAssistant::SuggestSettingsParameters{
    Zivid::CaptureAssistant::SuggestSettingsParameters::AmbientLightFrequency::none,
    Zivid::CaptureAssistant::SuggestSettingsParameters::MaxCaptureTime{ std::chrono::milliseconds{ 1200 } }
};

std::cout << "Running Capture Assistant with parameters:\n" << suggestSettingsParameters << std::endl;
auto settings = Zivid::CaptureAssistant::suggestSettings(camera, suggestSettingsParameters);

var suggestSettingsParameters = new Zivid.NET.CaptureAssistant.SuggestSettingsParameters {
    AmbientLightFrequency =
        Zivid.NET.CaptureAssistant.SuggestSettingsParameters.AmbientLightFrequencyOption.none,
    MaxCaptureTime = Duration.FromMilliseconds(1200)
};

Console.WriteLine("Running Capture Assistant with parameters:\n{0}", suggestSettingsParameters);
var settings = Zivid.NET.CaptureAssistant.Assistant.SuggestSettings(camera, suggestSettingsParameters);

There are only two parameters to configure with Capture Assistant:

Maximum Capture Time in number of milliseconds.
1. Minimum capture time is 200 ms. This allows only one acquisition.
2. The algorithm will combine multiple acquisitions if the budget allows.
3. The algorithm will attempt to cover as much of the dynamic range in the scene as possible.
4. A maximum capture time of more than 1 second will get good coverage in most scenarios.
Ambient light compensation
1. May restrict capture assistant to exposure periods that are multiples of the ambient light period.
2. 60Hz is found in Japan, Americas, Taiwan, South Korea and Philippines.
3. 50Hz is common in the rest of the world.

Manual configuration ¶

Another option is to configure settings manually. For more information about what each settings does, please see Camera Settings. Note that Zivid Two has a set of standard settings.

Single Acquisition¶

We can create settings for a single capture.

const auto settings =
    Zivid::Settings{ Zivid::Settings::Acquisitions{ Zivid::Settings::Acquisition{
                         Zivid::Settings::Acquisition::Aperture{ 5.66 },
                         Zivid::Settings::Acquisition::ExposureTime{ std::chrono::microseconds{ 6500 } } } },
                     Zivid::Settings::Processing::Filters::Outlier::Removal::Enabled::yes,
                     Zivid::Settings::Processing::Filters::Outlier::Removal::Threshold{ 5.0 } };

var settings = new Zivid.NET.Settings {
    Acquisitions = { new Zivid.NET.Settings.Acquisition { Aperture = 5.66,
                                                          ExposureTime =
                                                              Duration.FromMicroseconds(6500) } },
    Processing = { Filters = { Outlier = { Removal = { Enabled = true, Threshold = 5.0 } } } }
};

Multi Acquisition HDR¶

We may also create settings to be used in an HDR capture.

Zivid::Settings settings;
for(const auto aperture : { 11.31, 5.66, 2.83 })
{
    std::cout << "Adding acquisition with aperture = " << aperture << std::endl;
    const auto acquisitionSettings = Zivid::Settings::Acquisition{
        Zivid::Settings::Acquisition::Aperture{ aperture },
    };
    settings.acquisitions().emplaceBack(acquisitionSettings);
}

var settings = new Zivid.NET.Settings();
foreach(var aperture in new double[] { 11.31, 5.66, 2.83 })
{
    Console.WriteLine("Adding acquisition with aperture = " + aperture);
    var acquisitionSettings = new Zivid.NET.Settings.Acquisition { Aperture = aperture };
    settings.Acquisitions.Add(acquisitionSettings);
}

2D Settings¶

It is possible to only capture a 2D image. This is faster than a 3D capture. 2D settings are configured as follows.

const auto settings2D =
    Zivid::Settings2D{ Zivid::Settings2D::Acquisitions{ Zivid::Settings2D::Acquisition{
                           Zivid::Settings2D::Acquisition::ExposureTime{ std::chrono::microseconds{ 30000 } },
                           Zivid::Settings2D::Acquisition::Aperture{ 11.31 },
                           Zivid::Settings2D::Acquisition::Brightness{ 1.80 },
                           Zivid::Settings2D::Acquisition::Gain{ 2.0 } } },
                       Zivid::Settings2D::Processing::Color::Balance::Red{ 1 },
                       Zivid::Settings2D::Processing::Color::Balance::Green{ 1 },
                       Zivid::Settings2D::Processing::Color::Balance::Blue{ 1 } };

var settings2D = new Zivid.NET.Settings2D {
    Acquisitions = { new Zivid.NET.Settings2D.Acquisition {
        Aperture = 11.31, ExposureTime = Duration.FromMicroseconds(30000), Gain = 2.0, Brightness = 1.80
    } },
    Processing = { Color = { Balance = { Red = 1.0, Blue = 1.0, Green = 1.0 } } }
};

From File ¶

Zivid Studio can store the current settings to *.yml files. These can be read and applied in the API. You may find it easier to modify the settings in these (human-readable) yaml-files in your preferred editor.

const auto settings = Zivid::Settings("Settings.yml");

var settings = new Zivid.NET.Settings("Settings.yml");

Capture ¶

Now we can capture a 3D image. Whether there is a single acquisition or multiple acquisitions (HDR) is given by the number of acquisitions in settings.

const auto frame = camera.capture(settings);

using(var frame = camera.Capture(settings))

Capture2D ¶

If we only want to capture a 2D image, which is faster than 3D, we can do so via the 2D API.

const auto frame2D = camera.capture(settings2D);

using(var frame2D = camera.Capture(settings2D))

Save ¶

We can now save our results.

const auto *dataFile = "Frame.zdf";
frame.save(dataFile);

var dataFile = "Frame.zdf";
frame.Save(dataFile);

The API detects which format to use. See Point Cloud for a list of supported formats.

Tip

You can open and view Frame.zdf file in Zivid Studio.

Save 2D ¶

If we capture a 2D image, we can save it.

const auto image = frame2D.imageRGBA();
const auto *imageFile = "Image.png";
std::cout << "Saving image to file: " << imageFile << std::endl;
image.save(imageFile);

var image = frame2D.ImageRGBA();
var imageFile = "Image.png";
Console.WriteLine("Saving image to file: {0}", imageFile);
image.Save(imageFile);

Conclusion ¶

This tutorial shows how to use the Zivid SDK to connect to, configure, capture, and save from the Zivid camera.