タグ: Basler

Zoom & Pan for WPF Live View Using TransformGroup (C# / .NET 8)

In the previous article, we built a minimal setup to overlay a HUD (FPS, exposure, gain) on top of live video. As a continuation, this article adds mouse-driven zoom/pan, an ROI rectangle that follows the image, and a crosshair fixed to the screen center.

We keep the same layer-separated design (Video = zoom/pan, HUD = fixed) to minimize blur and jitter.

Environment / Prerequisites

Basler pylon Camera Software Suite (Basler.Pylon referenced)
.NET 8 / WPF (Windows desktop)
You have completed the previous HUD live-view article:
- Live view with CurrentFrame: ImageSource bound to an Image
- HUD overlay

Goals

Mouse wheel zoom centered at the cursor (1.1× per step)
Shift + drag (or middle button drag) to pan
ROI rectangle scales/moves with the image (follows zoom/pan)
Crosshair stays fixed in screen coordinates (HUD layer)

XAML: Two Layers + ROI Layer (Shared Transform)

Because the implementation has grown, some parts are omitted where appropriate.

<Window x:Class=”BaslerGUISample.MainWindow”
        xmlns=”http://schemas.microsoft.com/winfx/2006/xaml/presentation”
        xmlns:x=”http://schemas.microsoft.com/winfx/2006/xaml”
        xmlns:d=”http://schemas.microsoft.com/expression/blend/2008″
        xmlns:mc=”http://schemas.openxmlformats.org/markup-compatibility/2006″
        xmlns:local=”clr-namespace:BaslerGUISample”
        xmlns:models=”clr-namespace:BaslerGUISample.Models”
        mc:Ignorable=”d”
        Title=”BaslerGUISample” Height=”450″ Width=”500″ Closing=”Window_Closing”>

    <Window.Resources>
        <!– Shared transform for zoom/pan (used by both Image and ROI) –>
        <TransformGroup x:Key=”ContentTransform” Changed=”TransformGroup_Changed”>
            <ScaleTransform x:Name=”Zoom” ScaleX=”1″ ScaleY=”1″/>
            <TranslateTransform x:Name=”Pan” X=”0″ Y=”0″/>
        </TransformGroup>
        <models:HalfConverter x:Key=”Half”/>
    </Window.Resources>
    <Grid>  
        <Grid.RowDefinitions>
            <RowDefinition Height=”Auto”/>
            <RowDefinition Height=”Auto”/>
            <RowDefinition Height=”*”/>
        </Grid.RowDefinitions>
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width=”*”/>
            <ColumnDefinition Width=”*”/>
            <ColumnDefinition Width=”*”/>
            <ColumnDefinition Width=”*”/>
            <ColumnDefinition Width=”*”/>
        </Grid.ColumnDefinitions>

        <!– Row=0 is the same as before –>

        <!– Zoom controls –>
        <Grid Grid.Row=”1″ Grid.Column=”0″>
            <Button Content=”Fit” Width=”80″ Margin=”0,5″ Click=”Fit_Click”/>
        </Grid>
        <Grid Grid.Row=”1″ Grid.Column=”1″>
            <Button Content=”1:1″ Width=”80″ Margin=”0,5″ Click=”Pixel1to1_Click”/>
        </Grid>
        <Grid Grid.Row=”1″ Grid.Column=”2″>
            <Button Content=”Reset” Width=”80″ Margin=”0,5″ Click=”Reset_Click”/>
        </Grid>
        <Grid Grid.Row=”1″ Grid.Column=”3″>
            <TextBlock Text=”{Binding ZoomText, RelativeSource={RelativeSource AncestorType=local:MainWindow}}” VerticalAlignment=”Center” Margin=”8,0,0,0″/>
        </Grid>

        <!– Display area –>
        <Grid Grid.Row=”2″ Grid.Column=”0″ Grid.ColumnSpan=”5″
              ClipToBounds=”True”
              UseLayoutRounding=”True”
              SnapsToDevicePixels=”True”
              TextOptions.TextFormattingMode=”Display”
              TextOptions.TextRenderingMode=”ClearType”
              PreviewMouseWheel=”Root_PreviewMouseWheel”
              MouseLeftButtonDown=”Root_MouseDown”
              MouseMove=”Root_MouseMove”
              MouseUp=”Root_MouseUp”>

            <!– Video layer (zoom/pan applied) –>
            <Canvas x:Name=”ImageLayer”>
                <Image x:Name=”CameraImage”
                       Source=”{Binding CurrentFrame}”
                       RenderOptions.BitmapScalingMode=”NearestNeighbor”
                       Stretch=”Uniform”
                       RenderTransform=”{StaticResource ContentTransform}”/>
            </Canvas>

            <!– ROI layer (shares transform to follow the image) –>
            <Canvas x:Name=”RoiLayer”
                    IsHitTestVisible=”False”
                    RenderTransform=”{StaticResource ContentTransform}”>
                <Rectangle x:Name=”RoiRect” Width=”270″ Height=”200″
                        Canvas.Left=”100″ Canvas.Top=”130″
                        Stroke=”Lime” StrokeThickness=”1″
                        StrokeDashArray=”4,2″ />
            </Canvas>

            <!– HUD layer (screen-fixed, no zoom) –>
            <Grid x:Name=”HudLayer” IsHitTestVisible=”False”>
                <!– Top-left HUD box is the same as previous article –>

                <!– Crosshair fixed at screen center –>
                <Line X1=”0″
                    Y1=”{Binding ActualHeight, ElementName=HudLayer, Converter={StaticResource Half}}”
                    X2=”{Binding ActualWidth,  ElementName=HudLayer}”
                    Y2=”{Binding ActualHeight, ElementName=HudLayer, Converter={StaticResource Half}}”
                    Stroke=”White” StrokeThickness=”1″ StrokeDashArray=”2,2″ Opacity=”0.6″/>
                <Line X1=”{Binding ActualWidth, ElementName=HudLayer, Converter={StaticResource Half}}”
                    Y1=”0″
                    X2=”{Binding ActualWidth, ElementName=HudLayer, Converter={StaticResource Half}}”
                    Y2=”{Binding ActualHeight, ElementName=HudLayer}”
                    Stroke=”White” StrokeThickness=”1″ StrokeDashArray=”2,2″ Opacity=”0.6″/>
                
                <!– Add more HUD elements here –>
            </Grid>
        </Grid>
    </Grid>
</Window>

100

<Window x:Class=“BaslerGUISample.MainWindow”

xmlns=“http://schemas.microsoft.com/winfx/2006/xaml/presentation”

xmlns:x=“http://schemas.microsoft.com/winfx/2006/xaml”

xmlns:d=“http://schemas.microsoft.com/expression/blend/2008”

xmlns:mc=“http://schemas.openxmlformats.org/markup-compatibility/2006”

xmlns:local=“clr-namespace:BaslerGUISample”

xmlns:models=“clr-namespace:BaslerGUISample.Models”

mc:Ignorable=“d”

Title=“BaslerGUISample” Height=“450” Width=“500” Closing=“Window_Closing”>

<Window.Resources>

<!— Shared transform for zoom/pan (used by both Image and ROI) —>

</TransformGroup>

<models:HalfConverter x:Key=“Half”/>

</Window.Resources>

<Grid>

<Grid.RowDefinitions>

</Grid.RowDefinitions>

<Grid.ColumnDefinitions>

</Grid.ColumnDefinitions>

<!— Row=0 is the same as before —>

<!— Zoom controls —>

</Grid>

</Grid>

</Grid>

</Grid>

<!— Display area —>

<Grid Grid.Row=“2” Grid.Column=“0” Grid.ColumnSpan=“5”

ClipToBounds=“True”

UseLayoutRounding=“True”

SnapsToDevicePixels=“True”

TextOptions.TextFormattingMode=“Display”

TextOptions.TextRenderingMode=“ClearType”

PreviewMouseWheel=“Root_PreviewMouseWheel”

MouseLeftButtonDown=“Root_MouseDown”

MouseMove=“Root_MouseMove”

MouseUp=“Root_MouseUp”>

<!— Video layer (zoom/pan applied) —>

<Image x:Name=“CameraImage”

Source=“{Binding CurrentFrame}”

RenderOptions.BitmapScalingMode=“NearestNeighbor”

Stretch=“Uniform”

RenderTransform=“{StaticResource ContentTransform}”/>

</Canvas>

<!— ROI layer (shares transform to follow the image) —>

<Canvas x:Name=“RoiLayer”

IsHitTestVisible=“False”

RenderTransform=“{StaticResource ContentTransform}”>

<Rectangle x:Name=“RoiRect” Width=“270” Height=“200”

Canvas.Left=“100” Canvas.Top=“130”

Stroke=“Lime” StrokeThickness=“1”

StrokeDashArray=“4,2” />

</Canvas>

<!— HUD layer (screen–fixed, no zoom) —>

<!— Top–left HUD box is the same as previous article —>

<!— Crosshair fixed at screen center —>

<Line X1=“0”

Y1=“{Binding ActualHeight, ElementName=HudLayer, Converter={StaticResource Half}}”

X2=“{Binding ActualWidth, ElementName=HudLayer}”

Y2=“{Binding ActualHeight, ElementName=HudLayer, Converter={StaticResource Half}}”

Stroke=“White” StrokeThickness=“1” StrokeDashArray=“2,2” Opacity=“0.6”/>

<Line X1=“{Binding ActualWidth, ElementName=HudLayer, Converter={StaticResource Half}}”

Y1=“0”

X2=“{Binding ActualWidth, ElementName=HudLayer, Converter={StaticResource Half}}”

Y2=“{Binding ActualHeight, ElementName=HudLayer}”

Stroke=“White” StrokeThickness=“1” StrokeDashArray=“2,2” Opacity=“0.6”/>

<!— Add more HUD elements here —>

</Grid>

</Window>

HalfConverter (For Center Crosshair)

This converter makes it easy to draw lines centered in the HUD layer.

using System;
using System.Globalization;
using System.Windows.Data;

namespace BaslerGUISample.Models
{
    public class HalfConverter : IValueConverter
    {
        public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
            => value is double d ? d / 2.0 : 0.0;

        public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
            => Binding.DoNothing;
    }
}

using System;

using System.Globalization;

using System.Windows.Data;

namespace BaslerGUISample.Models

{

public class HalfConverter : IValueConverter

{

public object Convert(object value, Type targetType, object parameter, CultureInfo culture)

=> value is double d ? d / 2.0 : 0.0;

public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)

=> Binding.DoNothing;

}

Code-Behind: Zoom / Pan

In this article, zoom and pan are implemented purely in code-behind. You can refactor into ViewModel/Model later if needed.

using System.Windows;
using System.Windows.Input;
using System.Windows.Media;
using BaslerGUISample.ViewModels;

namespace BaslerGUISample
{
    /// <summary>
    /// Interaction logic for MainWindow.xaml
    /// </summary>
    public partial class MainWindow : Window
    {
        private readonly MainViewModel _viewModel;

        private TransformGroup? _contentTransform;
        private ScaleTransform? _scale;
        private TranslateTransform? _trans;

        private bool _panning;
        private Point _panStart;

        public MainWindow()
        {
            InitializeComponent();
            _viewModel = new MainViewModel();
            DataContext = _viewModel;
            _contentTransform = (TransformGroup)Resources[“ContentTransform”];
            _scale = (ScaleTransform)_contentTransform.Children[0];
            _trans = (TranslateTransform)_contentTransform.Children[1];
            UpdateZoomText();
        }

        public string ZoomText
        {
            get => (string)GetValue(ZoomTextProperty);
            set => SetValue(ZoomTextProperty, value);
        }
        public static readonly DependencyProperty ZoomTextProperty =
            DependencyProperty.Register(nameof(ZoomText), typeof(string), typeof(MainWindow),
                new PropertyMetadata(“Zoom: 1.00x”));

        /// <summary>
        /// Disconnect the camera before the window closes.
        /// </summary>
        private void Window_Closing(object sender, System.ComponentModel.CancelEventArgs e)
        {
            if (_viewModel.IsGrabbing)
            {
                _viewModel.Stop();
            }
            _viewModel.Disconnect();
        }
        
        private void Root_PreviewMouseWheel(object sender, MouseWheelEventArgs e)
        {
            const double step = 1.1;
            double factor = e.Delta > 0 ? step : 1.0 / step;

            var viewPt    = e.GetPosition(ImageLayer);
            var contentPt = ToContent(viewPt);

            double newScaleX = _scale!.ScaleX * factor;
            double newScaleY = _scale!.ScaleY * factor;
            newScaleX = Math.Clamp(newScaleX, 0.1, 20.0);
            newScaleY = Math.Clamp(newScaleY, 0.1, 20.0);
            _scale.ScaleX = newScaleX;
            _scale.ScaleY = newScaleY;

            var post = _contentTransform!.Transform(contentPt);
            _trans!.X += viewPt.X – post.X;
            _trans!.Y += viewPt.Y – post.Y;

        }

        private void Root_MouseDown(object sender, MouseButtonEventArgs e)
        {
            if (e.MiddleButton == MouseButtonState.Pressed || (e.LeftButton == MouseButtonState.Pressed && (Keyboard.IsKeyDown(Key.LeftShift) || Keyboard.IsKeyDown(Key.RightShift))))
            {
                _panning = true;
                _panStart = e.GetPosition(ImageLayer);
                Mouse.Capture(ImageLayer);
            }
        }

        private void Root_MouseMove(object sender, MouseEventArgs e)
        {
            if (!_panning) return;
            var now = e.GetPosition(ImageLayer);
            var delta = now – _panStart;
            _panStart = now;
            _trans!.X += delta.X;
             _trans!.Y += delta.Y;
        }

        private void Root_MouseUp(object sender, MouseButtonEventArgs e)
        {
            _panning = false;
            Mouse.Capture(null);
        }

        private void Reset_Click(object sender, RoutedEventArgs e)
        {
            _scale!.ScaleX = _scale.ScaleY = 1.0;
            _trans!.X = _trans.Y = 0.0;
        }

        private void Pixel1to1_Click(object sender, RoutedEventArgs e)
        {
            _scale!.ScaleX = _scale.ScaleY = 1.0;
        }

        private void Fit_Click(object sender, RoutedEventArgs e)
        {
            if (_viewModel.CurrentFrame is null)
                return;
            var w = ImageLayer.ActualWidth;
            var h = ImageLayer.ActualHeight;
            if (w <= 0 || h <= 0) return;

            double srcW = _viewModel.CurrentFrame.PixelWidth, srcH = _viewModel.CurrentFrame.PixelHeight;
            double s = Math.Min(w / srcW, h / srcH);
            _scale!.ScaleX = _scale.ScaleY = s;
            _trans!.X = (w – srcW * s) * 0.5;
            _trans!.Y = (h – srcH * s) * 0.5;
        }

        private void UpdateZoomText()
        {
            ZoomText = $”Zoom: {_scale?.ScaleX:0.00}x”;
        }

        private Point ToContent(Point viewPt)
        {
            var inv = _contentTransform!.Inverse;
            return inv.Transform(viewPt);
        }

        private void TransformGroup_Changed(object sender, EventArgs e)
        {
            UpdateZoomText();
        }
    }
}

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

using System.Windows;

using System.Windows.Input;

using System.Windows.Media;

using BaslerGUISample.ViewModels;

namespace BaslerGUISample

{

/// <summary>

/// Interaction logic for MainWindow.xaml

/// </summary>

public partial class MainWindow : Window

{

private readonly MainViewModel _viewModel;

private TransformGroup? _contentTransform;

private ScaleTransform? _scale;

private TranslateTransform? _trans;

private bool _panning;

private Point _panStart;

public MainWindow()

{

InitializeComponent();

_viewModel = new MainViewModel();

DataContext = _viewModel;

_contentTransform = (TransformGroup)Resources[“ContentTransform”];

_scale = (ScaleTransform)_contentTransform.Children[0];

_trans = (TranslateTransform)_contentTransform.Children[1];

UpdateZoomText();

}

public string ZoomText

{

get => (string)GetValue(ZoomTextProperty);

set => SetValue(ZoomTextProperty, value);

}

public static readonly DependencyProperty ZoomTextProperty =

DependencyProperty.Register(nameof(ZoomText), typeof(string), typeof(MainWindow),

new PropertyMetadata(“Zoom: 1.00x”));

/// <summary>

/// Disconnect the camera before the window closes.

/// </summary>

private void Window_Closing(object sender, System.ComponentModel.CancelEventArgs e)

{

if (_viewModel.IsGrabbing)

{

_viewModel.Stop();

}

_viewModel.Disconnect();

}

private void Root_PreviewMouseWheel(object sender, MouseWheelEventArgs e)

{

const double step = 1.1;

double factor = e.Delta > 0 ? step : 1.0 / step;

var viewPt = e.GetPosition(ImageLayer);

var contentPt = ToContent(viewPt);

double newScaleX = _scale!.ScaleX * factor;

double newScaleY = _scale!.ScaleY * factor;

newScaleX = Math.Clamp(newScaleX, 0.1, 20.0);

newScaleY = Math.Clamp(newScaleY, 0.1, 20.0);

_scale.ScaleX = newScaleX;

_scale.ScaleY = newScaleY;

var post = _contentTransform!.Transform(contentPt);

_trans!.X += viewPt.X – post.X;

_trans!.Y += viewPt.Y – post.Y;

}

private void Root_MouseDown(object sender, MouseButtonEventArgs e)

{

if (e.MiddleButton == MouseButtonState.Pressed || (e.LeftButton == MouseButtonState.Pressed && (Keyboard.IsKeyDown(Key.LeftShift) || Keyboard.IsKeyDown(Key.RightShift))))

{

_panning = true;

_panStart = e.GetPosition(ImageLayer);

Mouse.Capture(ImageLayer);

}

private void Root_MouseMove(object sender, MouseEventArgs e)

{

if (!_panning) return;

var now = e.GetPosition(ImageLayer);

var delta = now – _panStart;

_panStart = now;

_trans!.X += delta.X;

_trans!.Y += delta.Y;

}

private void Root_MouseUp(object sender, MouseButtonEventArgs e)

{

_panning = false;

Mouse.Capture(null);

}

private void Reset_Click(object sender, RoutedEventArgs e)

{

_scale!.ScaleX = _scale.ScaleY = 1.0;

_trans!.X = _trans.Y = 0.0;

}

private void Pixel1to1_Click(object sender, RoutedEventArgs e)

{

_scale!.ScaleX = _scale.ScaleY = 1.0;

}

private void Fit_Click(object sender, RoutedEventArgs e)

{

if (_viewModel.CurrentFrame is null)

return;

var w = ImageLayer.ActualWidth;

var h = ImageLayer.ActualHeight;

if (w <= 0 || h <= 0) return;

double srcW = _viewModel.CurrentFrame.PixelWidth, srcH = _viewModel.CurrentFrame.PixelHeight;

double s = Math.Min(w / srcW, h / srcH);

_scale!.ScaleX = _scale.ScaleY = s;

_trans!.X = (w – srcW * s) * 0.5;

_trans!.Y = (h – srcH * s) * 0.5;

}

private void UpdateZoomText()

{

ZoomText = $“Zoom: {_scale?.ScaleX:0.00}x”;

}

private Point ToContent(Point viewPt)

{

var inv = _contentTransform!.Inverse;

return inv.Transform(viewPt);

}

private void TransformGroup_Changed(object sender, EventArgs e)

{

UpdateZoomText();

}

ROI Handling and Applying It in Real Apps

In this sample, we assign the same TransformGroup to both the Image and the RoiLayer.

Because RoiLayer shares the transform, it naturally follows zoom/pan.
In real applications, you typically bind Canvas.Left/Top/Width/Height of RoiRect to a ViewModel, then apply those values to camera ROI parameters.
When applying ROI to the camera, remember GenICam constraints such as width/height increments.

Meanwhile, HUD elements (crosshair, texts) remain transform-free and screen-fixed, preventing blur and keeping interaction intuitive.

Example Screens

The UI looks like this:

Pan the live view by dragging while holding Shift. The ROI follows; the crosshair stays fixed.

Zoom with the mouse wheel. The zoom ratio in the upper area updates as well.

Use Fit to fit the image to the window. 1:1 sets the zoom to 1.0, and Reset returns zoom to 1.0 and pan offset to 0.

Summary

Video + ROI share the same transform; HUD stays fixed (layered design)
Mouse interaction provides cursor-centered zoom and intuitive pan
ROI follows the image while the crosshair remains screen-fixed

2025-12-26

Implementing Live View in a WPF App for Basler Cameras (pylon SDK / C# / .NET 8)

In the previous article (Displaying a Basler Camera Snapshot in a WPF App), we captured a single frame and displayed it in a WPF Image. This time, we’ll implement a live camera preview inside a WPF window.

The live view uses an event-driven approach: we receive frames via ImageGrabbed, convert them to BitmapSource, and update an Image control. The update is performed safely via the Dispatcher to avoid blocking or crashing the UI thread.

Environment / Assumptions

Basler pylon Camera Software Suite (reference Basler.Pylon)
.NET 8 / WPF (Windows desktop)
Camera: acA2500-14gm (assumed Mono8) If you use a color camera, you must convert based on pixel format such as BGR8packed.

Goal

Live preview controlled by Connect / Start / Stop / Disconnect
Smooth updates by continuously refreshing a BitmapSource bound to an Image
Safe UI updates (always via the Dispatcher)

UI (XAML)

GUILiveSampleXAML

We add two buttons: Live (start preview) and Stop (stop preview).

<Window x:Class=”BaslerGUISample.MainWindow”
        xmlns=”http://schemas.microsoft.com/winfx/2006/xaml/presentation”
        xmlns:x=”http://schemas.microsoft.com/winfx/2006/xaml”
        xmlns:d=”http://schemas.microsoft.com/expression/blend/2008″
        xmlns:mc=”http://schemas.openxmlformats.org/markup-compatibility/2006″
        xmlns:local=”clr-namespace:BaslerGUISample”
        mc:Ignorable=”d”
        Title=”BaslerGUISample” Height=”450″ Width=”500″ Closing=”Window_Closing”>
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height=”Auto”/>
            <RowDefinition Height=”*”/>
        </Grid.RowDefinitions>
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width=”*”/>
            <ColumnDefinition Width=”*”/>
            <ColumnDefinition Width=”*”/>
            <ColumnDefinition Width=”*”/>
            <ColumnDefinition Width=”*”/>
        </Grid.ColumnDefinitions>
        <Grid Grid.Row=”0″ Grid.Column=”0″>
            <Button Content=”Connect” Width=”80″ Margin=”4,0″ Command=”{Binding ConnectCommand}”/>
        </Grid>
        <Grid Grid.Row=”0″ Grid.Column=”1″>
            <Button Content=”Disconnect” Width=”80″ Margin=”4,0″ Command=”{Binding DisconnectCommand}”/>
        </Grid>
        <Grid Grid.Row=”0″ Grid.Column=”2″>
            <Button Content=”Snap” Width=”80″ Margin=”4,0″ Command=”{Binding SnapCommand}”/>
        </Grid>
        <Grid Grid.Row=”0″ Grid.Column=”3″>
            <Button Content=”Live” Width=”80″ Margin=”4,0″ Command=”{Binding StartCommand}”/>
        </Grid>
        <Grid Grid.Row=”0″ Grid.Column=”4″>
            <Button Content=”Stop” Width=”80″ Margin=”4,0″ Command=”{Binding StopCommand}”/>
        </Grid>
        <Grid Grid.Row=”1″ Grid.Column=”0″ Grid.ColumnSpan=”5″>
            <Image x:Name=”PreviewImage” Source=”{Binding CurrentFrame}” Stretch=”Uniform”/>
        </Grid>
    </Grid>
</Window>

<Window x:Class=“BaslerGUISample.MainWindow”

xmlns=“http://schemas.microsoft.com/winfx/2006/xaml/presentation”

xmlns:x=“http://schemas.microsoft.com/winfx/2006/xaml”

xmlns:d=“http://schemas.microsoft.com/expression/blend/2008”

xmlns:mc=“http://schemas.openxmlformats.org/markup-compatibility/2006”

xmlns:local=“clr-namespace:BaslerGUISample”

mc:Ignorable=“d”

Title=“BaslerGUISample” Height=“450” Width=“500” Closing=“Window_Closing”>

<Grid>

<Grid.RowDefinitions>

</Grid.RowDefinitions>

<Grid.ColumnDefinitions>

</Grid.ColumnDefinitions>

</Grid>

</Grid>

</Grid>

</Grid>

</Grid>

</Grid>

</Window>

The code-behind is the same as in the previous article (set DataContext to the ViewModel and disconnect on closing).

Model Side (`BaslerCameraSample`)

If we reuse the previous StartGrabbing() implementation, frames keep piling up in ConcurrentQueue<(DateTime, IGrabResult)> _bufferedImageQueue, which is great for async saving but makes live view unnecessarily complex.

So, we add a simple streaming method dedicated to live display:

/// <summary>
/// Starts streaming without enqueuing frames into _bufferedImageQueue.
/// This method is specialized for live preview.
/// </summary>
public void StartLive()
{
    if (Camera == null || !IsConnected)
        throw new InvalidOperationException(“Camera is not connected.”);

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

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

/// <summary>

/// Starts streaming without enqueuing frames into _bufferedImageQueue.

/// This method is specialized for live preview.

/// </summary>

public void StartLive()

{

if (Camera == null || !IsConnected)

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

if (IsGrabbing)

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

// Set acquisition mode to continuous

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

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

}

Add/Remove event handlers

To keep the design flexible, we expose methods to attach/detach ImageGrabbed handlers:

/// <summary>
/// Adds an event handler that is called when an image is grabbed.
/// </summary>
public void AddImageGrabbedEventHandler(EventHandler<ImageGrabbedEventArgs> handler)
{
    if (Camera == null)
        return;
    Camera!.StreamGrabber!.ImageGrabbed += handler;
}

public void RemoveImageGrabbedEventHandler(EventHandler<ImageGrabbedEventArgs> handler)
{
    if (Camera == null)
        return;
    Camera.StreamGrabber!.ImageGrabbed -= handler;
}

/// <summary>

/// Adds an event handler that is called when an image is grabbed.

/// </summary>

public void AddImageGrabbedEventHandler(EventHandler<ImageGrabbedEventArgs> handler)

{

if (Camera == null)

return;

Camera!.StreamGrabber!.ImageGrabbed += handler;

}

public void RemoveImageGrabbedEventHandler(EventHandler<ImageGrabbedEventArgs> handler)

{

if (Camera == null)

return;

Camera.StreamGrabber!.ImageGrabbed -= handler;

}

ViewModel: Event-Driven Preview → Update `BitmapSource`

We continue using BaslerCameraSample, but now we update CurrentFrame whenever ImageGrabbed fires.

If performance becomes an issue, consider using WriteableBitmap rather than creating a new BitmapSource every time.

using Basler.Pylon; // ImageGrabbedEventArgs
using BaslerSamples; // Camera control library
// The author uses BindableBase / DelegateCommand from a Common namespace.
// Please adapt to your environment.
// using Common;
using System;
using System.Windows;
using System.Windows.Media.Imaging;
using Application = System.Windows.Application;

namespace BaslerGUISample.ViewModels
{
    public partial class MainViewModel : BindableBase
    {
        private readonly BaslerCameraSample _cameraService = new();

        public MainViewModel()
        {
            // ConnectCommand, DisconnectCommand, SnapCommand are the same as the previous article.
            StartCommand = new DelegateCommand(Start, () => IsConnected && !IsGrabbing);
            StopCommand  = new DelegateCommand(Stop,  () => IsConnected && IsGrabbing);
        }

        private bool _isConnected;
        public bool IsConnected
        {
            get => _isConnected;
            set => SetProperty(ref _isConnected, value);
        }

        /// <summary>
        /// Indicates whether the camera is currently grabbing frames.
        /// </summary>
        private bool _isGrabbing;
        public bool IsGrabbing
        {
            get => _isGrabbing;
            set => SetProperty(ref _isGrabbing, value);
        }

        private BitmapSource? _currentFrame;
        public BitmapSource? CurrentFrame
        {
            get => _currentFrame;
            set => SetProperty(ref _currentFrame, value);
        }

        public void Start()
        {
            if (IsConnected == false) return;

            // Register handler (remove first to avoid duplicates)
            _cameraService.RemoveImageGrabbedEventHandler(OnImageGrabbed);
            _cameraService.AddImageGrabbedEventHandler(OnImageGrabbed);

            _cameraService.StartLive();
            IsGrabbing = _cameraService.IsGrabbing;
        }

        public void Stop()
        {
            if (_cameraService.IsConnected == false) return;

            _cameraService.StopGrabbing();

            // Unregister handler
            _cameraService.RemoveImageGrabbedEventHandler(OnImageGrabbed);
            IsGrabbing = _cameraService.IsGrabbing;
        }

        /// <summary>
        /// Called when a frame is received.
        /// </summary>
        private async void OnImageGrabbed(object? sender, ImageGrabbedEventArgs e)
        {
            IsGrabbing = _cameraService.IsGrabbing;

            // Clone because we don’t control when the original GrabResult gets disposed.
            using IGrabResult result = e.GrabResult.Clone();

            try
            {
                // Always update the image on the UI thread.
                await Application.Current.Dispatcher.InvokeAsync(() =>
                {
                    var frame = BaslerCameraSample.ConvertGrabResultToBitmap(result);
                    CurrentFrame = frame;
                });
            }
            catch (InvalidOperationException ex)
            {
                MessageBox.Show($”Failed to grab. Error: {ex.Message}”);
            }
        }
    }
}

using Basler.Pylon; // ImageGrabbedEventArgs

using BaslerSamples; // Camera control library

// The author uses BindableBase / DelegateCommand from a Common namespace.

// Please adapt to your environment.

// using Common;

using System;

using System.Windows;

using System.Windows.Media.Imaging;

using Application = System.Windows.Application;

namespace BaslerGUISample.ViewModels

{

public partial class MainViewModel : BindableBase

{

private readonly BaslerCameraSample _cameraService = new();

public MainViewModel()

{

// ConnectCommand, DisconnectCommand, SnapCommand are the same as the previous article.

StartCommand = new DelegateCommand(Start, () => IsConnected && !IsGrabbing);

StopCommand = new DelegateCommand(Stop, () => IsConnected && IsGrabbing);

}

private bool _isConnected;

public bool IsConnected

{

get => _isConnected;

set => SetProperty(ref _isConnected, value);

}

/// <summary>

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

/// </summary>

private bool _isGrabbing;

public bool IsGrabbing

{

get => _isGrabbing;

set => SetProperty(ref _isGrabbing, value);

}

private BitmapSource? _currentFrame;

public BitmapSource? CurrentFrame

{

get => _currentFrame;

set => SetProperty(ref _currentFrame, value);

}

public void Start()

{

if (IsConnected == false) return;

// Register handler (remove first to avoid duplicates)

_cameraService.RemoveImageGrabbedEventHandler(OnImageGrabbed);

_cameraService.AddImageGrabbedEventHandler(OnImageGrabbed);

_cameraService.StartLive();

IsGrabbing = _cameraService.IsGrabbing;

}

public void Stop()

{

if (_cameraService.IsConnected == false) return;

_cameraService.StopGrabbing();

// Unregister handler

_cameraService.RemoveImageGrabbedEventHandler(OnImageGrabbed);

IsGrabbing = _cameraService.IsGrabbing;

}

/// <summary>

/// Called when a frame is received.

/// </summary>

private async void OnImageGrabbed(object? sender, ImageGrabbedEventArgs e)

{

IsGrabbing = _cameraService.IsGrabbing;

// Clone because we don’t control when the original GrabResult gets disposed.

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

try

{

// Always update the image on the UI thread.

await Application.Current.Dispatcher.InvokeAsync(() =>

{

var frame = BaslerCameraSample.ConvertGrabResultToBitmap(result);

CurrentFrame = frame;

});

}

catch (InvalidOperationException ex)

{

MessageBox.Show($“Failed to grab. Error: {ex.Message}”);

}

Example Run

Click Connect, then Live to start continuous preview. Click Stop to stop streaming.

GUILiveSample

Common Pitfalls & Fixes

Colors look wrong (color cameras) Match conversion to the camera’s pixel format (e.g., PixelType.BGR8packed and PixelFormats.Bgr24).
Event handler registered twice Remove (-=) once before adding (+=), as shown in Start().
Rendering can’t keep up with camera FPS If the camera FPS is high, you often don’t need to render every frame. You can drop frames by using Monitor.TryEnter or Interlocked.Exchange to avoid overlapping UI updates.

Summary

Implemented smooth live view using pylon’s event-driven acquisition
Updated WPF UI safely through the Dispatcher
The structure is flexible and works well with ROI and resolution changes
Combining live preview with triggers is already valuable for many lab/inspection setups

Next: HUD Overlay

In the next article, we will overlay a HUD showing values such as FPS, exposure time, and gain on top of the live preview.

2025-12-17

Displaying a Basler Camera Snapshot in a WPF App (pylon SDK / C# / .NET 8)

“You have working code, but you want to preview images in a GUI as quickly as possible.” As a first step, this article builds a minimal WPF viewer with three buttons: Connect / Disconnect / Snap. With a single click, the app captures one frame and displays it in a WPF Image control.

Example run

Goal

Operate the camera using three buttons: Connect / Disconnect / Snap
Display the snapped frame in an Image
Ensure the camera is properly disconnected and disposed on exit (avoid resource leaks)

Project Structure

We reuse the existing BaslerCameraSample (class library) created in earlier articles (e.g., software-trigger capture) and add a new WPF application project BaslerGUISample, referencing that library.

View (XAML)

Place three buttons and an Image preview.

Window x:Class=”BaslerGUISample.MainWindow”
        xmlns=”http://schemas.microsoft.com/winfx/2006/xaml/presentation”
        xmlns:x=”http://schemas.microsoft.com/winfx/2006/xaml”
        xmlns:d=”http://schemas.microsoft.com/expression/blend/2008″
        xmlns:mc=”http://schemas.openxmlformats.org/markup-compatibility/2006″
        xmlns:local=”clr-namespace:BaslerGUISample”
        mc:Ignorable=”d”
        Title=”BaslerGUISample” Height=”450″ Width=”450″ Closing=”Window_Closing”>
  <Grid>
    <Grid.RowDefinitions>
      <RowDefinition Height=”Auto”/>
      <RowDefinition Height=”*”/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
      <ColumnDefinition Width=”*”/>
      <ColumnDefinition Width=”*”/>
      <ColumnDefinition Width=”*”/>
    </Grid.ColumnDefinitions>

    <Grid Grid.Row=”0″ Grid.Column=”0″>
      <Button Content=”Connect” Width=”80″ Margin=”4,0″ Command=”{Binding ConnectCommand}”/>
    </Grid>
    <Grid Grid.Row=”0″ Grid.Column=”1″>
      <Button Content=”Disconnect” Width=”80″ Margin=”4,0″ Command=”{Binding DisconnectCommand}”/>
    </Grid>
    <Grid Grid.Row=”0″ Grid.Column=”2″>
      <Button Content=”Snap” Width=”80″ Margin=”4,0″ Command=”{Binding SnapCommand}”/>
    </Grid>

    <Grid Grid.Row=”1″ Grid.Column=”0″ Grid.ColumnSpan=”3″>
      <Image x:Name=”PreviewImage” Source=”{Binding CurrentFrame}” Stretch=”UniformToFill”/>
    </Grid>
  </Grid>
</Window>

Window x:Class=“BaslerGUISample.MainWindow”

xmlns=“http://schemas.microsoft.com/winfx/2006/xaml/presentation”

xmlns:x=“http://schemas.microsoft.com/winfx/2006/xaml”

xmlns:d=“http://schemas.microsoft.com/expression/blend/2008”

xmlns:mc=“http://schemas.openxmlformats.org/markup-compatibility/2006”

xmlns:local=“clr-namespace:BaslerGUISample”

mc:Ignorable=“d”

Title=“BaslerGUISample” Height=“450” Width=“450” Closing=“Window_Closing”>

<Grid>

<Grid.RowDefinitions>

</Grid.RowDefinitions>

<Grid.ColumnDefinitions>

</Grid.ColumnDefinitions>

</Grid>

</Grid>

</Grid>

</Grid>

</Window>

Designer view example:

XAML layout

In code-behind, set DataContext = new MainViewModel(); and make sure the camera disconnects in Window_Closing (shown later).

ViewModel

Any MVVM base is fine (BindableBase / DelegateCommand are user-defined in this article; implementation omitted)
Use the existing BaslerCameraSample for connect/snap/disconnect
Bind CurrentFrame (BitmapSource) to Image.Source
If the UI freezes while connecting, consider making Connect asynchronous later

using BaslerSamples;
// The author implements BindableBase and DelegateCommand under a Common namespace.
// Please adapt to your own environment.
// using Common; 
using System;
using System.ComponentModel;
using System.Windows;
using System.Windows.Media.Imaging;

namespace BaslerGUISample.ViewModels
{
    public partial class MainViewModel : BindableBase
    {
        private readonly BaslerCameraSample _cameraService = new();

        public MainViewModel()
        {
            ConnectCommand    = new DelegateCommand(Connect,    () => !IsConnected);
            DisconnectCommand = new DelegateCommand(Disconnect, () =>  IsConnected);
            SnapCommand       = new DelegateCommand(Snap,       () =>  IsConnected);

            Connect(); // Call this if you want to auto-connect at startup
        }

        private bool _isConnected;
        public bool IsConnected
        {
            get => _isConnected;
            set
            {
                SetProperty(ref _isConnected, value);
            }
        }

        private BitmapSource? _currentFrame;
        public BitmapSource? CurrentFrame
        {
            get => _currentFrame;
            set => SetProperty(ref _currentFrame, value);
        }

        public DelegateCommand ConnectCommand    { get; }
        public DelegateCommand DisconnectCommand { get; }
        public DelegateCommand SnapCommand       { get; }

        public void Connect()
        {
            IsConnected = _cameraService.Connect();
        }

        /// <summary>
        /// Disconnects the camera.
        /// </summary>
        public void Disconnect()
        {
            _cameraService.Disconnect();
            IsConnected = _cameraService.IsConnected;
        }

        public void Snap()
        {
            try
            {
                CurrentFrame = _cameraService.SnapToBitmapSource();
            }
            catch (InvalidOperationException ex)
            {
                // Show a message box when the camera is not connected.
                MessageBox.Show($”Failed to snap. Error: {ex.Message}”);
            }
        }
    }
}

using BaslerSamples;

// The author implements BindableBase and DelegateCommand under a Common namespace.

// Please adapt to your own environment.

// using Common;

using System;

using System.ComponentModel;

using System.Windows;

using System.Windows.Media.Imaging;

namespace BaslerGUISample.ViewModels

{

public partial class MainViewModel : BindableBase

{

private readonly BaslerCameraSample _cameraService = new();

public MainViewModel()

{

ConnectCommand = new DelegateCommand(Connect, () => !IsConnected);

DisconnectCommand = new DelegateCommand(Disconnect, () => IsConnected);

SnapCommand = new DelegateCommand(Snap, () => IsConnected);

Connect(); // Call this if you want to auto-connect at startup

}

private bool _isConnected;

public bool IsConnected

{

get => _isConnected;

set

{

SetProperty(ref _isConnected, value);

}

private BitmapSource? _currentFrame;

public BitmapSource? CurrentFrame

{

get => _currentFrame;

set => SetProperty(ref _currentFrame, value);

}

public DelegateCommand ConnectCommand { get; }

public DelegateCommand DisconnectCommand { get; }

public DelegateCommand SnapCommand { get; }

public void Connect()

{

IsConnected = _cameraService.Connect();

}

/// <summary>

/// Disconnects the camera.

/// </summary>

public void Disconnect()

{

_cameraService.Disconnect();

IsConnected = _cameraService.IsConnected;

}

public void Snap()

{

try

{

CurrentFrame = _cameraService.SnapToBitmapSource();

}

catch (InvalidOperationException ex)

{

// Show a message box when the camera is not connected.

MessageBox.Show($“Failed to snap. Error: {ex.Message}”);

}

(Reference) MainWindow Code-Behind

public partial class MainWindow : Window
{
    private readonly MainViewModel _viewModel;

    public MainWindow()
    {
        InitializeComponent();
        _viewModel = new MainViewModel();
        DataContext = _viewModel;
    }

    /// <summary>
    /// Disconnect the camera before the window closes.
    /// </summary>
    private void Window_Closing(object sender, System.ComponentModel.CancelEventArgs e)
    {
        _viewModel.Disconnect();
    }
}

public partial class MainWindow : Window

{

private readonly MainViewModel _viewModel;

public MainWindow()

{

InitializeComponent();

_viewModel = new MainViewModel();

DataContext = _viewModel;

}

/// <summary>

/// Disconnect the camera before the window closes.

/// </summary>

private void Window_Closing(object sender, System.ComponentModel.CancelEventArgs e)

{

_viewModel.Disconnect();

}

Add `Disconnect()` to `BaslerCameraSample`

Since the earlier articles focused mainly on connecting and grabbing, we now add a proper Disconnect() to ensure resources are released when the app exits.

public void Disconnect()
{
    if (Camera != null)
    {
        if (IsGrabbing) StopGrabbing();
        if (Camera.IsOpen) Camera.Close();

        Camera.Dispose();
        Camera = null;
        Console.WriteLine(“Camera disconnected.”);
    }
}

public void Disconnect()

{

if (Camera != null)

{

if (IsGrabbing) StopGrabbing();

if (Camera.IsOpen) Camera.Close();

Camera.Dispose();

Camera = null;

Console.WriteLine(“Camera disconnected.”);

}

Implementation Tips / Common Pitfalls

UI thread updates When you move on to event-driven continuous acquisition, ImageGrabbed is raised from a non-UI thread. In that case, update CurrentFrame via Application.Current.Dispatcher.Invoke(...) (planned for a future article).
Stretch behavior UniformToFill: fills without margins (may crop) Uniform: shows the entire image (may add margins)
Error handling If connect/snap fails, show user-friendly feedback (e.g., MessageBox) instead of silently failing.

Summary

Implemented a minimal WPF viewer (Connect / Disconnect / Snap / preview)
Used MVVM to separate View and camera-control logic; bound BitmapSource to Image.Source
Added Disconnect() to reliably release camera resources on exit
This becomes a foundation for event-driven continuous preview in the next steps

Next Article Preview

Next, we’ll explain how to continuously acquire images using event-driven grabbing while updating the UI asynchronously. We’ll also connect it with queue-based saving and OpenCV display, aiming for a practical viewer.

About the Author

@MilleVision Sharing practical knowledge on industrial cameras and machine vision development, with a Basler pylon SDK × C# series.

Full Sample Code Package

A complete C# project (including unit tests) is available on BOOTH. It includes the omitted BindableBase and DelegateCommand implementations.

Exposure / gain / frame rate / ROI
Event-driven acquisition
Burst capture
Saving and logging
Updates planned alongside new articles

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

2025-12-15

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);
    }
}

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();
    }
}

// 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.”);
}

[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);
}

[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}”);
        }
    }
}

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}”);
}

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

📥 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;
    }
}

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.”);
}

