File Camera

Introduction

The Zivid file camera is a virtual camera that replays raw sensor data from a previously captured point cloud. This is useful for:

• View the point cloud in Zivid Studio or visualize it with the file camera visualization sample.

• Adjust filters and color settings to inspect their impact on the point cloud and the 2D color image.

• Work on your code without needing to have a camera connected at all times.

• Test the Zivid API without having a physical camera.

The recommended approach is to capture a frame with diagnostics enabled and create a file camera from it directly.

Available File Cameras

In this tutorial, each file camera demonstrates a use case within one of the main applications of the respective camera model. Choose a file camera based on your preferred camera model or application. These pre-built ZDF and ZFC files are available in Zivid Sample Data.

Zivid 3

XL250, Depalletization

Zivid 2+R

MR60, Small Bin Picking

MR130, Piece Picking

LR110, Parcel and Big Bin Picking

Zivid 2+

M60, Small Bin Picking

M130, Bin Picking

L110, Parcel and Big Bin Picking

Zivid 2

M70, Robot Guidance

L100, Bin Picking

File Camera with Zivid Samples

From ZDF

Utilizing a ZDF file is the recommended way of using file cameras.

This tutorial starts by connecting to the first available camera. Then a default settings object is created and diagnostics are enabled.

C++

source

std::cout << "Connecting to camera" << std::endl;
auto camera = zivid.connectCamera();

std::cout << "Creating default settings" << std::endl;
Zivid::Settings settings{
    Zivid::Settings::Acquisitions{ Zivid::Settings::Acquisition{} },
    Zivid::Settings::Color{
        Zivid::Settings2D{ Zivid::Settings2D::Acquisitions{ Zivid::Settings2D::Acquisition{} } } },
};
std::cout << "Enabling diagnostics" << std::endl;
settings.set(Zivid::Settings::Diagnostics::Enabled::yes);

C#

source

Console.WriteLine("Connecting to camera");
var camera = zivid.ConnectCamera();

Console.WriteLine("Creating default settings");
var settings = new Zivid.NET.Settings
{
    Acquisitions = { new Zivid.NET.Settings.Acquisition { } },
    Color = new Zivid.NET.Settings2D
    {
        Acquisitions = { new Zivid.NET.Settings2D.Acquisition { } }
    }
};
Console.WriteLine("Enabling diagnostics");
settings.Diagnostics.Enabled = true;

Python

source

print("Connecting to camera")
camera = app.connect_camera()

print("Creating default settings")
settings = zivid.Settings(
    acquisitions=[zivid.Settings.Acquisition()],
    color=zivid.Settings2D(acquisitions=[zivid.Settings2D.Acquisition()]),
)
print("Enabling diagnostics")
settings.diagnostics.enabled = True

The frame is now captured using those settings, saved to a ZDF file, and the camera is disconnected.

Note

The camera is only needed to capture the diagnostics frame. If a ZDF file captured with diagnostics enabled is already available, this step can be skipped.

C++

source

std::cout << "Capturing frame with diagnostics" << std::endl;
const auto frameWithDiagnostics = camera.capture2D3D(settings);

const auto frameWithDiagnosticsFile = "FrameWithDiagnostics.zdf";
std::cout << "Saving diagnostics frame to: " << frameWithDiagnosticsFile << std::endl;
frameWithDiagnostics.save(frameWithDiagnosticsFile);

std::cout << "Disconnecting from camera" << std::endl;
camera.disconnect();

C#

source

Console.WriteLine("Capturing frame with diagnostics");
var frameWithDiagnostics = camera.Capture2D3D(settings);

var frameWithDiagnosticsFile = "FrameWithDiagnostics.zdf";
Console.WriteLine("Saving diagnostics frame to: " + frameWithDiagnosticsFile);
frameWithDiagnostics.Save(frameWithDiagnosticsFile);

Console.WriteLine("Disconnecting from camera");
camera.Disconnect();

