🎯 Target Human

Real-time face recognition & tracking — enroll a person from a few photos, then find, lock onto, and photograph them automatically in a live camera feed.

---

Table of Contents

• Features
• How It Works
• Requirements
• Installation
  • Windows
  • Linux / macOS
• Enrolling People
• Running It
• Command-Line Options
• On-Screen Indicators
• Keyboard Controls
• Output Files
• Tracking & Re-Identification Logic
• Tips for Better Accuracy
• How Far Can It See?
• Troubleshooting
• Privacy & Legal Notice
• Contributing
• License

---

✨ Features

🎯 Targeted recognition	Enroll specific people and get alerts/captures only when they appear
🔍 Crowd + distance search	Zoom-scans the frame to find small/far-away faces
🔒 Persistent lock-on	Once confirmed, a person stays "locked" with motion-predicted tracking, surviving brief occlusion or blur
🧠 Auto-learning	High-confidence new views of a locked person are added to their profile automatically
📸 Automatic capture	Saves a cropped face photo and a full-frame photo the instant a person is confirmed, plus a CSV log
⚙️ Configurable	Adjustable strictness, camera source, zoom aggressiveness, cooldowns, and more
🖥️ CPU or GPU	Runs on CPU out of the box; optional NVIDIA GPU acceleration

---

🧩 How It Works

flowchart LR
    A[📁 Reference photos<br/>known_faces/] --> B[🧠 Build embeddings<br/>face_db.pkl]
    B --> C[📷 Live camera / video / RTSP]
    C --> D{Face detected?}
    D -- No --> C
    D -- Yes --> E[Compare against database]
    E --> F{Confidence ≥ threshold?}
    F -- No --> C
    F -- Yes --> G[🎯 Lock on + track]
    G --> H[📸 Capture photo + log]
    H --> I[🧠 Auto-learn new view]
    I --> C

Loading

1. You provide a handful of reference photos per person in known_faces/.
2. On first run (or via enroll.bat), the app builds a face embedding database (face_db.pkl) using InsightFace.
3. The tracker pulls frames from a camera/video/stream, detects faces, and compares each one against the database.
4. Matches above a confidence threshold get boxed, labeled, and — once confirmed — captured as photos and tracked frame-to-frame.

---

📋 Requirements

• — 3.12+ is not yet fully compatible with InsightFace's dependency chain on Windows
• A webcam, video file, or camera stream (RTSP/IP camera)
• ~300 MB free disk space and an internet connection for the first run (downloads the recognition model)
• Optional: NVIDIA GPU + CUDA for --gpu acceleration

---

⚙️ Installation

Windows

1. Install Python 3.11 if you don't already have a compatible version:

   winget install -e --id Python.Python.3.11 --silent --accept-package-agreements --accept-source-agreements

   (Restart your terminal after installing.)

2. Clone the repository:

   git clone https://github.com/hanzlabaig-dev/Target-Human.git
   cd Target-Human

3. Add photos of people to recognize — see Enrolling People.

4. Run:

   .\run.bat

   The first run creates a virtual environment, installs dependencies from requirements.txt, and downloads the recognition model (~300 MB, one-time). Subsequent runs skip straight to launching the camera.

If run.bat fails because your default Python is 3.12+, build the venv explicitly with 3.11:

py -3.11 -m venv venv
.\venv\Scripts\python -m pip install --upgrade pip
.\venv\Scripts\python -m pip install -r requirements.txt
.\venv\Scripts\python face_tracker.py run

Linux / macOS

git clone https://github.com/hanzlabaig-dev/Target-Human.git
cd Target-Human
chmod +x setup.sh run.sh
./run.sh

---

👤 Enrolling People

Create one folder per person inside known_faces/, named however you want it displayed on screen:

known_faces/
    Ali/
        photo1.jpg
        photo2.jpg
        photo3.jpg
    Sara/
        a.png
        b.png
        c.png

Guidelines:

• 5–10 photos per person is ideal (minimum 1 works, but accuracy suffers).
• Mix angles and conditions: front-facing, slight left/right turn, with/without glasses, different lighting.
• Face should be clearly visible, sharp, and reasonably large in the photo. If multiple faces appear, the largest one is used.
• Avoid heavy filters, sunglasses, or masks.

New photos are picked up automatically on the next run — no separate step needed. You can add people while it's running and press R to reload without restarting.

---

▶️ Running It

Windows:

.\run.bat          # normal mode
.\run_far.bat      # heavier zoom-scan for distant/small faces (needs a faster CPU)
.\enroll.bat       # rebuild the face database only, without opening the camera

Linux/macOS:

./run.sh

Direct command line (from inside the venv), for custom options:

python face_tracker.py run [options]

---

🎛️ Command-Line Options

