Core Concepts

Why Not Just Run the Model?

Modern vision models (ResNet, ViT, CLIP) are expensive. A ResNet-50 inference pass costs ~74ms on a CPU. But models are also notoriously fragile: a blurry, clipped, or out-of-distribution image doesn't cause an error — it causes a silent wrong prediction with high confidence.

VigilCV solves this by running a 223µs pre-flight gate before the model is ever invoked.

The Three Failure Modes We Target

1. Optical Degradation

Physical lens or capture issues:

Motion blur — Laplacian variance collapses toward 0

Defocus — Frequency content shifts to low bands

Lens occlusion — Entropy collapses; dynamic range shrinks

2. Signal Clipping

Histogram pathologies:

Underexposure — >20% of pixels below intensity 10

Overexposure — >20% of pixels above intensity 245

File corruption — Truncated JPEG/PNG header, zero-filled arrays

3. Covariate Shift (Distribution Drift)

Statistical changes between the training distribution and live inference data:

Domain shift — New camera hardware, different lighting conditions

Seasonal drift — Dataset captured in summer, model deployed in winter

Sensor noise — Camera firmware update changes sensor response

Why Heuristics Instead of Neural Metrics?

Many teams instinctively reach for a small CNN classifier ("blurry vs. not blurry"). VigilCV deliberately avoids this:

Approach	Latency	Requires Training Data	GPU	Interpretable
VigilCV Heuristics	223µs	No	No	Yes
Small CNN classifier	~8ms	Yes	Preferred	No
CLIP embedding	~38ms	No	Yes	No
ResNet features	~74ms	No	Yes	No

Signal-theoretic heuristics (Laplacian variance, Shannon entropy) have closed-form mathematical definitions, run in microseconds, and require zero training data. They are universally robust across domains.

Architecture Overview

Input Image
    │
    ├─► [FileGuard]       — Decode JPEG/PNG header, detect truncation/corruption
    │
    ├─► [BlurDetector]    — Discrete 3×3 Laplacian → variance over grayscale
    │
    ├─► [EntropyMeter]    — 8-bit histogram → Shannon entropy (bits)
    │
    ├─► [ExposureAuditor] — Per-channel clipping ratios (under/over)
    │
    └─► [DriftEngine]     — 54D spatial color moments → Wasserstein-1 + MMD
            │
            ▼
      QualityMetrics (dataclass)
            │
            ▼
      Pass / Raise QualityThresholdExceeded / Raise CorruptImageError

Every component is stateless — no global state, no class variables that mutate between calls. This makes VigilCV thread-safe for concurrent BatchAuditor workloads.