Summary
open_geotiff documents overview_level as a supported keyword argument and forwards it to read_geotiff_gpu / read_geotiff_dask / read_to_array. However, the VRT dispatch branch in xrspatial/geotiff/__init__.py:612-616 drops the kwarg:
# VRT files (string paths only -- VRT XML references other files on disk)
if isinstance(source, str) and source.lower().endswith('.vrt'):
return read_vrt(source, dtype=dtype, window=window, band=band,
name=name, chunks=chunks, gpu=gpu,
max_pixels=max_pixels)
read_vrt's own signature (xrspatial/geotiff/__init__.py:3180) does not accept overview_level. A caller passing open_geotiff('mosaic.vrt', overview_level=2) receives full-resolution data with no warning and no error -- the same silent-kwarg-drop class of bug that issue #1561 already fixed for the dask and GPU dispatch branches.
The sibling kwarg on_gpu_failure is rejected up front when gpu=False, so the dispatcher already has the precedent of raising for unsupported combinations. There is no comparable check for overview_level plus a .vrt source.
Proposed fix
Reject overview_level (and on_gpu_failure) at the dispatcher when the source is a VRT, using the same sentinel-based detection pattern on_gpu_failure already uses. Wording should mirror the existing VRT-incompatible error messages so the failure mode is consistent across kwargs.
A future enhancement could thread overview selection through VRT (each source file's overview level), but that is a feature, not an API-consistency fix. The minimum change is to make the silent kwarg drop loud.
Found during the geotiff API consistency sweep (Cat 5, MEDIUM).
Summary
open_geotiffdocumentsoverview_levelas a supported keyword argument and forwards it toread_geotiff_gpu/read_geotiff_dask/read_to_array. However, the VRT dispatch branch inxrspatial/geotiff/__init__.py:612-616drops the kwarg:read_vrt's own signature (xrspatial/geotiff/__init__.py:3180) does not acceptoverview_level. A caller passingopen_geotiff('mosaic.vrt', overview_level=2)receives full-resolution data with no warning and no error -- the same silent-kwarg-drop class of bug that issue #1561 already fixed for the dask and GPU dispatch branches.The sibling kwarg
on_gpu_failureis rejected up front whengpu=False, so the dispatcher already has the precedent of raising for unsupported combinations. There is no comparable check foroverview_levelplus a.vrtsource.Proposed fix
Reject
overview_level(andon_gpu_failure) at the dispatcher when the source is a VRT, using the same sentinel-based detection patternon_gpu_failurealready uses. Wording should mirror the existing VRT-incompatible error messages so the failure mode is consistent across kwargs.A future enhancement could thread overview selection through VRT (each source file's overview level), but that is a feature, not an API-consistency fix. The minimum change is to make the silent kwarg drop loud.
Found during the geotiff API consistency sweep (Cat 5, MEDIUM).