Merge pull request #99 from zivid/2025-04-23-update-csharp-samples

Samples: Automatic updates to public repository

Author: TTPinto

README.md

@@ -45,7 +45,7 @@ from the camera can be used.
             camera.
           - [CaptureHDRCompleteSettings](https://github.com/zivid/zivid-csharp-samples/tree/master/source/Camera/Basic/CaptureHDRCompleteSettings/CaptureHDRCompleteSettings.cs) - Capture point clouds, with color, from the Zivid camera
             with fully configured settings.
-          - [CaptureWithSettingsFromYML](https://github.com/zivid/zivid-csharp-samples/tree/master/source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs) - Capture images and point clouds, with or without color,
+          - [CaptureWithSettingsFromYML](https://github.com/zivid/zivid-csharp-samples/tree/master/source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs) - Capture images and point clouds, with and without color,
             from the Zivid camera with settings from YML file.
       - **Advanced**
           - [CaptureHalconViaGenICam](https://github.com/zivid/zivid-csharp-samples/tree/master/source/Camera/Advanced/CaptureHalconViaGenICam/CaptureHalconViaGenICam.cs) - Capture and save a point cloud, with colors, using GenICam

source/Applications/Basic/Visualization/ProjectImageStartAndStop/ProjectImageStartAndStop.cs

@@ -12,20 +12,6 @@ Start the Image Projection and Stop it.
 
 class Program
 {
-    static Zivid.NET.ImageBGRA CreateProjectorImage(Zivid.NET.Resolution resolution, Zivid.NET.ColorBGRA color)
-    {
-        var pixelArray = new Zivid.NET.ColorBGRA[resolution.Height, resolution.Width];
-        for (ulong y = 0; y < resolution.Height; y++)
-        {
-            for (ulong x = 0; x < resolution.Width; x++)
-            {
-                pixelArray[y, x] = color;
-            }
-        }
-        var projectorImage = new Zivid.NET.ImageBGRA(pixelArray);
-        return projectorImage;
-    }
-
     static int Main()
     {
         try
@@ -79,4 +65,18 @@ static int Main()
         }
         return 0;
     }
+
+    static Zivid.NET.ImageBGRA CreateProjectorImage(Zivid.NET.Resolution resolution, Zivid.NET.ColorBGRA color)
+    {
+        var pixelArray = new Zivid.NET.ColorBGRA[resolution.Height, resolution.Width];
+        for (ulong y = 0; y < resolution.Height; y++)
+        {
+            for (ulong x = 0; x < resolution.Width; x++)
+            {
+                pixelArray[y, x] = color;
+            }
+        }
+        var projectorImage = new Zivid.NET.ImageBGRA(pixelArray);
+        return projectorImage;
+    }
 }

source/Applications/PointCloudTutorial.md

@@ -51,7 +51,16 @@ on compute device memory) and the capture and camera information.
 
 ### Capture
 
-When you capture with Zivid, you get a frame in return.
+When you capture with Zivid, you get a frame in return. The point cloud
+is stored in the frame, and the frame is stored in the GPU memory. The
+capture can contain color or not, depending of the method that you call.
+For more information see this `table with different capture
+modes<capture-mode-table>`.
+
+#### Capture with color
+
+If you want to capture a point cloud with color, you can use the
+`Zivid::Camera::capture2D3D()` method.
 
 ([go to
 source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/Capture/Capture.cs#L26))
@@ -60,6 +69,18 @@ source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera
 using (var frame = camera.Capture2D3D(settings))
 ```
 
+#### Capture without color
+
+If you want to capture a point cloud without color, you can use the
+`Zivid::Camera::capture3D()` method.
+
+([go to
+source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs#L86))
+
+``` sourceCode cs
+using (var frame3D = camera.Capture3D(settings))
+```
+
 Check
 [CaptureTutorial](https://github.com/zivid/zivid-csharp-samples/tree/master/source/Camera/Basic/CaptureTutorial.md)
 for detailed instructions on how to capture.
@@ -104,13 +125,13 @@ copying from GPU memory.
 
 Note:
 
-`Zivid.NET.Camera.Capture()` method returns at some moment in time after
-the camera completes capturing raw images. The handle from
-`Zivid.NET.Frame.PointCloud` is available instantly. However, the actual
-point cloud data becomes available only after the processing on the GPU
-is finished. Any calls to data-copy methods (section below) will block
-and wait for processing to finish before proceeding with the requested
-copy operation.
+`Zivid.NET.Camera.Capture2D3D()` and `Zivid.NET.Camera.Capture3D()`
+methods return at some moment in time after the camera completes
+capturing raw images. The handle from `Zivid.NET.Frame.PointCloud` is
+available instantly. However, the actual point cloud data becomes
+available only after the processing on the GPU is finished. Any calls to
+data-copy methods (section below) will block and wait for processing to
+finish before proceeding with the requested copy operation.
 
 For detailed explanation, see [Point Cloud Capture
 Process](https://support.zivid.com/latest/academy/camera/point-cloud-capture-process.html).

source/Camera/Basic/CaptureTutorial.md

@@ -395,7 +395,7 @@ If we only want to capture 3D, the points cloud without color, we can do
 so via the `capture3D` API.
 
 ([go to
-source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs#L71))
+source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs#L86))
 
 ``` sourceCode cs
 using (var frame3D = camera.Capture3D(settings))
@@ -407,7 +407,7 @@ If we only want to capture a 2D image, which is faster than 3D, we can
 do so via the `capture2D` API.
 
 ([go to
-source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs#L28))
+source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs#L42))
 
 ``` sourceCode cs
 using (var frame2D = camera.Capture2D(settings))
@@ -464,62 +464,67 @@ using (var frame = new Zivid.NET.Frame(dataFile))
 
 ### Save 2D
 
-We can get the 2D color image from `Frame2D`, which is part of the
-`Frame` object, obtained from `capture2D3D()`.
+From a `capture2D()` you get a `Frame2D`. There are two color spaces
+available for 2D images: linear RGB and sRGB. The `imageRGBA()` will
+return an image in the linear RGB color space. If you append `_SRGB` to
+the function name then the returned image will be in the sRGB color
+space
 
-([go to source]())
+([go to
+source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs#L49))
 
 ``` sourceCode cs
-var image2D = frame.Frame2D.ImageBGRA_SRGB();
+var imageRGBA = frame2D.ImageRGBA();
+.. tab-item:: sRGB
 ```
 
-We can get 2D color image directly from the point cloud. This image will
-have the same resolution as the point cloud.
-
-([go to source]())
+([go to
+source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs#L67))
 
 ``` sourceCode cs
-var pointCloud = frame.PointCloud;
-var image2DInPointCloudResolution = pointCloud.CopyImageRGBA_SRGB();
+var imageSRGB = frame2D.ImageRGBA_SRGB();
 ```
 
-2D captures also produce 2D color images in linear RGB and sRGB color
-space.
+Then, we can save the 2D image in linear RGB or sRGB color space.
 
 ([go to
-source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/Capture/Capture.cs#L28))
+source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs#L50-L52))
 
 ``` sourceCode cs
-var imageRGBA = frame.Frame2D.ImageRGBA_SRGB();
+var imageFile = "ImageRGBA_linear.png";
+Console.WriteLine($"Saving 2D color image (Linear RGB) to file: {imageFile}");
+imageRGBA.Save(imageFile);
 .. tab-item:: sRGB
 ```
 
 ([go to
-source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs#L30))
+source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs#L68-L70))
 
 ``` sourceCode cs
-var imageSRGB = frame2D.ImageSRGB();
+var imageFile = "ImageRGBA_sRGB.png";
+Console.WriteLine($"Saving 2D color image (sRGB color space) to file: {imageFile}");
+imageSRGB.Save(imageFile);
 ```
 
-Then, we can save the 2D image in linear RGB or sRGB color space.
+We can get 2D color image directly from the point cloud. This image will
+have the same resolution as the point cloud and it will be in the sRGB
+color space.
 
-([go to
-source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/Capture/Capture.cs#L29-L31))
+([go to source]())
 
 ``` sourceCode cs
-var imageFile = "ImageRGB.png";
-Console.WriteLine("Saving 2D color image (sRGB color space) to file: " + imageFile);
-imageRGBA.Save(imageFile);
-.. tab-item:: sRGB
+var pointCloud = frame.PointCloud;
+var image2DInPointCloudResolution = pointCloud.CopyImageRGBA_SRGB();
 ```
 
-([go to
-source](https://github.com/zivid/zivid-csharp-samples/tree/master//source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs#L31-L33))
+We can get the 2D color image from `Frame2D`, which is part of the
+`Frame` object, obtained from `capture2D3D()`. This image will have the
+resolution given by the 2D settings inside the 2D3D settings.
+
+([go to source]())
 
 ``` sourceCode cs
-var imageFile = "ImageSRGB.png";
-Console.WriteLine("Saving 2D color image (sRGB color space) to file: " + imageFile);
-imageSRGB.Save(imageFile);
+var image2D = frame.Frame2D.ImageBGRA_SRGB();
 ```
 
 ## Multithreading

source/Camera/Basic/CaptureWithSettingsFromYML/CaptureWithSettingsFromYML.cs

@@ -1,70 +1,85 @@
 /*
-Capture images and point clouds, with or without color, from the Zivid camera with settings from YML file.
+Capture images and point clouds, with and without color, from the Zivid camera with settings from YML file.
+
+Choose whether to get the image in the linear RGB or the sRGB color space.
 
 The YML files for this sample can be found under the main Zivid sample instructions.
 */
 
 using System;
-using System.Collections.Generic;
 using Zivid.NET;
+using System.Collections.Generic;
 
 class Program
 {
-    static int Main()
+    static int Main(string[] args)
     {
         try
         {
-            var zivid = new Zivid.NET.Application();
+            if (Array.Exists(args, arg => arg == "-h" || arg == "--help"))
+            {
+                ShowHelp();
+                return 0;
+            }
+
+            var userOptions = ParseOptions(args);
 
+            var zivid = new Zivid.NET.Application();
             Console.WriteLine("Connecting to camera");
             var camera = zivid.ConnectCamera();
 
             Console.WriteLine("Loading settings from file");
-            var settingsFile = Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData)
-                               + "/Zivid/Settings/" + SettingsFolder(camera) + "/Settings01.yml";
+            if (string.IsNullOrEmpty(userOptions.SettingsPath))
+            {
+                userOptions.SettingsPath = Environment.GetFolderPath(Environment.SpecialFolder.CommonApplicationData)
+                    + "/Zivid/Settings/" + SettingsFolder(camera) + "/Settings01.yml";
+            }
+
+            string settingsFile = userOptions.SettingsPath;
             var settings = new Zivid.NET.Settings(settingsFile);
 
             Console.WriteLine("Capturing 2D frame");
             using (var frame2D = camera.Capture2D(settings))
             {
-                var imageSRGB = frame2D.ImageSRGB();
-                var imageFile = "ImageSRGB.png";
-                Console.WriteLine("Saving 2D color image (sRGB color space) to file: " + imageFile);
-                imageSRGB.Save(imageFile);
-
-                // More information about linear RGB and sRGB color spaces is available at:
-                // https://support.zivid.com/en/latest/reference-articles/color-spaces-and-output-formats.html#color-spaces
-                // To get linear RGB image, use the following line instead:
-                // var imageLinearRGB = frame2D.ImageRGBA();
-
                 var pixelRow = 100;
                 var pixelCol = 50;
 
-                Console.WriteLine("Extracting 2D pixel array");
-                var pixelArraySRGB = imageSRGB.ToArray();
-                Console.WriteLine("Height: {0}, Width: {1}", pixelArraySRGB.GetLength(0), pixelArraySRGB.GetLength(1));
-                Console.WriteLine("Color at pixel ({0},{1}):  R:{2}  G:{3}  B:{4}  A:{5}",
-                                  pixelRow,
-                                  pixelCol,
-                                  pixelArraySRGB[pixelRow, pixelCol].r,
-                                  pixelArraySRGB[pixelRow, pixelCol].g,
-                                  pixelArraySRGB[pixelRow, pixelCol].b,
-                                  pixelArraySRGB[pixelRow, pixelCol].a);
-
-                Console.WriteLine("Extracting 3D array of bytes");
-                var nativeArray = imageSRGB.ToByteArray();
-                Console.WriteLine("Height: {0}, Width: {1}, Channels: {2}",
-                                  nativeArray.GetLength(0),
-                                  nativeArray.GetLength(1),
-                                  nativeArray.GetLength(2));
-                Console.WriteLine("Color at pixel ({0},{1}):  R:{2}  G:{3}  B:{4}  A:{5}",
-                                  pixelRow,
-                                  pixelCol,
-                                  nativeArray[pixelRow, pixelCol, 0],
-                                  nativeArray[pixelRow, pixelCol, 1],
-                                  nativeArray[pixelRow, pixelCol, 2],
-                                  nativeArray[pixelRow, pixelCol, 3]);
-
+                if (userOptions.LinearRgb)
+                {
+                    var imageRGBA = frame2D.ImageRGBA();
+                    var imageFile = "ImageRGBA_linear.png";
+                    Console.WriteLine($"Saving 2D color image (Linear RGB) to file: {imageFile}");
+                    imageRGBA.Save(imageFile);
+
+                    Console.WriteLine("Extracting 2D pixel array");
+                    var pixelArrayRGBA = imageRGBA.ToArray();
+                    Console.WriteLine("Height: {0}, Width: {1}", pixelArrayRGBA.GetLength(0), pixelArrayRGBA.GetLength(1));
+                    Console.WriteLine("Color at pixel ({0},{1}):  R:{2}  G:{3}  B:{4}  A:{5}",
+                                      pixelRow,
+                                      pixelCol,
+                                      pixelArrayRGBA[pixelRow, pixelCol].r,
+                                      pixelArrayRGBA[pixelRow, pixelCol].g,
+                                      pixelArrayRGBA[pixelRow, pixelCol].b,
+                                      pixelArrayRGBA[pixelRow, pixelCol].a);
+                }
+                else
+                {
+                    var imageSRGB = frame2D.ImageRGBA_SRGB();
+                    var imageFile = "ImageRGBA_sRGB.png";
+                    Console.WriteLine($"Saving 2D color image (sRGB color space) to file: {imageFile}");
+                    imageSRGB.Save(imageFile);
+
+                    Console.WriteLine("Extracting 2D pixel array");
+                    var pixelArraySRGB = imageSRGB.ToArray();
+                    Console.WriteLine("Height: {0}, Width: {1}", pixelArraySRGB.GetLength(0), pixelArraySRGB.GetLength(1));
+                    Console.WriteLine("Color at pixel ({0},{1}):  R:{2}  G:{3}  B:{4}  A:{5}",
+                                      pixelRow,
+                                      pixelCol,
+                                      pixelArraySRGB[pixelRow, pixelCol].r,
+                                      pixelArraySRGB[pixelRow, pixelCol].g,
+                                      pixelArraySRGB[pixelRow, pixelCol].b,
+                                      pixelArraySRGB[pixelRow, pixelCol].a);
+                }
             }
 
             Console.WriteLine("Capturing 3D frame");
@@ -99,6 +114,26 @@ static int Main()
         return 0;
     }
 
+    static (string SettingsPath, bool LinearRgb) ParseOptions(string[] args)
+    {
+        string settingsPath = "";
+        bool linearRgb = false;
+
+        foreach (var arg in args)
+        {
+            if (arg.StartsWith("--settings-path="))
+            {
+                settingsPath = arg.Substring("--settings-path=".Length);
+            }
+            else if (arg.Equals("--linear-rgb"))
+            {
+                linearRgb = true;
+            }
+        }
+
+        return (settingsPath, linearRgb);
+    }
+
     static string SettingsFolder(Zivid.NET.Camera camera)
     {
         var model = camera.Info.Model;
@@ -112,7 +147,16 @@ static string SettingsFolder(Zivid.NET.Camera camera)
             case Zivid.NET.CameraInfo.ModelOption.Zivid2PlusMR130: return "zivid2Plus/R";
             case Zivid.NET.CameraInfo.ModelOption.Zivid2PlusMR60: return "zivid2Plus/R";
             case Zivid.NET.CameraInfo.ModelOption.Zivid2PlusLR110: return "zivid2Plus/R";
-            default: throw new System.InvalidOperationException("Unhandled enum value " + model.ToString());
+            default: throw new InvalidOperationException("Unhandled enum value " + model.ToString());
         }
     }
+
+    static void ShowHelp()
+    {
+        Console.WriteLine("Usage: CaptureWithSettingsFromYML.exe [options]");
+        Console.WriteLine("Options:");
+        Console.WriteLine("  --settings-path=<path>   Path to the camera settings YML file (default: based on camera model)");
+        Console.WriteLine("  --linear-rgb             Use linear RGB instead of sRGB");
+        Console.WriteLine("  -h, --help               Show this help message");
+    }
 }