zwitschi
2ba40f3578
Group the top-level docs into docs/project, docs/design, docs/assets and docs/process, each with its own README index. Delete the superseded docs/screens/head-review page and sheets. Rewrite every markdown link, absolute docs path and tool/test reference to the new locations, fix the pre-existing broken anchors and remove the dead Joke Shop photo-board link. check_docs OK, Python tooling 167/167.
94 lines
4.2 KiB
Markdown
94 lines
4.2 KiB
Markdown
# 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 (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](../../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/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`](SIDECAR-TEMPLATE.md) into a new folder and fill it in.
|