# Real-location references

Evidence of what the real places look like, kept separate from the two other image sets:

| Folder | What it holds | Role |
| --- | --- | --- |
| `docs/screens/refs/` (this folder) | Licensed photographs and, where useful, measured notes | **Evidence**: proportions, signage, materials, lighting, street furniture |
| [`../concepts/`](../concepts/README.md) | AI-generated art-direction frames | **Proposal**: colour, mood, detail density |
| [`../../screenshots/`](../../screenshots/README.md) | Build captures | **Proof**: what the game actually renders |

A generated frame never overrides a photograph for shape or signage. Where they disagree, the
photo wins and the concept only informs palette and atmosphere.

## Layout

```
docs/screens/refs/
  README.md                 # this file
  SIDECAR-TEMPLATE.md       # copy per folder
  hollywood/                # 6840 Hollywood Blvd block
    SIDECAR.md
    *.jpg|png
  joke-shop/                # 8433 Sunset Blvd block
    SIDECAR.md
  tv-studio/                # studio entrance reference set
    SIDECAR.md
  blocks/<block-id>/        # local map-development blocks (TODO: Local map development)
    SIDECAR.md
```

One folder per venue or block, one `SIDECAR.md` per folder listing **every** image in it. Keep the
folders flat; do not add sub-collections that the sidecar cannot describe.

## Naming

```
<subject>-<view>-<source>-<YYYYMMDD>.<ext>
el-capitan-entrance-day-wikimedia-20231102.jpg
sunset-canopy-building-standard-ownphoto-20251103.jpg
```

Use lowercase words separated by hyphens, the camera view (`day`, `night`, `entrance`, `profile`,
`across-street`), the source (`wikimedia`, `ownphoto`, `mapillary`), and the capture or download
date. Never overwrite an existing file; add a new dated file instead
(see [ADR-0014](../../adr/0014-runtime-image-root.md)).

## Licence gate

Only commit an image when redistribution is unambiguous:

- **Own photography** — permitted, with the photographer named in the sidecar.
- **CC0 / public domain** — preferred.
- **CC BY** — allowed with the attribution text recorded here and in
  [`../../../CREDITS.md`](../../../CREDITS.md).
- **CC BY-SA** — allowed only after a share-alike review of the derived textures and meshes; record
  the decision in the sidecar before use.
- **Rejected**: Street View, scraped social media, unlicensed commercial imagery, and AI upscales of
  unknown originals.

Anything that fails this gate may still be used locally for study, but it stays in `tmp/` and never
enters the repository or a build.

## Privacy gate

Blur or crop identifiable faces, minors, licence plates, screens and private interiors; do not
photograph behind closed doors; obtain property permission where a venue requires it. The image
committed here is the redacted copy, not the original.

## How the folder is used

- Build the venue **three-up boards** (photo | concept | current capture) for the review verdicts.
- Link the board from the venue map document (`docs/hollywood-boulevard-map.md`,
  `docs/joke-shop-map.md`) and from the local-map block notes.
- Cite the sidecar when a texture, proportion or signage decision is derived from a photo.
- Refresh the board when a venue change makes an old reference misleading, and note the change in
  the sidecar.

## Checks

- Every image in a folder must be listed in that folder's `SIDECAR.md`.
- The sidecar must name the licence and attribution for each entry.
- `python3 tools/check_docs.py` must pass after adding or moving a file (each tracked image has to
  be linked from its folder README).
- Generated images belong in `../concepts/`, not here.

Copy [`SIDECAR-TEMPLATE.md`](SIDECAR-TEMPLATE.md) into a new folder and fill it in.