# Real-Time Person Anonymizer (Background-Subtraction Pipeline)

A Python application that detects and anonymizes people in a live webcam stream using classical background subtraction. No ML model; two dependencies (OpenCV, NumPy).

## 1. PRD

**Problem.** Off-the-shelf anonymizers depend on ML detectors (YOLO, MediaPipe) that need pre-trained weights, often a GPU, and internet at setup. A privacy tool that runs on any laptop CPU with only OpenCV and NumPy fills a real gap.

**Target users.** Students and instructors demonstrating CV without ML; researchers needing offline on-device privacy.

**Goals.** Detect people in a static-camera scene; obscure with mosaic or Gaussian blur in real time; expose live-tunable thresholds; record the anonymized stream; protect against degenerate "too close" detection.

**Non-goals.** Face recognition; identity tracking; moving-camera support; ML-based detection.

**Main features.** Live anonymization, two modes (mosaic, Gaussian), live threshold tuning, too-close protection, AVI recording.

## 2. FSPEC

**Overview.** `Final.py` opens a webcam, runs a setup screen, learns the empty-scene background over 10 seconds, then processes each frame through a five-stage pipeline and displays (and records) the result.

**End-to-end flow.** Launch → setup (camera index, exposure / white balance / focus, AE/AWB/AF disable) → `SPACE` → 10 s warmup → main loop (view modes, live tuning, `b` to recapture background) → `q` to quit.

**Behavior.**

- *Setup screen.* Modal with camera selector, sliders, and AE/AWB/AF status chips.
- *Warmup.* 10 seconds of empty-scene frames averaged into the reference image.
- *Anonymization.* Mosaic destroys pixel data via `INTER_NEAREST` resize-down/up; Gaussian (`GAUSSIAN_STRENGTH = 99`) is reversible in principle. Edges feather over 9 px.
- *Too-close.* Mask > 55 % of the frame disables blurring and shows "TOO CLOSE".
- *View modes.* `1` overlay; `2` anonymized (**only mode that writes the AVI**); `3` three-panel debug.
- *Live tuning.* Keys adjust BGR/HSV thresholds and mosaic block size without restart.

**Inputs.** Webcam frames; keyboard/mouse.  **Outputs.** Live window; XVID `.avi` (auto-timestamped).

## 3. DEVSPEC

**Architecture.** Five-stage pipeline, illustrated in `modified_blur_pipeline_workflow.svg`:

1. **Warmup** — average empty-scene frames into a frozen background.
2. **Foreground** (`compute_foreground_mask`) — BGR diff AND HSV diff above thresholds, OR BGR diff above `BGR_STRONG_THRESHOLD = 50`.
3. **Cleanup** (`clean_mask`) — open → extremity-connect dilate → close → dilate.
4. **Detection** (`find_persons`) — contour filter (area, aspect ratio, top-ignore), then bbox merge within `MERGE_DISTANCE = 60` px.
5. **Anonymize** — mosaic or Gaussian, feathered into the frame.

**Design decisions.** OpenCV + NumPy only — zero weights, any CPU, fully offline. BGR *and* HSV are both checked because either alone fails under colored clothing or shadow. Morphology order matters (open before close: kill noise before bridging gaps). Boxes merge at 60 px so a fragmented body is one detection. Top 5 % is ignored for overhead-light flicker. Mosaic is irreversible — a stronger privacy guarantee than Gaussian.

**Version progression.**

| Version | File | Added |
|---|---|---|
| v1 | `person_blur.py` | Baseline; Gaussian only |
| Modified | `Modified_Blur.py` | Mosaic mode; larger morphology |
| V2 | `Modified_Blur_V2.py` | Too-close protection |
| V3 | `Modified_Blur_V3.py` | Setup screen; AE/AWB/AF disable |
| V3.1 / V3.2 | `..._V3_1.py`, `..._V3_2.py` | Setup refinements |
| V3.1.1 → **Final.py** | `..._V3_1_1.py` | Polished setup panel |

**Tunable parameters.**

| Constant | Value | Purpose |
|---|---|---|
| `BGR_THRESHOLD` / `HSV_THRESHOLD` | 25 / 35 | Foreground sensitivity |
| `BGR_STRONG_THRESHOLD` | 50 | Strong-BGR shortcut |
| `MORPH_OPEN` / `CLOSE` / `DILATE` | 5 / 13 / 5 | Cleanup kernels |
| `EXTREMITY_CONNECT_SIZE` | 7 | Keeps fingertips attached |
| `MOSAIC_BLOCK_SIZE` (4–30) | 12 | Mosaic pixel size |
| `GAUSSIAN_STRENGTH` | 99 | Gaussian kernel |
| `MIN_CONTOUR_AREA` | 2000 | Person-size gate |
| `MERGE_DISTANCE` | 60 | Bbox merge radius |
| Too-close threshold | > 55 % | Disables blur |

## 4. Testing

Manual: interactive webcam sessions plus recorded clips in `NeededVideos/`.

**Cases.** Warmup completes in 10 s; single-person and two-person detection; fast motion; partial occlusion; too-close trigger at ~55 %; live threshold and block-size tuning; view-mode switching; AVI output is playable.

**Corpus.** `Almost_Perfect.avi` (best case), `2peopletesting.avi` (multi-person merge), `BadArms.avi` (arms detached), `Bad_hand_mask.avi` (hands missed), `Closeup testingfastmotions.avi` (motion blur), `CHBACEL.avi` (general), `First_Somewhat_Working.avi` (regression baseline), `Incorrect blurring method.avi` (anonymization edge case), `NOlegs.avi` (lower-body dropout).

## 5. Benchmarking

Qualitative comparison.

| Approach | Setup | Deps | HW | Static acc. | Moving cam | Privacy | Complexity |
|---|---|---|---|---|---|---|---|
| Us           | Low | OpenCV, NumPy | CPU | Good | Poor | Strong (mosaic irreversible) | Low |
| YOLOv8       | High | Ultralytics, Torch | GPU pref. | Excellent | Excellent | Weaker | High |
| MediaPipe    | Medium | mediapipe | CPU | Very good | Very good | Weaker | Medium |
| HOG + SVM    | Low | OpenCV | CPU | Modest | Modest | Same as blur | Low |
| Haar Cascade | Low | OpenCV | CPU | Poor | Poor | Same as blur | Low |

**Discussion.** Wins: simplicity, zero weights, full offline operation, irreversible mosaic privacy. Loses: moving-camera scenarios, lighting drift, no class awareness (any motion becomes a "person"). Appropriate for educational demos, lecture capture, constrained hardware; inappropriate for production surveillance, mobile, or outdoor use.