Uni vs Matics

Mathematical analysis & template engine for fractal art.

Uni vs Matics scans a corpus of fractal images and reduces each qualifying piece to mathematics, not an image file — then serves a static website that reconstructs, morphs, and sonifies those equations live in the browser. Images that don't yield useful, unique equations (fog/blur, TV-snow static, text/emoji-dominant frames, near-duplicates) are filtered out automatically.

The primary form is an exact reconstruction equation per image, per YCbCr channel — channel(x,y) = Σ_k c_k·ψ_k(x,y), a sparse multi-level CDF 9/7 biorthogonal wavelet (lifting) expansion at true native resolution. Each template also carries:

1. Structured attributes — line-vector field, orientation field, colour palette + per-channel Gaussian mixtures, spatial colour field, luminance density grid, lumen-degradation propagation field, morph-allotment gradients, radial/angular FFT spectra.
2. Symbolic equations — the same numbers as human-readable math.
3. Generative IFS — affine maps + weights + variation + box-counting dimension that regenerate a fractalized image in the source's family.

Two engines consume this: an exact-copy engine (the viewer rebuilds the actual image at native resolution, with a deviation dial, a math-layer still, scroll-through-all, live-morph and a generative equation→music player) and a world engine (a flat layered math compositor — each piece is decomposed into its math layers: the reconstruction, glow, structure, colour field, edges and fine detail, all from the equation, stacked and blended flat with their own blend modes, geometry locked to the frame, then morphed piece→piece; no camera, no orbiting a 3D plane). The world engine exposes a full effects palette — every blend mode, the CSS filter set, per-layer toggles and an evolve (build/collapse/merge) control. Sound is music, not a drone: a generative composer derives a key/scale/tempo from each equation and plays a melody + bass + palette-chord pads, distinct per image. You can also turn your own image into its equation (and its own music) entirely in the browser.

The analysis is classical computer vision and signal processing throughout (OpenCV + NumPy + SciPy) — no OCR, no trained models. Coefficients ship compactly as LEB128 delta-varint positions + Int16 values (base64), and the browser runs a 9/7 inverse that is byte/pixel-identical to the analyzer.

Docs: structure → docs/ARCHITECTURE.md · capabilities → docs/SKILL_TREE.md · milestones → docs/ROADMAP.md · visitor-facing pipeline → web/workflow.html · deep reference → web/docs.html.

---

Layout

ftcore/        analysis + reconstruction engine (io, detect, analyze, generative, reconstruct, template, uniqueness)
run.py         CLI: corpus → templates (multiprocessing); loads NATIVE rgb for reconstruction
build_web.py   templates → static-site data bundle (web/data/: dv1 coeffs, webp thumbs, motion DNA + per-piece motion)
web/           the static site — landing, browser, viewer (exact-copy engine), video (world engine),
               equations, uploads (in-browser equationalizer), workflow, docs/wiki + assets
make_social.mjs  Playwright → greyscale 3D-still collage social image (web/social/collage.png)
screenshots.mjs  Playwright capture → per-page social images
docs/          ARCHITECTURE.md · SKILL_TREE.md · ROADMAP.md (canonical project docs)
TODO.md        project task list (original spec captured verbatim)
RESUME.md      session handoff

Run the engine

# from this directory
python run.py --input ../downloads/deviantart --output ./out_full --workers 14
python run.py --input ../downloads/deviantart --output ./out --limit 30 --no-mp   # smoke

# export the static-site data bundle
python build_web.py --templates ./out_full --web ./web

Outputs: out_full/templates/*.json + *.eq.txt, out_full/rejected.json (every dropped image + reason), out_full/summary.json.

Run the website

The site is pure static (HTML/CSS/JS + JSON) and fetch()es its data, so it must be served over HTTP — file:// won't work.

cd web && python -m http.server 8080      # → http://localhost:8080/

Deploy

Pure-static deploy to the lab pages host via Forgejo Actions (.forgejo/workflows/deploy.yml): on push to main, web/ is rsynced to univsmatics.git.unityailab.com (lab convention: <lowercased-repo-name>.git.unityailab.com, served by the wildcard nginx vhost).

Auth is the box's SSH key — there is nothing to log into. git@git.unityailab.com:UnityAILab/UniVsMatics.git push/clone/fetch all work via the SSH key (ssh -T git@git.unityailab.com → "successfully authenticated"). NEVER build a login form / password→token / OAuth helper to reach Forgejo — it's SSH-key auth for git ops.

The repo MUST live under the UnityAILab org (not a personal GFourteen/ namespace). The deploy Action reads the org-level secrets PAGES_DEPLOY_KEY / PAGES_DEPLOY_HOST / PAGES_DEPLOY_USER; a personal-namespace repo can't see them, so the rsync step has no key and nothing ships. Org push-create is disabled on this Forgejo, so a new org repo is created (or a personal one transferred) in the web UI, then pushed over SSH. Requires Actions enabled on the repo + an online org runner.

Fixed 2026-06-22 — the site 404'd because the repo was GFourteen/UniVsMatics (personal namespace, no org deploy secrets), and a tools/forgejo-login.mjs password-form had been built to "log in" (unnecessary — SSH already authenticates). Fix: deleted the login script, transferred the repo to UnityAILab, repointed the remote to the org URL, and pushed main → the Action fired on the org runner and the site went live. The issue was never auth/login — it was personal-namespace vs org-deploy.

Social images

python make_social.py builds one shared og:image: the real, full-colour, high-def reconstruction of "Imprisonment" rebuilt directly from its equation at native resolution, turned on its side (portrait → landscape, uniform scale + tiny centre-crop, no stretch) and text-scrubbed → web/social/collage.png (1200×630). Every page points its og:image/twitter:image at that single card and supplies its own tailored social description.

Cache-busting

Asset/data freshness is gated on one stamp: FT.VERSION in web/assets/common.js. FT.json() appends ?v= to every data fetch, and every <script src="assets/*.js?v=…"> tag carries the same query. Bump it on every deploy so browsers can't serve a stale JS/data mix (the root cause of the Phase 4 empty-lists / "Template not found" / dead-3D, all traced to cached pre-9/7 assets). web/version.txt is the human-readable build marker.

---

The source art

The corpus is one artist's body of work — vectored fractal pieces by a schizophrenic artist with photographic memory, who recalled the hallucinations they experienced and rendered them faithfully as fractal art. Uni Vs Matics exists to capture the mathematics underneath those recalled forms, so the structures can be studied, browsed, regenerated, and heard.

---

By GFourteen. Source art © its author. Self-hosted at git.unityailab.com.