convolution: validate kernel and agg inputs (#3623)

[brendancol]

What

Validate inputs to the two public convolution entry points.

• convolve_2d: new _validate_kernel rejects a non-array, non-2D, or even-sided kernel with a ValueError that names kernel. These previously reached the numba kernel and raised a TypingError, or (even side lengths) returned a silently off-center result. The check is duck-typed on ndim/shape, so numpy and cupy kernels both pass.
• convolution_2d: validate that agg is a 2D DataArray with _validate_raster. A numpy input previously failed with "'memoryview' object has no attribute 'astype'".

Tests

xrspatial/tests/test_convolution.py gains cases for None/1D/3D/list kernels, even-sided kernels, and a non-DataArray agg, plus positive paths for both functions. test_focal.py and test_edge_detection.py pass unchanged; the cupy backend was spot-checked (valid path works, bad kernels rejected identically, cupy kernels still accepted).

Compatibility

No exception type changes on existing valid usage. Even-sided kernels used to "work" (silently wrong); they now raise, matching custom_kernel's long-standing odd-shape contract. Internal callers (focal, edge_detection, emerging_hotspots) all pass odd 2D arrays.

Closes #3623

[brendancol]

PR Review: convolution: validate kernel and agg inputs (#3623)

Reviewed the full convolution.py and test_convolution.py on the PR branch, plus _validate_raster/_validate_boundary in utils.py. Ran the test file against the branch: 15 passed. The change does what it says, and the tests cover the cases that mattered.

Blockers (must fix before merge)

None.

Suggestions (should fix, not blocking)

• _validate_kernel (xrspatial/convolution.py:356) checks shape and dimensionality but not dtype. A 2D object-dtype or string kernel with odd sides passes the guard and still reaches numba, producing the cryptic TypingError this PR is meant to prevent. custom_kernel has the same gap, so this is not a regression, and dtype validation may be out of scope. Worth a one-line note in the PR if you are leaving it deliberately.

Nits (optional improvements)

• The duck-typed not hasattr(kernel, 'ndim') branch (convolution.py:356) reports only the type name, while the other two branches report the shape. That is the right call when there is no shape to report; just flagging that the three messages read a bit differently by design.

What looks good

• Keeping _validate_kernel separate from custom_kernel rather than reusing it is the right call: custom_kernel hard-requires np.ndarray, which would reject valid cupy kernels. Duck-typing on ndim/shape keeps all four backends working, and the odd-side-length contract matches custom_kernel.
• Kernel validation runs before the ArrayTypeFunctionMapping dispatch (convolution.py:514), so every backend gets the same up-front check through one code path.
• The _validate_raster guard added to convolution_2d (convolution.py:647) is load-bearing, not redundant with the re-validation inside convolve_2d. A numpy array has a .data attribute (a memoryview), so agg.data would otherwise succeed and fail later with 'memoryview' object has no attribute 'astype'. The guard turns that into a clear TypeError naming the parameter, and the test pins the old failure mode.
• Tests cover the paths that regressed: bad kernel types (None, 1D, 3D, list), even side lengths, non-DataArray input to convolution_2d, and the positive path.

Checklist

• Algorithm matches reference/paper (validation-only change, no algorithm touched)
• All implemented backends produce consistent results (validation is pre-dispatch, backend-agnostic)
• NaN handling is correct (unchanged)
• Edge cases are covered by tests
• Dask chunk boundaries handled correctly (unchanged)
• No premature materialization or unnecessary copies
• Benchmark exists or is not needed (validation cost is negligible)
• README feature matrix updated (not applicable; no new public function)
• Docstrings present and accurate