security-game/docs/screens/refs

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/	AI-generated art-direction frames	Proposal: colour, mood, detail density
../../screenshots/	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 (first board, 2026-11-03)
    README.md               # board overview and image gallery
    SIDECAR.md              # provenance table
    *.jpg|png
  tv-studio/                # studio entrance reference set
    README.md
    SIDECAR.md
  blocks/<block-id>/        # local map blocks (TODO: 3D model re-evaluation → H–M)
    README.md
    SIDECAR.md

One folder per venue or block with a README.md (the board: what each image is evidence for) and a SIDECAR.md listing every image in it. tools/check_docs.py requires each tracked image to be linked from the folder README, so the gallery and the sidecar stay in step. Keep the folders flat; do not add sub-collections that the sidecar cannot describe.

Naming

<subject>-<view>-<source>-<ISO date>.<ext>
el-capitan-facade-day-wikimedia-2009-10-27.jpg
sunset-canopy-night-ownphoto-2025-11-03.jpg

Use the full YYYY-MM-DD date when known; YYYY-MM or YYYY is acceptable for historical photos where only that much is recorded (e.g. masonic-temple-historic-pd-1922.jpg). The sidecar always carries the original capture date as precisely as the source states it.

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).

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.
• 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/design/venues.md#hollywood-boulevard, docs/design/venues.md#the-joke-shop) 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 into a new folder and fill it in.