How to Control and Verify Frame Rate Using the Basler pylon SDK (C# / .NET 8)
When developing vision applications—especially for real-time inspection or production environments—one of the most important performance metrics is frame rate (fps). You may need to know:
- Can the camera actually capture frames at the rate I’ve set?
- What limits the maximum achievable frame rate?
- How do I read both the requested and the actual frame rate?
This article explains how to set frame rate, enable frame-rate control, and check the actual resulting fps using the Basler pylon SDK in C#.
✔ Environment
| Item | Details |
|---|---|
| Camera | Basler acA2500-14gm |
| SDK | Basler pylon Camera Software Suite |
| Lang | C# / .NET 8 (Windows) |
💡 AcquisitionFrameRate vs. ResultingFrameRate
| Parameter | Meaning |
|---|---|
| AcquisitionFrameRate | The requested frame rate (user setting) |
| ResultingFrameRate | The actual achievable frame rate calculated by the camera |
Even if you set 30 fps, the resulting fps may be lower depending on exposure time, ROI, interface bandwidth, etc.
🔧 Enabling Frame Rate Control
Frame-rate control must be explicitly enabled:
|
1 2 3 4 5 6 7 |
/// <summary> /// Enable or disable frame-rate control. /// When enabled, the camera attempts to acquire images at the specified frame rate. /// When disabled, the camera operates at the maximum possible fps. /// </summary> public bool EnableFrameRate(bool enable) => SetPLCameraParameter(PLCamera.AcquisitionFrameRateEnable, enable); |
Helper method for Boolean parameters
AcquisitionFrameRateEnable is a boolean parameter (IBoolean), so we define:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
public bool SetPLCameraParameter(BooleanName parameter, bool value) { if (Camera == null || !IsConnected) return false; if (Camera.Parameters[parameter].IsWritable) { Camera.Parameters[parameter].SetValue(value); Console.WriteLine($“{parameter} set to {value}.”); return true; } Console.WriteLine($“{parameter} is not writable.”); return false; } |
🔧 Setting the Desired Frame Rate
|
1 2 |
public bool SetFrameRate(double frameRate) => SetPLCameraParameter(PLCamera.AcquisitionFrameRateAbs, frameRate); |
💡 Depending on the camera model, the parameter name may be:
AcquisitionFrameRateAcquisitionFrameRateAbs
Verify via pylon Viewer or by checking:
|
1 |
Camera.Parameters.Contains(PLCamera.AcquisitionFrameRateAbs) |
📏 Reading the Requested and Actual Frame Rate
Requested (user-set) frame rate:
|
1 2 |
public double GetFrameRate() => GetPLCameraParameter(PLCamera.AcquisitionFrameRateAbs); |
Actual achievable rate:
|
1 2 |
public double GetResultingFrameRate() => GetPLCameraParameter(PLCamera.ResultingFrameRateAbs); |
ResultingFrameRate is essential—it tells you whether your settings are physically achievable given the exposure time, bandwidth, and ROI.
🚧 What Limits Maximum Frame Rate?
1. Image Size / ROI
Smaller ROI = fewer pixels = higher possible fps.
2. Exposure Time
If exposure is too long, the sensor cannot start the next frame.
Example:
ExposureTime = 50,000 µs (50 ms) → max possible fps is 20 fps.
3. Interface Bandwidth (USB3 / GigE)
High-resolution images or 24-bit RGB increase bandwidth usage, lowering achievable fps.
📝 When Your Frame Rate Setting Is Ignored
If you set AcquisitionFrameRate but nothing changes, check:
✔ Is AcquisitionFrameRateEnable set to true?
If false, the camera ignores your setting and runs at the highest allowable frame rate.
|
1 2 3 4 |
_baslerCameraSample.EnableFrameRate(false); // Disabled _baslerCameraSample.SetFrameRate(15); // Has no effect double fps = _baslerCameraSample.GetResultingFrameRate(); |
🧪 Example Test: 5 fps → 15 fps → 30 fps
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
[TestMethod()] public void SetFrameRateTest() { _baslerCameraSample.Connect(); _baslerCameraSample.EnableFrameRate(true); // 5 fps Assert.IsTrue(_baslerCameraSample.SetFrameRate(5)); Assert.IsTrue(Math.Abs(_baslerCameraSample.GetFrameRate() – 5) < 0.1); // 15 fps Assert.IsTrue(_baslerCameraSample.SetFrameRate(15)); Assert.IsTrue(Math.Abs(_baslerCameraSample.GetFrameRate() – 15) < 0.1); // 30 fps Assert.IsTrue(_baslerCameraSample.SetFrameRate(30)); Assert.IsTrue(Math.Abs(_baslerCameraSample.GetFrameRate() – 30) < 0.1); // Check actual achievable fps var resulting = _baslerCameraSample.GetResultingFrameRate(); Console.WriteLine($“Requested: 30 fps, Resulting: {resulting:F2} fps”); } |
Example output on my machine:
|
1 2 |
Frame Rate: 30.00 fps, Resulting Frame Rate: 14.59 fps |
Even though 30 fps was requested, the actual fps dropped to ~14.6 fps due to bandwidth or exposure constraints.
🧭 Troubleshooting
| Symptom | Likely Cause |
|---|---|
| Frame rate does not increase | Exposure too long / ROI too large |
| Cannot set AcquisitionFrameRate | AcquisitionFrameRateEnable is false |
| ResultingFrameRate reads 0 | Camera not streaming or not initialized |
📝 Summary
- Enable frame-rate control via
AcquisitionFrameRateEnable = true - Set target fps with
AcquisitionFrameRateAbs - Verify actual achievable fps via
ResultingFrameRateAbs - Exposure time, ROI size, and bandwidth all influence the maximum fps
Understanding both the requested and actual frame rate is essential for designing stable, real-time machine vision systems.
🔜 Next Article
Next, we will build on frame-rate control by implementing continuous acquisition (burst capture) for high-speed inspections and inline processing.
筆者: @MilleVision
コメントを残す