タグ: .NET

Implementing Background Subtraction (Motion Detection) in WPF with Basler pylon SDK + OpenCV (C# / .NET 8)

Once your live view is working, a natural next step is highlighting only what moved. In this article, we implement a simple background subtraction pipeline to detect motion regions, draw bounding boxes, and display the results in a WPF Image.

✅ Environment

Because this implementation converts between BitmapSource and Mat, install the NuGet package:

OpenCvSharp4.WpfExtensions

Item	Details
Camera	Basler acA2500-14gm
SDK	pylon Camera Software Suite
Language / GUI	C# / .NET 8 / WPF
Libraries	OpenCvSharp4 (`OpenCvSharp4.Windows`, `OpenCvSharp4.WpfExtensions`)

Recommended camera settings (for stable subtraction): Set ExposureAuto=Off, GainAuto=Off, and keep illumination stable (reduce flicker).

Prerequisites from earlier posts (reference):

Implementation Overview

We will follow this workflow:

Capture a background frame (a frame with no motion)
Preprocess with Gaussian blur
Compute absolute difference (AbsDiff) → threshold (Threshold) → opening (MorphologyEx(Open))
Extract contours (FindContours) → draw bounding rectangles
Display the processed frame in WPF

Adding opening after threshold helps remove small speckle noise.

🧩 XAML (Minimal UI)

Add one column for a “Set BG” button and sliders for tuning.

<Grid Grid.Row=”2″ Grid.Column=”0″>
    <Button Content=”Set BG” Width=”80″ Margin=”0,5″ ToolTip=”Capture background”
            Command=”{Binding SetBackgroundCommand}”/>
</Grid>
<Grid Grid.Row=”2″ Grid.Column=”1″ ColumnSpan=”2″ VerticalAlignment=”Center”>
    <StackPanel Orientation=”Horizontal”>
        <TextBlock Text=”Threshold:” Margin=”10,0″/>
        <Slider x:Name=”ThresholdSlider” Minimum=”0″ Maximum=”255″
                Value=”{Binding DetectionThreshold}” Width=”100″ SmallChange=”1″/>
    </StackPanel>
</Grid>
<Grid Grid.Row=”2″ Grid.Column=”3″ ColumnSpan=”2″ VerticalAlignment=”Center”>
    <StackPanel Orientation=”Horizontal”>
        <TextBlock Text=”Min area:” Margin=”10,0″/>
        <Slider x:Name=”MinAreaSlider” Minimum=”200″ Maximum=”100000″
                Value=”{Binding MinArea}” Width=”100″ SmallChange=”100″/>
    </StackPanel>
</Grid>

<Button Content=“Set BG” Width=“80” Margin=“0,5” ToolTip=“Capture background”

Command=“{Binding SetBackgroundCommand}”/>

</Grid>

<Slider x:Name=“ThresholdSlider” Minimum=“0” Maximum=“255”

Value=“{Binding DetectionThreshold}” Width=“100” SmallChange=“1”/>

</StackPanel>

</Grid>

<Slider x:Name=“MinAreaSlider” Minimum=“200” Maximum=“100000”

Value=“{Binding MinArea}” Width=“100” SmallChange=“100”/>

</StackPanel>

</Grid>

BackgroundSubtraction_View

🔧 Core Code (Background Subtraction Pipeline)

This logic ideally belongs in the Model layer, but to keep diffs small from previous articles, it is implemented in the ViewModel.

The author tested on a Mono8 camera. If you use a color camera, convert to grayscale as needed.

The ViewModel implements IDisposable to ensure OpenCV Mat resources are released.

using Basler.Pylon;
using BaslerSamples;
using Common;
using OpenCvSharp;
using OpenCvSharp.WpfExtensions;
using System;
using System.Threading;
using System.Threading.Tasks;
using System.Windows;
using System.Windows.Media.Imaging;
using Application = System.Windows.Application;
using Size = OpenCvSharp.Size;

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

        // Flag: capture the next arriving frame as the background
        private volatile bool _captureBgNext = false;

        public MainViewModel()
        {
            // Other commands omitted
            SetBackgroundCommand = new DelegateCommand(SetBackground, () => IsGrabbing);
        }

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

        private Mat? _backgroundFrame;
        /// <summary>
        /// Background frame used for subtraction.
        /// </summary>
        public Mat? BackgroundFrame
        {
            get => _backgroundFrame;
            set
            {
                var old = _backgroundFrame;
                if (SetProperty(ref _backgroundFrame, value))
                {
                    old?.Dispose();
                    BgBlurCached = null; // Drop blur cache when background changes
                }
            }
        }

        private Mat? _bgBlurCached;
        /// <summary>
        /// Cached blurred background (to avoid blurring every frame).
        /// </summary>
        public Mat? BgBlurCached
        {
            get => _bgBlurCached;
            set
            {
                var old = _bgBlurCached;
                if (SetProperty(ref _bgBlurCached, value))
                {
                    old?.Dispose();
                }
            }
        }

        /// <summary>
        /// True if a background frame has been set.
        /// </summary>
        public bool HasBackground => BackgroundFrame != null;

        private double _detectionThreshold = 30.0;
        /// <summary>
        /// Threshold for motion detection.
        /// </summary>
        public double DetectionThreshold
        {
            get => _detectionThreshold;
            set => SetProperty(ref _detectionThreshold, value);
        }

        private double _minArea = 800.0;
        /// <summary>
        /// Minimum bounding-rect area to keep as a detection.
        /// </summary>
        public double MinArea
        {
            get => _minArea;
            set => SetProperty(ref _minArea, value);
        }

        /// <summary>
        /// Command to capture the background image.
        /// </summary>
        public DelegateCommand SetBackgroundCommand { get; }

        public void Dispose()
        {
            if (IsGrabbing)
            {
                Stop();
            }
            Disconnect();
            BackgroundFrame = null;
            BgBlurCached = null;
        }

        /// <summary>
        /// Capture the next arriving frame as the background.
        /// </summary>
        public void SetBackground()
        {
            _captureBgNext = true;
            BgBlurCached = null;
        }

        private int _updating; // overload protection (drop frames while processing)

        private async void OnImageGrabbed(object? sender, ImageGrabbedEventArgs e)
        {
            IsGrabbing = _cameraService.IsGrabbing;

            if (Interlocked.Exchange(ref _updating, 1) == 1) return;
            try
            {
                await UpdateCurrentFrame(e.GrabResult);
                // HUD update (~10 Hz) omitted
            }
            catch (InvalidOperationException ex)
            {
                MessageBox.Show($”Failed to grab. Error: {ex.Message}”);
            }
            catch (TaskCanceledException)
            {
                // Can occur if the app closes while live view is running.
            }
            finally
            {
                Interlocked.Exchange(ref _updating, 0);
            }
        }

        /// <summary>
        /// Main frame-update routine.
        /// Runs background subtraction, draws bounding boxes, and updates CurrentFrame.
        /// </summary>
        private async Task UpdateCurrentFrame(IGrabResult result)
        {
            if (!result.GrabSucceeded) return;

            // 1) GrabResult -> Mat (reuse implementation from the Mat article)
            using Mat raw = result.ToMat();

            // Ensure single-channel input (safe for color cameras too)
            using Mat frame = new Mat();
            if (raw.Channels() == 1)
            {
                raw.CopyTo(frame);
            }
            else
            {
                Cv2.CvtColor(raw, frame, ColorConversionCodes.BGR2GRAY);
            }

            if (_captureBgNext)
            {
                BackgroundFrame = frame.Clone();
                _captureBgNext = false;
            }

            // If background isn’t set, just display the frame
            if (HasBackground == false)
            {
                await SetCurrentFrame(frame);
                return;
            }

            // 2) Preprocess: blur
            using Mat blur = new();
            Cv2.GaussianBlur(frame, blur, new Size(5, 5), 0);

            // Build blurred background cache if missing
            if (BgBlurCached == null || BgBlurCached.Empty())
            {
                BgBlurCached = new Mat();
                Cv2.GaussianBlur(BackgroundFrame!, BgBlurCached, new Size(5, 5), 0);
            }

            // 3) diff -> threshold -> opening
            using var diff = new Mat();
            Cv2.Absdiff(blur, BgBlurCached, diff);

            using var bw = new Mat();
            Cv2.Threshold(diff, bw, DetectionThreshold, 255, ThresholdTypes.Binary);

            using var k = Cv2.GetStructuringElement(MorphShapes.Rect, new Size(3, 3));
            Cv2.MorphologyEx(bw, bw, MorphTypes.Open, k, iterations: 1);

            // 4) contours -> bounding boxes
            Cv2.FindContours(bw, out var contours, out _, RetrievalModes.External, ContourApproximationModes.ApproxSimple);

            using var colorFrame = new Mat();
            Cv2.CvtColor(frame, colorFrame, ColorConversionCodes.GRAY2BGR);

            int thick = Math.Max(1, colorFrame.Width / 400);
            foreach (var c in contours)
            {
                var rect = Cv2.BoundingRect(c);
                if (rect.Width * rect.Height < MinArea) continue;
                Cv2.Rectangle(colorFrame, rect, Scalar.Red, thick);
            }

            // 5) display
            await SetCurrentFrame(colorFrame);
        }

        private readonly object _lock = new();

        /// <summary>
        /// Converts a Mat to BitmapSource and updates CurrentFrame on the UI thread.
        /// </summary>
        private async Task SetCurrentFrame(Mat mat)
        {
            BitmapSource src = mat.ToBitmapSource();
            src.Freeze(); // Required because it was created on a non-UI thread

            await Application.Current.Dispatcher.BeginInvoke(() =>
            {
                lock (_lock) { CurrentFrame = src; }
            });
        }
    }
}

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

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

