6.5 KiB
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 pins all parameters and is hash-checked by the module. Approval 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. The four-tier comparison 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. Use new, refresh, validate, and status during production. Run approve only after explicit final approval of an exact card revision; it keeps the full accepted package in artifacts/cards/ and compacts superseded work to textual provenance plus low printing references. compact --card ID applies that retention once to an already approved card. Neither command installs harness fixtures.
One printing from the CLI
From the repository root, with paths replaced by the selected approved layers:
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:
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.
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 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 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.
python3 tools/card-production/assemble_card.py --root in-progress/cards/ID-title/revisions/v02
Read each revision's review/build-validation.json and review/printings-comparison.png for measured results and visual-review scope.