> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/function-blocks/blocks-reference/image-transformations/transformation-filters/background-subtractor.md).

# Background Subtractor

This function block detects moving/foreground regions by comparing current frames against a learned background model. Use it to separate foreground objects (people, vehicles, moving parts) from a stable background and produce a binary/grayscale foreground mask for further analysis.

## 📥 Inputs (sockets) <a href="#inputs" id="inputs"></a>

`Input Image` Accepts the input image or video frame to be analyzed (color or grayscale).

## 📤 Outputs (sockets) <a href="#outputs" id="outputs"></a>

`Foreground Mask` Outputs a grayscale/binary mask where foreground pixels are highlighted.

## 🕹️ Controls <a href="#controls" id="controls"></a>

`Method` Choose the background subtraction algorithm (e.g. MOG2 or KNN) available in the dropdown.

`History` Controls how many past frames are used to build the background model. Higher values make the model adapt slower.

`VarThreshold` Controls sensitivity to pixel changes. Lower values make the subtractor more sensitive to small changes; higher values make it less sensitive.

## ⚙️ Running mechanism <a href="#running-mechanism" id="running-mechanism"></a>

Each time the block runs it:

* Uses the selected `Method` and the current `History` / `VarThreshold` settings.
* If settings changed, the internal background model is reinitialized to reflect the new parameters.
* Processes the incoming `Input Image` and produces the `Foreground Mask` showing detected foreground regions.

This mask is updated frame-by-frame and can be consumed by other blocks for counting, tracking, or saving.

## 🎯 Features <a href="#features" id="features"></a>

* Quick switching between algorithms using `Method`.
* Real-time parameter tuning with `History` and `VarThreshold` sliders to balance adaptation speed vs. stability.
* Produces a ready-to-use foreground mask that can be piped into detection or analysis blocks.

## 📝 Usage <a href="#usage" id="usage"></a>

1. Connect an image-producing block (camera, video, or load image) into `Input Image`.
2. Select desired `Method` and tune `History` and `VarThreshold` while observing results.
3. Use the `Foreground Mask` with downstream blocks for detection, counting, or logging.

## 💡 Tips and Tricks <a href="#tips-and-tricks" id="tips-and-tricks"></a>

* For noisy results, try smoothing the input first with `Blur` or reduce high-frequency noise using `Denoising` before feeding the image to this block.
* To remove small speckles from the mask, attach `Morphological Transformations` after this block to apply opening/closing operations.
* If you only care about a specific area, crop the input with `Image ROI Select` or `Image ROI` before background subtraction to speed up processing.
* Use `Show Image` to preview the `Foreground Mask` in a larger viewer for parameter tuning.
* For object-level analysis, feed the mask into `Blob Detector` or use `Find Contour` to extract and measure detected components.
* To annotate or highlight detections on the original frame, combine with `Draw Detections` or `Draw Rectangle` using coordinates derived from contour/blob analysis.
* If your input frames are very large, insert `Image Resizer` to downscale first for faster processing.
* Persist important frames or masks using `Image Logger` or `Image Write` when a trigger condition occurs (e.g., detection count exceeds a threshold).
* Use `Image Memory` to freeze a frame for inspection while live processing continues.

(hints above reference only the available function blocks list)

## 🛠️ Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

* If the foreground mask is too sensitive (many flickering pixels), increase `VarThreshold` or increase `History` so the model adapts slower.
* If moving objects are not detected reliably, decrease `VarThreshold` or reduce prior smoothing.
* If the mask contains small isolated noise, add `Morphological Transformations` (opening) or run `Blur` on the input.
* If the background changes frequently (lighting, moving background), reduce `History` so the model adapts faster, or restrict processing to a stable ROI with `Image ROI Select`.
* If you cannot see the mask clearly, use `Show Image` to open the mask in the image viewer for better inspection.

## 🔗 Recommended block combinations <a href="#recommended-combinations" id="recommended-combinations"></a>

* Preprocessing: `Blur` → `Background Subtractor` → `Morphological Transformations`
* Focused detection: `Image ROI Select` → `Background Subtractor` → `Blob Detector` → `Draw Detections`
* Logging and review: `Background Subtractor` → `Show Image` (preview) and `Image Logger` or `Image Write` (save masks/frames)
* Post-analysis: `Background Subtractor` → `Find Contour` / `Measure Object Distance` → `Data to JSON` or `CSV Export`

These combinations help build reliable video-analysis pipelines using the available blocks.