rasterize: validate resolution= shape and element type (#2576)

[brendancol]

Summary

• Tighten resolution= validation in rasterize() so the parameter only accepts a scalar number or a length-2 sequence of numbers.
• Anything else (length-0/1/3+ sequences, strings, dicts, bools, non-numeric elements) now raises a clean ValueError naming the offending input.
• Preserves the existing finite/positive checks.

Before this fix, (1, 2, 3) was silently truncated, (1,) crashed with IndexError, 'foo' leaked a raw float() conversion error, and {'x': 1, 'y': 1} raised KeyError: 0.

Backend coverage: pure input validation that runs before any backend dispatch, so it applies uniformly across numpy, cupy, dask+numpy, dask+cupy.

Test plan

• New tests in xrspatial/tests/test_rasterize_resolution_validation_2576.py cover the happy paths (scalar int/float, length-2 tuple/list) and the rejection paths (3-tuple, 1-tuple, empty tuple, string, dict, bool, (1.0, None), (1.0, "bar"), plus an error-message-content check).
• Existing resolution coverage tests in test_rasterize_coverage_2026_05_17.py and test_rasterize_coverage_2026_05_21.py still pass.

Closes #2576

[brendancol]

PR Review: rasterize: validate resolution= shape and element type (#2576)

Blockers (must fix before merge)

None.

Suggestions (should fix, not blocking)

• xrspatial/rasterize.py:3217-3221: the isinstance(resolution, (int, float, tuple, list)) whitelist rejects numpy scalars (np.float32, np.int32, np.int64) and 1-D numpy arrays. Before this PR, resolution=np.array([2.0, 1.0]) and resolution=np.int32(2) worked via duck typing through float(). Numpy-typed scalars from geospatial pipelines are a realistic input. Consider widening the accepted types: add np.number to the scalar check and np.ndarray (with a 1-D / size-2 guard) to the sequence check, or fall back to a numbers.Real-based check.

• xrspatial/tests/test_rasterize_resolution_validation_2576.py:15: import numpy as np is unused. Drop the import. Once the numpy-scalar acceptance above is applied, add tests for resolution=np.array([2.0, 1.0]) and resolution=np.float32(2.0) to pin that behaviour.

Nits (optional improvements)

• xrspatial/rasterize.py:3215: the comment says "leaking IndexError (length-1 sequences)". The IndexError actually comes from resolution[1] on a length-1 input. Minor wording polish -- could read "length-1 sequences would crash at resolution[1]" to be precise.

What looks good

• Validation runs after the explicit-width/height branch, so it does not slow that common path.
• Error messages name the offending input via {resolution!r}, which is what the finding asked for.
• bool is rejected before the int check, so resolution=True does not silently produce a 1x1 raster.
• The finite/positive check is preserved unchanged.
• Tests cover all six rejection cases from the finding plus happy paths and the error-message-content check.
• CHANGELOG entry is clear and references the issue.

Checklist

• Algorithm matches reference/paper (input-validation patch, n/a)
• All implemented backends produce consistent results (validation runs before dispatch)
• NaN handling is correct (preserved unchanged)
• Edge cases are covered by tests
• Dask chunk boundaries handled correctly (n/a)
• No premature materialization or unnecessary copies
• Benchmark exists or is not needed (n/a)
• README feature matrix updated (n/a, no API change)
• Docstrings present and accurate

[brendancol]

Follow-up review pass

All findings from the previous review have been addressed in 0d5e827.

Dispositions

• Suggestion 1 (numpy scalar / ndarray support): Fixed. The scalar check now accepts (int, float, np.number) (excluding bool and np.bool_), and the sequence check accepts (tuple, list, np.ndarray) with a 1-D guard so a 2-D array does not slip past as a length-2 sequence.
• Suggestion 2 (unused numpy import + numpy-scalar tests): Fixed. numpy is now used by the new tests covering np.float32(2.0), np.int32(2), np.array([2.0, 1.0]), and the 2-D rejection path.
• Nit (comment wording): Fixed. The comment now says "length-1 sequences would crash at resolution[1]".

Verification

• 16/16 tests in test_rasterize_resolution_validation_2576.py pass.
• 7/7 existing resolution=-related tests in test_rasterize_coverage_2026_05_17.py and test_rasterize_coverage_2026_05_21.py still pass.

No new findings on this pass.