Python

source

print("Capturing frame with diagnostics")
frame_with_diagnostics = camera.capture_2d_3d(settings)

frame_with_diagnostics_file = "FrameWithDiagnostics.zdf"
print(f"Saving diagnostics frame to: {frame_with_diagnostics_file}")
frame_with_diagnostics.save(frame_with_diagnostics_file)

print("Disconnecting from camera")
camera.disconnect()

The saved ZDF file is loaded and passed to createFileCamera to obtain a file camera.

C++

source

std::cout << "Loading ZDF with diagnostics enabled from: " << frameWithDiagnosticsFile << std::endl;
const auto loadedFrameWithDiagnostics = Zivid::Frame(frameWithDiagnosticsFile);

std::cout << "Creating file camera from frame" << std::endl;
auto fileCamera = zivid.createFileCamera(loadedFrameWithDiagnostics);

C#

source

Console.WriteLine("Loading ZDF with diagnostics enabled from: " + frameWithDiagnosticsFile);
var loadedFrameWithDiagnostics = new Zivid.NET.Frame(frameWithDiagnosticsFile);

Console.WriteLine("Creating file camera from frame");
var fileCamera = zivid.CreateFileCamera(loadedFrameWithDiagnostics);

Python

source

print(f"Loading ZDF with diagnostics enabled from: {frame_with_diagnostics_file}")
loaded_frame_with_diagnostics = zivid.Frame(frame_with_diagnostics_file)

print("Creating file camera from frame")
file_camera = app.create_file_camera(loaded_frame_with_diagnostics)

From ZFC

This is an alternative approach, where a ZFC file is loaded instead of a ZDF file. The ZFC file is loaded and passed to createFileCamera to obtain a file camera.

C++

source

const auto fileCamera =
    userInput ? fileCameraPath : std::string(ZIVID_SAMPLE_DATA_DIR) + "/FileCameraZivid2PlusMR60.zfc";
std::cout << "Creating virtual camera using file: " << fileCamera << std::endl;
auto camera = zivid.createFileCamera(fileCamera);

C#

source

    fileCamera = Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData) + "/Zivid/FileCameraZivid2PlusMR60.zfc";
Console.WriteLine("Creating virtual camera using file: " + fileCamera);
var camera = zivid.CreateFileCamera(fileCamera);

Python

source

    default=get_sample_data_path() / "FileCameraZivid2PlusMR60.zfc",
print(f"Creating virtual camera using file: {file_camera}")
camera = app.create_file_camera(file_camera)

Note

The following settings are locked to the values stored in the frame and cannot be changed:

• 3D acquisition settings (exposure time, aperture, projector brightness, and gain)

• Engine

• Sampling Pixel

• Sampling Color (2D)

• 2D acquisition settings

Only processing settings (3D filters, resampling, 2D color, and region of interest) can be freely adjusted.

From ZDF

The settings stored in the frame are retrieved and the processing filters are adjusted. Since diagnostics are no longer needed in the output file, they are disabled.

C++

source

std::cout << "Configuring settings" << std::endl;
auto settingsFromFrame = loadedFrameWithDiagnostics.settings();
settingsFromFrame.set(Zivid::Settings::Diagnostics::Enabled::no);
settingsFromFrame.set(Zivid::Settings::Processing::Filters::Smoothing::Gaussian::Enabled::yes);
settingsFromFrame.set(Zivid::Settings::Processing::Filters::Smoothing::Gaussian::Sigma{ 1.5 });
settingsFromFrame.set(Zivid::Settings::Processing::Filters::Reflection::Removal::Enabled::yes);
settingsFromFrame.set(Zivid::Settings::Processing::Filters::Reflection::Removal::Mode::global);

C#

source

