BUG: Raise informative error for 2D spatial coordinates and fix rio.shape (#848)

[VolodymyrLinuxovich]

• Closes reprojecting xarray dataset: TypeError: only length-1 arrays can be converted to Python scalars #848
• Tests added
• Fully documented, including docs/history.rst for all changes and docs/rioxarray.rst for new API. The new exception is picked up by the existing automodule:: rioxarray.exceptions.

Problem

When a DataArray's x/y spatial coordinates are 2D (a curvilinear grid, like the ERA5 data regridded with xESMF in #848), the bounds, resolution and transform code calls float() on coordinate slices and fails with an unhelpful error:

TypeError: only 0-dimensional arrays can be converted to Python scalars

rio.width/rio.height are also wrong in that case, because they used the coordinate's .size, which is the size of the whole 2D array rather than the dimension length.

Change

• _check_dimensions, used by bounds, resolution, transform and reproject, now raises a new CoordinateDimensionError (a RioXarrayError) when the x or y coordinate isn't 1-dimensional. The message explains the requirement and points to reproject(..., src_geoloc_array=...) for curvilinear grids, as suggested in reprojecting xarray dataset: TypeError: only length-1 arrays can be converted to Python scalars #848.
• rio.width/rio.height use self._obj.sizes[dim], so rio.shape is correct with 2D coordinates.

This doesn't add automatic reprojection of curvilinear grids. It replaces a confusing failure with an actionable one and fixes shape.

Before / after

A 5×6 array with 2D x/y coordinates, running rio.shape and then rio.reproject("EPSG:2193"):

master:  shape: (30, 30)
         TypeError: only 0-dimensional arrays can be converted to Python scalars
this PR: shape: (5, 6)
         CoordinateDimensionError: The x coordinate must be 1-dimensional to determine the bounds,
         resolution, or transform; it has 2 dimensions. To reproject data on a curvilinear grid,
         pass the 2D coordinates to 'reproject' using the 'src_geoloc_array' keyword argument.

Tests

• Six new tests: bounds, resolution, transform(recalc=True) and reproject raise CoordinateDimensionError for a DataArray with 2D coordinates; rio.shape is correct; bounds raises for a Dataset too.
• pre-commit (black, isort, flake8, blacken-docs) passes. pylint rioxarray/ rates the changed modules 10.00/10. mypy rioxarray/ reports no new errors: the same 3 pre-existing errors in _spatial_utils.py appear on master.
• Full suite, locally (Python 3.12, pip wheels: rasterio 1.5.1 / GDAL 3.12.4, xarray 2026.7.0, numpy 2.5.3): the six new tests pass and there are no new failures. In the same environment, master has the identical set of 91 failing tests. They come from the wheel's GDAL lacking the netCDF/HDF drivers and from numpy 2.5 behavior, not from this change, and CI's conda environment isn't affected.

[rmz-oz]

fwiw the rio.shape fix also changes what reproject(..., src_geoloc_array=...) returns, which is the route the new error message points to. with a 5x6 array and 2D x/y, master gives rio.shape == (30, 30) and reproject("EPSG:2193", src_geoloc_array=(xx, yy)) comes back 42x23, while rasterio.warp.calculate_default_transform(..., 6, 5, src_geoloc_array=(xx, yy)) gives 8x4. on this branch rioxarray matches rasterio. that's probably also behind the 317 TiB allocation in #848 with a ~2000x2000 grid, so a test for the geoloc path might be worth adding (the new reproject test only checks the error).

[VolodymyrLinuxovich]

Thanks, @rmz-oz. I confirmed the 42×23 vs. 8×4 mismatch on master and added a regression test comparing the result against Rasterio’s calculate_default_transform. This likely explains the 317 TiB allocation in #848.

[snowman2]

@VolodymyrLinuxovich mind rebasing your MR?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.72%. Comparing base (ae6635a) to head (d171c27).
⚠️ Report is 225 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #940      +/-   ##
==========================================
- Coverage   95.90%   95.72%   -0.19%     
==========================================
  Files          12       18       +6     
  Lines        1735     2106     +371     
==========================================
+ Hits         1664     2016     +352     
- Misses         71       90      +19     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[VolodymyrLinuxovich]

@VolodymyrLinuxovich mind rebasing your MR?

Thanks, did it

[snowman2]

Thanks @VolodymyrLinuxovich 👍