Upload DATASET_README.md

DATASET_README.md

@@ -0,0 +1,305 @@
+---
+license: mit
+task_categories:
+  - image-classification
+  - image-feature-extraction
+  - zero-shot-image-classification
+language:
+  - en
+tags:
+  - architecture
+  - synthetic-data
+  - visual-similarity
+  - retrieval
+  - sim-to-real
+size_categories:
+  - 1K<n<10K
+pretty_name: "Facade — synthetic architectural style corpus"
+---
+
+# Facade — synthetic architectural style corpus
+
+**1,000 generated reference plates across 20 architectural styles**, with
+structured attribute labels, generated style readings, and a precomputed
+retrieval index.
+
+Built for a visual-similarity search task: photograph a building, retrieve the
+closest reference plates, get a reading of the style. Live app:
+**[Facade](https://huggingface.co/spaces/Jonathandav/facade)**
+
+---
+
+## What this is
+
+Every plate is generated from a **sampled attribute specification** — style,
+massing, material, window rhythm, roofline, palette — plus controlled nuisance
+factors (viewing angle, crop, light, condition). Nothing is left to the
+generator's discretion.
+
+That design buys three things:
+
+1. **Ground truth for free.** Every image inherits its labels from the
+   specification, so retrieval evaluation needs no manual annotation.
+2. **Measurable instruction compliance.** Because each style declares an
+   expected saturation band and dominant edge orientation, whether the
+   generator obeyed is a computed quantity rather than an opinion.
+3. **Sliceable nuisance factors.** Angle, crop and light are controlled, so
+   accuracy can be reported *conditioned on* them instead of averaged over
+   them.
+
+## What this is **not**
+
+The corpus depicts **generic facades in a style**. No plate represents a real
+building and none is attributable to any architect. Style labels describe the
+*generation specification*, not an art-historical judgement about any structure
+in the world.
+
+Intended use is **visual-similarity search**. This is not an authoritative
+identification tool and carries no claim about any building's date, architect,
+or heritage status.
+
+---
+
+## Files
+
+| path | contents |
+|---|---|
+| `plates/` | 1,000 reference images, 512 px PNG, `<style_id>-<nnn>.png` |
+| `plate_manifest.parquet` | per-plate labels, prompts, seeds and generated readings |
+| `style_seed.csv` | the 20 style definitions and their expected measurements |
+| `index_embeddings.npy` | precomputed image embeddings for the shipped model |
+| `index_plate_ids.csv` | row order for the embedding matrix |
+| `index_model.txt` | which model produced the index |
+| `eda_summary.json` | measured compliance and signal statistics |
+| `generation_log.csv` | per-attempt generation record (acceptance, rejection reasons) |
+| `notebooks/` | corpus generation, EDA, model comparison, publishing |
+
+### Loading
+
+```python
+import numpy as np, pandas as pd
+from huggingface_hub import hf_hub_download
+
+REPO = "Jonathandav/facade-styles"
+get  = lambda f: hf_hub_download(REPO, f, repo_type="dataset")
+
+E        = np.load(get("index_embeddings.npy"))          # (1000, d)
+ids      = pd.read_csv(get("index_plate_ids.csv"))       # row order
+manifest = pd.read_parquet(get("plate_manifest.parquet"))
+styles   = pd.read_csv(get("style_seed.csv"))
+```
+
+Plates resolve directly:
+`https://huggingface.co/datasets/Jonathandav/facade-styles/resolve/main/plates/ST01-000.png`
+
+---
+
+## The 20 styles
+
+Bauhaus International · Brutalist · Art Deco · Ottoman Revival · Mandate
+Eclectic · Neoclassical · Gothic Revival · Venetian Gothic · Georgian ·
+Victorian Terrace · Mid-century Modern · Postmodern · Deconstructivist ·
+Contemporary Curtain Wall · Mediterranean Vernacular · Adobe Pueblo · Soviet
+Constructivist · Scandinavian Functionalist · Industrial Warehouse · Japanese
+Metabolist
+
+Fifty plates each. Anything outside these twenty is still forced onto the
+nearest of them — worth knowing before trusting a result.
+
+---
+
+## How it was built
+
+| stage | detail |
+|---|---|
+| image model | SDXL-Turbo, 6 steps, `guidance_scale=3.0`, 512 px |
+| text model | Qwen2.5-1.5B-Instruct, for the style readings |
+| acceptance | every plate measured after generation; rejects regenerated with a fresh seed, up to 5 attempts |
+
+Prompt construction is deliberate. The style name, period and iconic features
+lead the prompt, because diffusion weights early tokens most heavily.
+`prompt_2` is **not** passed: in SDXL the second encoder produces the pooled
+embedding that conditions the whole image, and putting a generic photographic
+style there collapsed every architectural style into the same contemporary
+office block.
+
+---
+
+## Measured properties
+
+### Style compliance
+
+Each style declares an expected saturation band and dominant edge orientation.
+Both are computed from pixels and compared against the declaration.
+
+| test | result |
+|---|---|
+| declared saturation rank vs measured | **Spearman ρ = 0.67, p ≈ 1.5 × 10⁻¹³², n = 1000** |
+| saturation within calibrated band | see `eda_summary.json` |
+| edge orientation as declared | see `eda_summary.json` |
+
+The saturation bands are **calibrated from the corpus**, not set a priori. The
+first attempt used absolute thresholds chosen before any image existed and
+scored 8% compliance — because measured saturation ran 0.30–0.85 while the
+"medium" band had been guessed at 0.22–0.50. What the style table actually
+asserts is a *ranking*, not a value on a calibrated scale, so the headline test
+is rank agreement and the bands were rederived from corpus quantiles.
+
+### Does style dominate the nuisance factors?
+
+Variance in each measured feature attributable to each factor (η²):
+
+| feature | style | light | crop | view | condition |
+|---|---|---|---|---|---|
+| saturation | **0.63** | 0.12 | ~0.01 | ~0.00 | ~0.00 |
+| brightness | **0.66** | 0.18 | ~0.01 | ~0.00 | ~0.00 |
+| contrast | **0.43** | 0.19 | ~0.01 | ~0.00 | ~0.00 |
+| orientation ratio | **0.56** | 0.04 | ~0.00 | ~0.00 | ~0.00 |
+| edge density | **0.63** | 0.07 | 0.02 | ~0.01 | ~0.00 |
+| angle entropy | **0.63** | ~0.01 | ~0.00 | ~0.01 | ~0.00 |
+
+Style dominates every feature. Crop, view and condition sit at essentially
+zero — which validates the sampler: those axes are *cycled* rather than drawn
+independently, so they cannot correlate with style. If they did, an embedding
+model could score well by learning framing instead of architecture.
+
+Light is the only meaningful contaminant, and only on the photometric
+features, which is physically unsurprising. Contrast has both the weakest style
+margin and the strongest light effect, making it the least trustworthy of the
+six.
+
+---
+
+## Retrieval benchmark
+
+Image-to-image retrieval over the corpus, style as the label, chance ≈ 0.049.
+
+| model | Recall@1 | Recall@3 | MRR | lift |
+|---|---|---|---|---|
+| SigLIP-B/16 | 0.972 | 0.994 | 0.983 | 19.8× |
+| **LAION-CLIP-B/32** | 0.970 | 0.991 | 0.981 | 19.8× |
+| CLIP-B/32 | 0.955 | 0.988 | 0.972 | 19.5× |
+
+**These are at ceiling and the comparison cannot resolve.** Plates of the same
+style share nearly identical prompt strings, differing only in angle, crop,
+light and condition, so same-style plates are near-siblings. Every slice — by
+crop, view, light or condition — falls between 0.975 and 1.000. The differences
+between models are inside noise.
+
+Note also that `material` and `period` are functionally determined by `style`
+in this corpus (one value each per style), so they are not independent label
+axes. `ornament_level` is.
+
+### Most confused pairs
+
+| true | retrieved | rate |
+|---|---|---|
+| Georgian | Victorian Terrace | 0.16 |
+| Victorian Terrace | Georgian | 0.08 |
+| Mandate Eclectic | Ottoman Revival | 0.06 |
+| Brutalist | Bauhaus International | 0.04 |
+
+Georgian ↔ Victorian Terrace was **predicted before running any embedding
+model**, from centroid distance in measured saturation/orientation space. Two
+British brick terraces a century apart, and both the pixel metric and CLIP
+agree they are the hardest pair.
+
+The remaining confusions have a structure the pixel metric could not see:
+Bauhaus International acts as an *attractor* for the modernist styles —
+Brutalist, Soviet Constructivist and Japanese Metabolist all leak toward it.
+That is a semantic effect, not a geometric one.
+
+---
+
+## Sim-to-real
+
+The corpus is synthetic; queries are not. Evaluated on **17 hand-labelled
+photographs** of real buildings in Tel Aviv, Jaffa, Paris and the Greek
+islands, retrieving against the wholly synthetic index.
+
+| model | real R@3 | synthetic R@3 | gap |
+|---|---|---|---|
+| **LAION-CLIP-B/32** | **0.94** (16/17) | 0.991 | **−0.05** |
+| SigLIP-B/16 | 0.88 (15/17) | 0.994 | −0.11 |
+| CLIP-B/32 | 0.76 (13/17) | 0.988 | −0.22 |
+
+Per style (LAION): Bauhaus 1.00 · Ottoman Revival 1.00 · Mandate Eclectic 0.83
+· Neoclassical 1.00 · Gothic Revival 1.00 · Mediterranean Vernacular 1.00.
+
+**The headline finding.** The synthetic benchmark ranked SigLIP first by 0.002
+on Recall@1. On real photographs LAION wins and has less than half the domain
+gap. **Selecting on the saturated benchmark would have shipped the weaker
+model.** A benchmark at ceiling does not merely fail to discriminate — it
+discriminates wrongly.
+
+Mandate Eclectic scores lowest, and it was also the group flagged as
+lowest-confidence during hand-labelling. Labelling uncertainty surfacing in the
+results is a reassuring sign about both.
+
+Failure cases are architecturally sensible rather than random: a Bauhaus
+building retrieved as Soviet Constructivist (contemporaneous interwar
+modernism, strip windows, white render), and a night photograph of a Mandate
+building retrieved as Mediterranean Vernacular (both cream render with
+shutters).
+
+---
+
+## Generator failures found during construction
+
+Four, documented in `notebooks/02_facade_eda.ipynb`. **Three were silent** — no
+exception, no warning, and output that looked entirely plausible.
+
+| # | failure | how it was caught | silent |
+|---|---|---|---|
+| 1 | the pooled embedding overrode every style | Bauhaus, Brutalist and Gothic all rendered as the same beige office block | yes |
+| 2 | detail crops destroyed the class signal | style unrecoverable from a cropped window grid | yes |
+| 3 | `key_features` never reached the image prompt | code review after failure 1 | no |
+| 4 | prompts truncated at 77 tokens | validator token-budget check | yes |
+
+A fifth was a **measurement** bug rather than a generation one: the orientation
+classifier could only emit three of the five declared labels, so every style
+declaring `curved` or `diagonal` scored zero and looked like a total generator
+failure. Fixing the metric raised orientation compliance from 60% to 83%.
+
+The general lesson, and the reason this section exists: a synthetic corpus
+needs instrumented acceptance criteria. Looking reasonable is not evidence of a
+working generator, and a broken metric can invent a failure as easily as a
+broken generator can hide one.
+
+---
+
+## Known limitations
+
+- Style boundaries blur where visual grammars genuinely overlap; the confusion
+  matrix above reports which pairs.
+- Synthetic-to-synthetic retrieval saturates and cannot rank models reliably —
+  see the sim-to-real section.
+- `material` and `period` are determined by `style` and are not independent
+  labels.
+- The real-photograph evaluation is small (n = 17) and unevenly distributed;
+  per-style figures are reported alongside the mean for that reason.
+- Generated plates are stylistic composites and may combine period details that
+  would not co-occur on a real building.
+- One style's declared edge orientation disagrees with measurement. The
+  declaration is probably wrong, and it has been left visible rather than
+  fitted to the data.
+
+## Ethical notes
+
+No plate depicts a real building or is attributable to any architect. The
+accompanying app states, in the interface, that its output is a stylistic
+suggestion carrying no claim about a building's architect, date, or heritage
+status. Both the image and text prompts explicitly bar the models from naming
+real architects or buildings and from asserting heritage status.
+
+## Citation
+
+```bibtex
+@misc{facade_styles_2026,
+  title  = {Facade: a synthetic architectural style corpus with
+            sim-to-real evaluation},
+  author = {Jonathan Dav},
+  year   = {2026},
+  url    = {https://huggingface.co/datasets/Jonathandav/facade-styles}
+}
+```