Console.WriteLine("Configuring settings");
var settingsFromFrame = loadedFrameWithDiagnostics.Settings;
settingsFromFrame.Diagnostics.Enabled = false;
settingsFromFrame.Processing.Filters.Smoothing.Gaussian.Enabled = true;
settingsFromFrame.Processing.Filters.Smoothing.Gaussian.Sigma = 1.5;
settingsFromFrame.Processing.Filters.Reflection.Removal.Enabled = true;
settingsFromFrame.Processing.Filters.Reflection.Removal.Mode = Zivid.NET.Settings.ProcessingGroup.FiltersGroup.ReflectionGroup.RemovalGroup.ModeOption.Global;

Python

source

print("Configuring settings")
settings_from_frame = loaded_frame_with_diagnostics.settings
settings_from_frame.diagnostics.enabled = False
settings_from_frame.processing.filters.smoothing.gaussian.enabled = True
settings_from_frame.processing.filters.smoothing.gaussian.sigma = 1.5
settings_from_frame.processing.filters.reflection.removal.enabled = True
settings_from_frame.processing.filters.reflection.removal.mode = (
    zivid.Settings.Processing.Filters.Reflection.Removal.Mode.global_
)

The frame is captured from the file camera and saved.

C++

source

std::cout << "Capturing from file camera" << std::endl;
const auto fileCameraFrame = fileCamera.capture2D3D(settingsFromFrame);

const auto fileCameraFrameFile = "FrameFromFileCameraWithNoDiagnostics.zdf";
std::cout << "Saving file camera frame to: " << fileCameraFrameFile << std::endl;
fileCameraFrame.save(fileCameraFrameFile);

C#

source

Console.WriteLine("Capturing from file camera");
var fileCameraFrame = fileCamera.Capture2D3D(settingsFromFrame);

var fileCameraFrameFile = "FrameFromFileCameraWithNoDiagnostics.zdf";
Console.WriteLine("Saving file camera frame to: " + fileCameraFrameFile);
fileCameraFrame.Save(fileCameraFrameFile);

Python

source

print("Capturing from file camera")
file_camera_frame = file_camera.capture_2d_3d(settings_from_frame)

file_camera_frame_file = "FrameFromFileCameraWithNoDiagnostics.zdf"
print(f"Saving file camera frame to: {file_camera_frame_file}")
file_camera_frame.save(file_camera_frame_file)

From ZFC

For the ZFC file camera, the acquisition settings are fixed to the values stored in the file. The ZFC files in the sample data use default settings, so a default settings object is created and the processing settings are adjusted.

C++

source

std::cout << "Configuring settings" << std::endl;
Zivid::Settings settings{
    Zivid::Settings::Acquisitions{ Zivid::Settings::Acquisition{} },
    Zivid::Settings::Processing::Filters::Smoothing::Gaussian::Enabled::yes,
    Zivid::Settings::Processing::Filters::Smoothing::Gaussian::Sigma{ 1.5 },
    Zivid::Settings::Processing::Filters::Reflection::Removal::Enabled::yes,
    Zivid::Settings::Processing::Filters::Reflection::Removal::Mode::global,
};
settings.set(
    Zivid::Settings::RegionOfInterest::Box{
        Zivid::Settings::RegionOfInterest::Box::Enabled::yes,
        Zivid::Settings::RegionOfInterest::Box::PointO{ { -266, 190, 771 } },
        Zivid::Settings::RegionOfInterest::Box::PointA{ { 203, 207, 771 } },
        Zivid::Settings::RegionOfInterest::Box::PointB{ { -255, -131, 771 } },
        Zivid::Settings::RegionOfInterest::Box::Extents{ 0, 298 } });

Zivid::Settings2D settings2D{ Zivid::Settings2D::Acquisitions{ Zivid::Settings2D::Acquisition{} } };
settings.color() = Zivid::Settings::Color{ settings2D };

C#

source