[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

Tool: PFS → JSON / C# DTO (Web)

Drag & drop a PFS file to generate PfsSettingsDto.cs and JSON automatically.

https://pfs.millevision.net/

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]

🔧 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();
            }
        }
    }
}

// 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();
    }
}

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;
    }
}

/// <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);
}

/// <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);
    }
}

/// <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;

/// <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();
}

/// <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.”);
    }
}

[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]

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));
}

/// <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();
}

/// <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;
    }
}

[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

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();
}

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

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.”);
    }
}

[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);

/// <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;
}

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();

_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”);
}

[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

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);
}

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);

📷 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));
}

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

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

タグ: Basler

Environment / Prerequisites

Goals

XAML: Two Layers + ROI Layer (Shared Transform)

HalfConverter (For Center Crosshair)

Code-Behind: Zoom / Pan

ROI Handling and Applying It in Real Apps

Example Screens

Summary

Environment / Assumptions

Goal

UI (XAML)

Model Side (BaslerCameraSample)

Add/Remove event handlers

ViewModel: Event-Driven Preview → Update BitmapSource

Example Run

Common Pitfalls & Fixes

Summary

Next: HUD Overlay

Goal

Project Structure

View (XAML)

ViewModel

(Reference) MainWindow Code-Behind

Add Disconnect() to BaslerCameraSample

Implementation Tips / Common Pitfalls

Summary

Next Article Preview

About the Author

Full Sample Code Package

✅ 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

Tool: PFS → JSON / C# DTO (Web)

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)

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

Model Side (`BaslerCameraSample`)

ViewModel: Event-Driven Preview → Update `BitmapSource`

Add `Disconnect()` to `BaslerCameraSample`

⏱ 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

💡 `AcquisitionFrameRate` vs. `ResultingFrameRate`

✔ Is `AcquisitionFrameRateEnable` set to true?