feat: Add direct signal-to-noise over-sampling helper

[Jammy2211]

Summary

Add a helper that thresholds an existing signal-to-noise map directly, avoiding accidental division by noise a second time. The cutoff stays fixed even when the map has low S/N. Preserve the input mask and pixel metadata.

Part of #602. The companion PyAutoGalaxy PR corrects the adapt-image documentation; existing workspace thresholding remains compatible.

API Changes

Adds aa.util.over_sample.over_sample_size_via_snr_from, also exposed through al.util.over_sample. The existing adaptive helper keeps its behavior. See full details below.

Test Plan

• Focused over-sampling suite: 23 passed.
• Downstream PyAutoLens export and exact threshold equivalence: passed.
• Full suite: PyAutoArray: 1,922 passed, 0 failed (82 warnings).
• Heart: GREEN, score 100.

Full API Changes (for automation & release notes)

Added

• over_sample_size_via_snr_from(signal_to_noise_map, signal_to_noise_cut=3.0, sub_size_lower=2, sub_size_upper=4) returns an Array2D of integer sub-sizes, using a strict greater-than cutoff without noise division or cutoff lowering.

Migration

• Already-computed S/N maps may use the new helper instead of passing them as data to over_sample_size_via_adapt_from.

Generated by the PyAutoLabs agent workflow.

[Jammy2211]

Companion documentation PR: PyAutoLabs/PyAutoGalaxy#644. Both belong to issue #602.