Skip to content

v0.2.0-alpha — Visual DNA lands

Pre-release
Pre-release

Choose a tag to compare

View all tags
@Shepdesign Shepdesign released this 21 May 22:09
· 57 commits to main since this release
v0.2.0-alpha
a0d9e2b

hooked on facets v0.2.0-alpha — Visual DNA lands

Second alpha. One big new feature — Visual DNA — plus the indexer plumbing to make it sing. Still pre-alpha; still installable; still don't ship it to a production storefront yet.

📦 Download hooked-on-facets-0.2.0-alpha.zip · 📝 Wiki: Visual DNA · 🗺️ Roadmap

🎨 What's new: Visual DNA

A facet where shoppers describe what they want by dropping an image, pasting a URL, or eyedropping any color on screen — and the catalog filters to products that match.

Three input modalities, two matching modes.

Mode When it kicks in What it does
v2 — indexed ΔE ranking Indexer has populated _visual_dna_lab rows from product featured images The endpoint converts the input hex to LAB and returns products ranked by ΔE76 distance, computed in SQL. The Resolver intersects with whatever other facet filters are active and preserves the ΔE order so subsequent narrowing doesn't break the ranking.
v1 — snap to nearest term No LAB data is indexed yet (no featured images, indexer hasn't run since the migration) Falls back gracefully: the dominant hex snaps to the closest existing color term in the target facet, applied as a normal filter.

The frontend tries v2 first, falls back to v1 silently. Zero configuration to opt in.

Browser support for the three modalities:

Modality Support
Drop image file Universal
Paste image URL Universal — but the image host must send permissive CORS for canvas reads
EyeDropper API Chromium-only (Chrome / Edge / Brave / Opera). Feature-detected and hidden where unsupported.

🔧 Under the hood

  • src/VisualDna/ColorExtractor.php — loads featured images via WP_Image_Editor, downsamples to 96 px on the long side, samples pixels with GD, quantizes to 4096 buckets, picks the heaviest non-near-white/black bucket, and converts the average RGB to LAB (D65). Mirrors the storefront JS pipeline pixel-for-pixel — verified bit-perfect against synthetic test images (25/25 ΔE=0.00).
  • POST /wp-json/hof/v1/visual-dna — {hex, limit?} in, top-K product IDs ranked by ΔE76 out. Reports indexed_count so the frontend can decide whether to use v2 or fall back.
  • Resolver::resolve_ids reserved _visual_ids key — intersects matched IDs with this ordered list and preserves the input order. Works from both the /filter REST endpoint and URL state (?hof[_visual_ids][]=…).
  • Schema migration to DB version 1.2.0 — three nullable DECIMAL columns (lab_l, lab_a, lab_b) plus a visual_dna_lookup covering index on (facet_name, lab_l). Auto-runs on plugins_loaded via dbDelta when the stored version trails the constant — no manual upgrade step.
  • bin/verify-visual-dna.{php,sh} — verification harness. Generates synthetic test PNGs, sideloads them as featured images on N products, runs the full reindex, and diffs extracted vs expected LAB. Re-runnable on any catalog.

🚧 Known gaps

  • Color only. Visual DNA matches the dominant color of a product image — pattern, shape, texture don't factor in. A striped red-and-blue shirt and a solid violet shirt may land near each other in LAB space.
  • One color per product. Products with multiple distinct colors collapse to their heaviest non-extreme bucket. Per-product palette matching is on the roadmap as Visual DNA v3.
  • Index time cost. Each product with a featured image pays ~30–80 ms for the extraction during reindex. On a 100k-product catalog the initial extraction is meaningful — plan for it on import.

🆙 Upgrade from v0.1.0-alpha

  1. Replace the plugin files (drop-in upgrade — no settings or option changes required).
  2. On first request after the upgrade, the schema migration auto-runs (hof_db_version jumps to 1.2.0).
  3. To populate the LAB index, trigger a reindex — admin button or wp eval 'new HookedOnFacets\Indexer()->reindex_all();'.
  4. (Optional) Add a Visual DNA facet to your facet set with display: "visual_dna" and a target_facet pointing at any color-bearing facet you already configured.

Still in the box

Everything from v0.1.0-alpha continues to work: the ten public facet displays (Checkbox, Radio, Dropdown, Toggle, Hierarchy, Range, Date Range, Search, Color Swatch, Swipe Deck), the 2D Slider and Ask view facets, the React 18 admin SPA, the vanilla JS public runtime, the React + WP-components admin, BYOK Anthropic key for Ask.

Feedback

Issues, PRs, "this didn't work for me" reports — all welcome.

Assets 3
Loading