AI-Anti-Peeping-Screen-Privacy-Guard - GitLite

KO | EN

gitlite — search

#agents #codex #ui #open-source #awesome-list #cloud-native #monitoring #vue #sql #ios

AI-Anti-Peeping-Screen-Privacy-Guard

(★ 10)

Python AI anti-peeping screen privacy system using MediaPipe, OpenCV, face detection, gaze estimation, and a real-time privacy shield.

파일 탐색기

ZIP 다운로드

- .gitkeep
- __init__.py
- config.py
- detector.py
- overlay.py
- risk_engine.py
- __init__.py
- test_risk_engine.py
.gitignore
config.json
download_model.py
LICENSE
main.py
PROJECT_REPORT.md
README.md
requirements.txt
run_windows.bat

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

PrivacyGuard AI is a Python desktop prototype inspired by anti-peeping privacy
features on modern phones. It uses the webcam and an on-device face-landmark
model to detect a primary user and possible additional viewers. If a privacy
risk persists, the program covers the desktop with a topmost privacy shield.

The application processes webcam frames in memory. It does **not** record,
save, upload, or identify the people visible to the camera.

## What the project demonstrates

- Multiple-face detection from a live webcam
- Approximate head-direction and iris-position analysis
- A 0–100 extra-viewer risk score
- Time smoothing to reduce one-frame false alarms
- A full-screen privacy overlay
- An emergency `Esc` pause so the user cannot be trapped behind the overlay
- Local-only computer-vision processing

## What you need

| Requirement | Why it is needed |
| --- | --- |
| Windows 10 or Windows 11 | The supplied launcher and multi-monitor overlay are optimized for Windows. |
| 64-bit Python 3.11–3.13 | Runs the application and supports the current MediaPipe package. |
| Webcam | Provides the live view used to find faces. |
| Internet for initial setup | Downloads Python packages and the official model once. |
| Good front lighting | Face and iris landmarks are less reliable in darkness. |

The code can also run on Linux, but `run_windows.bat` is specifically for
Windows.

## What every file is for

```text
PrivacyGuardAI/
├── main.py                       Main desktop interface and camera loop
├── config.json                   Detection timing and sensitivity settings
├── download_model.py             Downloads the official MediaPipe model
├── requirements.txt              Python packages to install
├── run_windows.bat               One-click Windows setup and launcher
├── PROJECT_REPORT.md             Project explanation for college/GitHub
├── privacyguard/
│   ├── config.py                 Loads and validates config.json
│   ├── detector.py               Face, head-direction, iris and risk analysis
│   ├── overlay.py                Full-screen privacy shield
│   └── risk_engine.py            Stable trigger/release timing logic
├── tests/
│   └── test_risk_engine.py       Automated tests for the privacy decisions
└── models/
    └── face_landmarker.task      Created after the model download
```

## Fastest Windows setup

### Step 1 — Install Python

1. Open <https://www.python.org/downloads/>.
2. Download a 64-bit Python 3 release.
3. During installation, enable **Add Python to PATH**.
4. Finish the installation.

Open Command Prompt and verify:

```bat
py --version
```

### Step 2 — Extract this project

Extract the ZIP file. For example:

```text
C:\Users\Ankit\Documents\PrivacyGuardAI
```

Do not run the program from inside the ZIP preview.

### Step 3 — Use the automatic launcher

Double-click:

```text
run_windows.bat
```

The first run will:

1. Create an isolated `.venv` environment.
2. Install MediaPipe, OpenCV, Pillow and NumPy.
3. Download the face-landmark model.
4. Start the application.

Later runs reuse the same environment.

## Manual setup commands

Use these if you want to understand every operation.

Open Command Prompt inside the extracted folder:

```bat
cd C:\Users\Ankit\Documents\PrivacyGuardAI
```

Create a virtual environment so the packages for this project do not interfere
with other Python projects:

```bat
py -3 -m venv .venv
```

Activate it:

```bat
.venv\Scripts\activate
```

Install the required libraries:

