BlueGit

golden-age paperdoll-renderer

design: finished result folder = .ppda + atlases + raw files/, bookkeeping only in-progress, export data in .ppda v4 (Tim t993u/t994u)

timfa Grok Bot · pushed by timfa

Authored 2026-11-07 · 6 days ago

Hash
12909d604b24b7e6aafe4bc98552edfb5373aa89
Parent
f2f838c0
1 file changed +7 −0
design.md +7 −0
@@ -461,3 +461,10 @@ Decision (superseded and reverted per Tim t991u, see below): automatic per-body
461 461 - For each pixel the depth composition still picks the winning layer, and the stored depth pixel of that layer is the one shown. Pixels with no winner stay transparent.
462 462 - Only **Resultaat** decodes depth into the canonical 16-bit value, for the composition and the relighting. It looks the same for every depth format, within one quantization level.
463 463 - Synthetic layers with no stored file pixels (tests) fall back to the canonical gray.
464
465 ## Decision 2026-11-07 (Tim t993u/t994u): finished result folder holds only consumer output
466 - A finished `renders/<sex>-<settype>-atlas/` contains only the `.ppda`, the four atlas PNGs and a `raw files/` subfolder. `raw files/` groups every loose per-frame map folder (`raw files/<sex>/<set>/<clip>/f……/p…_y…_<map>.png`). There are no other JSON files.
467 - `render.json`, `complete.json`, `progress.jsonl`, `resume.jsonl`, `run.lock` and archived `attempt-*` markers exist only in the temporary `inprogress-*` build folder. After the build is verified (atlas reader + export_set reader) and the lock is released, they are removed, with `complete.json` last, and only then is the folder swapped into place.
468 - What still matters after completion goes into the `.ppda`, not into `raw files/`. `.ppda` format 4 adds `export`: the full render contract (formerly `render.json`), `passes` and `png_sha256` (SHA-256 per loose PNG, keyed by its `raw files/…` path). The export_set reader rebuilds its render/complete view from that, and checks the `.ppda` SHA-256 and every loose PNG checksum as before. Formats 2–3 and older result folders (loose maps and manifests at the root) are still read.
469 - `depth_clamped` statistics are progress-only now; they are not persisted.
470 - Crash safety: a build is complete when it has `complete.json`, or when it has no `render.json` and does have a `.ppda` (already stripped). `recover` verifies such an unlocked build, strips any remaining bookkeeping (idempotent) and promotes it. Resume refuses completed builds as before. Quarantined `.corrupt-aNNN-K` files are still kept, never deleted; that is the only exception to the consumer-only layout.
@@ -461,3 +461,10 @@ Decision (superseded and reverted per Tim t991u, see below): automatic per-body
461- For each pixel the depth composition still picks the winning layer, and the stored depth pixel of that layer is the one shown. Pixels with no winner stay transparent.
461- For each pixel the depth composition still picks the winning layer, and the stored depth pixel of that layer is the one shown. Pixels with no winner stay transparent.
462- Only **Resultaat** decodes depth into the canonical 16-bit value, for the composition and the relighting. It looks the same for every depth format, within one quantization level.
462- Only **Resultaat** decodes depth into the canonical 16-bit value, for the composition and the relighting. It looks the same for every depth format, within one quantization level.
463- Synthetic layers with no stored file pixels (tests) fall back to the canonical gray.
463- Synthetic layers with no stored file pixels (tests) fall back to the canonical gray.
464
465## Decision 2026-11-07 (Tim t993u/t994u): finished result folder holds only consumer output
466- A finished `renders/<sex>-<settype>-atlas/` contains only the `.ppda`, the four atlas PNGs and a `raw files/` subfolder. `raw files/` groups every loose per-frame map folder (`raw files/<sex>/<set>/<clip>/f……/p…_y…_<map>.png`). There are no other JSON files.
467- `render.json`, `complete.json`, `progress.jsonl`, `resume.jsonl`, `run.lock` and archived `attempt-*` markers exist only in the temporary `inprogress-*` build folder. After the build is verified (atlas reader + export_set reader) and the lock is released, they are removed, with `complete.json` last, and only then is the folder swapped into place.
468- What still matters after completion goes into the `.ppda`, not into `raw files/`. `.ppda` format 4 adds `export`: the full render contract (formerly `render.json`), `passes` and `png_sha256` (SHA-256 per loose PNG, keyed by its `raw files/…` path). The export_set reader rebuilds its render/complete view from that, and checks the `.ppda` SHA-256 and every loose PNG checksum as before. Formats 2–3 and older result folders (loose maps and manifests at the root) are still read.
469- `depth_clamped` statistics are progress-only now; they are not persisted.
470- Crash safety: a build is complete when it has `complete.json`, or when it has no `render.json` and does have a `.ppda` (already stripped). `recover` verifies such an unlocked build, strips any remaining bookkeeping (idempotent) and promotes it. Resume refuses completed builds as before. Quarantined `.corrupt-aNNN-K` files are still kept, never deleted; that is the only exception to the consumer-only layout.