zelica 0.1.0

AI-powered real-time webcam enhancer SDK

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

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

2. Install dependencies

pip install -r requirements.txt

3. Run — basic preview

.\run.bat --show-window

4. Run — Pro Camera Mode

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

5. Run — night-street preset

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

6. Run — daylight preset

.\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 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.