```bat
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

Download the official MediaPipe Face Landmarker model into `models/`:

```bat
python download_model.py
```

Start the app:

```bat
python main.py
```

If PowerShell blocks activation, activation is optional. Use the environment's
Python directly:

```bat
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe download_model.py
.venv\Scripts\python.exe main.py
```

## How to test the project

1. Sit in front of the webcam, approximately centred.
2. Click **Start protection**.
3. Confirm that your face gets the green `PRIMARY USER` box.
4. Ask another person to enter the camera view and look toward the laptop.
5. Their box should show `EXTRA VIEWER` as the risk score rises.
6. After the condition persists for about 0.8 seconds, the privacy shield
   should cover the desktop.
7. When the extra person leaves, stay visible and centred. The screen returns
   after approximately 1.5 seconds of a stable safe view.
8. Press `Esc` at any time to pause automatic protection for 10 seconds.

Use **Test privacy shield** before starting the camera if you want to check the
overlay safely.

## How the detection works

### 1. Camera input

OpenCV reads frames from the front webcam. Each frame is mirrored to behave
like a normal selfie preview.

### 2. Face landmarks

MediaPipe Face Landmarker detects up to four faces and returns 478 landmarks
for each face. These include face boundaries, eyes, nose and iris points.

### 3. Primary-user selection

The most centred, relatively large face is selected as the **primary user**.
This is only a positioning rule—it is not biometric authentication.

### 4. Extra-viewer score

Every non-primary face receives a score:

```text
55 base points for an additional visible face
+ up to 30 points when the head appears directed toward the camera
+ up to 15 points when the irises appear centred toward the camera
= 0–100 approximate privacy-risk score
```

The default threshold is 72.

### 5. Time smoothing

The shield does not react to a single frame. The risk must persist for the
configured period. A safe view must also remain stable before the shield is
removed. This avoids rapid flashing when face detection briefly fails.

### 6. Privacy action

A borderless, topmost Tkinter window spans the desktop and covers sensitive
content. This demonstrates the response an operating-system-level feature
could perform.

## Adjusting sensitivity

Close the application and edit `config.json`.

| Setting | Default | Meaning |
| --- | ---: | --- |
| `camera_index` | `0` | Webcam number; try `1` if the wrong camera opens. |
| `risk_threshold` | `72` | Lower values trigger more easily; higher values require clearer attention. |
| `peeping_trigger_seconds` | `0.8` | How long extra-viewer risk must continue. |
| `safe_release_seconds` | `1.5` | Safe time required before revealing the screen. |
| `protect_when_no_face` | `true` | Cover the desktop if no face remains visible. |
| `no_face_trigger_seconds` | `1.5` | Delay before no-face protection. |
| `detection_interval_ms` | `80` | Delay between analyses; larger is slower but uses less CPU. |
| `max_faces` | `4` | Maximum faces processed in one frame. |

Useful changes:

```json
"risk_threshold": 65.0
```

This makes the demonstration more sensitive.

```json
"protect_when_no_face": false
```

This disables protection when everyone leaves the camera view.

## Run automated tests

The risk-timing logic can be tested without a webcam:

```bat
.venv\Scripts\python.exe -m unittest discover -s tests -v
```

## Troubleshooting

### `py` is not recognized

Install Python from python.org and make sure **Add Python to PATH** is selected.
Restart Command Prompt after installing it.

### The model download fails

Check the internet connection and run:

```bat
.venv\Scripts\python.exe download_model.py
```

The file should appear at:

```text
models\face_landmarker.task
```

### Camera does not open

1. Close Camera, Teams, Zoom, OBS and browser pages using the webcam.
2. In Windows, open **Settings → Privacy & security → Camera**.
3. Enable camera access and desktop-app camera access.
4. If you have multiple webcams, change `camera_index` from `0` to `1`.

### The shield activates too easily

Increase `risk_threshold` to `78` or increase
`peeping_trigger_seconds` to `1.2`.

### It does not detect a second viewer

- Improve the room lighting.
- Ask the person to face the camera more directly.
- Reduce `risk_threshold` to `65` for demonstration.
- Keep both faces within the webcam frame.

### High CPU usage

Increase `detection_interval_ms` from `80` to `120` or lower
`camera_width` and `camera_height`.

## Important limitations

- This is a portfolio prototype, not an OEM security feature.
- It estimates attention; it cannot prove that someone read the screen.
- The primary user is selected by position and face size, not identity.
- A person remaining alone after the original user leaves may be treated as the
  new primary face.
- A normal Python application cannot provide the same hardware/OS integration
  as a phone manufacturer.
- Other software with higher privileges may appear above or close the overlay.

For a stronger version, add on-device owner enrolment, Windows session locking,
application-specific redaction, and a signed installer.

## Privacy and responsible use

- Tell people when the webcam-based feature is active.
- Do not modify the code to secretly photograph or identify people.
- Do not store raw frames unless every participant has explicitly consented.
- Keep all biometric processing on the device.
- Present detections as a **possible risk**, not proof of wrongdoing.

## GitHub upload

The downloaded `.task` model and `.venv` are intentionally excluded by
`.gitignore`. Upload the remaining source code:

```bat
git init
git add .
git commit -m "Build PrivacyGuard AI anti-peeping prototype"
git branch -M main
git remote add origin https://github.com/YOUR-USERNAME/PrivacyGuardAI.git
git push -u origin main
```

## Technical references

- [MediaPipe Face Landmarker for Python](https://developers.google.com/edge/mediapipe/solutions/vision/face_landmarker/python)
- [MediaPipe Face Landmarker model](https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/latest/face_landmarker.task)
- [OpenCV Python documentation](https://docs.opencv.org/)

## License

The project source is released under the MIT License. The downloaded MediaPipe
model and installed dependencies retain their respective upstream licenses.