geotiff: include GB allocation estimate in max_pixels error message

[brendancol]

Summary

• PixelSafetyLimitError now reports a ~X.XX GB at 4 bytes/pixel estimate next to the pixel count, for both the requested allocation and the safety limit.
• The VRT per-source resample-intermediate error gets the same hint.
• 4 bytes/pixel matches the float32 convention already in MAX_PIXELS_DEFAULT's docstring. The "at 4 bytes/pixel" suffix spells out the assumption.

Closes #2553.

Backend coverage

CPU error-message change only. numpy / cupy / dask+numpy / dask+cupy paths all share the same dimension guard, so no backend-specific handling is needed.

Test plan

• Existing test_security.py assertions on "exceed the safety limit" still pass.
• New test_error_message_includes_gb_estimate covers the layout-path message.
• New test_gb_hint_helper_rounds_to_two_decimals covers the helper directly.
• New test_per_source_cap_error_includes_gb_hint covers the VRT path.
• Full xrspatial/geotiff/tests/ suite passes (5989 passed, 81 skipped, 1 xfailed).

[brendancol]

PR Review: geotiff: include GB allocation estimate in max_pixels error message

Blockers (must fix before merge)

None.

Suggestions (should fix, not blocking)

• xrspatial/geotiff/_layout.py:43. _gb_hint divides by 1024 ** 3 (GiB), but the docstring at line 31 says "~1 billion pixels, which is ~4 GB for float32 single-band", which is decimal GB (/ 10**9). With this PR, the error for MAX_PIXELS_DEFAULT reads "~3.73 GB at 4 bytes/pixel" rather than the "~4 GB" the docstring promises. Two options:

  • Switch the divisor to 1000 ** 3 so the message lines up with the existing "~4 GB" docstring claim, or
  • Update the docstring to "~3.73 GiB" so the unit is unambiguous.

  The decimal switch is the smaller change. It also matches what users see from df, du, S3, and most other tools that report sizes in GB.

Nits (optional improvements)

• xrspatial/geotiff/tests/vrt/test_window.py:454. test_per_source_cap_error_includes_gb_hint accepts the hint from either the dimension guard or the per-source guard, since the dimension guard fires first at these dimensions. That leaves the per-source-specific message without direct coverage. Either tighten the test to force the per-source path (set max_pixels between the output dimensions and the sub-window product), or add a second case so a future regression in the per-source string is caught. Low priority because the existing assertion still proves the hint reaches the error.

What looks good

• _PIXEL_HINT_BYTES = 4 is documented inline, so the assumption is auditable.
• Existing match="exceed the safety limit" assertions are preserved, so no test churn from the message change.
• The inline from ._layout import _gb_hint in _vrt.py matches the existing pattern in that file (lines 1294 and 1371 do the same with _reader).
• test_gb_hint_helper_rounds_to_two_decimals pins the format string directly, so any future change to the hint surface is caught.

Checklist

• Algorithm matches reference/paper. N/A, pure error-message change.
• All implemented backends produce consistent results. Shared dimension guard, no backend split.
• NaN handling is correct. N/A.
• Edge cases are covered by tests. Zero-pixel case covered.
• Dask chunk boundaries handled correctly. N/A.
• No premature materialization or unnecessary copies. Error path only.
• Benchmark exists or is not needed. Not needed.
• README feature matrix updated (if applicable). N/A.
• Docstrings present and accurate. See Suggestion above.

[brendancol]

Follow-up review pass (commit d159684)

Review dispositions

• Suggestion (decimal GB vs GiB): Fixed. _gb_hint now divides by 10**9 so MAX_PIXELS_DEFAULT reports ~4.00 GB at 4 bytes/pixel, matching the docstring.

• Nit (per-source guard coverage): Fixed. test_per_source_cap_error_includes_gb_hint now monkeypatches _check_dimensions to a no-op so the per-source f-string is asserted in isolation.

Additional change from user follow-up

The user asked that the byte estimate use the actual dtype of the data (so f64 reports 8 bytes/pixel, u8 reports 1, etc.) instead of a fixed float32 assumption.

• _gb_hint(pixels, dtype=None) reads dtype.itemsize when supplied; the float32 default is now a fallback for callers that have no dtype resolved yet.
• _check_dimensions(width, height, samples, max_pixels, dtype=None) forwards dtype to _gb_hint.
• Plumbing: _read_strips and _read_tiles in _decode.py already had dtype in scope; both call sites now pass it. read_vrt selects bands before the dimension check and passes selected_bands[0].dtype. The per-source VRT error uses vrt_band.dtype.

Example outputs

• f64, 50000x50000: ~20.00 GB at 8 bytes/pixel vs limit ~8.00 GB at 8 bytes/pixel
• u8, 50000x50000: ~2.50 GB at 1 bytes/pixel vs limit ~1.00 GB at 1 bytes/pixel
• i16, 50000x50000: ~5.00 GB at 2 bytes/pixel vs limit ~2.00 GB at 2 bytes/pixel

Tests

• New test_error_message_uses_passed_dtype_for_gb_hint covers f64 and u8 dtypes through the layout guard.
• test_gb_hint_helper_rounds_to_two_decimals now also exercises f64, u8, and i16 at the helper.
• Full xrspatial/geotiff/tests/ suite: 5990 passed, 81 skipped, 1 xfailed.

[brendancol]

Follow-up: actionable recovery hints (commit 8695083)

Per user follow-up, the PixelSafetyLimitError message now ends with a small "To read this file, try one of:" list rather than just naming max_pixels=. The list adapts to whether dask is installed.

Output shape

TIFF image dimensions (50000 x 50000 x 1 = 2,500,000,000 pixels, ~10.00 GB at 4 bytes/pixel) exceed the safety limit of 1,000,000,000 pixels (~4.00 GB at 4 bytes/pixel).
To read this file, try one of:
  * Pass a larger max_pixels= if the allocation is acceptable.
  * Read a sub-region with window=(r0, c0, r1, c1), e.g. window=(0, 0, 1024, 1024).
  * Read lazily in chunks with chunks=1024 so each decoded buffer stays under max_pixels.

When dask is not importable, the third line switches to:

  * Install dask (`pip install dask` or `conda install -c conda-forge dask`) to read the file lazily via chunks=1024.

Notes

• Detection uses importlib.util.find_spec('dask') so dask is not imported just to format an error.
• _suggest_chunk_side picks the largest square chunk whose pixel count fits under max_pixels for the band count, capped at 1024 to stay near common COG tile sizes (256 / 512 / 1024). For the default 1e9 / 1-band case that resolves to 1024.
• Multi-band reduces the per-side budget (4 bands at 1M pixels -> 500), so the suggestion stays under the cap.
• Pathological max_pixels=0 or samples=0 inputs fall back to safe values rather than dividing by zero.

Tests

• test_error_message_includes_window_suggestion — window= line and concrete example.
• test_error_message_suggests_chunks_when_dask_installed — monkeypatched find_spec to force the dask-present branch.
• test_error_message_recommends_install_when_dask_missing — monkeypatched to force the dask-absent branch.
• test_suggested_chunk_side_scales_with_max_pixels — exercises the chunksize heuristic at the default budget, a tight budget, a multi-band budget, and pathological inputs.
• Full xrspatial/geotiff/tests/ suite: 5994 passed, 81 skipped, 1 xfailed.