Merge pull request #286 from zivid/2026-02-05-update-cpp-samples

Samples: Add a new C++ sample and update others

    Conclude the modifications made to which settings are used to capture in
    the samples.
    The new sample is a direct translation for the same script in python.
    It takes a ZDF file in input and then converts to different selected
    file formats, or all of the file formats if none is given.
    There are also options to control colorspace and if you want to use
    unordered point clouds.

Author: TTPinto

README.md

@@ -106,6 +106,8 @@ from the camera can be used.
               - [ProjectImageStartAndStop](https://github.com/zivid/zivid-cpp-samples/tree/master/source/Applications/Basic/Visualization/ProjectImageStartAndStop/ProjectImageStartAndStop.cpp) - Start the Image Projection and Stop it.
               - [ReadPCLVis3D](https://github.com/zivid/zivid-cpp-samples/tree/master/source/Applications/Basic/Visualization/ReadPCLVis3D/ReadPCLVis3D.cpp) - Read point cloud from PCL file and visualize it.
           - **FileFormats**
+              - [ConvertZDF](https://github.com/zivid/zivid-cpp-samples/tree/master/source/Applications/Basic/FileFormats/ConvertZDF/ConvertZDF.cpp) - Convert point cloud data from a ZDF file to your
+                preferred format
               - [ReadIterateZDF](https://github.com/zivid/zivid-cpp-samples/tree/master/source/Applications/Basic/FileFormats/ReadIterateZDF/ReadIterateZDF.cpp) - Read point cloud data from a ZDF file, iterate through
                 it, and extract individual points.
       - **Advanced**

source/Applications/Advanced/MultiCamera/MultiCameraCalibration/MultiCameraCalibration.cpp

@@ -43,14 +43,25 @@ namespace
     };
 
     // Detect checkerboard feature points from each camera capture
-    std::vector<Detection> getDetections(const std::vector<Zivid::Camera> &connectedCameras)
+    std::vector<Detection> getDetections(
+        const std::vector<Zivid::Camera> &connectedCameras,
+        const std::string &settingsPath)
     {
         auto detectionsList = std::vector<Detection>();
 
         for(auto camera : connectedCameras)
         {
             const auto serial = camera.info().serialNumber().toString();
             std::cout << "Capturing frame with camera: " << serial << std::endl;
+            if(settingsPath.empty())
+            {
+                const auto frame = Zivid::Calibration::captureCalibrationBoard(camera);
+            }
+            else
+            {
+                const auto settings = Zivid::Settings(settingsPath);
+                const auto frame = camera.capture2D3D(settings);
+            }
             const auto frame = Zivid::Calibration::captureCalibrationBoard(camera);
             std::cout << "Detecting checkerboard in point cloud" << std::endl;
             const auto detectionResult = Zivid::Calibration::detectCalibrationBoard(frame);
@@ -111,25 +122,31 @@ int main(int argc, char **argv)
 {
     try
     {
-        Zivid::Application zivid;
-
+        bool showHelp = false;
         std::string transformationMatricesSavePath;
-
-        clipp::group cli;
-        cli.push_back(
-            clipp::values("Path to YAML files", transformationMatricesSavePath)
-            % "Path where the transformation matrices YAML files will be saved");
-
-        if(!parse(argc, argv, cli))
+        std::string settingsPath;
+        auto cli =
+            (clipp::option("-h", "--help").set(showHelp) % "Show help message",
+             clipp::values("Path to YAML files", transformationMatricesSavePath)
+                 % "Path where the transformation matrices YAML files will be saved",
+             clipp::option("--settings-path")
+                 & clipp::value("path", settingsPath) % "Path to the camera settings YML file");
+        if(!clipp::parse(argc, argv, cli))
         {
             auto fmt = clipp::doc_formatting{}.alternatives_min_split_size(1).surround_labels("\"", "\"");
             std::cout << "SYNOPSIS:" << std::endl;
             std::cout << clipp::usage_lines(cli, "MultiCameraCalibration", fmt) << std::endl;
             std::cout << "OPTIONS:" << std::endl;
             std::cout << clipp::documentation(cli) << std::endl;
+            if(showHelp)
+            {
+                return EXIT_SUCCESS;
+            }
             throw std::runtime_error("No path provided.");
         }
 
+        Zivid::Application zivid;
+
         std::cout << "Finding cameras" << std::endl;
         auto cameras = zivid.cameras();
         std::cout << "Number of cameras found: " << cameras.size() << std::endl;
@@ -142,7 +159,7 @@ int main(int argc, char **argv)
         std::cout << "Number of connected cameras: " << connectedCameras.size() << std::endl;
 
         // detect checkerboard feature points from Capture for each camera
-        const auto detections = getDetections(connectedCameras);
+        const auto detections = getDetections(connectedCameras, settingsPath);
 
         // Perform multi-camera calibration
         runMultiCameraCalibration(detections, transformationMatricesSavePath);

source/Applications/Advanced/MultiCamera/MultiCameraCalibrationFromZDF/MultiCameraCalibrationFromZDF.cpp

@@ -92,11 +92,9 @@ int main(int argc, char **argv)
 {
     try
     {
-        Zivid::Application zivid;
-
+        auto zdfFileList = std::vector<std::string>{};
         std::string transformationMatricesSavePath;
 
-        auto zdfFileList = std::vector<std::string>{};
         auto cli =
             (clipp::required("-zdf")
                  & clipp::values("ZDF filenames", zdfFileList)
@@ -116,6 +114,7 @@ int main(int argc, char **argv)
             throw std::runtime_error("No files provided.");
         }
 
+        Zivid::Application zivid;
         // Read from ZDF and detect checkerboard feature
         const auto detections = getDetectionsFromZDF(zdfFileList);
 

source/Applications/Advanced/MultiCamera/StitchByTransformation/StitchByTransformation.cpp

@@ -24,6 +24,10 @@ namespace
         using Model = Zivid::CameraInfo::Model::ValueType;
         switch(camera.info().model().value())
         {
+            // Not using [[fallthrough]] because of clang-tidy bug: https://github.com/llvm/llvm-project/issues/47588
+            case Model::zividOnePlusSmall:  // intentional fallthrough
+            case Model::zividOnePlusMedium: // intentional fallthrough
+            case Model::zividOnePlusLarge: throw std::invalid_argument("Invalid camera model");
             case Model::zividTwo: return "Zivid_Two_M70";
             case Model::zividTwoL100: return "Zivid_Two_L100";
             case Model::zivid2PlusM130: return "Zivid_Two_Plus_M130";
@@ -33,9 +37,6 @@ namespace
             case Model::zivid2PlusMR60: return "Zivid_Two_Plus_MR60";
             case Model::zivid2PlusLR110: return "Zivid_Two_Plus_LR110";
             case Model::zivid3XL250: return "Zivid_Three_XL250";
-            case Model::zividOnePlusSmall: return "Zivid_One_Plus_Small";
-            case Model::zividOnePlusMedium: return "Zivid_One_Plus_Medium";
-            case Model::zividOnePlusLarge: return "Zivid_One_Plus_Large";
 
             default: throw std::runtime_error("Unhandled camera model: " + camera.info().model().toString());
         }
@@ -107,26 +108,39 @@ int main(int argc, char **argv)
 {
     try
     {
-        Zivid::Application zivid;
-
+        bool showHelp = false;
         auto transformationMatricesfileList = std::vector<std::string>{};
         std::string stitchedPointCloudFileName;
-        auto saveStitched = false;
-        auto cli = (clipp::values("File Names", transformationMatricesfileList)
-                        % "List of YAML files containing the corresponding transformation matrices.",
-                    clipp::required("-o", "--output-file").set(saveStitched)
-                        % "Save the stitched point cloud to a file with this name. (.ply)")
-                   & clipp::value("Output point cloud (PLY) file name", stitchedPointCloudFileName);
-
-        if(!parse(argc, argv, cli))
+        std::string settingsPath;
+        auto cli =
+            (clipp::option("-h", "--help").set(showHelp) % "Show help message",
+             clipp::values("File Names", transformationMatricesfileList)
+                 % "List of YAML files containing the corresponding transformation matrices",
+             clipp::option("-o", "--output-file")
+                 & clipp::value("Output point cloud (PLY) file name", stitchedPointCloudFileName)
+                       % "Save the stitched point cloud to a file with this name (.ply)",
+             clipp::option("--settings-path")
+                 & clipp::value("path", settingsPath) % "Path to the camera settings YML file");
+
+        if(!parse(argc, argv, cli) || showHelp)
         {
             std::cout << "SYNOPSIS:" << std::endl;
             std::cout << clipp::usage_lines(cli, "StitchByTransformation") << std::endl;
             std::cout << "OPTIONS:" << std::endl;
             std::cout << clipp::documentation(cli) << std::endl;
-            throw std::runtime_error("No file provided.");
+            if(showHelp)
+            {
+                return EXIT_SUCCESS;
+            }
+
+            throw std::runtime_error("No path provided.");
         }
 
+        Zivid::Application zivid;
+
+        bool pathNotProvided = settingsPath.empty();
+        bool saveStitched = !stitchedPointCloudFileName.empty();
+
         auto cameras = zivid.cameras();
         std::cout << "Number of cameras found: " << cameras.size() << std::endl;
 
@@ -139,8 +153,12 @@ int main(int argc, char **argv)
 
         for(auto &camera : connectedCameras)
         {
-            const auto settingsPath = std::string(ZIVID_SAMPLE_DATA_DIR) + "/Settings/" + sanitizedModelName(camera)
-                                      + "_ManufacturingSpecular.yml";
+            if(pathNotProvided)
+            {
+                settingsPath = std::string(ZIVID_SAMPLE_DATA_DIR) + "/Settings/" + sanitizedModelName(camera)
+                               + "_ManufacturingSpecular.yml";
+            }
+
             std::cout << "Imaging from camera: " << camera.info().serialNumber() << std::endl;
             const auto frame = camera.capture2D3D(Zivid::Settings(settingsPath));
             const auto unorganizedPointCloud = frame.pointCloud().toUnorganizedPointCloud();