README.md

---
title: PAREIDOLIA
emoji: 👁️
colorFrom: gray
colorTo: indigo
sdk: gradio
sdk_version: 6.16.0
app_file: app.py
pinned: false
license: apache-2.0
short_description: "point at anything. find the face that was always there."
models:
  - openbmb/MiniCPM-V-4_5
  - openbmb/VoxCPM2
datasets:
  - AndresCarreon/pareidolia-menagerie
tags:
  - track:wood
  - sponsor:openbmb
  - achievement:offbrand
  - achievement:sharing
  - achievement:fieldnotes
  - achievement:offgrid
  - build-small-hackathon
  - minicpm
  - voxcpm
  - camera
  - multimodal
---

# 👁️ PAREIDOLIA

**Everything secretly has a face.**

Point your camera at any object. A small **MiniCPM-V** spirit-medium studies the
photo the way you study clouds — it finds the two bonnet bolts that were always
eyes, the outlet cap that was always a mouth — and the face that was hiding in
your fire hydrant opens its eyes, blinks at you, and tells you, in its own
voice, exactly what it has been putting up with.

> *"Forty years on this corner. Not one dog has shown me respect."*

Every awakened object joins the **Menagerie** — one public wall, shared by every
visitor, where all of them blink, glance around, and mutter.

![A fire hydrant wakes up — eyes find its bonnet bolts, then it speaks](https://huggingface.co/spaces/build-small-hackathon/pareidolia/resolve/main/demo/pareidolia-hero.gif)

*▶️ [Watch the 75-second demo on YouTube](https://youtu.be/tRAISheTCT8) (works muted).*

## ✨ The moment that sells it

You photograph your own coffee mug. Mist crosses the photo while the medium
works — *"there is something here…"* — then it names what it found: *"the two
painted notes… symmetric…"* Two eyes the exact color of the glaze fade onto the
ceramic and **blink**. And then the mug speaks. It has noticed things about you.
It has been keeping a list.

No face is invented. The eyes land on features that are *really there* — that's
the whole point, and the whole name.

## 🧠 How it works — taste from the model, facts from the code

A hard separation of church and state, twice over:

```
your photo (browser downscales; YOUR ZeroGPU quota pays for your séance)
   │
   ▼  one @spaces.GPU window, ~20s
┌─ THE MEDIUM · MiniCPM-V-4_5 ──────────────────────────────────┐
│  ONE structured generation (critique-then-final JSON):        │
│  privacy gate → object + condition → named VISIBLE features   │
│  ("left bonnet bolt: eye") → persona → the grudge             │
└──────────────┬────────────────────────────────────────────────┘
               ▼
┌─ THE SURVEYOR · OpenCV, deterministic ────────────────────────┐
│  snaps each named feature to the strongest real anchor nearby │
│  (Hough circles, blobs, corners; pair-coherence rules) —      │
│  the model never places a pixel; the code never invents an eye│
└──────────────┬────────────────────────────────────────────────┘
               ▼
┌─ THE VOICE · VoxCPM2 ─────────────────────────────────────────┐
│  voice DESIGNED from a text description — ten distinct        │
│  characters, zero reference audio                             │
└──────────────┬────────────────────────────────────────────────┘
               ▼
the LIFE engine (client-side SVG): eyes tinted from the photo's own
palette → first blink → saccades, pupil-follow → the mouth rides the
audio's amplitude. The wall replays all of it forever with ZERO GPU.
```

The writing is governed, not vibes: a grudge-archetype bank keyed to the
object's *visible condition* (the_veteran/rusted, the_martyr/worn,
the_perfectionist/pristine, the_diva/displayed…), and an iron rule that every
line must reference something actually in the photo.

Privacy is structural: the same generation gates **real human faces and NSFW**
before anything else runs — the refusal is simply *"It is already awake."* —
and nothing reaches the public wall except server-held, gate-checked records.
No user identity is ever stored.

## 📦 Models (≈ 11B total — well under the 32B cap)

| role | model | size | license |
|---|---|---|---|
| sees the face, writes the soul | [openbmb/MiniCPM-V-4_5](https://huggingface.co/openbmb/MiniCPM-V-4_5) | 8.7B | Apache-2.0 |
| speaks the grudge | [openbmb/VoxCPM2](https://huggingface.co/openbmb/VoxCPM2) | 2.29B | Apache-2.0 |

Both models run **in-Space**. No external APIs, no remote endpoints.

## 🏆 Badges

- **Off-Brand** — the entire UI is custom (static `web/` served by `gr.Server`;
  zero gradio components on screen).
- **Off the Grid** — all inference in-Space on ZeroGPU.
- **Sharing is Caring** — every awakening publishes its full wake-trace (the
  medium's JSON, the surveyor's snap deltas, the chosen voice) to
  [AndresCarreon/pareidolia-menagerie](https://huggingface.co/datasets/AndresCarreon/pareidolia-menagerie).
- **Field Notes** — [FIELD_NOTES.md](FIELD_NOTES.md) — the build log, including
  the dependency saga and what a vision model does when you ask it to find
  eyes in a stapler (also written up as a [field report](BLOG.md)).

## 📋 Submission links

- **Demo video:** [youtu.be/tRAISheTCT8](https://youtu.be/tRAISheTCT8) — 75s, real awakenings + real voices, works muted. ([.mp4 mirror](https://huggingface.co/spaces/build-small-hackathon/pareidolia/resolve/main/demo/pareidolia-demo.mp4))
- **Social post:** [x.com/_Andresio/status/2066372315202441312](https://x.com/_Andresio/status/2066372315202441312)

## ▶️ Run it locally

```bash
pip install -r requirements-dev.txt
PAREIDOLIA_BACKEND=mock python app.py   # mock medium: no GPU, no ML deps needed
```

The Space runs `PAREIDOLIA_BACKEND=zerogpu`; mock returns canned awakenings
with realistic latency so the whole experience works on a laptop.

## 🙏 Credits

- Models: OpenBMB **MiniCPM-V-4_5** + **VoxCPM2** (Apache-2.0).
- Seed-wall photos: CC0 / public-domain images via Openverse & Wikimedia
  Commons — per-image attribution in [`seeds/eval/LICENSES.md`](seeds/eval/LICENSES.md).
- Type: Cormorant Garamond (SIL OFL).

*It was in there all along.*