FilterTracking

A real-time webcam application built with OpenCV + MediaPipe Hands that applies fun visual effects to the camera feed using hand gestures. Make a "peace" sign ✌️ or point your fingertips at the camera to trigger effects like blur, negative, glitch, or random RGB colors.

Created for a final project ("Project Tai").

---

Features

• Real-time hand detection (up to 2 hands) using MediaPipe Hands.
• Two trigger modes:
  • Peace Sign – effect activates when a ✌️ gesture is detected (index + middle fingers extended, the rest folded).
  • Fingertip – effect follows the fingertips / palm area.
• Four effects: Blur, Negative, Glitch, RGB Random.
• Three tracking modes for Fingertip: all fingers, thumb + index, and left/right separated.
• Smooth fade transitions, faint landmark overlay, on-screen status & help.
• Window can be resized while preserving aspect ratio (letterbox, no stretching).

---

Requirements

• Python 3.8 – 3.14 (tested with Python 3.14).
• A webcam detected as camera index 0.
• The hand_landmarker.task model file (auto-downloaded on first run if missing; already included in this folder).
• Python packages (see requirements.txt):
  • mediapipe>=0.10.30 (requires the Tasks / HandLandmarker API)
  • opencv-python
  • numpy

---

QUICK START!!

For windows users, you can simply clone this repo and run run.bat file included on repo file!

Installation

Open a terminal in this folder, then:

# (Optional but recommended) create a virtual environment first
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # Linux/macOS

# Install dependencies
pip install -r requirements.txt

⚠️ About MediaPipe versions & API

Starting from MediaPipe 0.10.30 and above (including 1.0.x), the legacy mp.solutions.hands / mp.solutions.drawing_utils modules have been removed from the package. Old code that calls mp.solutions will fail with:

AttributeError: module 'mediapipe' has no attribute 'solutions'

This script has therefore been migrated to the Tasks API (mediapipe.tasks.vision.HandLandmarker). This new API requires a model file hand_landmarker.task, which is downloaded automatically into this folder on first run (internet connection needed at that time).

---

How to Run

python index.py

On the first execution, the script downloads hand_landmarker.task (~7.8 MB) if it is not present yet, then opens the webcam window. Press q to quit.

---

Controls / Keys

Key	Function
1	Trigger: Peace Sign
2	Trigger: Fingertip
a	Effect: Blur
b	Effect: Negative
c	Effect: Glitch
r	Effect: RGB Random
3 / F1	Tracker (Fingertip): All fingers
4 / F2	Tracker (Fingertip): Thumb + Index
5 / F3	Tracker (Fingertip): Left/Right separated
f	Fullscreen on/off
h	Hide / show GUI (status & overlay)
p	Show / close help panel
q	Quit

Press p inside the app to see the help list on screen.

---

How It Works (Brief)

1. The camera frame is read and flipped (mirror) then converted to RGB.
2. HandLandmarker (Tasks API) processes the frame and returns hand landmarks (replacing mp.solutions.hands.Hands).
3. get_finger_states() determines which fingers are open/closed.
4. In Peace mode, is_peace_sign() detects the ✌️ gesture.
5. In Fingertip mode, compute_hand_openness() computes the spread of the fingertips relative to the palm to determine the effect area.
6. The effect is applied via a mask (blur/negative/glitch/rgb) with a smooth fade transition (trigger_alpha).

Implementation note: to avoid rewriting the logic above, the result from HandLandmarker is wrapped by the _HandLandmarkerContext / _tasks_to_legacy_result adapters so it still exposes multi_hand_landmarks and multi_handedness attributes like the old API.

---

File Structure

File	Description
index.py	Main application code.
hand_landmarker.task	MediaPipe Hands model (Tasks API). Auto-downloaded if missing.
requirements.txt	Python dependency list & versions.
README.md	This documentation.

---

Troubleshooting

• Camera won't open – make sure it isn't used by another app and that camera permission is granted; the camera is expected to be detected as index 0.
• Failed to download hand_landmarker.task – run once with an internet connection, or download it manually from https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task and place it in this folder.
• module 'mediapipe' has no attribute 'solutions' – this is an error from old code using the mp.solutions API. This script already uses the Tasks API, so make sure you are running the latest peace_blur_cam.py (not an old copy).
• MediaPipe import is slow / TensorFlow warnings – normal; the script already suppresses most logs to keep output clean.