Account for harmless pixel shifts in image checks

[Copilot]

Summary

Objectives:

• Ignore semantically identical images with small pixel shifts.
• Preserve failures for material image differences.

Select one: This pull request is...

• a bug fix: increment the patch version
• a small improvement: increment the minor version
• a new feature: increment the minor version
• an incompatible (non-backwards compatible) API change: increment the major version

Small Change

• To merge, I will use "Squash and merge". That is, this change should be a single commit.
• Logic: I have visually inspected the entire pull request myself.
• Pre-commit checks: All the pre-commits checks have passed.

Big Change

• To merge, I will use "Create a merge commit". That is, this change is large enough to require multiple units of work (i.e., it should be multiple commits).

1. Does this do what we want it to do?

Required:

• Product Management: I have confirmed with the stakeholders that the objectives above are correct and complete.
• Testing: I have added or modified at least one "min-case" configuration file to test this change. Every objective above is represented in at least one cfg.
• Testing: I have considered likely and/or severe edge cases and have included them in testing.

If applicable:

• Testing: this pull request introduces an important feature or bug fix that we must test often. I have updated the weekly-test configuration files, not just a "min-case" one.
• Testing: this pull request adds at least one new possible parameter to the cfg. I have tested using this parameter with and without any other parameter that may interact with it.

2. Are the implementation details accurate & efficient?

Required:

• Logic: I have visually inspected the entire pull request myself.
• Logic: I have left GitHub comments highlighting important pieces of code logic. I have had these code blocks reviewed by at least one other team member.

If applicable:

• Dependencies: This pull request introduces a new dependency. I have discussed this requirement with at least one other team member. The dependency is noted in zppy/conda, not just an import statement.

3. Is this well documented?

Required:

• Documentation: by looking at the docs, a new user could easily understand the functionality introduced by this pull request.

4. Is this code clean?

Required:

• Readability: The code is as simple as possible and well-commented, such that a new team member could understand what's happening.
• Pre-commit checks: All the pre-commits checks have passed.

• Fixes [Feature]: Account for pixel shifts in image checker tests #859

[Copilot]

Pull request overview

This PR enhances zppy’s integration image-checking utilities to tolerate small
pixel translations so semantically identical images don’t fail comparisons, while
keeping materially different images flagged. This aligns with zppy’s role as an
HPC workflow orchestrator by reducing noisy failures during automated validation
when underlying plotting dependencies change.

Changes:

• Refactors mismatched-pixel fraction logic into a helper and introduces
  constants for thresholds.
• Adds a shift-tolerant comparison path that attempts small translations before
  declaring an image mismatch.
• Adds a regression test ensuring small pixel shifts are ignored.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
tests/integration/image_checker.py	Adds shift-tolerant image comparison helpers and threshold constants used by integration image checks.
tests/images/test_image_checker.py	Adds a pytest that creates a shifted image pair and verifies it no longer counts as a mismatch.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[forsyth2]

Important testing note: Simply re-running the 8/12 image checker test with this code would overwrite the existing image check failures directories linked there.

[forsyth2]

Asking Claude to evaluate the performance impact of this diff, it gives:

---

Net effect on your 30-60 min run

Since the extra work only triggers for images that were already failing/borderline, the overall test suite time increase depends entirely on how many images currently sit above the 0.0002 mismatch threshold. If that's a handful of images, you'll see a small, likely unnoticeable increase (extra seconds per flagged image). If dozens of images are borderline, you could see a more noticeable bump, since each one now costs up to ~24x its diff-computation time.

If you want to bound this cost, options include: caching/reusing intermediate crops, short-circuiting when image sizes are large (skip shift-matching above some resolution), or reducing MAXIMUM_PIXEL_SHIFT if ±2 is more generous than needed.

[xylar]

These seem to strenuous to be useful. If you take a look at the set of MPAS-Analysis diffs that were just generated, I would want a useful checker to detect those shifts. It should be possible to use a transform like an FFT to find out if the images are shifted by essentially any amount in x and y from each other in a single operation. The test should show a super strong peak a a fixed shift. I would think 0.02% of pixels changed would be overly rigorous but 2 pixels max shift is too few for sure.