Console.WriteLine("Configuring settings");
var settings2D = new Zivid.NET.Settings2D
{
    Acquisitions = { new Zivid.NET.Settings2D.Acquisition { } }
};
var settings = new Zivid.NET.Settings
{
    Acquisitions = { new Zivid.NET.Settings.Acquisition { } },
    Processing =
    {
        Filters =
        {
            Smoothing =
            {
                Gaussian = { Enabled = true, Sigma = 1.5 }
            },
            Reflection =
            {
                Removal = { Enabled = true, Mode = ReflectionFilterModeOption.Global}
            }
        }
    }
};
var roiBox = new Zivid.NET.Settings.RegionOfInterestGroup.BoxGroup
{
    Enabled = true,
    PointO = new Zivid.NET.PointXYZ { x = -266, y = 190, z = 771 },
    PointA = new Zivid.NET.PointXYZ { x = 203, y = 207, z = 771 },
    PointB = new Zivid.NET.PointXYZ { x = -255, y = -131, z = 771 }
};
roiBox.Extents = new Zivid.NET.Range<double>(0, 298);
settings.RegionOfInterest.Box = roiBox;
settings.Color = settings2D;

Python

source

print("Configuring settings")
settings = zivid.Settings()
settings.acquisitions.append(zivid.Settings.Acquisition())
settings.processing.filters.smoothing.gaussian.enabled = True
settings.processing.filters.smoothing.gaussian.sigma = 1.5
settings.processing.filters.reflection.removal.enabled = True
settings.processing.filters.reflection.removal.mode = (
    zivid.Settings.Processing.Filters.Reflection.Removal.Mode.global_
)
settings.region_of_interest.box = zivid.Settings.RegionOfInterest.Box(
    enabled=True,
    point_o=(-266, 190, 771),
    point_a=(203, 207, 771),
    point_b=(-255, -131, 771),
    extents=(0, 298),
)
settings_2d = zivid.Settings2D()
settings_2d.acquisitions.append(zivid.Settings2D.Acquisition())
settings.color = settings_2d

The frame is captured from the file camera and saved.

C++

source

std::cout << "Capturing frame" << std::endl;
const auto frame = camera.capture2D3D(settings);

const auto dataFile = "Frame.zdf";
std::cout << "Saving frame to file: " << dataFile << std::endl;
frame.save(dataFile);

C#

source

Console.WriteLine("Capturing frame");
using (var frame = camera.Capture2D3D(settings))
{
    var dataFile = "Frame.zdf";
    Console.WriteLine("Saving frame to file: " + dataFile);
    frame.Save(dataFile);
}

Python

source

print("Capturing frame")
frame = camera.capture_2d_3d(settings)
data_file = "Frame.zdf"
print(f"Saving frame to file: {data_file}")
frame.save(data_file)

File Camera with Zivid Studio

From ZDF

Open or create a file camera from within the Cameras panel. Click the ⋯ menu in the Cameras panel to access the following options:

• Use captured frame as file camera - Creates a file camera from the frame currently displayed in the viewer.

  This option is available only when the frame captured/loaded has the diagnostics enabled.

• Open ZDF file as file camera - Opens a file dialog to select any .zdf file and load it directly as a file camera.

  The file must have been captured with diagnostics enabled.

Studio automatically applies the settings stored in the frame when a file camera is opened.

From ZFC

Open a pre-built file camera in Zivid Studio by double-clicking the ZFC file or dragging and dropping it in.

Using a ZFC file requires loading the settings from the original ZDF file into Zivid Studio after the file camera is loaded.

Note

Acquisition settings (2D/3D Options and individual acquisitions) are locked while a file camera is active and appear dimmed in the panel. Only processing settings (3D Filters, Resampling, 2D Color Balance & Gamma, and Region of Interest) can be freely adjusted.

Version History

SDK	Changes
2.18.0	Added support for creating a file camera from a captured frame.
2.14.0	Added support to open file camera by double-clicking on it or from Zivid Studio with File → Open.
2.9.0	File cameras added for current camera models.