Skip to content

Expose coregistered reads through the xarray backend engine via a target-grid kwarg #3376

@brendancol

Description

@brendancol

Summary

The xarray backend engine added in #3375 (engine="xrspatial") forwards to the standalone open_geotiff function, so it deliberately does not expose the coregistered-read options (coregister, auto_reproject, resampling). Those live on the .xrs.open_geotiff accessor because they reproject and resample onto a target array's grid, and xr.open_dataset opens a single source from scratch with no target. This issue tracks whether to expose coregistered reads through the engine via a target-grid backend kwarg.

Current behavior

import xarray as xr
xr.open_dataset("scene.tif", engine="xrspatial",
                backend_kwargs={"coregister": True})
# TypeError: open_geotiff() got an unexpected keyword argument 'coregister'

Coregistration today goes through the accessor on an existing array:

target.xrs.open_geotiff("scene.tif", coregister=True, auto_reproject=True)

This is documented in docs/source/reference/geotiff.rst (the backend-engine section notes coregister/auto_reproject are accessor-only).

Proposed behavior

Add a way to pass a target grid through the engine, e.g. a like= (or target=) backend kwarg holding a DataArray/Dataset whose grid the read should be coregistered onto:

xr.open_dataset("scene.tif", engine="xrspatial",
                backend_kwargs={"like": target, "coregister": True,
                                "auto_reproject": True})

The engine would route to the accessor path (_open_geotiff_windowed(target, source, ...)) instead of the standalone function when like= is supplied.

Design questions

  • Kwarg name: like= (matches xr.zeros_like/ones_like intuition) or target=?
  • Should like= be the trigger, or should coregister=True without a like= raise a clear error pointing at it?
  • The engine returns a Dataset; the accessor's coregister path returns a DataArray on the target grid. Variable naming would follow the same default_name/stem rule as the plain engine path.
  • Multi-file: open_mfdataset(..., backend_kwargs={"like": target}) would coregister every source onto the same grid. Worth verifying it composes.
  • GPU/.vrt/allow_rotated combos already raise on the accessor coregister path; the engine wrapper would inherit those rejections for free.

Why

Lets users coregister straight through the standard xarray API without dropping to the accessor, and makes open_mfdataset onto a fixed grid a one-liner. Out of scope for #3375, which only wraps the standalone reader.

Metadata

Metadata

Assignees

No one assigned

    Labels

    geotiffGeoTIFF moduleproposalIdea that needs design discussion

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions