Milestone 4 of 8

Build aligned arrays and metadata

Stack patches and masks in global row-major order, keep metadata aligned through shared indexes, and reject duplicate spatial identities or mismatched rows.

Arrays become a dataset only when every row still refers to the same patch in every representation. Stack pixels, masks, and metadata through one order.

Goal

Build aligned patch and mask arrays, preserve global and per-image order, reject identity collisions, and verify expected counts and row alignment.

Aligned dataset contract

Save patches as shape (patch_count, PH, PW, C) and masks as (patch_count, PH, PW). Save metadata rows in the same row-major order. Every row has one unique (image_id, top, left) identity and retains source, transformation, group, bounds, padding, and index fields.

Do not sort arrays, masks, and metadata independently. A reorder is valid only when one shared index is applied to every aligned field.

Deliverables

Implement stacking and alignment checks in src/patches.py and src/report.py. Produce aligned NumPy archives, output/patch_metadata.csv, and output/image_patch_summary.csv with per-image patch counts, valid-pixel counts, and policy identities.

Checks

Check patch and mask shape, dtype, row count, and identity uniqueness. For each image, compare observed patch count with its generated grid. Verify that metadata row i, patch row i, and mask row i share image ID and origin. Check global indexes and per-image indexes are deterministic and complete.

Use empty-patch images, separate grayscale and RGB runs, overlapping patches, and padded edge patches. Deliberately permute one metadata row or remove one mask row and make the verifier report the alignment failure. Confirm source arrays remain unchanged.

Workspace

Keep stacking, shared-index alignment, and summary records here. Coverage, group selection, and batching belong to later milestones.

Hints

HintRow identity is evidence
Two patches can have the same pixel values and still represent different coordinates. Keep the composite identity even when the arrays look equal.
HintOne index, three fields
When selecting or reordering rows, use one shared index for patch data, masks, and metadata.

Review

Pick one aligned row and read its patch, mask, and metadata together. What would a swapped mask row falsely tell a later coverage calculation?

How to check your work

Checks compare shapes, row order, identities, counts, and per-image summaries with the fixtures. Alignment is an invariant, not a visual impression.