Option	Description
--target Ali Sara	Only track/capture these specific people
--source 1	Use a different camera device (index)
--source video.mp4	Run against a video file instead of a live camera
--source rtsp://...	Use an IP/RTSP camera stream (better for long-range setups)
--far	More aggressive zoom-scan for distant faces
--threshold 0.50	Stricter matching (fewer false positives)
--threshold 0.38	More lenient matching (fewer missed matches)
--model buffalo_s	Smaller/faster model, slightly less accurate — good for weaker hardware
--gpu	Use an NVIDIA GPU (requires pip install onnxruntime-gpu)
--lock-age 20	Seconds to keep searching for a lost/occluded person before dropping the lock
--no-learn	Disable auto-learning of new face views
--cooldown 10	Minimum seconds between repeat captures of the same person

python face_tracker.py run --target Ali --threshold 0.5 --model buffalo_s

---

🖼️ On-Screen Indicators

Indicator	Meaning
🟩 Green + TARGET	Confirmed match — photo captured
🟨 Name?	Possible match, still being confirmed
🟦 Cyan	Enrolled person, but not in the current --target list
🟥 Unknown	Face detected but not in the database
⬜ ...	Face just detected, still being analyzed

---

⌨️ Keyboard Controls

Key	Action
Q	Quit
D	Toggle deep-scan mode
[ / ]	Lower / raise matching strictness live
R	Reload photos from known_faces/
+ / -	Camera hardware zoom (supported webcams only)
Z	Toggle automatic camera zoom

---

📂 Output Files

captures/
    <PersonName>/
        20260924_143339_126_face.jpg   # zoomed/cropped face
        20260924_143339_126_full.jpg   # full camera frame
    captures_log.csv                   # timestamp, name, confidence score, etc.

The enrollment database is stored in face_db.pkl at the project root and updates automatically as auto-learning adds new views (capped at 40 photos per person).

---

🔁 Tracking & Re-Identification Logic

• Once a person is confirmed, they become the locked target: the bounding box follows them using motion prediction, and the frame is zoom-searched around their last known position each cycle.
• If they're briefly blocked or blurred, the lock persists for 10 seconds (--lock-age), shown as an orange "Name - searching..." marker at their last position.
• If they reappear within 20 seconds (--reid-window), they're re-locked instantly without needing to reconfirm.
• No duplicate photos are taken while a cooldown is active for that person.
• Auto-learning: clear, high-confidence new views of a locked person are saved into their profile in face_db.pkl (max 40 per person), so accuracy improves the longer the tracker runs. Disable with --no-learn.

---

🎯 Tips for Better Accuracy

• Good enrollment photos matter more than any setting — invest time here first.
• Use 5–10 varied, sharp, well-lit photos per person.
• Adjust --threshold live with [ and ] while running to tune false positives vs. missed matches.
• For distant or small faces, try --far or a higher-resolution/optical-zoom camera.

---

📏 How Far Can It See?

Recognition needs enough resolved pixels on the face:

• A 1080p camera detects faces down to roughly 24 px wide.
• Reliable recognition starts around 40 px wide.

To extend range: use a higher-resolution camera (4K), one with optical zoom, an IP/PTZ camera, or run with --far. Digital zoom helps the detector and aligner but can't recover detail the camera never captured.

---

🛠️ Troubleshooting

ModuleNotFoundError: No module named 'cv2' / install fails on Python 3.12+

InsightFace's dependencies (notably scipy) don't yet have prebuilt wheels for Python 3.12 on Windows. Install Python 3.11 and rebuild the venv:

py -3.11 -m venv venv
.\venv\Scripts\python -m pip install -r requirements.txt

'git' is not recognized

Git isn't installed. On Windows:

winget install -e --id Git.Git --silent --accept-package-agreements --accept-source-agreements

Restart your terminal afterward.

Laptop shuts down / overheats after a few minutes

This is CPU-heavy processing causing a thermal shutdown, not a software bug. Try:

• Using the lighter model: --model buffalo_s
• Avoiding --far and deep-scan (D) unless needed
• Ensuring good airflow/cooling and running on AC power

Slow performance / low FPS

Try --model buffalo_s, lower camera resolution, or enable --gpu if you have a compatible NVIDIA GPU.

---

🔐 Privacy & Legal Notice

Warning

This tool performs biometric face recognition and can track and photograph people automatically, including at a distance and in crowds. Face data is sensitive and regulated in many jurisdictions (e.g., GDPR in the EU/UK, BIPA in Illinois, and similar laws elsewhere).

Only use this on people who are aware of and have consented to being recognized and tracked. Do not deploy it for covert surveillance of individuals without their knowledge or consent, and check local laws before using it in any public, shared, or commercial space.

---

🤝 Contributing

Issues and pull requests are welcome. If you spot a bug or have an improvement, feel free to open an issue at github.com/hanzlabaig-dev/Target-Human/issues.

---

📄 License

Licensed under the MIT License — free to use, modify, and distribute, provided the original copyright notice is retained. See the LICENSE file for full terms.

Built by Hanzla Baig