Metadata-Version: 2.4
Name: zelica
Version: 0.1.0
Summary: AI-powered real-time webcam enhancer SDK
Author-email: Zelica Authors <zelica@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/zelica/zelica
Project-URL: Documentation, https://github.com/zelica/zelica#readme
Project-URL: Repository, https://github.com/zelica/zelica
Project-URL: Bug Tracker, https://github.com/zelica/zelica/issues
Keywords: webcam,enhancement,camera,real-time,virtual-cam
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video :: Capture
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: opencv-python-headless>=4.8.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pyvirtualcam>=0.6.0
Provides-Extra: face
Requires-Dist: mediapipe==0.10.35; extra == "face"
Provides-Extra: directml
Requires-Dist: onnxruntime-directml>=1.15.0; extra == "directml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"

# Zelica

Zelica is a real-time AI webcam enhancer that transforms your raw camera feed into a polished, broadcast-quality stream — live. It applies professional-grade image processing pipeline stages on every frame: adaptive white balance, exposure control, noise reduction, face-aware skin enhancement, and a full suite of Pro Camera controls modeled after a DSLR settings panel.

---

## What Zelica Does

Zelica captures frames from your webcam via OpenCV, runs them through a multi-stage enhancement pipeline, optionally detects face regions using MediaPipe, and outputs the result as a `pyvirtualcam` virtual camera device that any other application can consume (Zoom, Discord, OBS, browsers, etc.).

Without a virtual camera backend installed it falls back to a preview window — so you always see what it is producing.

---

## The Enhancement Pipeline

Every frame goes through the following stages in order:

| Stage | What it does |
|---|---|
| **White Balance (MaxRGB)** | Neutralises colour casts by analysing the brightest channels in each region. A runtime C extension (`zelica_rust.dll`) handles the heavy lifting with a Python fallback. |
| **Exposure Boost** | Smoothly drives the V-channel mean toward a target luminance using an exponentially weighted moving average — brightens dark rooms without blowing out highlights. |
| **CLAHE** | Applies contrast-limited adaptive histogram equalisation on the L-channel of LAB colour space, then a gamma/offset tone curve to recover shadow detail. |
| **Colour Grade** | Modest saturation lift, value gain and contrast adjustment tuned for a natural but vivid look. |
| **Noise Reduction** | Bilateral filter on the L-channel — smooths grain while preserving edges. |
| **Face ROI + Eye Sharpening** | When MediaPipe detects a face, the face patch is mildly smoothed and sharpened, eyes get an extra unsharp-mask pass, and the result is blended back with a feathered mask so edges stay clean. |
| **Background Softening** | When the AI quality score reports very low lighting, a light Gaussian blur is blended across the background to reduce noise artefacts. |
| **Quality Overlay** | A live HUD reports the ZELICA AI Score (lighting / noise / sharpness blended), noise percentage, sharpness and current exposure status. |

---

## Pro Camera Mode (`--pro`)

Zelica includes a full simulated DSLR control panel that runs after the base pipeline. It is disabled by default and activated with `--pro`.

### ISO (Brightness / Sensor Sensitivity)

`--iso <100–6400>` simulates sensor ISO. Low values (100–200) give the cleanest image; higher values (800–3200) brighten the scene further but introduce a controlled Gaussian grain that mimics real sensor noise — exactly like pushing a physical ISO in low light.

### Shutter Speed

`--shutter <label>` controls perceived motion blur. Fast labels like `1/1000s` leave the frame untouched; slower labels like `1s` or `5s` blend a directional motion-blur kernel proportional to the exposure time. Useful for a silky waterfall look vs. a sharp freeze-frame.

### White Balance

`--wb <mode>` selects a colour-temperature preset or custom Kelvin target:

| Mode | Character |
|---|---|
| `auto` | MaxRGB auto-adapting balance (default) |
| `daylight` | Cool, neutral daylight |
| `cloudy` | Slightly warm |
| `tungsten` | Neutralises warm indoor bulbs |
| `fluorescent` | Compensates for green tube lights |
| `custom_kelvin` | Set exact temperature with `--wb-kelvin <2000–9000>` |

`--wb-tint <float>` lets you fine-tune green → magenta shift.

### Manual Focus (Focus Peaking)

`--focus-peaking` draws a green Laplacian edge overlay on sharply focused regions — exactly like a focus-assist tool on a real camera. Great for macro and manual focus scenarios.

### Exposure Compensation (EV)

`--ev <float>` applies a uniform brightness gain. `+1.0` doubles brightness, `-1.0` halves it. Combined with auto-brightness it becomes a smart exposure override.

### Auto Brightness

Enabled by default. Continuously adjusts output exposure toward a target mean luminance. Disable with `--no-auto-brightness` if you want full manual control.

### RAW Simulation

`--no-raw-sim` disables it; enabled by default. Simulates RAW headroom with shadow lift, soft highlight roll-off, and a slight contrast/saturation boost — giving more latitude in post and a more film-like tonal response.

### Metering Modes

`--metering <mode>` selects how Zelica samples the scene for auto-exposure:

