Today I focused on stabilizing and tightening the border rendering pipeline in the Files System, especially around correctness, determinism, and testability.
What I did
- Designed a new border-render command as a controlled, step-by-step entry point instead of jumping straight into jobs.
- Clarified and locked down the print-size mental model:
- Treated 6×4 inches as an absolute print size, not orientation-bound.
- Implemented auto-orientation logic so 6×4 and 4×6 behave identically, based on the input image’s aspect ratio.
- Formalized the two-stage pipeline:
- Step 1: centered crop to (target_mm – 6mm)
- Step 2: add 3mm white border per side to reach the final print size.
- Added a self-test mechanism directly into the command:
- Generated outputs are automatically compared against known-good reference images.
- Introduced dimension checks before pixel diffing to fail fast on structural mismatches.
- Improved the self-test to be practical and reliable:
- Normalized images in-memory before comparison to avoid JPEG false negatives.
- Used tolerant comparison metrics instead of naive pixel equality.
- Generated diff and composite images only when a failure occurs.
- Enforced a clean test workspace contract:
- Only original.jpg, step_1.jpg, and step_2_final.jpg are treated as canonical.
- All generated artifacts are deleted at the start of every run to guarantee determinism.
- Standardized execution details (RunCloud PHP binary) so command runs match production reality.
What I learned
- Image pipelines fail silently when orientation assumptions leak into size semantics — treating print sizes as absolute is critical.
- A self-test that “sometimes works” is worse than no test; dimension gates + normalization dramatically improve signal.
- Cleaning generated artifacts upfront is not cosmetic — it’s essential for trusting visual comparisons.
- Debug images (diff + composite) are far more valuable than logs when working with image correctness.
- Building this as a command first (instead of a job) makes iteration, validation, and reasoning much clearer.
Overall, today was about turning a fuzzy, visual problem into a deterministic, testable system. The pipeline is now strict enough to expose what’s wrong, instead of hiding it.