using Basler.Pylon;

using BaslerSamples;

using Common;

using OpenCvSharp;

using OpenCvSharp.WpfExtensions;

using System;

using System.Threading;

using System.Threading.Tasks;

using System.Windows;

using System.Windows.Media.Imaging;

using Application = System.Windows.Application;

using Size = OpenCvSharp.Size;

namespace BaslerGUISample.ViewModels

{

public partial class MainViewModel : BindableBase, IDisposable

{

BaslerCameraSample _cameraService = new BaslerCameraSample();

// Flag: capture the next arriving frame as the background

private volatile bool _captureBgNext = false;

public MainViewModel()

{

// Other commands omitted

SetBackgroundCommand = new DelegateCommand(SetBackground, () => IsGrabbing);

}

private bool _isGrabbing;

/// <summary>

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

/// </summary>

public bool IsGrabbing

{

get => _isGrabbing;

set => SetProperty(ref _isGrabbing, value);

}

private Mat? _backgroundFrame;

/// <summary>

/// Background frame used for subtraction.

/// </summary>

public Mat? BackgroundFrame

{

get => _backgroundFrame;

set

{

var old = _backgroundFrame;

if (SetProperty(ref _backgroundFrame, value))

{

old?.Dispose();

BgBlurCached = null; // Drop blur cache when background changes

}

private Mat? _bgBlurCached;

/// <summary>

/// Cached blurred background (to avoid blurring every frame).

/// </summary>

public Mat? BgBlurCached

{

get => _bgBlurCached;

set

{

var old = _bgBlurCached;

if (SetProperty(ref _bgBlurCached, value))

{

old?.Dispose();

}

/// <summary>

/// True if a background frame has been set.

/// </summary>

public bool HasBackground => BackgroundFrame != null;

private double _detectionThreshold = 30.0;

/// <summary>

/// Threshold for motion detection.

/// </summary>

public double DetectionThreshold

{

get => _detectionThreshold;

set => SetProperty(ref _detectionThreshold, value);

}

private double _minArea = 800.0;

/// <summary>

/// Minimum bounding-rect area to keep as a detection.

/// </summary>

public double MinArea

{

get => _minArea;

set => SetProperty(ref _minArea, value);

}

/// <summary>

/// Command to capture the background image.

/// </summary>

public DelegateCommand SetBackgroundCommand { get; }

public void Dispose()

{

if (IsGrabbing)

{

Stop();

}

Disconnect();

BackgroundFrame = null;

BgBlurCached = null;

}

/// <summary>

/// Capture the next arriving frame as the background.

/// </summary>

public void SetBackground()

{

_captureBgNext = true;

BgBlurCached = null;

}

private int _updating; // overload protection (drop frames while processing)

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

{

IsGrabbing = _cameraService.IsGrabbing;

if (Interlocked.Exchange(ref _updating, 1) == 1) return;

try

{

await UpdateCurrentFrame(e.GrabResult);

// HUD update (~10 Hz) omitted

}

catch (InvalidOperationException ex)

{

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

}

catch (TaskCanceledException)

{

// Can occur if the app closes while live view is running.

}

finally

{

Interlocked.Exchange(ref _updating, 0);

}

/// <summary>

/// Main frame-update routine.

/// Runs background subtraction, draws bounding boxes, and updates CurrentFrame.

/// </summary>

private async Task UpdateCurrentFrame(IGrabResult result)

{

if (!result.GrabSucceeded) return;

// 1) GrabResult -> Mat (reuse implementation from the Mat article)

using Mat raw = result.ToMat();

// Ensure single-channel input (safe for color cameras too)

using Mat frame = new Mat();

if (raw.Channels() == 1)

{

raw.CopyTo(frame);

}

else

{

Cv2.CvtColor(raw, frame, ColorConversionCodes.BGR2GRAY);

}

if (_captureBgNext)

{

BackgroundFrame = frame.Clone();

_captureBgNext = false;

}

// If background isn’t set, just display the frame

if (HasBackground == false)

{

await SetCurrentFrame(frame);

return;

}

// 2) Preprocess: blur

using Mat blur = new();

Cv2.GaussianBlur(frame, blur, new Size(5, 5), 0);

// Build blurred background cache if missing

if (BgBlurCached == null || BgBlurCached.Empty())

{

BgBlurCached = new Mat();

Cv2.GaussianBlur(BackgroundFrame!, BgBlurCached, new Size(5, 5), 0);

}

// 3) diff -> threshold -> opening

using var diff = new Mat();

Cv2.Absdiff(blur, BgBlurCached, diff);

using var bw = new Mat();

Cv2.Threshold(diff, bw, DetectionThreshold, 255, ThresholdTypes.Binary);

using var k = Cv2.GetStructuringElement(MorphShapes.Rect, new Size(3, 3));

Cv2.MorphologyEx(bw, bw, MorphTypes.Open, k, iterations: 1);

// 4) contours -> bounding boxes

Cv2.FindContours(bw, out var contours, out _, RetrievalModes.External, ContourApproximationModes.ApproxSimple);

using var colorFrame = new Mat();

Cv2.CvtColor(frame, colorFrame, ColorConversionCodes.GRAY2BGR);

int thick = Math.Max(1, colorFrame.Width / 400);

foreach (var c in contours)

{

var rect = Cv2.BoundingRect(c);

if (rect.Width * rect.Height < MinArea) continue;

Cv2.Rectangle(colorFrame, rect, Scalar.Red, thick);

}

// 5) display

await SetCurrentFrame(colorFrame);

}

private readonly object _lock = new();

/// <summary>

/// Converts a Mat to BitmapSource and updates CurrentFrame on the UI thread.

/// </summary>

private async Task SetCurrentFrame(Mat mat)

{

BitmapSource src = mat.ToBitmapSource();

src.Freeze(); // Required because it was created on a non-UI thread

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

{

lock (_lock) { CurrentFrame = src; }

});

}

Code-Behind

Dispose the ViewModel when the window closes.

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

/// <summary>

/// Dispose ViewModel before the window closes.

/// </summary>

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

{

_viewModel.Dispose();

}

Example Run

Click Set BG to capture the background frame.

BackgroundSubtraction_BG 2. Move an object in the scene → motion regions are detected and boxed. 3. Use sliders to tune sensitivity and minimum area.

BackgroundSubtraction_Detect

Tuning Tips

Retake background when illumination changes
Threshold: increase to suppress sensor noise; decrease to detect subtle motion
Morphology iterations: increase if edges are jagged; decrease if boxes “bloat”
Min area: simple filter to reduce false positives
Speed-ups:
- Apply camera ROI to reduce the processed area
- Cv2.Resize to process a smaller image (scale coordinates back)
- Cache blurred background (as shown) to avoid blurring every frame

Common Pitfalls

Symptom	Likely Cause	Fix
Nothing detected	Threshold too high / changes too small	Lower threshold or increase blur kernel
Entire frame white	Auto exposure/gain is fluctuating	Set `ExposureAuto/GainAuto=Off`, stabilize lighting
Too many speckles	Sensor noise / tiny vibration	Keep opening (`MorphTypes.Open`) and tune kernel
UI freezes	Processing too heavy	Move processing to another Task, use ROI / resize
Memory grows	`Mat.Dispose()` missing	Use `using` blocks (as shown) and cache carefully

Summary

Background subtraction highlights only moving regions
Fixed exposure/gain + stable lighting improves reliability
Tune threshold, minimum area, and morphology to balance sensitivity vs noise
ROI and resizing are effective for performance

2026-01-19

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

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

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

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

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

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

✔ What You Will Learn

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

✔ Environment

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

🔍 What Is ROI?

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

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

Reducing ROI has several benefits:

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

🔧 Setting ROI in C#

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

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

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

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

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

public bool SetOffsetX(int offsetX)

=> SetPLCameraParamter(PLCamera.OffsetX, offsetX);

public bool SetOffsetY(int offsetY)

=> SetPLCameraParamter(PLCamera.OffsetY, offsetY);

public bool SetWidth(int width)

=> SetPLCameraParamter(PLCamera.Width, width);

public bool SetHeight(int height)

=> SetPLCameraParamter(PLCamera.Height, height);

Setting ROI in one operation

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

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

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

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

    return true;
}

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

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

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

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

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

{

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

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

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

{

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

return false;

}

else

{

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

return false;

}

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

{

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

return false;

}

else

{

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

return false;

}

return true;

}

public int GetWidth()

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

public int GetHeight()

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

public int GetSensorWidth()

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

public int GetSensorHeight()

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

ROI using `Rect` (WPF)

using Windows;

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

using Windows;

public bool SetROI(Rect roi)

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

📈 Why ROI Increases Frame Rate

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

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

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

✔ Constraints When Setting ROI

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

To inspect the increment value:

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

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

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

public long GetInc(IntegerName parameter)

{

if (Camera == null || !IsConnected)

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

if (Camera.Parameters[parameter].IsReadable)

{

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

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

return inc;

}

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

}

Example test:

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

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

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

[TestMethod()]

public void GetIncTest()

{

if (!_baslerCameraSample.IsConnected)

_baslerCameraSample.Connect();

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

Assert.AreEqual(1, incWidth);

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

Assert.AreEqual(1, incHeight);

}

📏 Testing Frame Rate with ROI

static BaslerCameraSample _baslerCameraSample = new BaslerCameraSample();

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

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

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

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

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

static BaslerCameraSample _baslerCameraSample = new BaslerCameraSample();

[TestMethod()]

public void SetROITest()

{

_baslerCameraSample.Connect();

_baslerCameraSample.EnableFrameRate(true);

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

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

var fps1 = _baslerCameraSample.GetResultingFrameRate();

_baslerCameraSample.BurstCapture(5, “ROITest_640x480”);

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

var fps2 = _baslerCameraSample.GetResultingFrameRate();

_baslerCameraSample.BurstCapture(5, “ROITest_2592x1944”);

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

Assert.IsTrue(fps1 > fps2);

}

🧪 Real-World Comparison

Full Resolution (2592 × 1944)

Frame timestamps demonstrate slower readout:

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

ROI (640 × 480)

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

Summary Comparison

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

→ ROI doubles the effective frame rate in this test.

⚠️ Common Errors & Solutions

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

📝 Summary

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

筆者: @MilleVision

📦 Full Sample Code Package

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

2025-12-07

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

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

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

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

✔ What You Will Learn

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

✔ Environment

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

🔄 Basic Burst Capture: Capturing N Consecutive Frames

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

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

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

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

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

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

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

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

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

        var elapsed = sw.ElapsedMilliseconds;

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

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

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

タグ: .NET

✅ Environment

Implementation Overview

🧩 XAML (Minimal UI)

🔧 Core Code (Background Subtraction Pipeline)

Code-Behind

Example Run

Tuning Tips

Common Pitfalls

Summary

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)

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

✔ What You Will Learn

✔ Environment

🔍 What Is ROI?

🔧 Setting ROI in C#

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

ROI using `Rect` (WPF)