86 lines
6.3 KiB
Markdown
86 lines
6.3 KiB
Markdown
# Shared card production tools
|
||
|
||
`finish_masks.py` implements the approved `raw-ridges-v1` finish recipe for future stained-glass cards. It analyzes fitted opaque 2000×2800 artwork directly, without depending on spike diagnostics. Existing cards, proof builders and runtime fixtures are not migrated.
|
||
|
||
The immutable [recipe](recipes/raw-ridges-v1.json) pins all parameters and is hash-checked by the module. [Approval](recipes/raw-ridges-v1-approval.json) records the user's approval and the two reference Normal mask hashes. Changes to the recipe require a new revision; overrides are a separate reviewed recipe.
|
||
|
||
For reusable frame/backing inputs, load a pinned version from the [shared tier layer library](../../artifacts/layers/README.md). The [four-tier comparison](../../spikes/tier-layer-library-proof/README.md) demonstrates shared layers and this finish module together without migrating historical fixtures.
|
||
|
||
`card_workspace.py` manages the [working-card layout, progress index and approval move](../../docs/card-workspace.md). Use `new`, `refresh`, `validate`, and `status` during production. Run `approve` only after explicit final approval of an exact card revision; this organization migration does not approve or install any cards.
|
||
|
||
## One printing from the CLI
|
||
|
||
From the repository root, with paths replaced by the selected approved layers:
|
||
|
||
```sh
|
||
python3 tools/card-production/finish_masks.py \
|
||
--art path/art-master.png \
|
||
--printing normal \
|
||
--overlay path/normal-overlay.png \
|
||
--text path/text.png \
|
||
--name card-id \
|
||
--output path/output/masks
|
||
```
|
||
|
||
The output contains `card-id-normal-{2000,1000,500}-mask.png`, raw-ridge and pane-weight diagnostics, and a validation/provenance JSON with source hashes, recipe/module hashes and library versions. All finish exports are opaque grayscale RGBA. Diagnostics are authoring data, not extra runtime textures. The command does not compose card faces, create glyph-protection maps, install fixtures or modify shaders.
|
||
|
||
| Printing | `--overlay` | `--text` |
|
||
|---|---|---|
|
||
| Normal | Actual combined frame and backings | Actual rendered lettering |
|
||
| Textless | Actual frame only | Omit |
|
||
| Borderless | Actual backings only | Actual rendered lettering |
|
||
| Boundless | Omit | Omit |
|
||
|
||
Components must contain alpha on the same full canvas and use the artwork transform. Incorrect dimensions, missing required components, absent alpha, non-opaque framed corners and components supplied to a printing that excludes them fail explicitly. The assembler remains responsible for supplying the right frame/backing geometry, checking joins/corners and producing the face and optional glyph mask.
|
||
|
||
## Reuse one analysis across all printings
|
||
|
||
A new card's builder can import the module after resolving the repository root independently of its working directory:
|
||
|
||
```python
|
||
import sys
|
||
from PIL import Image
|
||
sys.path.insert(0, str(repo_root / 'tools/card-production'))
|
||
from finish_masks import prepare_illustration, compile_finish, export_finish
|
||
|
||
illustration = prepare_illustration(Image.open(art_master))
|
||
for printing, overlay_path, text_path in [
|
||
('normal', normal_overlay, text_layer),
|
||
('textless', textless_frame, None),
|
||
('borderless', borderless_backing, text_layer),
|
||
('boundless', None, None),
|
||
]:
|
||
overlay = Image.open(overlay_path) if overlay_path else None
|
||
text = Image.open(text_path) if text_path else None
|
||
master = compile_finish(illustration, printing, overlay, text)
|
||
exports = export_finish(master, output_dir, card_id, printing)
|
||
```
|
||
|
||
Record `raw-ridges-v1`, the recipe hash, source revision/fit transform and actual component hashes in the assembler's validation. The module owns numeric extraction; the pipeline owns printing composition and review requirements. New stained-glass assembly uses this helper rather than copying finish code from an older proof.
|
||
|
||
## Verification
|
||
|
||
Requires Python 3.10+, NumPy and Pillow, using the existing production environment. Record versions in each assembly report; the CLI does so automatically.
|
||
|
||
```sh
|
||
python3 -m unittest discover -s tools/card-production/tests -p 'test_*.py'
|
||
python3 tools/card-production/tests/check_approved_refs.py
|
||
```
|
||
|
||
Tests cover source-edge handling, dark colored lines, broad shadow steps, canvas validation, actual alpha union, removed-component recovery, retained leading, invalid printing inputs and opaque exports for all four printings. The reference check regenerates raw confidence and Normal masks for The Fall and Burning Bush in a temporary directory, comparing every approved mask SHA-256 at 2000, 1000 and 500px widths. It writes only its check report beside the tests; it does not rebuild existing card assets.
|
||
|
||
[Reference check report](tests/approved-reference-check.json) records reproduction. The approved references are retained in `spikes/finish-mask-line-continuity-proof/raw-ridges/`. Approval of those Normal fixtures establishes the recipe; new art and other printings still need their own static and moving-light review. Raw ridges can include etched flecks and painted strokes, so inspect coating mottling without adding unreviewed cleanup to v1.
|
||
|
||
|
||
## Reviewed central-flourish card assembly
|
||
|
||
[assemble_card.py](assemble_card.py) assembles the refreshed BE-042, BE-010 and BE-002 working revisions with explicitly pinned `v3` shared layers. Each revision's `build.py` supplies its directory; builders do not depend on spike outputs. Artwork approval, font hashes/resolution, wording, glyph coverage, minimum sizes and unclipped bounds are required. The assembler derives the fixed reference line box from the font tables, centers combined verse ink in the remaining band, validates title/ornament clearance and checks reference stress cases at all three resolutions.
|
||
|
||
It analyzes fitted artwork once through `raw-ridges-v1`, composes all four printings, derives matching finish/text masks, writes low/med/high exports and editable high SVGs, then refreshes the working manifests at assembly-review. Approved card packages are frozen; the tool does not approve cards or install harness fixtures. It requires a layout with the declared central-flourish spacing policy and does not provide a Common or bespoke Legendary layout.
|
||
|
||
```sh
|
||
python3 tools/card-production/assemble_card.py --root in-progress/cards/BE-042-calling-of-the-first-disciples/revisions/v03
|
||
```
|
||
|
||
Read each revision's `review/build-validation.json` and `review/printings-comparison.png` for measured results and visual-review scope.
|