Software Trigger Capture with the Basler pylon SDK (C# / .NET)

When working with industrial cameras such as Basler, you don’t always want to run the camera in free-run mode (continuous acquisition). There are many situations where you need to capture exactly when something meaningful happens, for example:

The moment a button on an experimental setup is pressed
When a temperature or voltage reaches a certain threshold
When an external event occurs in another device or system

In such cases, software-triggered acquisition is extremely useful.

In this article, we’ll look at how to perform software-trigger capture using the Basler pylon SDK in C#, and compare it against free-run / GrabOne() acquisitions using simple stopwatch-based timing.

✅ Environment

Item	Value
Camera	Basler acA2500-14gm
SDK	Basler pylon Camera Software Suite
Lang	C# / .NET 8.0 (Windows)

As in previous articles (for example: How to record camera settings alongside captured images (C# / .NET)), we extend the same BaslerCameraSample class and add software-trigger-related functions plus an example test.

🔧 Configuring the Software Trigger

In pylon, software trigger is configured by setting the trigger mode and trigger source as follows:

public bool SetSoftwareTrigger(bool enable)
{
    if(Camera == null)
        return false;
    if (enable)
    {
        // Set the trigger source to Software.
        var isTriggerSourceSet = SetPLCameraParameter(PLCamera.TriggerSource, PLCamera.TriggerSource.Software);
        // Check if trigger source was set successfully.
        if (!isTriggerSourceSet)
        {
            Console.WriteLine(“Failed to set software trigger source.”);
            return false;
        }
        // Enable trigger mode.
        return SetPLCameraParameter(PLCamera.TriggerMode, PLCamera.TriggerMode.On);
    }
    else
    {
        // Disable trigger mode (free-run).
        return SetPLCameraParameter(PLCamera.TriggerMode, PLCamera.TriggerMode.Off);
    }
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

public bool SetSoftwareTrigger(bool enable)

{

if(Camera == null)

return false;

if (enable)

{

// Set the trigger source to Software.

var isTriggerSourceSet = SetPLCameraParameter(PLCamera.TriggerSource, PLCamera.TriggerSource.Software);

// Check if trigger source was set successfully.

if (!isTriggerSourceSet)

{

Console.WriteLine(“Failed to set software trigger source.”);

return false;

}

// Enable trigger mode.

return SetPLCameraParameter(PLCamera.TriggerMode, PLCamera.TriggerMode.On);

}

else

{

// Disable trigger mode (free-run).

return SetPLCameraParameter(PLCamera.TriggerMode, PLCamera.TriggerMode.Off);

}

When you want to capture an image, you call ExecuteSoftwareTrigger() to fire the trigger and acquire a frame at that instant:

// Fire a software trigger to acquire a single frame.
public void ExecuteSoftwareTrigger(int timeoutMs = 5000)
{
    if (Camera?.WaitForFrameTriggerReady(timeoutMs, TimeoutHandling.ThrowException) == true)
    {
        Camera?.ExecuteSoftwareTrigger();
    }
}

1

2

3

4

5

6

7

8

// Fire a software trigger to acquire a single frame.

public void ExecuteSoftwareTrigger(int timeoutMs = 5000)

{

if (Camera?.WaitForFrameTriggerReady(timeoutMs, TimeoutHandling.ThrowException) == true)

{

Camera?.ExecuteSoftwareTrigger();

}

Before calling ExecuteSoftwareTrigger, you must start camera streaming with Camera.StreamGrabber.Start(). In other words, the camera must already be armed and grabbing when the trigger is executed.

🔁 Example: Using the Software Trigger

Here is one example of how to use the software trigger. There are many ways to structure this, but using the existing implementation from earlier articles, we follow this sequence:

Enable software trigger mode
Start streaming
Fire the software trigger
Wait for frame acquisition (via ImageGrabbed) and then stop streaming

Because there is a delay between firing the trigger and the ImageGrabbed event, we wait until the handler confirms that a frame was actually acquired before stopping streaming.

[TestMethod()]
public async Task ExecuteSoftwareTriggerTest()
{
    if (!_baslerCameraSample.IsConnected)
        _baslerCameraSample.Connect();

    // Enable software trigger mode.
    var isEnabled = _baslerCameraSample.SetSoftwareTrigger(true);
    Assert.IsTrue(isEnabled);

    // Start streaming.
    _baslerCameraSample.StartGrabbing();

    // Assume some event occurs 1000 ms from now.
    await Task.Delay(1000);
    // Measure elapsed time from the moment of the event.
    var startTime = DateTime.Now;

    // Fire the software trigger.
    _baslerCameraSample.ExecuteSoftwareTrigger();
    var elapsedTrigger = (DateTime.Now – startTime).TotalMilliseconds;
    // Example: Elapsed time(Trigger): 5.9921 ms
    Console.WriteLine($”Elapsed time(Trigger): {elapsedTrigger} ms”);
    Assert.IsTrue(elapsedTrigger <= 10, “Elapsed time should be less than 10 ms”);

    // It takes some time until the ImageGrabbed event runs after the trigger.
    // Use a CancellationToken so that we can cancel the wait when the frame is detected.
    try
    {
        var cts = new CancellationTokenSource();
        var waitTask = Task.Delay(1000, cts.Token);
        while (!waitTask.IsCompleted)
        {
            await Task.Delay(1);
            // Detect frame acquisition via the buffered image queue.
            if (_baslerCameraSample.BufferedImageQueue.Count > 0)
                cts.Cancel();
        }
        await waitTask;
        // If not canceled, no frame arrived within the time limit → treat as failure.
        Assert.Fail(“OnImageGrabed was not called within the expected time.”);
    }
    catch (TaskCanceledException)
    {
        // Expected: canceled by OnImageGrabed (frame arrival).
    }

    // Stop streaming after receiving the frame.
    _baslerCameraSample.StopGrabbing();

    // Dequeue the captured image, measure the time OnImageGrabed was called, and save the image.
    Assert.AreEqual(1, _baslerCameraSample.BufferedImageQueue.Count);
    _baslerCameraSample.BufferedImageQueue.TryDequeue(out var item);
    var elapsedOnImageGrabed = (item.Item1-startTime).TotalMilliseconds;
    // Example: Elapsed time(OnImageGrabed): 112.0971 ms
    Console.WriteLine($”Elapsed time(OnImageGrabed): {elapsedOnImageGrabed} ms”);
    var bitmap = BaslerCameraSample.ConvertGrabResultToBitmap(item.Item2);
    var fileName = $”TriggeredCapture_{DateTime.Now:yyyyMMdd_HHmmss}.bmp”;
    BaslerCameraSample.SaveBitmap(bitmap, fileName);
    Assert.IsTrue(File.Exists(fileName), $”File {fileName} should be created.”);
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

[TestMethod()]

public async Task ExecuteSoftwareTriggerTest()

{

if (!_baslerCameraSample.IsConnected)

_baslerCameraSample.Connect();

// Enable software trigger mode.

var isEnabled = _baslerCameraSample.SetSoftwareTrigger(true);

Assert.IsTrue(isEnabled);

// Start streaming.

_baslerCameraSample.StartGrabbing();

// Assume some event occurs 1000 ms from now.

await Task.Delay(1000);

// Measure elapsed time from the moment of the event.

var startTime = DateTime.Now;

// Fire the software trigger.

_baslerCameraSample.ExecuteSoftwareTrigger();

var elapsedTrigger = (DateTime.Now – startTime).TotalMilliseconds;

// Example: Elapsed time(Trigger): 5.9921 ms

Console.WriteLine($“Elapsed time(Trigger): {elapsedTrigger} ms”);

Assert.IsTrue(elapsedTrigger <= 10, “Elapsed time should be less than 10 ms”);

// It takes some time until the ImageGrabbed event runs after the trigger.

// Use a CancellationToken so that we can cancel the wait when the frame is detected.

try

{

var cts = new CancellationTokenSource();

var waitTask = Task.Delay(1000, cts.Token);

while (!waitTask.IsCompleted)

{

await Task.Delay(1);

// Detect frame acquisition via the buffered image queue.

if (_baslerCameraSample.BufferedImageQueue.Count > 0)

cts.Cancel();

}

await waitTask;

// If not canceled, no frame arrived within the time limit → treat as failure.

Assert.Fail(“OnImageGrabed was not called within the expected time.”);

}

catch (TaskCanceledException)

{

// Expected: canceled by OnImageGrabed (frame arrival).

}

// Stop streaming after receiving the frame.

_baslerCameraSample.StopGrabbing();

// Dequeue the captured image, measure the time OnImageGrabed was called, and save the image.

Assert.AreEqual(1, _baslerCameraSample.BufferedImageQueue.Count);

_baslerCameraSample.BufferedImageQueue.TryDequeue(out var item);

var elapsedOnImageGrabed = (item.Item1–startTime).TotalMilliseconds;

// Example: Elapsed time(OnImageGrabed): 112.0971 ms

Console.WriteLine($“Elapsed time(OnImageGrabed): {elapsedOnImageGrabed} ms”);

var bitmap = BaslerCameraSample.ConvertGrabResultToBitmap(item.Item2);

var fileName = $“TriggeredCapture_{DateTime.Now:yyyyMMdd_HHmmss}.bmp”;

BaslerCameraSample.SaveBitmap(bitmap, fileName);

Assert.IsTrue(File.Exists(fileName), $“File {fileName} should be created.”);

}

Here, BufferedImageQueue refers to the queue filled by the OnImageGrabbed event handler (as implemented in the earlier event-driven capture article).

⏱ Experiment: Software Trigger vs “Just call `GrabOne()`”

You might wonder:

“What’s the difference between using a software trigger and simply calling GrabOne() after an event occurs?”

To test this, we extend ExecuteSoftwareTriggerTest to also measure the time taken by a plain GrabOne() call and compare the two.

[TestMethod()]
public async Task ExecuteSoftwareTriggerTest()
{
    // ～～ previous code omitted for brevity ～～
    
    // Disable trigger mode.
    var isDisabled = _baslerCameraSample.SetSoftwareTrigger(false);
    Assert.IsTrue(isDisabled);

    // Measure how long it takes to grab a single frame with GrabOne().
    var grabSW = new Stopwatch();
    grabSW.Start();
    var grabbedImage = _baslerCameraSample.Snap();
    grabSW.Stop();
    var elapesedGrabOne = grabSW.ElapsedMilliseconds;
    // Example: Elapsed time(GrabOne): 193 ms
    Console.WriteLine($”Elapsed time(GrabOne): {elapesedGrabOne} ms”);

    // Waiting for a trigger while the camera is already streaming
    // can acquire an image faster than starting a full GrabOne() capture from scratch.
    // Also, with GrabOne() you don’t know exactly when the trigger (event) occurred,
    // whereas with a software trigger you can tightly associate the image with the trigger timing.
    Assert.IsTrue(elapsedOnImageGrabed < elapesedGrabOne);
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

[TestMethod()]

public async Task ExecuteSoftwareTriggerTest()

{

// ～～ previous code omitted for brevity ～～

// Disable trigger mode.

var isDisabled = _baslerCameraSample.SetSoftwareTrigger(false);

Assert.IsTrue(isDisabled);

// Measure how long it takes to grab a single frame with GrabOne().

var grabSW = new Stopwatch();

grabSW.Start();

var grabbedImage = _baslerCameraSample.Snap();

grabSW.Stop();

var elapesedGrabOne = grabSW.ElapsedMilliseconds;

// Example: Elapsed time(GrabOne): 193 ms

Console.WriteLine($“Elapsed time(GrabOne): {elapesedGrabOne} ms”);

// Waiting for a trigger while the camera is already streaming

// can acquire an image faster than starting a full GrabOne() capture from scratch.

// Also, with GrabOne() you don’t know exactly when the trigger (event) occurred,

// whereas with a software trigger you can tightly associate the image with the trigger timing.

Assert.IsTrue(elapsedOnImageGrabed < elapesedGrabOne);

}

📊 Results

On my test environment (Basler acA2500-14gm, GigE, AMD Ryzen 9, Windows), software-trigger capture achieved a faster time-to-image than a plain GrabOne().

This is likely because the camera is already streaming and armed, so the sensor doesn’t need to be restarted for each frame.

Summary:

Mode	Acquisition Time	Characteristics
Software trigger	~112 ms	Faster image acquisition; precise knowledge of when the trigger occurred
GrabOne	~193 ms	Simple to implement; trigger timing is not strictly known

📝 Summary

Software trigger is ideal when you want to capture semantically meaningful moments:
- e.g., synchronization with experimental data, test equipment, or external signals
Compared to GrabOne():
- Software trigger can reduce the delay between event and image acquisition
- It also lets you know exactly when the trigger was fired

In the next article, we’ll look at how to display camera images in WPF, using the same design that I’m adopting in my in-development camera configuration management tool.

Author: @MilleVision

🛠 Full Sample Code Project(With Japanese comment)

All sample code introduced in this Qiita series is available as a C# project with unit tests on BOOTH:

Includes unit tests for easy verification and learning
Will be updated alongside new articles

👉 Product page

2025-12-12

Reproducing Camera Conditions: Saving and Loading Basler Settings as PFS Files

Basler pylon SDK × C#

When you need to reproduce a specific capture condition or quickly switch between multiple setups, being able to save and load Basler camera settings as PFS files is extremely useful.

In this article, we’ll look at how to save and restore camera settings in .pfs format using the Basler pylon SDK.

What Is the PFS Format?

A PFS file (pylon Feature Stream file) is Basler’s configuration format for saving and loading camera settings.

✅ Typical Use Cases

Backup of camera settings
- Decide on a stable configuration once → save it → reuse it after reboot or on another PC.
Sharing experiment conditions
- Distribute settings so everyone in a lab or production line captures under the same conditions.
Loading settings from your software
- Call camera.Parameters.Load("config.pfs") to instantly apply a predefined setup (shown later).

✅ Environment

Item	Value
Camera	Basler acA2500-14gm
SDK	Basler pylon Camera Software Suite
Language	C# / .NET 8
File Format	`.pfs` (pylon Feature Set / Feature Stream)

📝 Saving Camera Settings (Save)

As in previous articles, we’ll extend the same BaslerCameraSample class introduced in:

How to Display and Save Basler Camera Images with OpenCV
How to Capture a Single Image Using the Basler pylon SDK in C#

To save settings, we can use the Camera.Parameters.Save() method. The example below saves the CameraDevice settings. The ParameterPath argument can be either a direct string or one of the predefined properties of the ParameterPath class.

using Basler.Pylon;

namespace BaslerSamples
{
    public static class BaslerCameraSample
    {
        public void SaveCameraDeviceParameters(string filePath)
        {
            if (Camera == null || !IsConnected)
                throw new InvalidOperationException(“Camera is not connected.”);

            if (string.IsNullOrWhiteSpace(filePath))
                throw new ArgumentException(“File path cannot be null or empty.”, nameof(filePath));

            Camera.Parameters.Save(filePath, ParameterPath.CameraDevice);
            Console.WriteLine($”Camera settings saved to {filePath}”);
        }
    }
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

using Basler.Pylon;

namespace BaslerSamples

{

public static class BaslerCameraSample

{

public void SaveCameraDeviceParameters(string filePath)

{

if (Camera == null || !IsConnected)

throw new InvalidOperationException(“Camera is not connected.”);

if (string.IsNullOrWhiteSpace(filePath))

throw new ArgumentException(“File path cannot be null or empty.”, nameof(filePath));

Camera.Parameters.Save(filePath, ParameterPath.CameraDevice);

Console.WriteLine($“Camera settings saved to {filePath}”);

}

In many practical scenarios, saving just CameraDevice is sufficient. However, if you want to dump multiple parameter groups at once, you can iterate over all string properties of ParameterPath via reflection.

Even though we check Camera.Parameters.Contains(value) before calling Save(), some properties may still cause Save() to throw an ArgumentException due to model differences or unsupported paths. In that case we catch and skip them.

Note: Relying on exceptions as control flow is not ideal; if you know of a cleaner approach, feel free to adapt this logic.

public void SaveAllParameters(string directory)
{
    var t = typeof(ParameterPath);

    var stringProps = t
        .GetProperties(BindingFlags.Public | BindingFlags.Static)
        .Where(p => p.PropertyType == typeof(string));

    foreach (var prop in stringProps)
    {
        // Static property, so the first argument of GetValue should be null.
        string value = (string)(prop.GetValue(null) ?? string.Empty);
        if (!string.IsNullOrEmpty(value) && Camera.Parameters.Contains(value))
        {
            string filePath = System.IO.Path.Combine(directory, $”{value}.pfs”);
            try
            {
                Camera.Parameters.Save(filePath, value);
            }
            catch (ArgumentException)
            {
                // Skip parameters that cannot be saved by this camera.
                continue;
            }
            Console.WriteLine($”Saved {value} to {filePath}”);
        }
    }
    Console.WriteLine($”Camera settings saved to {directory}”);
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

public void SaveAllParameters(string directory)

{

var t = typeof(ParameterPath);

var stringProps = t

.GetProperties(BindingFlags.Public | BindingFlags.Static)

.Where(p => p.PropertyType == typeof(string));

foreach (var prop in stringProps)

{

// Static property, so the first argument of GetValue should be null.

string value = (string)(prop.GetValue(null) ?? string.Empty);

if (!string.IsNullOrEmpty(value) && Camera.Parameters.Contains(value))

{

string filePath = System.IO.Path.Combine(directory, $“{value}.pfs”);

try

{

Camera.Parameters.Save(filePath, value);

}

catch (ArgumentException)

{

// Skip parameters that cannot be saved by this camera.

continue;

}

Console.WriteLine($“Saved {value} to {filePath}”);

}

Console.WriteLine($“Camera settings saved to {directory}”);

}

📂 Example of a Saved PFS File

If you open a .pfs file in a text editor, you can see that the configuration values are stored in a tab-separated (TSV) format.

Most of the important parameters are grouped under CameraDevice, so in many cases saving just that group is enough.

ExposureMode	Timed       // Exposure mode
ExposureAuto	Off         // Auto exposure off (manual control)
ExposureTimeRaw	35000       // Unit: µs
AcquisitionFrameRateEnable	1 // Enable frame rate control
AcquisitionFrameRateAbs	30.0003 // Frame rate setting

1

2

3

4

5

6

ExposureMode Timed // Exposure mode

ExposureAuto Off // Auto exposure off (manual control)

ExposureTimeRaw 35000 // Unit: µs

AcquisitionFrameRateEnable 1 // Enable frame rate control

AcquisitionFrameRateAbs 30.0003 // Frame rate setting

📥 Loading Settings (Load)

Next, let’s load a previously saved .pfs file back into the camera.

public bool LoadCameraDeviceParameters(string filePath)
{
    if (Camera == null || !IsConnected)
        throw new InvalidOperationException(“Camera is not connected.”);

    if (string.IsNullOrWhiteSpace(filePath))
        throw new ArgumentException(“File path cannot be null or empty.”, nameof(filePath));

    try
    {
        Camera.Parameters.Load(filePath, ParameterPath.CameraDevice);
        Console.WriteLine($”Camera settings loaded from {filePath}”);
        return true;
    }
    catch (Exception ex)
    {
        Console.WriteLine($”Failed to load camera settings: {ex.Message}”);
        return false;
    }
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

public bool LoadCameraDeviceParameters(string filePath)

{

if (Camera == null || !IsConnected)

throw new InvalidOperationException(“Camera is not connected.”);

if (string.IsNullOrWhiteSpace(filePath))

throw new ArgumentException(“File path cannot be null or empty.”, nameof(filePath));

try

{

Camera.Parameters.Load(filePath, ParameterPath.CameraDevice);

Console.WriteLine($“Camera settings loaded from {filePath}”);

return true;

}

catch (Exception ex)

{

Console.WriteLine($“Failed to load camera settings: {ex.Message}”);

return false;

}

Example: Save & Load Round Trip

The following test changes the frame rate, saves the settings, then loads them back and verifies that the value was restored.

[TestMethod()]
public void LoadCameraDeviceSettingsTest()
{
    if (!_baslerCameraSample.IsConnected)
        _baslerCameraSample.Connect();

    // Change frame rate as an example.
    _baslerCameraSample.EnableFrameRate(true);
    _baslerCameraSample.SetFrameRate(10); // 10 fps

    // Save current settings.
    _baslerCameraSample.SaveCameraDeviceParameters(“LoadCameraDeviceSettingsTest.pfs”);
    _baslerCameraSample.SetFrameRate(15); // Change to 15 fps

    _baslerCameraSample.LoadCameraDeviceParameters(“LoadCameraDeviceSettingsTest.pfs”);
    var loadedFrameRate = _baslerCameraSample.GetFrameRate();
    Assert.AreEqual(10, loadedFrameRate, “Loaded frame rate should be 10 fps.”);
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

[TestMethod()]

public void LoadCameraDeviceSettingsTest()

{

if (!_baslerCameraSample.IsConnected)

_baslerCameraSample.Connect();

// Change frame rate as an example.

_baslerCameraSample.EnableFrameRate(true);

_baslerCameraSample.SetFrameRate(10); // 10 fps

// Save current settings.

_baslerCameraSample.SaveCameraDeviceParameters(“LoadCameraDeviceSettingsTest.pfs”);

_baslerCameraSample.SetFrameRate(15); // Change to 15 fps

_baslerCameraSample.LoadCameraDeviceParameters(“LoadCameraDeviceSettingsTest.pfs”);

var loadedFrameRate = _baslerCameraSample.GetFrameRate();

Assert.AreEqual(10, loadedFrameRate, “Loaded frame rate should be 10 fps.”);

}

After loading, the camera’s frame rate returns to 10 fps, confirming that the PFS file was applied correctly.

⚠️ Notes & Caveats

Point	Details
What gets saved	Only parameters that are exposed as user-accessible by the camera
Trigger & device-specific settings	Some hardware-dependent features may be excluded
Applying PFS to another camera	Prefer using the same model or a model with compatible features

✅ Summary

Using Camera.Parameters.Save() / Load() you can easily reproduce capture conditions.
.pfs files are essentially TSV-based configuration files.
Very useful for:
- Backing up camera setups
- Sharing experiment conditions
- Managing multiple capture profiles

Coming Up Next

In the next article, we’ll look at how to log metadata such as exposure, gain, and ROI together with captured images.

I’m also working on a GUI tool to conveniently view and edit Basler camera settings; that will be introduced in a future post.

Author: @MilleVision

2025-12-11

Displaying and Saving Basler Camera Images with OpenCV

pylon SDK × OpenCvSharp / C#

When working with Basler cameras, converting captured images into OpenCV’s Mat format gives you access to a wide range of image processing algorithms.

In this article, we’ll take a GrabResult from the Basler pylon SDK, convert it to an OpenCV Mat, and then:

Display it in real time using Cv2.ImShow
Save it as an image file using Cv2.ImWrite

✅ Environment

Item	Value
Camera	Basler acA2500-14gm
SDK	Basler pylon Camera Software Suite
Pixel Format	Mono8 (8-bit grayscale)
OpenCV Wrapper	OpenCvSharp4.Windows (via NuGet)

🎯 Goal: Convert `GrabResult` → `Mat` → Display & Save

Conceptual flow:

[GrabResult] → [byte[]] → [Mat] → [ImShow / ImWrite]

1 2	[GrabResult] → [byte[]] → [Mat] → [ImShow / ImWrite]

🔧 Converting `GrabResult` to `Mat`

We’ll use PixelDataConverter.Convert() to extract pixel data from IGrabResult into a byte[], and then wrap that buffer as an OpenCV Mat.

A convenient way is to implement an extension method on IGrabResult:

// IGrabResultExtensions.cs
using System;
using System.Runtime.InteropServices;
using Basler.Pylon;
using OpenCvSharp;

namespace BaslerSamples
{
    /// <summary>
    /// Extension methods for converting Basler IGrabResult to OpenCV Mat.
    /// </summary>
    public static class IGrabResultExtensions
    {
        /// <summary>
        /// Converts a successful grab result to an OpenCV Mat (Mono8 → CV_8UC1).
        /// </summary>
        /// <param name=”result”>Grabbed image result from the Basler camera.</param>
        /// <returns>Mat instance that wraps the image data.</returns>
        /// <exception cref=”InvalidOperationException”>Thrown if the grab did not succeed.</exception>
        public static Mat ToMat(this IGrabResult result)
        {
            if (!result.GrabSucceeded)
                throw new InvalidOperationException(“Grab failed.”);

            var converter = new PixelDataConverter
            {
                OutputPixelFormat = PixelType.Mono8
            };

            int width = result.Width;
            int height = result.Height;
            byte[] buffer = new byte[width * height];

            converter.Convert(buffer, result);

            // Convert to OpenCV Mat (Gray8 → CV_8UC1)
            GCHandle handle = GCHandle.Alloc(buffer, GCHandleType.Pinned);
            try
            {
                IntPtr ptr = handle.AddrOfPinnedObject();
                // Mat.FromPixelData is an OpenCvSharp helper that creates a Mat from raw pixel data.
                return Mat.FromPixelData(height, width, MatType.CV_8UC1, ptr);
            }
            finally
            {
                handle.Free();
            }
        }
    }
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

// IGrabResultExtensions.cs

using System;

using System.Runtime.InteropServices;

using Basler.Pylon;

using OpenCvSharp;

namespace BaslerSamples

{

/// <summary>

/// Extension methods for converting Basler IGrabResult to OpenCV Mat.

/// </summary>

public static class IGrabResultExtensions

{

/// <summary>

/// Converts a successful grab result to an OpenCV Mat (Mono8 → CV_8UC1).

/// </summary>

/// <param name=”result”>Grabbed image result from the Basler camera.</param>

/// <returns>Mat instance that wraps the image data.</returns>

/// <exception cref=”InvalidOperationException”>Thrown if the grab did not succeed.</exception>

public static Mat ToMat(this IGrabResult result)

{

if (!result.GrabSucceeded)

throw new InvalidOperationException(“Grab failed.”);

var converter = new PixelDataConverter

{

OutputPixelFormat = PixelType.Mono8

};

int width = result.Width;

int height = result.Height;

byte[] buffer = new byte[width * height];

converter.Convert(buffer, result);

// Convert to OpenCV Mat (Gray8 → CV_8UC1)

GCHandle handle = GCHandle.Alloc(buffer, GCHandleType.Pinned);

try

{

IntPtr ptr = handle.AddrOfPinnedObject();

// Mat.FromPixelData is an OpenCvSharp helper that creates a Mat from raw pixel data.

return Mat.FromPixelData(height, width, MatType.CV_8UC1, ptr);

}

finally

{

handle.Free();

}

💡 Note: For color formats (e.g., BGR8, RGB8), you’ll need to adjust OutputPixelFormat and MatType (e.g., CV_8UC3) accordingly.

🖼 Real-Time Display with `Cv2.ImShow`

We now extend the BaslerCameraSample class (introduced in the previous article on event-driven capture) to display buffered images using OpenCV.

Here, we assume that _bufferedImageQueue is a queue of (DateTime, IGrabResult) that the ImageGrabbed event handler enqueues into.

using System;
using System.Collections.Concurrent;
using System.Threading;
using System.Threading.Tasks;
using OpenCvSharp;

public partial class BaslerCameraSample
{
    /// <summary>
    /// Queue for buffering grabbed images for OpenCV display.
    /// </summary>
    private readonly ConcurrentQueue<(DateTime Timestamp, IGrabResult Result)> _bufferedImageQueue
        = new();

    /// <summary>
    /// Displays buffered images using OpenCV’s ImShow until cancellation is requested
    /// and the buffer is drained.
    /// </summary>
    /// <param name=”cts”>Cancellation token source for stopping the display loop.</param>
    public async Task ShowBufferedImages(CancellationTokenSource cts)
    {
        // Loop while capturing is active or there are still items in the buffer.
        while (!cts.IsCancellationRequested && (IsGrabbing || _bufferedImageQueue.Count > 0))
        {
            if (_bufferedImageQueue.TryDequeue(out var item))
            {
                using (Mat mat = item.Result.ToMat())
                {
                    Cv2.ImShow(“Camera”, mat);
                    // WaitKey(0) blocks, so use a short delay (1 ms) for realtime display.
                    Cv2.WaitKey(1);
                }
            }
            else
            {
                // Avoid busy-waiting when the queue is temporarily empty.
                await Task.Delay(1);
            }
        }

        // Optionally clear the queue here.
        _bufferedImageQueue.Clear();
    }
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

using System;

using System.Collections.Concurrent;

using System.Threading;

using System.Threading.Tasks;

using OpenCvSharp;

public partial class BaslerCameraSample

{

/// <summary>

/// Queue for buffering grabbed images for OpenCV display.

/// </summary>

private readonly ConcurrentQueue<(DateTime Timestamp, IGrabResult Result)> _bufferedImageQueue

= new();

/// <summary>

/// Displays buffered images using OpenCV’s ImShow until cancellation is requested

/// and the buffer is drained.

/// </summary>

/// <param name=”cts”>Cancellation token source for stopping the display loop.</param>

public async Task ShowBufferedImages(CancellationTokenSource cts)

{

// Loop while capturing is active or there are still items in the buffer.

while (!cts.IsCancellationRequested && (IsGrabbing || _bufferedImageQueue.Count > 0))

{

if (_bufferedImageQueue.TryDequeue(out var item))

{

using (Mat mat = item.Result.ToMat())

{

Cv2.ImShow(“Camera”, mat);

// WaitKey(0) blocks, so use a short delay (1 ms) for realtime display.

Cv2.WaitKey(1);

}

else

{

// Avoid busy-waiting when the queue is temporarily empty.

await Task.Delay(1);

}

// Optionally clear the queue here.

_bufferedImageQueue.Clear();

}

Example Test: Live Display for 10 Seconds

/// <summary>
/// Tests event-driven grabbing combined with OpenCV realtime display.
/// </summary>
[TestMethod]
public async Task ShowBufferedImagesTest()
{
    if (!_baslerCameraSample.IsConnected)
        _baslerCameraSample.Connect();

    Task? showTask = null;
    var cts = new CancellationTokenSource();

    try
    {
        _baslerCameraSample.StartGrabbing();
        Assert.IsTrue(_baslerCameraSample.IsGrabbing,
            “Camera should be grabbing after StartGrabbing is called.”);

        // Start OpenCV display loop.
        showTask = _baslerCameraSample.ShowBufferedImages(cts);

        // Display camera feed for 10 seconds.
        await Task.Delay(10000);
    }
    catch (InvalidOperationException ex)
    {
        Assert.Fail($”StartGrabbing failed: {ex.Message}”);
    }
    finally
    {
        // Stop grabbing and request display loop to end.
        _baslerCameraSample.StopGrabbing();
        Assert.IsFalse(_baslerCameraSample.IsGrabbing,
            “Camera should not be grabbing after StopGrabbing is called.”);

        cts.Cancel();
        if (showTask is not null)
            await showTask;
    }
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

/// <summary>

/// Tests event-driven grabbing combined with OpenCV realtime display.

/// </summary>

[TestMethod]

public async Task ShowBufferedImagesTest()

{

if (!_baslerCameraSample.IsConnected)

_baslerCameraSample.Connect();

Task? showTask = null;

var cts = new CancellationTokenSource();

try

{

_baslerCameraSample.StartGrabbing();

Assert.IsTrue(_baslerCameraSample.IsGrabbing,

“Camera should be grabbing after StartGrabbing is called.”);

// Start OpenCV display loop.

showTask = _baslerCameraSample.ShowBufferedImages(cts);

// Display camera feed for 10 seconds.

await Task.Delay(10000);

}

catch (InvalidOperationException ex)

{

Assert.Fail($“StartGrabbing failed: {ex.Message}”);

}

finally

{

// Stop grabbing and request display loop to end.

_baslerCameraSample.StopGrabbing();

Assert.IsFalse(_baslerCameraSample.IsGrabbing,

“Camera should not be grabbing after StopGrabbing is called.”);

cts.Cancel();

if (showTask is not null)

await showTask;

}

Running this test opens an OpenCV window named “Camera” that shows the live feed from your Basler camera.

💾 Saving `Mat` with `ImWrite`

To save a Mat to disk, use ImWrite(). The following example:

Captures one frame using Snap()
Converts it to Mat
Saves the image
Applies a simple threshold operation and saves again
Also saves via BitmapSource for comparison

ImShowTest

/// <summary>
/// Captures a single frame, converts it to Mat, saves it, and
/// applies a binary threshold for comparison.
/// </summary>
[TestMethod]
public void SnapAndSaveMatTest()
{
    if (!_baslerCameraSample.IsConnected)
        _baslerCameraSample.Connect();

    // Capture one frame
    using var result = _baslerCameraSample.Snap(1000);
    using (var mat = result.ToMat())
    {
        Assert.IsNotNull(mat);

        // Save the original image using OpenCV
        mat.ImWrite(“SnapAndSaveMatTest_Mat.bmp”);

        // Apply simple thresholding
        Cv2.Threshold(mat, mat, 128, 255, ThresholdTypes.Binary);
        mat.ImWrite(“SnapAndSaveMatTest_Mat_Thresholded.bmp”);

        Assert.IsTrue(System.IO.File.Exists(“SnapAndSaveMatTest_Mat.bmp”));
    }

    // Also save using BitmapSource for comparison
    var bitmap = _baslerCameraSample.ConvertGrabResultToBitmap(result);
    BaslerCameraSample.SaveBitmap(bitmap, “SnapAndSaveMatTest_Bitmap.bmp”);

    Assert.IsNotNull(result);
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

/// <summary>

/// Captures a single frame, converts it to Mat, saves it, and

/// applies a binary threshold for comparison.

/// </summary>

[TestMethod]

public void SnapAndSaveMatTest()

{

if (!_baslerCameraSample.IsConnected)

_baslerCameraSample.Connect();

// Capture one frame

using var result = _baslerCameraSample.Snap(1000);

using (var mat = result.ToMat())

{

Assert.IsNotNull(mat);

// Save the original image using OpenCV

mat.ImWrite(“SnapAndSaveMatTest_Mat.bmp”);

// Apply simple thresholding

Cv2.Threshold(mat, mat, 128, 255, ThresholdTypes.Binary);

mat.ImWrite(“SnapAndSaveMatTest_Mat_Thresholded.bmp”);

Assert.IsTrue(System.IO.File.Exists(“SnapAndSaveMatTest_Mat.bmp”));

}

// Also save using BitmapSource for comparison

var bitmap = _baslerCameraSample.ConvertGrabResultToBitmap(result);

BaslerCameraSample.SaveBitmap(bitmap, “SnapAndSaveMatTest_Bitmap.bmp”);

Assert.IsNotNull(result);

}

This creates three files:

SnapAndSaveMatTest_Bitmap.bmp — saved from BitmapSource
SnapAndSaveMatTest_Mat.bmp — saved from OpenCV Mat
SnapAndSaveMatTest_Mat_Thresholded.bmp — thresholded version

Comparing (1) and (2) confirms that both pipelines produce the same image.

BitmapSource	Mat	Mat(Binary)

📌 Tips & Common Pitfalls

Point	Notes
Pixel format	For color (`BGR8`, `RGB8`), use `MatType.CV_8UC3` and correct channel order
Nothing shows in `ImShow`	You must call `Cv2.WaitKey()`; otherwise the window won’t update
OpenCvSharp packages	Install both `OpenCvSharp4` and `OpenCvSharp4.runtime.windows` via NuGet
Performance considerations	Pinning buffers is fast, but for very high rates you may want to profile allocations

✅ Summary

You can convert Basler pylon GrabResult to an OpenCV Mat via PixelDataConverter and a byte[] buffer.
Cv2.ImShow enables simple live viewing; Cv2.ImWrite lets you save images directly from Mat.
Once in Mat form, you can apply the full power of OpenCV: filtering, edge detection, feature extraction, etc.

Author: @MilleVision

2025-12-10

Stabilizing Basler Camera Acquisition with Event-Driven Capture and Async Saving (C# / pylon SDK)

In previous articles, we covered burst capture (continuous acquisition) and performance tuning using ROI.

As a follow-up, this article explains how to make your acquisition loop more robust by combining event-driven image grabbing with asynchronous save processing.

✅ Why Event-Driven Acquisition Helps

Key characteristics:

Your handler is called only when a frame arrives
It integrates cleanly with UI frameworks like WPF

For single-frame capture, you can simply use GrabOne(). However, for GUI applications (live previews, start/stop capture buttons, etc.), using the ImageGrabbed event often results in a cleaner design and more responsive UI.

🔧 Minimal Event-Based Implementation

We will extend the same BaslerCameraSample class used in previous articles:

ROI article: Using ROI to Boost Burst Capture Performance
Single-frame capture article: How to Capture a Single Image with Basler pylon SDK in C#

First, we register an ImageGrabbed event handler and start streaming.

/// <summary>
/// Starts continuous image acquisition until StopGrabbing is called.
/// Each time an image is grabbed, the OnImageGrabbed event handler is invoked.
/// </summary>
public void StartGrabbing()
{
    if (Camera == null || !IsConnected)
        throw new InvalidOperationException(“Camera is not connected.”);

    if (IsGrabbing)
        throw new InvalidOperationException(“Camera is already grabbing.”);

    Camera.StreamGrabber!.ImageGrabbed += OnImageGrabbed;
    // Set acquisition mode to continuous
    SetPLCameraParameter(PLCamera.AcquisitionMode, PLCamera.AcquisitionMode.Continuous);
    Camera.StreamGrabber.Start(GrabStrategy.OneByOne, GrabLoop.ProvidedByStreamGrabber);
}

/// <summary>
/// Event handler called whenever an image is grabbed.
/// Converts the image to BitmapSource and saves it with a timestamp-based file name.
/// </summary>
void OnImageGrabbed(object? sender, ImageGrabbedEventArgs e)
{
    using IGrabResult result = e.GrabResult.Clone();
    Console.WriteLine($”Image grabbed successfully: {result.Timestamp} ms”);
    if (result.GrabSucceeded)
    {
        var bmp = ConvertGrabResultToBitmap(result);
        string filename = $”frame_{DateTime.Now:HHmmss_fff}.bmp”;
        SaveBitmap(bmp, filename);
    }
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

/// <summary>

/// Starts continuous image acquisition until StopGrabbing is called.

/// Each time an image is grabbed, the OnImageGrabbed event handler is invoked.

/// </summary>

public void StartGrabbing()

{

if (Camera == null || !IsConnected)

throw new InvalidOperationException(“Camera is not connected.”);

if (IsGrabbing)

throw new InvalidOperationException(“Camera is already grabbing.”);

Camera.StreamGrabber!.ImageGrabbed += OnImageGrabbed;

// Set acquisition mode to continuous

SetPLCameraParameter(PLCamera.AcquisitionMode, PLCamera.AcquisitionMode.Continuous);

Camera.StreamGrabber.Start(GrabStrategy.OneByOne, GrabLoop.ProvidedByStreamGrabber);

}

/// <summary>

/// Event handler called whenever an image is grabbed.

/// Converts the image to BitmapSource and saves it with a timestamp-based file name.

/// </summary>

void OnImageGrabbed(object? sender, ImageGrabbedEventArgs e)

{

using IGrabResult result = e.GrabResult.Clone();

Console.WriteLine($“Image grabbed successfully: {result.Timestamp} ms”);

if (result.GrabSucceeded)

{

var bmp = ConvertGrabResultToBitmap(result);

string filename = $“frame_{DateTime.Now:HHmmss_fff}.bmp”;

SaveBitmap(bmp, filename);

}

It’s convenient to expose an IsGrabbing property on BaslerCameraSample:

/// <summary>
/// Indicates whether the camera is currently grabbing images.
/// </summary>
public bool IsGrabbing => Camera?.StreamGrabber?.IsGrabbing ?? false;

1

2

3

4

/// <summary>

/// Indicates whether the camera is currently grabbing images.

/// </summary>

public bool IsGrabbing => Camera?.StreamGrabber?.IsGrabbing ?? false;

To stop continuous acquisition, detach the event handler and stop the stream grabber:

/// <summary>
/// Stops continuous image acquisition and removes the event handler.
/// </summary>
public void StopGrabbing()
{
    if (Camera == null || !IsConnected)
        throw new InvalidOperationException(“Camera is not connected.”);

    if (!IsGrabbing)
        throw new InvalidOperationException(“Camera is not grabbing.”);

    Camera.StreamGrabber!.ImageGrabbed -= OnImageGrabbed;
    Camera.StreamGrabber.Stop();
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

/// <summary>

/// Stops continuous image acquisition and removes the event handler.

/// </summary>

public void StopGrabbing()

{

if (Camera == null || !IsConnected)

throw new InvalidOperationException(“Camera is not connected.”);

if (!IsGrabbing)

throw new InvalidOperationException(“Camera is not grabbing.”);

Camera.StreamGrabber!.ImageGrabbed -= OnImageGrabbed;

Camera.StreamGrabber.Stop();

}

Whether you attach/detach the event handler every time depends on your application design. For simple apps, you might register the handler once (e.g., in the constructor) and keep it for the lifetime of the object.

Example: 1 Second of Continuous Capture

[TestMethod()]
public async Task StartGrabbingTest()
{
    if (!_baslerCameraSample.IsConnected)
        _baslerCameraSample.Connect();

    try
    {
        _baslerCameraSample.StartGrabbing();
        Assert.IsTrue(_baslerCameraSample.IsGrabbing,
            “Camera should be grabbing after StartGrabbing is called.”);

        await Task.Delay(1000); // Capture for 1 second
    }
    catch (InvalidOperationException ex)
    {
        Assert.Fail($”StartGrabbing failed: {ex.Message}”);
    }
    finally
    {
        _baslerCameraSample.StopGrabbing();
        Assert.IsFalse(_baslerCameraSample.IsGrabbing,
            “Camera should not be grabbing after StopGrabbing is called.”);
    }
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

[TestMethod()]

public async Task StartGrabbingTest()

{

if (!_baslerCameraSample.IsConnected)

_baslerCameraSample.Connect();

try

{

_baslerCameraSample.StartGrabbing();

Assert.IsTrue(_baslerCameraSample.IsGrabbing,

“Camera should be grabbing after StartGrabbing is called.”);

await Task.Delay(1000); // Capture for 1 second

}

catch (InvalidOperationException ex)

{

Assert.Fail($“StartGrabbing failed: {ex.Message}”);

}

finally

{

_baslerCameraSample.StopGrabbing();

Assert.IsFalse(_baslerCameraSample.IsGrabbing,

“Camera should not be grabbing after StopGrabbing is called.”);

}

⚠️ Problem: Saving Overhead Can Stall the Pipeline

Depending on your PC and image size, saving each image may take several to tens of milliseconds. At higher frame rates, a simple event handler that saves directly inside ImageGrabbed may not keep up, causing:

Increased latency
Dropped frames
Unstable frame intervals

🧭 Solution: Buffer with `ConcurrentQueue` and Save on a Separate Thread

Overall flow:

[Basler SDK]
     ↓
[OnImageGrabbed event]
     ↓
[Enqueue into ConcurrentQueue]
     ↓
[Background task dequeues and saves frames]

1

2

3

4

5

6

7

8

[Basler SDK]

↓

[OnImageGrabbed event]

↓

[Enqueue into ConcurrentQueue]

↓

[Background task dequeues and saves frames]

First, modify OnImageGrabbed to push cloned results into a queue instead of saving immediately.

/// <summary>
/// Queue used to buffer grabbed images for asynchronous processing.
/// Each ImageGrabbed event enqueues one cloned grab result with a timestamp.
/// </summary>
readonly ConcurrentQueue<(DateTime Timestamp, IGrabResult Result)> _bufferedImageQueue = new();

/// <summary>
/// Event handler called whenever an image is grabbed.
/// Instead of saving immediately, we enqueue a cloned IGrabResult.
/// </summary>
void OnImageGrabbed(object? sender, ImageGrabbedEventArgs e)
{
    IGrabResult result = e.GrabResult.Clone();
    if (result.GrabSucceeded)
        _bufferedImageQueue.Enqueue((DateTime.Now, result));
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

/// <summary>

/// Queue used to buffer grabbed images for asynchronous processing.

/// Each ImageGrabbed event enqueues one cloned grab result with a timestamp.

/// </summary>

readonly ConcurrentQueue<(DateTime Timestamp, IGrabResult Result)> _bufferedImageQueue = new();

/// <summary>

/// Event handler called whenever an image is grabbed.

/// Instead of saving immediately, we enqueue a cloned IGrabResult.

/// </summary>

void OnImageGrabbed(object? sender, ImageGrabbedEventArgs e)

{

IGrabResult result = e.GrabResult.Clone();

if (result.GrabSucceeded)

_bufferedImageQueue.Enqueue((DateTime.Now, result));

}

Next, run a separate asynchronous loop that dequeues items and saves them:

/// <summary>
/// Asynchronously saves buffered images until cancellation is requested
/// and the queue is drained. Intended to run on a background task.
/// </summary>
public async Task SaveBufferedImages(CancellationTokenSource cts)
{
    // Loop while grabbing is active or there are still items in the queue
    while (!cts.IsCancellationRequested && (IsGrabbing || _bufferedImageQueue.Count > 0))
    {
        if (_bufferedImageQueue.TryDequeue(out var item))
        {
            var bmp = ConvertGrabResultToBitmap(item.Result);
            SaveBitmap(bmp, $”frame_{item.Timestamp:HHmmss_fff}.bmp”);
            item.Result.Dispose();
        }
        else
        {
            // Avoid busy-waiting when the queue is empty
            await Task.Delay(1);
        }
    }

    // Optionally clear the queue (or leave it for the next run, depending on your design)
    _bufferedImageQueue.Clear();
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

/// <summary>

/// Asynchronously saves buffered images until cancellation is requested

/// and the queue is drained. Intended to run on a background task.

/// </summary>

public async Task SaveBufferedImages(CancellationTokenSource cts)

{

// Loop while grabbing is active or there are still items in the queue

while (!cts.IsCancellationRequested && (IsGrabbing || _bufferedImageQueue.Count > 0))

{

if (_bufferedImageQueue.TryDequeue(out var item))

{

var bmp = ConvertGrabResultToBitmap(item.Result);

SaveBitmap(bmp, $“frame_{item.Timestamp:HHmmss_fff}.bmp”);

item.Result.Dispose();

}

else

{

// Avoid busy-waiting when the queue is empty

await Task.Delay(1);

}

// Optionally clear the queue (or leave it for the next run, depending on your design)

_bufferedImageQueue.Clear();

}

Example: Combining Event-Driven Capture with Async Saving

We can now update the test to run acquisition and saving concurrently:

[TestMethod()]
public async Task StartGrabbingTest()
{
    if (!_baslerCameraSample.IsConnected)
        _baslerCameraSample.Connect();

    Task? saveTask = null;
    var cts = new CancellationTokenSource();

    try
    {
        _baslerCameraSample.StartGrabbing();
        Assert.IsTrue(_baslerCameraSample.IsGrabbing,
            “Camera should be grabbing after StartGrabbing is called.”);

        // Start background save loop
        saveTask = _baslerCameraSample.SaveBufferedImages(cts);

        await Task.Delay(1000); // Capture for 1 second
    }
    catch (InvalidOperationException ex)
    {
        Assert.Fail($”StartGrabbing failed: {ex.Message}”);
    }
    finally
    {
        _baslerCameraSample.StopGrabbing();
        Assert.IsFalse(_baslerCameraSample.IsGrabbing,
            “Camera should not be grabbing after StopGrabbing is called.”);

        // Stop the save loop and wait for it to finish
        cts.Cancel();
        if (saveTask is not null)
            await saveTask;
    }
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

[TestMethod()]

public async Task StartGrabbingTest()

{

if (!_baslerCameraSample.IsConnected)

_baslerCameraSample.Connect();

Task? saveTask = null;

var cts = new CancellationTokenSource();

try

{

_baslerCameraSample.StartGrabbing();

Assert.IsTrue(_baslerCameraSample.IsGrabbing,

“Camera should be grabbing after StartGrabbing is called.”);

// Start background save loop

saveTask = _baslerCameraSample.SaveBufferedImages(cts);

await Task.Delay(1000); // Capture for 1 second

}

catch (InvalidOperationException ex)

{

Assert.Fail($“StartGrabbing failed: {ex.Message}”);

}

finally

{

_baslerCameraSample.StopGrabbing();

Assert.IsFalse(_baslerCameraSample.IsGrabbing,

“Camera should not be grabbing after StopGrabbing is called.”);

// Stop the save loop and wait for it to finish

cts.Cancel();

if (saveTask is not null)

await saveTask;

}

Depending on your requirements:

If real-time streaming is critical and your CPU has enough headroom, you can save while grabbing.
If your CPU is heavily loaded but RAM is sufficient, you can buffer during capture and save after stopping (by starting SaveBufferedImages only after StopGrabbing).

✅ Summary

Using the ImageGrabbed event yields a clean, C#-idiomatic structure for continuous acquisition.
Directly saving in the event handler can become a bottleneck at higher frame rates.
A robust pattern is: Clone → Enqueue → Async Save on a background task using ConcurrentQueue.
This separation helps stabilize continuous acquisition and makes your pipeline more resilient under load.

In the next article, we’ll look at integrating Basler cameras with OpenCV, enabling more advanced image processing workflows.

Author: @MilleVision

📦 Full Sample Project(With Japanese Comment)

A complete C# project that includes event-driven acquisition, ROI, burst capture, and asynchronous saving is available here(With Japanese Comment):

👉 https://millevision.booth.pm/items/7316233

2025-12-09

Boosting Frame Rate with ROI on Basler Cameras Using the pylon SDK (C# / .NET 8)

When developing machine-vision applications, you may find yourself asking:

“Can I increase the frame rate if I only need a portion of the image?”
“Can I reduce image size to speed up processing?”

The answer is often yes—by using ROI (Region of Interest).

By reducing the sensor readout area, you can significantly decrease data size and improve achievable frame rate. In this article, we explore how to configure ROI using the Basler pylon SDK in C#, along with real-world comparisons of full-frame vs ROI performance.

✔ What You Will Learn

How to configure ROI (Region of Interest) on Basler cameras
How ROI improves frame rate and processing speed
Common constraints, pitfalls, and error handling

✔ Environment

Item	Details
Camera	Basler acA2500-14gm
SDK	Basler pylon Camera Software Suite
Lang	C# / .NET 8 (Windows)
Lens	VS-LD25N (25 mm C-mount)

🔍 What Is ROI?

ROI (Region of Interest) defines a rectangular area on the camera sensor that you want to capture. Basler cameras expose four parameters to control ROI:

OffsetX — horizontal position
OffsetY — vertical position
Width — ROI width
Height — ROI height

Reducing ROI has several benefits:

Smaller image size
Shorter readout time → higher potential frame rate
Faster downstream processing

🔧 Setting ROI in C#

Below are helper methods added to the BaslerCameraSample class from previous articles:

public bool SetOffsetX(int offsetX)
    => SetPLCameraParamter(PLCamera.OffsetX, offsetX);

public bool SetOffsetY(int offsetY)
    => SetPLCameraParamter(PLCamera.OffsetY, offsetY);

public bool SetWidth(int width)
    => SetPLCameraParamter(PLCamera.Width, width);

public bool SetHeight(int height)
    => SetPLCameraParamter(PLCamera.Height, height);

1

2

3

4

5

6

7

8

9

10

11

public bool SetOffsetX(int offsetX)

=> SetPLCameraParamter(PLCamera.OffsetX, offsetX);

public bool SetOffsetY(int offsetY)

=> SetPLCameraParamter(PLCamera.OffsetY, offsetY);

public bool SetWidth(int width)

=> SetPLCameraParamter(PLCamera.Width, width);

public bool SetHeight(int height)

=> SetPLCameraParamter(PLCamera.Height, height);

Setting ROI in one operation

Because ROI must remain inside the sensor boundaries, the order of parameter updates matters.

ublic bool SetROI(int offsetX, int offsetY, int width, int height)
{
    if (width <= 0 || height <= 0)
        throw new ArgumentException(“ROI width and height must be greater than zero.”);

    if (GetWidth() + offsetX < GetSensorWidth())
    {
        if (!SetOffsetX(offsetX) || !SetWidth(width))
            return false;
    }
    else
    {
        if (!SetWidth(width) || !SetOffsetX(offsetX))
            return false;
    }

    if (GetHeight() + offsetY < GetSensorHeight())
    {
        if (!SetOffsetY(offsetY) || !SetHeight(height))
            return false;
    }
    else
    {
        if (!SetHeight(height) || !SetOffsetY(offsetY))
            return false;
    }

    return true;
}

public int GetWidth()
    => (int)GetPLCameraParamter(PLCamera.Width);

public int GetHeight()
    => (int)GetPLCameraParamter(PLCamera.Height);

public int GetSensorWidth()
    => (int)GetPLCameraParamter(PLCamera.SensorWidth);

public int GetSensorHeight()
    => (int)GetPLCameraParamter(PLCamera.SensorHeight);

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

ublic bool SetROI(int offsetX, int offsetY, int width, int height)

{

if (width <= 0 || height <= 0)

throw new ArgumentException(“ROI width and height must be greater than zero.”);

if (GetWidth() + offsetX < GetSensorWidth())

{

if (!SetOffsetX(offsetX) || !SetWidth(width))

return false;

}

else

{

if (!SetWidth(width) || !SetOffsetX(offsetX))

return false;

}

if (GetHeight() + offsetY < GetSensorHeight())

{

if (!SetOffsetY(offsetY) || !SetHeight(height))

return false;

}

else

{

if (!SetHeight(height) || !SetOffsetY(offsetY))

return false;

}

return true;

}

public int GetWidth()

=> (int)GetPLCameraParamter(PLCamera.Width);

public int GetHeight()

=> (int)GetPLCameraParamter(PLCamera.Height);

public int GetSensorWidth()

=> (int)GetPLCameraParamter(PLCamera.SensorWidth);

public int GetSensorHeight()

=> (int)GetPLCameraParamter(PLCamera.SensorHeight);

ROI using `Rect` (WPF)

using Windows;

public bool SetROI(Rect roi)
    => SetROI((int)roi.X, (int)roi.Y, (int)roi.Width, (int)roi.Height);

1

2

3

4

using Windows;

public bool SetROI(Rect roi)

=> SetROI((int)roi.X, (int)roi.Y, (int)roi.Width, (int)roi.Height);

📈 Why ROI Increases Frame Rate

Sensor readout time is almost always proportional to the number of pixels captured. Reducing the readout area:

Lowers pixel count
Reduces required bandwidth
Allows the camera to reach higher frame rates

This effect is independent of exposure time, so even long exposures benefit from faster readout afterward.

✔ Constraints When Setting ROI

Parameter	Notes
Width / Height	Many Basler models require values to follow a specific increment (2, 4, 8, 16… depending on sensor)
OffsetX / OffsetY	Must not exceed sensor boundaries

To inspect the increment value:

public long GetInc(IntegerName parameter)
{
    if (Camera == null || !IsConnected)
        throw new InvalidOperationException(“Camera is not connected.”);

    if (Camera.Parameters[parameter].IsReadable)
    {
        long inc = Camera.Parameters[parameter].GetIncrement();
        Console.WriteLine($”{parameter} increment: {inc}”);
        return inc;
    }

    throw new InvalidOperationException($”{parameter} is not readable.”);
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

public long GetInc(IntegerName parameter)

{

if (Camera == null || !IsConnected)

throw new InvalidOperationException(“Camera is not connected.”);

if (Camera.Parameters[parameter].IsReadable)

{

long inc = Camera.Parameters[parameter].GetIncrement();

Console.WriteLine($“{parameter} increment: {inc}”);

return inc;

}

throw new InvalidOperationException($“{parameter} is not readable.”);

}

Example test:

[TestMethod()]
public void GetIncTest()
{
    if (!_baslerCameraSample.IsConnected)
        _baslerCameraSample.Connect();

    var incWidth = _baslerCameraSample.GetInc(PLCamera.Width);
    Assert.AreEqual(1, incWidth);

    var incHeight = _baslerCameraSample.GetInc(PLCamera.Height);
    Assert.AreEqual(1, incHeight);
}

1

2

3

4

5

6

7

8

9

10

11

12

[TestMethod()]

public void GetIncTest()

{

if (!_baslerCameraSample.IsConnected)

_baslerCameraSample.Connect();

var incWidth = _baslerCameraSample.GetInc(PLCamera.Width);

Assert.AreEqual(1, incWidth);

var incHeight = _baslerCameraSample.GetInc(PLCamera.Height);

Assert.AreEqual(1, incHeight);

}

📏 Testing Frame Rate with ROI

static BaslerCameraSample _baslerCameraSample = new BaslerCameraSample();

[TestMethod()]
public void SetROITest()
{
    _baslerCameraSample.Connect();

    _baslerCameraSample.EnableFrameRate(true);
    _baslerCameraSample.SetFrameRate(30); // 30 fps target

    _baslerCameraSample.SetROI(1246, 1200, 640, 480);
    var fps1 = _baslerCameraSample.GetResultingFrameRate();
    _baslerCameraSample.BurstCapture(5, “ROITest_640x480”);

    _baslerCameraSample.SetROI(0, 0, 2592, 1944);
    var fps2 = _baslerCameraSample.GetResultingFrameRate();
    _baslerCameraSample.BurstCapture(5, “ROITest_2592x1944″);

    Console.WriteLine($”FPS with ROI: {fps1:F2}, full-frame FPS: {fps2:F2}”);
    Assert.IsTrue(fps1 > fps2);
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

static BaslerCameraSample _baslerCameraSample = new BaslerCameraSample();

[TestMethod()]

public void SetROITest()

{

_baslerCameraSample.Connect();

_baslerCameraSample.EnableFrameRate(true);

_baslerCameraSample.SetFrameRate(30); // 30 fps target

_baslerCameraSample.SetROI(1246, 1200, 640, 480);

var fps1 = _baslerCameraSample.GetResultingFrameRate();

_baslerCameraSample.BurstCapture(5, “ROITest_640x480”);

_baslerCameraSample.SetROI(0, 0, 2592, 1944);

var fps2 = _baslerCameraSample.GetResultingFrameRate();

_baslerCameraSample.BurstCapture(5, “ROITest_2592x1944”);

Console.WriteLine($“FPS with ROI: {fps1:F2}, full-frame FPS: {fps2:F2}”);

Assert.IsTrue(fps1 > fps2);

}

🧪 Real-World Comparison

Full Resolution (2592 × 1944)

Frame timestamps demonstrate slower readout:

Frame	0	1	2	3	4
T [ms]	72	140	209	277	346

ROI (640 × 480)

Frame	0	1	2	3	4
T [ms]	23	67	87	120	154

Summary Comparison

Mode	Resolution	Resulting Frame Rate
Full Frame	2592×1944	~14.6 fps
ROI	640×480	~30.0 fps

→ ROI doubles the effective frame rate in this test.

⚠️ Common Errors & Solutions

Issue	Cause
`InvalidParameterException`	ROI exceeds sensor bounds, or width/height violates increments
No frames after setting ROI	Some camera models require reinitialization after ROI changes

📝 Summary

ROI can significantly reduce readout time and increase frame rate
Combining ROI with proper frame-rate settings improves real-time performance
Pay attention to width/height increments and sensor boundaries
Ideal for speeding up burst capture and reducing processing load

筆者: @MilleVision

📦 Full Sample Code Package

👉 https://millevision.booth.pm/items/7316233 Includes ROI, burst capture, trigger control, and full pylon SDK integration.(With Japanese Comment)

2025-12-07

Implementing High-Speed Burst Capture with the Basler pylon SDK (C# / .NET 8)

In machine vision and inspection systems, it’s often not enough to capture a single frame—you frequently need to capture multiple images in rapid succession, also known as burst capture or continuous acquisition.

In this article, we walk through how to implement burst capture using the Basler pylon SDK in C#, including:

A basic capture loop
Controlling frame interval
Saving images with timestamps
Practical performance considerations

✔ What You Will Learn

How to implement a burst capture loop
How to control acquisition interval using frame-rate settings
How to save frames with timestamps for later analysis
How to avoid dropped frames and performance bottlenecks

✔ Environment

Item	Details
Camera	Basler acA2500-14gm
SDK	Basler pylon Camera Software Suite
Lang	C# / .NET 8 (Windows)

🔄 Basic Burst Capture: Capturing N Consecutive Frames

Before implementing burst capture, define a helper method to control trigger mode:

public bool SetTriggerMode(string mode)
    => SetPLCameraParameter(PLCamera.TriggerMode, mode);

1 2	public bool SetTriggerMode(string mode) => SetPLCameraParameter(PLCamera.TriggerMode, mode);

The following method performs a free-run (trigger-off) burst capture, saving each frame with both an index and elapsed time. Including timestamps makes later debugging and performance analysis much easier.

public void BurstCapture(int count, string baseName = “burst”)
{
    SetTriggerMode(PLCamera.TriggerMode.Off); // Free-run mode

    if (Camera == null || !IsConnected)
        throw new InvalidOperationException(“Camera is not connected.”);

    if (Camera.StreamGrabber == null)
        throw new InvalidOperationException(“Camera StreamGrabber is not available.”);

    var sw = new Stopwatch();
    Camera.StreamGrabber.Start();
    sw.Start();

    for (int i = 0; i < count; i++)
    {
        using IGrabResult? result =
            Camera.StreamGrabber.RetrieveResult(5000, TimeoutHandling.ThrowException);

        var elapsed = sw.ElapsedMilliseconds;

        if (result?.GrabSucceeded ?? false)
        {
            var bmp = ConvertGrabResultToBitmap(result);
            string filename = $”{baseName}_{i:D3}_{elapsed}ms.bmp”;
            SaveBitmap(bmp, filename);
        }
    }

    sw.Stop();
    Camera.StreamGrabber.Stop();
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

public void BurstCapture(int count, string baseName = “burst”)

{

SetTriggerMode(PLCamera.TriggerMode.Off); // Free-run mode

if (Camera == null || !IsConnected)

throw new InvalidOperationException(“Camera is not connected.”);

if (Camera.StreamGrabber == null)

throw new InvalidOperationException(“Camera StreamGrabber is not available.”);

var sw = new Stopwatch();

Camera.StreamGrabber.Start();

sw.Start();

for (int i = 0; i < count; i++)

{

using IGrabResult? result =

Camera.StreamGrabber.RetrieveResult(5000, TimeoutHandling.ThrowException);

var elapsed = sw.ElapsedMilliseconds;

if (result?.GrabSucceeded ?? false)

{

var bmp = ConvertGrabResultToBitmap(result);

string filename = $“{baseName}_{i:D3}_{elapsed}ms.bmp”;

SaveBitmap(bmp, filename);

}

sw.Stop();

Camera.StreamGrabber.Stop();

}

🕒 Controlling the Capture Interval

Burst capture does not automatically enforce timing. To control the interval—for example, 10 fps—enable and set AcquisitionFrameRate:

AcquisitionFrameRateEnable = true  
AcquisitionFrameRate = desired fps

1

2

3

AcquisitionFrameRateEnable = true

AcquisitionFrameRate = desired fps

Reference: How to Control and Verify Frame Rate Using the Basler pylon SDK (C# / .NET 8)

📷 Example: Capturing 10 Frames at 10 fps

[TestMethod()]
public void BurstCaptureTest_10times()
{
    if (!_baslerCameraSample.IsConnected)
        _baslerCameraSample.Connect();

    _baslerCameraSample.EnableFrameRate(true);
    _baslerCameraSample.SetFrameRate(10); // 10 fps (100 ms/frame)

    _baslerCameraSample.BurstCapture(10, “BurstCaptureTest”);

    for (int i = 0; i < 10; i++)
    {
        string filename = $”BurstCaptureTest_{i:D3}_*.bmp”;
        var files = System.IO.Directory.GetFiles(“.”, filename);
        Assert.IsTrue(files.Length > 0, $”File {filename} not found.”);
    }
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

[TestMethod()]

public void BurstCaptureTest_10times()

{

if (!_baslerCameraSample.IsConnected)

_baslerCameraSample.Connect();

_baslerCameraSample.EnableFrameRate(true);

_baslerCameraSample.SetFrameRate(10); // 10 fps (100 ms/frame)

_baslerCameraSample.BurstCapture(10, “BurstCaptureTest”);

for (int i = 0; i < 10; i++)

{

string filename = $“BurstCaptureTest_{i:D3}_*.bmp”;

var files = System.IO.Directory.GetFiles(“.”, filename);

Assert.IsTrue(files.Length > 0, $“File {filename} not found.”);

}

📊 Example Output

Captured images at 10 fps while the object was rotating:

45ms	143ms	243ms	343ms	443ms

543ms	643ms	743ms	843ms	943ms

⚠️ Common Problems & How to Fix Them

Issue	Cause / Solution
Missing frames	Saving images takes too long → save in a background thread using `ConcurrentQueue`
CPU load too high	Full-resolution images are heavy → reduce ROI
First-frame timestamp inconsistent	Trigger mode behavior → use hardware/software trigger for strict timing

🔁 Slow Burst Capture at Full Resolution?

→ Reduce ROI to Increase Frame Rate

Full-resolution capture (e.g., 2592×1944) can bottleneck both bandwidth and processing time. Reducing the Region of Interest (ROI) often dramatically improves:

Frame rate
Latency
Stability

ROI-based optimization will be covered in the next article.

📝 Summary

Burst capture in pylon is implemented with StreamGrabber.Start() + a loop
Frame rate control determines capture timing
Image saving can become a bottleneck—offload saving to another thread if necessary
Combining ROI with burst capture greatly improves performance

筆者: @MilleVision

📦 Full Sample Code Package

A complete working version of all code shown in this article (including burst capture templates) is available here:

👉 https://millevision.booth.pm/items/7316233

2025-12-07

How to Control and Verify Frame Rate Using the Basler pylon SDK (C# / .NET 8)

When developing vision applications—especially for real-time inspection or production environments—one of the most important performance metrics is frame rate (fps). You may need to know:

Can the camera actually capture frames at the rate I’ve set?
What limits the maximum achievable frame rate?
How do I read both the requested and the actual frame rate?

This article explains how to set frame rate, enable frame-rate control, and check the actual resulting fps using the Basler pylon SDK in C#.

✔ Environment

Item	Details
Camera	Basler acA2500-14gm
SDK	Basler pylon Camera Software Suite
Lang	C# / .NET 8 (Windows)

💡 `AcquisitionFrameRate` vs. `ResultingFrameRate`

Parameter	Meaning
AcquisitionFrameRate	The requested frame rate (user setting)
ResultingFrameRate	The actual achievable frame rate calculated by the camera

Even if you set 30 fps, the resulting fps may be lower depending on exposure time, ROI, interface bandwidth, etc.

🔧 Enabling Frame Rate Control

Frame-rate control must be explicitly enabled:

/// <summary>
/// Enable or disable frame-rate control.  
/// When enabled, the camera attempts to acquire images at the specified frame rate.
/// When disabled, the camera operates at the maximum possible fps.
/// </summary>
public bool EnableFrameRate(bool enable)
    => SetPLCameraParameter(PLCamera.AcquisitionFrameRateEnable, enable);

1

2

3

4

5

6

7

/// <summary>

/// Enable or disable frame-rate control.

/// When enabled, the camera attempts to acquire images at the specified frame rate.

/// When disabled, the camera operates at the maximum possible fps.

/// </summary>

public bool EnableFrameRate(bool enable)

=> SetPLCameraParameter(PLCamera.AcquisitionFrameRateEnable, enable);

Helper method for Boolean parameters

AcquisitionFrameRateEnable is a boolean parameter (IBoolean), so we define:

public bool SetPLCameraParameter(BooleanName parameter, bool value)
{
    if (Camera == null || !IsConnected)
        return false;

    if (Camera.Parameters[parameter].IsWritable)
    {
        Camera.Parameters[parameter].SetValue(value);
        Console.WriteLine($”{parameter} set to {value}.”);
        return true;
    }

    Console.WriteLine($”{parameter} is not writable.”);
    return false;
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

public bool SetPLCameraParameter(BooleanName parameter, bool value)

{

if (Camera == null || !IsConnected)

return false;

if (Camera.Parameters[parameter].IsWritable)

{

Camera.Parameters[parameter].SetValue(value);

Console.WriteLine($“{parameter} set to {value}.”);

return true;

}

Console.WriteLine($“{parameter} is not writable.”);

return false;

}

🔧 Setting the Desired Frame Rate

public bool SetFrameRate(double frameRate)
    => SetPLCameraParameter(PLCamera.AcquisitionFrameRateAbs, frameRate);

1 2	public bool SetFrameRate(double frameRate) => SetPLCameraParameter(PLCamera.AcquisitionFrameRateAbs, frameRate);

💡 Depending on the camera model, the parameter name may be:

AcquisitionFrameRate
AcquisitionFrameRateAbs

Verify via pylon Viewer or by checking:

Camera.Parameters.Contains(PLCamera.AcquisitionFrameRateAbs)

1	Camera.Parameters.Contains(PLCamera.AcquisitionFrameRateAbs)

📏 Reading the Requested and Actual Frame Rate

Requested (user-set) frame rate:

public double GetFrameRate()
    => GetPLCameraParameter(PLCamera.AcquisitionFrameRateAbs);

1 2	public double GetFrameRate() => GetPLCameraParameter(PLCamera.AcquisitionFrameRateAbs);

Actual achievable rate:

public double GetResultingFrameRate()
    => GetPLCameraParameter(PLCamera.ResultingFrameRateAbs);

1 2	public double GetResultingFrameRate() => GetPLCameraParameter(PLCamera.ResultingFrameRateAbs);

ResultingFrameRate is essential—it tells you whether your settings are physically achievable given the exposure time, bandwidth, and ROI.

🚧 What Limits Maximum Frame Rate?

1. Image Size / ROI

Smaller ROI = fewer pixels = higher possible fps.

2. Exposure Time

If exposure is too long, the sensor cannot start the next frame.

Example: ExposureTime = 50,000 µs (50 ms) → max possible fps is 20 fps.

3. Interface Bandwidth (USB3 / GigE)

High-resolution images or 24-bit RGB increase bandwidth usage, lowering achievable fps.

📝 When Your Frame Rate Setting Is Ignored

If you set AcquisitionFrameRate but nothing changes, check:

✔ Is `AcquisitionFrameRateEnable` set to true?

If false, the camera ignores your setting and runs at the highest allowable frame rate.

_baslerCameraSample.EnableFrameRate(false); // Disabled
_baslerCameraSample.SetFrameRate(15);      // Has no effect

double fps = _baslerCameraSample.GetResultingFrameRate();

1

2

3

4

_baslerCameraSample.EnableFrameRate(false); // Disabled

_baslerCameraSample.SetFrameRate(15); // Has no effect

double fps = _baslerCameraSample.GetResultingFrameRate();

🧪 Example Test: 5 fps → 15 fps → 30 fps

[TestMethod()]
public void SetFrameRateTest()
{
    _baslerCameraSample.Connect();
    _baslerCameraSample.EnableFrameRate(true);

    // 5 fps
    Assert.IsTrue(_baslerCameraSample.SetFrameRate(5));
    Assert.IsTrue(Math.Abs(_baslerCameraSample.GetFrameRate() – 5) < 0.1);

    // 15 fps
    Assert.IsTrue(_baslerCameraSample.SetFrameRate(15));
    Assert.IsTrue(Math.Abs(_baslerCameraSample.GetFrameRate() – 15) < 0.1);

    // 30 fps
    Assert.IsTrue(_baslerCameraSample.SetFrameRate(30));
    Assert.IsTrue(Math.Abs(_baslerCameraSample.GetFrameRate() – 30) < 0.1);

    // Check actual achievable fps
    var resulting = _baslerCameraSample.GetResultingFrameRate();
    Console.WriteLine($”Requested: 30 fps, Resulting: {resulting:F2} fps”);
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

[TestMethod()]

public void SetFrameRateTest()

{

_baslerCameraSample.Connect();

_baslerCameraSample.EnableFrameRate(true);

// 5 fps

Assert.IsTrue(_baslerCameraSample.SetFrameRate(5));

Assert.IsTrue(Math.Abs(_baslerCameraSample.GetFrameRate() – 5) < 0.1);

// 15 fps

Assert.IsTrue(_baslerCameraSample.SetFrameRate(15));

Assert.IsTrue(Math.Abs(_baslerCameraSample.GetFrameRate() – 15) < 0.1);

// 30 fps

Assert.IsTrue(_baslerCameraSample.SetFrameRate(30));

Assert.IsTrue(Math.Abs(_baslerCameraSample.GetFrameRate() – 30) < 0.1);

// Check actual achievable fps

var resulting = _baslerCameraSample.GetResultingFrameRate();

Console.WriteLine($“Requested: 30 fps, Resulting: {resulting:F2} fps”);

}

Example output on my machine:

Frame Rate: 30.00 fps, Resulting Frame Rate: 14.59 fps

1 2	Frame Rate: 30.00 fps, Resulting Frame Rate: 14.59 fps

Even though 30 fps was requested, the actual fps dropped to ~14.6 fps due to bandwidth or exposure constraints.

🧭 Troubleshooting

Symptom	Likely Cause
Frame rate does not increase	Exposure too long / ROI too large
Cannot set AcquisitionFrameRate	`AcquisitionFrameRateEnable` is false
ResultingFrameRate reads 0	Camera not streaming or not initialized

📝 Summary

Enable frame-rate control via AcquisitionFrameRateEnable = true
Set target fps with AcquisitionFrameRateAbs
Verify actual achievable fps via ResultingFrameRateAbs
Exposure time, ROI size, and bandwidth all influence the maximum fps

Understanding both the requested and actual frame rate is essential for designing stable, real-time machine vision systems.

🔜 Next Article

Next, we will build on frame-rate control by implementing continuous acquisition (burst capture) for high-speed inspections and inline processing.

筆者: @MilleVision

2025-12-06

Manual Gain Control with the Basler pylon SDK (C# / .NET 8)

筆者: [@MilleVision](https://qiita.com/MilleVision)

Manual Gain Control with the Basler pylon SDK (C# / .NET 8)

When working with industrial cameras such as those from Basler, exposure time alone is not always enough to achieve the brightness you need. This is especially true when:

The subject moves quickly
You must keep exposure time short
The lighting environment limits the available exposure

In these situations, manual gain control becomes an important tool.

This article explains how to read, set, and validate gain values in C# using the Basler pylon SDK. We will also examine how gain affects noise and how to balance exposure vs. gain using practical example images.

✔ Environment

Item	Details
Camera	Basler acA2500-14gm
Lens	VS Technology VS-LD25N (25 mm C-mount)
SDK	Basler pylon Camera Software Suite
Lang	C# / .NET 8 (Windows)

💡 What Is Gain?

Gain represents electronic amplification of the sensor signal.

Increasing gain brightens the image
But it also amplifies noise, reducing image quality

Because of this trade-off, gain should be balanced with exposure time rather than used alone. Exposure increases brightness with lower noise, but may blur moving objects. Gain brightens the image without changing shutter time but introduces noise.

🔧 Code: Setting and Reading Gain

Below are simple helper methods for manual gain control.

Set Gain (manual mode)

public bool SetGain(double gainValue)
{
    if (!SetGainAutoMode(PLCamera.GainAuto.Off))
        return false;

    return SetPLCameraParamter(PLCamera.Gain, gainValue);
}

1

2

3

4

5

6

7

public bool SetGain(double gainValue)

{

if (!SetGainAutoMode(PLCamera.GainAuto.Off))

return false;

return SetPLCameraParamter(PLCamera.Gain, gainValue);

}

Auto Gain Mode

public bool SetGainAutoMode(string mode)
    => SetPLCameraParamter(PLCamera.GainAuto, mode);

1 2	public bool SetGainAutoMode(string mode) => SetPLCameraParamter(PLCamera.GainAuto, mode);

Read Gain

public double GetGain()
    => GetPLCameraParamter(PLCamera.Gain);

1 2	public double GetGain() => GetPLCameraParamter(PLCamera.Gain);

📷 Gain in Practice: Image Comparisons

① Exposure Fixed, Gain Increased

In this test, exposure time is constant while only gain is changed. You can clearly see how higher gain results in brighter images but more noise.

Gain 0 dB	Gain 12 dB	Gain 24 dB

② Same Brightness, Different Gain (Exposure Adjusted)

Here, exposure time was adjusted so that the brightness remained approximately constant, allowing you to see just the difference in noise.

Gain 0 dB (60ms)	Gain 12 dB (24ms)	Gain 24 dB (12ms)

💡 GainRaw ↔ Gain (dB) Conversion

Basler cameras often expose two gain parameters:

Gain (in dB) — user-friendly
GainRaw — internal integer register value

The mapping between them varies by camera model, but it can typically be approximated by a linear transform:

double ConvertGainRawToDb(long rawValue)
{
    var rawMin = Camera.Parameters[PLCamera.GainRaw].GetMinimum();
    var rawMax = Camera.Parameters[PLCamera.GainRaw].GetMaximum();
    var dbMin = Camera.Parameters[PLCamera.Gain].GetMinimum();
    var dbMax = Camera.Parameters[PLCamera.Gain].GetMaximum();

    return dbMin + (dbMax – dbMin) * (rawValue – rawMin) / (double)(rawMax – rawMin);
}

long ConvertGainDbToRaw(double dbValue)
{
    var rawMin = Camera.Parameters[PLCamera.GainRaw].GetMinimum();
    var rawMax = Camera.Parameters[PLCamera.GainRaw].GetMaximum();
    var dbMin = Camera.Parameters[PLCamera.Gain].GetMinimum();
    var dbMax = Camera.Parameters[PLCamera.Gain].GetMaximum();

    return (long)Math.Round(rawMin + (rawMax – rawMin) * (dbValue – dbMin) / (dbMax – dbMin));
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

double ConvertGainRawToDb(long rawValue)

{

var rawMin = Camera.Parameters[PLCamera.GainRaw].GetMinimum();

var rawMax = Camera.Parameters[PLCamera.GainRaw].GetMaximum();

var dbMin = Camera.Parameters[PLCamera.Gain].GetMinimum();

var dbMax = Camera.Parameters[PLCamera.Gain].GetMaximum();

return dbMin + (dbMax – dbMin) * (rawValue – rawMin) / (double)(rawMax – rawMin);

}

long ConvertGainDbToRaw(double dbValue)

{

var rawMin = Camera.Parameters[PLCamera.GainRaw].GetMinimum();

var rawMax = Camera.Parameters[PLCamera.GainRaw].GetMaximum();

var dbMin = Camera.Parameters[PLCamera.Gain].GetMinimum();

var dbMax = Camera.Parameters[PLCamera.Gain].GetMaximum();

return (long)Math.Round(rawMin + (rawMax – rawMin) * (dbValue – dbMin) / (dbMax – dbMin));

}

This is useful when a camera supports only GainRaw or when you need precise dB control.

🧭 Troubleshooting Common Gain Issues

Issue	Cause / Solution
Gain does not change	`GainAuto` is not set to Off
Parameter write error	Value outside the allowed range — check `GetMin()` / `GetMax()`
Noise becomes excessive	Gain too high — prefer exposure when possible
Cannot write to `Gain`	Parameter not writable → likely because auto gain is active

When Gain Cannot Be Set

If GainAuto is not disabled, the parameter:

Camera.Parameters[PLCamera.Gain].IsWritable

1 2	Camera.Parameters[PLCamera.Gain].IsWritable

will be false, preventing manual writes.

Always check IsWritable before writing to avoid runtime exceptions.

📝 Summary

Gain amplifies brightness and noise — unlike exposure, which brightens with less noise
Set GainAuto = Off to enable manual gain control
The balance between exposure and gain is crucial:
- Exposure = cleaner images, but motion blur risk
- Gain = no blur, but increased noise

By comparing images side-by-side, we can see why most machine-vision systems prioritize exposure first, then use gain sparingly.

🔜 Next Article

With exposure and gain under control, the next major topic is trigger modes and frame synchronization. We’ll explore hardware triggers, software triggers, and best practices for synchronized acquisition.

筆者: @MilleVision

2025-12-05

How to Manually Control Exposure Time Using the Basler pylon SDK (C# / .NET 8)

Have you ever felt that your industrial camera images look too dark, too bright, or fluctuate unexpectedly?
Automatic exposure (auto-exposure) can be useful, but in many machine-vision or inspection systems, consistent lighting is essential, and automatic adjustments can cause instability.

With the Basler pylon SDK, you can switch exposure control to manual mode and specify an exact exposure time (in microseconds), enabling stable and predictable imaging.

This article explains how to set, read, and validate exposure time manually using C# and the pylon SDK.

✔ Environment

Item	Details
Camera	Basler acA2500-14gm
SDK	Basler pylon Camera Software Suite
Lang	C# / .NET 8.0 (Windows)

💡 Background: GenICam and Camera Parameters

Parameters such as ExposureTimeAbs used in this article follow GenICam (Generic Interface for Cameras) — an industry standard used by Basler, FLIR, IDS, JAI, and many other industrial camera manufacturers.

With GenICam SFNC (Standard Features Naming Convention), you can access:

Exposure
Gain
ROI / image size
Trigger settings
Acquisition modes

all using a common parameter model.

👉 GenICam SFNC specification:
https://www.emva.org/standards-technology/genicam/

This article focuses on practical usage, but knowing that pylon follows GenICam helps when switching between camera brands.

🔧 Setting Exposure Time Manually

Below is an extension to the BaslerCameraSample class from the previous article.

Method: Set Exposure Time (manual mode)

// Set exposure time manually (unit: microseconds)
public bool SetExposure(double exposureTimeUs)
{
    // Disable auto exposure (switch to manual)
    if (!SetExposureMode(PLCamera.ExposureAuto.Off))
        return false;

    // Set exposure time (e.g., 5000 µs = 5 ms)
    if (!SetPLCameraParamter(PLCamera.ExposureTimeAbs, exposureTimeUs))
        return false;

    Console.WriteLine($”Exposure time set to {exposureTimeUs} μs.”);
    return true;
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

// Set exposure time manually (unit: microseconds)

public bool SetExposure(double exposureTimeUs)

{

// Disable auto exposure (switch to manual)

if (!SetExposureMode(PLCamera.ExposureAuto.Off))

return false;

// Set exposure time (e.g., 5000 µs = 5 ms)

if (!SetPLCameraParamter(PLCamera.ExposureTimeAbs, exposureTimeUs))

return false;

Console.WriteLine($“Exposure time set to {exposureTimeUs} μs.”);

return true;

}

Helper Functions

Set auto-exposure mode (Off / Once / Continuous)

public bool SetExposureMode(string mode)
    => SetPLCameraParamter(PLCamera.ExposureAuto, mode);

1 2	public bool SetExposureMode(string mode) => SetPLCameraParamter(PLCamera.ExposureAuto, mode);

Set an enum parameter

public bool SetPLCameraParamter(ParameterListEnum parameter, string value)
{
    if (Camera == null || !IsConnected)
        return false;

    if (Camera.Parameters[parameter].IsWritable)
    {
        Camera.Parameters[parameter].SetValue(value);
        Console.WriteLine($”{parameter} set to {value}.”);
        return true;
    }
    Console.WriteLine($”{parameter} is not writable.”);
    return false;
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

public bool SetPLCameraParamter(ParameterListEnum parameter, string value)

{

if (Camera == null || !IsConnected)

return false;

if (Camera.Parameters[parameter].IsWritable)

{

Camera.Parameters[parameter].SetValue(value);

Console.WriteLine($“{parameter} set to {value}.”);

return true;

}

Console.WriteLine($“{parameter} is not writable.”);

return false;

}

Set a floating-point parameter (e.g., ExposureTimeAbs)

public bool SetPLCameraParamter(FloatName parameter, double value)
{
    if (Camera == null || !IsConnected)
        return false;

    if (Camera.Parameters[parameter].IsWritable)
    {
        Camera.Parameters[parameter].SetValue(value);
        Console.WriteLine($”{parameter} set to {value}.”);
        return true;
    }
    Console.WriteLine($”{parameter} is not writable.”);
    return false;
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

public bool SetPLCameraParamter(FloatName parameter, double value)

{

if (Camera == null || !IsConnected)

return false;

if (Camera.Parameters[parameter].IsWritable)

{

Camera.Parameters[parameter].SetValue(value);

Console.WriteLine($“{parameter} set to {value}.”);

return true;

}

Console.WriteLine($“{parameter} is not writable.”);

return false;

}

🔍 Reading the Current Exposure Time

Use GetValue() to read exposure parameters from the camera.

// Read exposure time in microseconds
public double GetExposureTime()
    => GetPLCameraParamter(PLCamera.ExposureTimeAbs);

public double GetPLCameraParamter(FloatName parameter)
{
    if (Camera == null || !IsConnected)
        throw new InvalidOperationException(“Camera is not connected.”);

    if (Camera.Parameters[parameter].IsReadable)
    {
        double value = Camera.Parameters[parameter].GetValue();
        Console.WriteLine($”{parameter} value: {value}”);
        return value;
    }
    throw new InvalidOperationException($”{parameter} is not readable.”);
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

// Read exposure time in microseconds

public double GetExposureTime()

=> GetPLCameraParamter(PLCamera.ExposureTimeAbs);

public double GetPLCameraParamter(FloatName parameter)

{

if (Camera == null || !IsConnected)

throw new InvalidOperationException(“Camera is not connected.”);

if (Camera.Parameters[parameter].IsReadable)

{

double value = Camera.Parameters[parameter].GetValue();

Console.WriteLine($“{parameter} value: {value}”);

return value;

}

throw new InvalidOperationException($“{parameter} is not readable.”);

}

💡 About ExposureAuto Modes

Value	Behavior
Off	Manual exposure (used in this article)
Once	Adjusts exposure once, then fixes it
Continuous	Continuously adjusts to maintain brightness

📷 Example: Change Exposure and Capture Images

The test below captures images at 5 ms, 20 ms, and 50 ms.

[TestMethod()]
public void SetExposureTest()
{
    _baslerCameraSample.Connect();

    // 5 ms
    _baslerCameraSample.SetExposure(5000);
    var img1 = _baslerCameraSample.SnapToBitmapSource();
    BaslerCameraSample.SaveBitmap(img1, “Exposure_5ms.bmp”);
    Assert.IsTrue(Math.Abs(_baslerCameraSample.GetExposureTime() – 5000) < 100);

    // 20 ms
    _baslerCameraSample.SetExposure(20000);
    var img2 = _baslerCameraSample.SnapToBitmapSource();
    BaslerCameraSample.SaveBitmap(img2, “Exposure_20ms.bmp”);
    Assert.IsTrue(Math.Abs(_baslerCameraSample.GetExposureTime() – 20000) < 100);

    // 50 ms
    _baslerCameraSample.SetExposure(50000);
    var img3 = _baslerCameraSample.SnapToBitmapSource();
    BaslerCameraSample.SaveBitmap(img3, “Exposure_50ms.bmp”);
    Assert.IsTrue(Math.Abs(_baslerCameraSample.GetExposureTime() – 50000) < 100);
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

[TestMethod()]

public void SetExposureTest()

{

_baslerCameraSample.Connect();

// 5 ms

_baslerCameraSample.SetExposure(5000);

var img1 = _baslerCameraSample.SnapToBitmapSource();

BaslerCameraSample.SaveBitmap(img1, “Exposure_5ms.bmp”);

Assert.IsTrue(Math.Abs(_baslerCameraSample.GetExposureTime() – 5000) < 100);

// 20 ms

_baslerCameraSample.SetExposure(20000);

var img2 = _baslerCameraSample.SnapToBitmapSource();

BaslerCameraSample.SaveBitmap(img2, “Exposure_20ms.bmp”);

Assert.IsTrue(Math.Abs(_baslerCameraSample.GetExposureTime() – 20000) < 100);

// 50 ms

_baslerCameraSample.SetExposure(50000);

var img3 = _baslerCameraSample.SnapToBitmapSource();

BaslerCameraSample.SaveBitmap(img3, “Exposure_50ms.bmp”);

Assert.IsTrue(Math.Abs(_baslerCameraSample.GetExposureTime() – 50000) < 100);

}

📊 Exposure Comparison

5 ms (darker)	20 ms (balanced)	50 ms (brighter)

🧭 Common Issues & Troubleshooting

Issue	Cause / Solution
Exposure does not change	`ExposureAuto` is still On
Value outside valid range	Exposure too long or too short for the camera model
Image too dark/bright	Lighting or gain settings are insufficient
Exposure fluctuates	External lighting or auto exposure still enabled

📝 Summary

Set ExposureAuto = Off to enable manual exposure control
Exposure time is specified in microseconds (μs)
pylon SDK accesses all parameters through Camera.Parameters[...], following GenICam SFNC

🔜 Coming Up Next

Exposure alone may not give enough brightness range depending on your lighting environment.
The next article will cover manual gain control using the pylon SDK.

2025-12-04

How to Capture a Single Image from Basler ace Camera using pylon SDK in C#

Basler industrial cameras can be controlled easily using the pylon Camera Software Suite.
In this article, I’ll show you how to connect to a camera, grab a single frame, convert it to a BitmapSource, and save it as a .bmp file—all using C# and .NET 8.

When I first started working with Basler cameras in a .NET environment, I found very few practical code examples.
This guide is based on tested code from my own applications.

This article covers:

Connecting to a camera
Capturing one frame (Snap)
Converting to BitmapSource (WPF-friendly)
Saving the image as .bmp

⚠️ Important Notice

This article demonstrates how to develop custom applications using the Basler pylon Camera Software Suite SDK.

The content here is based on my own testing and implementation
It is not endorsed by Basler AG
The SDK itself is not redistributed here (no DLLs, headers, etc.)

To use the SDK, download it directly from Basler’s official website:

🔗 pylon SDK download
https://www.baslerweb.com/en/products/software/basler-pylon-camera-software-suite/

Make sure to review the EULA, especially if using the SDK in commercial or high-risk environments:
https://www.baslerweb.com/en/service/eula/

The sample code in this article is provided strictly for learning and reference. Use it at your own responsibility.

✔ Environment

Item	Details
SDK	Basler pylon Camera Software Suite
Language	C# (.NET 8.0 — Windows)
Camera	Basler acA2500-14gm
OS	Windows 10 / 11

1. Connecting to the Camera

First, create a simple wrapper class for managing the connection.
You can connect to the first available camera or use a specified camera name (as shown in Basler pylon Viewer).

using System;
using Basler.Pylon;

namespace BaslerSamples
{
    public class BaslerCameraSample
    {
        public Camera? Camera { get; private set; }
        public bool IsConnected => Camera?.IsConnected ?? false;

        public bool Connect()
        {
            var camera = new Camera();
            return ConnectInternal(camera);
        }

        public bool Connect(string cameraName)
        {
            try
            {
                var camera = new Camera(cameraName);
                return ConnectInternal(camera);
            }
            catch (InvalidOperationException e)
            {
                Console.WriteLine($”Failed to create camera. Message: {e.Message}”);
                return false;
            }
        }

        private bool ConnectInternal(Camera camera)
        {
            try
            {
                camera.Open();
                if (camera.IsOpen)
                {
                    Console.WriteLine(“Camera connected successfully.”);
                    Camera = camera;
                    return true;
                }
                else
                {
                    Console.WriteLine(“Failed to open camera.”);
                    return false;
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($”Error connecting to camera: {ex.Message}”);
                return false;
            }
        }
    }
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

using System;

using Basler.Pylon;

namespace BaslerSamples

{

public class BaslerCameraSample

{

public Camera? Camera { get; private set; }

public bool IsConnected => Camera?.IsConnected ?? false;

public bool Connect()

{

var camera = new Camera();

return ConnectInternal(camera);

}

public bool Connect(string cameraName)

{

try

{

var camera = new Camera(cameraName);

return ConnectInternal(camera);

}

catch (InvalidOperationException e)

{

Console.WriteLine($“Failed to create camera. Message: {e.Message}”);

return false;

}

private bool ConnectInternal(Camera camera)

{

try

{

camera.Open();

if (camera.IsOpen)

{

Console.WriteLine(“Camera connected successfully.”);

Camera = camera;

return true;

}

else

{

Console.WriteLine(“Failed to open camera.”);

return false;

}

catch (Exception ex)

{

Console.WriteLine($“Error connecting to camera: {ex.Message}”);

return false;

}

2. Capturing a Single Image

The simplest way to grab one frame is by calling GrabOne() through the Stream Grabber.

public IGrabResult Snap(int timeoutMs = 5000)
{
    if (Camera == null)
        throw new InvalidOperationException(“Camera is not connected.”);

    var streamGrabber = Camera.StreamGrabber 
        ?? throw new InvalidOperationException(“StreamGrabber is not available.”);
    var grabResult = streamGrabber.GrabOne(timeoutMs);

    if (grabResult != null && grabResult.GrabSucceeded)
        return grabResult;
    else
        throw new Exception(“Failed to grab image: ” + (grabResult?.ErrorDescription ?? “Unknown error”));
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

public IGrabResult Snap(int timeoutMs = 5000)

{

if (Camera == null)

throw new InvalidOperationException(“Camera is not connected.”);

var streamGrabber = Camera.StreamGrabber

?? throw new InvalidOperationException(“StreamGrabber is not available.”);

var grabResult = streamGrabber.GrabOne(timeoutMs);

if (grabResult != null && grabResult.GrabSucceeded)

return grabResult;

else

throw new Exception(“Failed to grab image: “ + (grabResult?.ErrorDescription ?? “Unknown error”));

}

3. Converting to `BitmapSource` (for WPF)

IGrabResult cannot be displayed directly in WPF.
We convert it to a BitmapSource using PixelDataConverter.

using System.Windows.Media;
using System.Windows.Media.Imaging;

public BitmapSource SnapToBitmapSource(int timeoutMs = 5000)
{
    using IGrabResult grabResult = Snap(timeoutMs);
    PixelDataConverter converter = new();

    var (outputType, pixelFormat, bytesPerPixel) = grabResult.PixelTypeValue switch
    {
        PixelType.RGB8packed => (PixelType.RGB8packed, PixelFormats.Rgb24, 3),
        PixelType.BGR8packed => (PixelType.BGR8packed, PixelFormats.Bgr24, 3),
        _ => (PixelType.Mono8, PixelFormats.Gray8, 1),
    };

    converter.OutputPixelFormat = outputType;

    int width = grabResult.Width;
    int height = grabResult.Height;
    int stride = width * bytesPerPixel;

    byte[] buffer = new byte[stride * height];
    converter.Convert(buffer, grabResult);

    return BitmapSource.Create(width, height, 96, 96, pixelFormat, null, buffer, stride);
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

using System.Windows.Media;

using System.Windows.Media.Imaging;

public BitmapSource SnapToBitmapSource(int timeoutMs = 5000)

{

using IGrabResult grabResult = Snap(timeoutMs);

PixelDataConverter converter = new();

var (outputType, pixelFormat, bytesPerPixel) = grabResult.PixelTypeValue switch

{

PixelType.RGB8packed => (PixelType.RGB8packed, PixelFormats.Rgb24, 3),

PixelType.BGR8packed => (PixelType.BGR8packed, PixelFormats.Bgr24, 3),

_ => (PixelType.Mono8, PixelFormats.Gray8, 1),

};

converter.OutputPixelFormat = outputType;

int width = grabResult.Width;

int height = grabResult.Height;

int stride = width * bytesPerPixel;

byte[] buffer = new byte[stride * height];

converter.Convert(buffer, grabResult);

return BitmapSource.Create(width, height, 96, 96, pixelFormat, null, buffer, stride);

}

Supports:

RGB8packed
BGR8packed
Mono8 (default fallback)

4. Saving the Image as `.bmp`

A simple helper method using BmpBitmapEncoder:

public static void SaveBitmap(BitmapSource bitmap, string filePath)
{
    using FileStream fileStream = new(filePath, FileMode.Create);
    var encoder = new BmpBitmapEncoder();
    encoder.Frames.Add(BitmapFrame.Create(bitmap));
    encoder.Save(fileStream);
}

1

2

3

4

5

6

7

public static void SaveBitmap(BitmapSource bitmap, string filePath)

{

using FileStream fileStream = new(filePath, FileMode.Create);

var encoder = new BmpBitmapEncoder();

encoder.Frames.Add(BitmapFrame.Create(bitmap));

encoder.Save(fileStream);

}

5. Example Test Code

You can easily test the entire pipeline (grab → convert → save) using the following:

static BaslerCameraSample _baslerCameraSample = new BaslerCameraSample();

[TestMethod()]
public void SnapToBitmapSourceTest()
{
    if (!_baslerCameraSample.IsConnected)
        _baslerCameraSample.Connect();

    var result = _baslerCameraSample.SnapToBitmapSource(1234);
    Assert.IsNotNull(result);

    BaslerCameraSample.SaveBitmap(result, “SaveBitmapTest.bmp”);
    Assert.IsTrue(File.Exists(“SaveBitmapTest.bmp”));
}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

static BaslerCameraSample _baslerCameraSample = new BaslerCameraSample();

[TestMethod()]

public void SnapToBitmapSourceTest()

{

if (!_baslerCameraSample.IsConnected)

_baslerCameraSample.Connect();

var result = _baslerCameraSample.SnapToBitmapSource(1234);

Assert.IsNotNull(result);

BaslerCameraSample.SaveBitmap(result, “SaveBitmapTest.bmp”);

Assert.IsTrue(File.Exists(“SaveBitmapTest.bmp”));

}

✔ Output Example

The captured image will be saved as:SaveBitmapTest.bmp

Example output:

(Image from the original article)

✨ Conclusion

Although official documentation covers the basics, hands-on .NET examples for pylon are still relatively rare.
Fortunately, pylon’s .NET API is clean and integrates smoothly with Windows desktop applications such as WPF.

2025-12-03

Blog

✅ Environment

🔧 Configuring the Software Trigger

🔁 Example: Using the Software Trigger

⏱ Experiment: Software Trigger vs “Just call GrabOne()”

📊 Results

📝 Summary

🛠 Full Sample Code Project(With Japanese comment)

What Is the PFS Format?

✅ Typical Use Cases

✅ Environment

📝 Saving Camera Settings (Save)

📂 Example of a Saved PFS File

📥 Loading Settings (Load)

Example: Save & Load Round Trip

⚠️ Notes & Caveats

✅ Summary

Coming Up Next

Displaying and Saving Basler Camera Images with OpenCV

✅ Environment

🎯 Goal: Convert GrabResult → Mat → Display & Save

🔧 Converting GrabResult to Mat

🖼 Real-Time Display with Cv2.ImShow

Example Test: Live Display for 10 Seconds

💾 Saving Mat with ImWrite

📌 Tips & Common Pitfalls

✅ Summary

Stabilizing Basler Camera Acquisition with Event-Driven Capture and Async Saving (C# / pylon SDK)

✅ Why Event-Driven Acquisition Helps

🔧 Minimal Event-Based Implementation

Example: 1 Second of Continuous Capture

⚠️ Problem: Saving Overhead Can Stall the Pipeline

🧭 Solution: Buffer with ConcurrentQueue and Save on a Separate Thread

Example: Combining Event-Driven Capture with Async Saving

✅ Summary

📦 Full Sample Project(With Japanese Comment)

Boosting Frame Rate with ROI on Basler Cameras Using the pylon SDK (C# / .NET 8)

✔ What You Will Learn

✔ Environment

🔍 What Is ROI?

🔧 Setting ROI in C#

Setting ROI in one operation

ROI using Rect (WPF)

📈 Why ROI Increases Frame Rate

✔ Constraints When Setting ROI

📏 Testing Frame Rate with ROI

🧪 Real-World Comparison

Full Resolution (2592 × 1944)

ROI (640 × 480)

Summary Comparison

⚠️ Common Errors & Solutions

📝 Summary

📦 Full Sample Code Package

Implementing High-Speed Burst Capture with the Basler pylon SDK (C# / .NET 8)

✔ What You Will Learn

✔ Environment

🔄 Basic Burst Capture: Capturing N Consecutive Frames

🕒 Controlling the Capture Interval

📷 Example: Capturing 10 Frames at 10 fps

📊 Example Output

⚠️ Common Problems & How to Fix Them

🔁 Slow Burst Capture at Full Resolution?

→ Reduce ROI to Increase Frame Rate

📝 Summary

📦 Full Sample Code Package

How to Control and Verify Frame Rate Using the Basler pylon SDK (C# / .NET 8)

✔ Environment

💡 AcquisitionFrameRate vs. ResultingFrameRate

🔧 Enabling Frame Rate Control

Helper method for Boolean parameters

🔧 Setting the Desired Frame Rate

📏 Reading the Requested and Actual Frame Rate

Requested (user-set) frame rate:

Actual achievable rate:

🚧 What Limits Maximum Frame Rate?

1. Image Size / ROI

2. Exposure Time

3. Interface Bandwidth (USB3 / GigE)

📝 When Your Frame Rate Setting Is Ignored

✔ Is AcquisitionFrameRateEnable set to true?

⏱ Experiment: Software Trigger vs “Just call `GrabOne()`”

🎯 Goal: Convert `GrabResult` → `Mat` → Display & Save

🔧 Converting `GrabResult` to `Mat`

🖼 Real-Time Display with `Cv2.ImShow`

💾 Saving `Mat` with `ImWrite`

🧭 Solution: Buffer with `ConcurrentQueue` and Save on a Separate Thread

ROI using `Rect` (WPF)

💡 `AcquisitionFrameRate` vs. `ResultingFrameRate`

✔ Is `AcquisitionFrameRateEnable` set to true?

3. Converting to `BitmapSource` (for WPF)

4. Saving the Image as `.bmp`