| Mode | Behaviour |
|---|---|
| `matrix` (default) | Evaluative 6×4 weighted grid, brighter toward centre, darker toward edges |
| `center_weighted` | Average of a centred 70 % oval region |
| `spot` | Single point at `--spot-x` / `--spot-y` with configurable radius |
| `multi_zone` | Full 6×4 grid analysis; visually zones the frame with coloured dots showing under/over/normal exposure |

### Live Histogram HUD

`--histogram` draws a luminance histogram in the lower-left corner with mean luminance, estimated EV, and per-zone clipping warnings (`BLOWN` highlights or `CRUSHED` shadows). Professionals rely on this to avoid unrecoverable over/underexposure.

### Metering Indicator HUD

`--no-metering-indicator` hides it; enabled by default in `--pro` mode. Draws a semi-transparent overlay showing the active metering zone and a small info panel with the current ISO, shutter speed, EV, and WB mode.

---

## Getting Started

### 1. Create the virtual environment

```powershell
python -m venv .venv
.\.venv\Scripts\activate
```

### 2. Install dependencies

```powershell
pip install -r requirements.txt
```

### 3. Run — basic preview

```powershell
.\run.bat --show-window
```

### 4. Run — Pro Camera Mode

```powershell
.\run.bat --pro --iso 800 --shutter 1/60s --wb auto --metering matrix --ev +0.3 --histogram --show-window
```

### 5. Run — night-street preset

```powershell
.\run.bat --pro --iso 3200 --shutter 1/30s --wb tungsten --metering center_weighted --ev +0.7 --focus-peaking --show-window
```

### 6. Run — daylight preset

```powershell
.\run.bat --pro --iso 100 --shutter 1/500s --wb daylight --metering matrix --ev 0.0 --show-window
```

Once running, press **q** or **Esc** in the preview window to stop. `Ctrl+C` in the terminal also works.

---

## CLI Flags

| Flag | Default | Description |
|---|---|---|
| `--camera` | `0` | Webcam device index |
| `--width` | `1280` | Output width |
| `--height` | `720` | Output height |
| `--fps` | `30` | Target frames per second |
| `--show-window` | `off` | Show OpenCV preview window |
| `--disable-media-pipe` | `off` | Skip face ROI detection |
| `--pro` | `off` | Enable Pro Camera Mode |
| `--iso` | `400` | ISO value (100–6400) |
| `--shutter` | `1/30s` | Shutter speed label |
| `--wb` | `auto` | White balance mode |
| `--wb-kelvin` | `5500` | Custom WB Kelvin (2000–9000) |
| `--wb-tint` | `0.0` | Green (-1) to magenta (+1) tint |
| `--metering` | `matrix` | Metering mode |
| `--ev` | `0.0` | Exposure compensation in EV |
| `--no-auto-brightness` | `off` | Disable auto-brightness |
| `--no-raw-sim` | `off` | Disable RAW simulation |
| `--focus-peaking` | `off` | Show focus peaking overlay |
| `--histogram` | `off` | Show live histogram HUD |
| `--no-metering-indicator` | `off` | Hide metering indicator HUD |

---

## Troubleshooting

- **Preview stays black** — make sure no other app is using the webcam. The pipeline retries DSHOW, MSMF and generic backends automatically.
- **Virtual camera unavailable** — you can still use the preview window. Install [OBS Studio](https://obsproject.com/) and its built-in Virtual Camera, then restart Zelica. The `obs` backend is tried first; `unitycapture` is the fallback.
- **Low FPS** — typical throughput is 5–10 fps on this hardware because bilateral filtering, CLAHE and face detection are computationally heavy. This is normal for a pure-Python/OpenCV pipeline at 720p. Reduce resolution with `--width 640 --height 480` to improve speed.
- **Face detection flickers / off** — rerun with `--disable-media-pipe`. MediaPipe `.dll` / wheel compatibility varies by Python version and Windows build.

---

## Project Structure

```
ZELICA/
├── main.py                         # CLI entry point + Pro Mode argument parser
├── run.bat                         # Windows launcher (activates .venv if present)
├── requirements.txt
├── src/zelica/
│   ├── __init__.py
│   ├── pipeline.py                 # ZelicaPipeline: capture → process → virtual cam
│   ├── enhancements.py             # Base DSP: WB, exposure, CLAHE, denoise, face/eyes
│   ├── face_roi.py                 # MediaPipe face landmark → bbox + eye boxes
│   ├── rust_bridge.py              # ctypes wrapper for zelica_rust.dll (WB fast path)
│   ├── pro_mode.py                 # Pro functions: ISO, shutter, WB modes, metering, EV,
│   │                               #   focus peaking, histogram, metering indicator, RAW sim
│   └── pro_mode_state.py           # ProModeConfig + ProMode orchestrator (smoothed state)
└── rust_ext/
    └── ...                         # Rust crate producing zelica_rust.dll
```

---

## Notes

- The virtual camera output is in **BGR / 8-bit** format via `pyvirtualcam`.
- The Rust extension is optional. If `zelica_rust.dll` is missing, the Python white-balance fallback runs automatically with identical results — slightly slower on the first few frames.
- ONNX-based super-resolution and further Phase 3 enhancements are planned after baseline pipeline validation.
