DATASET_README.md

---
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}
}
```