Stabilizer Class FAQs¶

What is the Stabilizer Class and what does it do?¶

Answer: The Stabilizer Class is an auxiliary class that enables video stabilization for Vidgear with minimal latency and little to no additional computational overhead. Since v0.3.5, the Stabilizer module follows a plugin-style design with a Stabilizer(...) factory function backed by a StabilizerMode enum. The default (and currently only) backend is the Average Sliding-Window (ASW) stabilizer. For more details, see the Stabilizer Class documentation ➶.

Which stabilization algorithms are available, and how do I switch between them?¶

Answer: Since v0.3.5, the Stabilizer module is implemented as a plugin-style package with a Stabilizer(...) factory backed by a StabilizerMode enum.

• The default mode is StabilizerMode.ASW (Average Sliding-Window), which matches the behavior of earlier versions.
• StabilizerMode.KALMAN is currently a placeholder and raises NotImplementedError. It is planned for a future release.

Refer to the mode for more details.

from vidgear.gears.stabilizer import Stabilizer, StabilizerMode

stab = Stabilizer(mode=StabilizerMode.ASW, smoothing_radius=30)

What happens if I pass an invalid or unsupported mode value?¶

Answer: The Stabilizer(...) factory strictly validates the mode parameter.

• Passing a value that is not a StabilizerMode enum member raises a TypeError.
• Selecting StabilizerMode.KALMAN raises a NotImplementedError, as it is reserved for a future implementation.

Always use a valid enum value.

How does the Average Sliding-Window (ASW) stabilizer work?¶

Answer: The ASW backend tracks salient feature points using OpenCV’s goodFeaturesToTrack across consecutive frames and computes affine transformations using Lucas-Kanade optical flow.

• Per-frame transformations are accumulated into a trajectory (path).
• This path is smoothed using a normalized box filter of width smoothing_radius.
• The difference between the smoothed path and the original path is applied back to each frame to reduce jitter while preserving intentional motion.

How much latency should I expect with the ASW Stabilizer?¶

Answer: The ASW Stabilizer introduces:

• A warm-up latency of smoothing_radius frames, during which stabilize method returns None.
• Per-frame processing time proportional to O(smoothing_radius).

Performance considerations: Higher-resolution frames increase processing time. You can reduce latency by:

• Resizing frames using the reducer method before stabilization.
• The smoothing_radius parameter balances quality and latency:
• Larger values: smoother output, higher latency, reduced sudden panning
• Smaller values: lower latency, less smoothing

Does the ASW Stabilizer's memory grow unbounded on long streams?¶

Answer: No. Since v0.3.5, the ASW backend uses bounded fixed-size deques for frame buffering and transform history. Memory usage is capped at O(smoothing_radius) regardless of stream length.

Earlier versions used unbounded lists that grew with the total number of processed frames.

Why does the stabilize method return None for the first several frames?¶

Answer: The ASW Stabilizer requires a full sliding window of size smoothing_radius before it can compute a smoothed trajectory.

• Until the window is filled, stabilize returns None.
• This is expected behavior. Skip None outputs and continue processing frames.

How can I remove black borders after stabilization?¶

Answer: Use the crop_n_zoom parameter to crop and zoom frames back to their original size, reducing visible black borders (similar to effects in Adobe After Effects).

• Works together with border_size.
• When enabled, border_size is used for cropping instead of padding.
• Default value: False.

Can I use Stabilizer directly with OpenCV?¶

Answer: Yes. Refer to the bare minimum OpenCV usage example ➶.

Why is stabilization not working properly for my video?¶

Answer: The ASW Stabilizer is designed for low-frequency motion and may not perform well with high-frequency jitter.

Possible causes and solutions: * Increase smoothing_radius for stronger smoothing (at the cost of latency) * Very dark frames may prevent feature detection. Enable logging=True to check for "Video-Frame is too dark" warnings

Can I reuse a Stabilizer instance after calling clean()?¶

Answer: Yes. Calling clean():

• Clears the internal frame queue
• Resets transform history
• Resets the warm-up state

The same instance can then be reused for a new video stream without reinitialization.

Which OpenCV versions are supported by the Stabilizer?¶

Answer: The Stabilizer module supports:

• OpenCV 3.x
• OpenCV 4.x and later

Internally, the implementation automatically selects:

• cv2.estimateRigidTransform for OpenCV 3
• cv2.estimateAffinePartial2D for OpenCV 4+

No manual configuration is required.

Does the existing Stabilizer() API from before v0.3.5 still work?¶

Answer: Yes. The Stabilizer(...) API is fully backward-compatible.

• If mode is not specified, it defaults to StabilizerMode.ASW
• Behavior remains consistent with the earlier monolithic implementation