Task: add documentation for pixel grids

[Kirill888]

Problem Description

odc.stac.load output pixel grid can be confusing to users. Unexpected result often look like an error in implementation: an extra pixel column/row, but in fact it is an expected feature of the loading process and has to do with "pixel grid snapping". There is a common expectation that output will start exactly at min(x) of the input data. This is not always the case. Most commonly this manifests when loading data at reduced resolution, example #94.

Another source of confusion is to do with coordinates of the returned xarray. Coordinates are for pixel centers, not for the edge. Common mistake is to assume that image spans [img.x[0], img.x[-1]]. It does not.

• ❌ [img.x[0], img.x[-1]], pixel centers are not pixel edges
• ✅ [img.x[0]-res/2, img.x[-1]+res/2], better but need to know pixel size
• ✅✅ img.odc.geobox.boundingbox.range_x, best

Worth noting that users of stackstac experience similar confusion, and there is a pinned issue gjoseph92/stackstac#152 helping users.

Pixel Grid Snapping

Just because two images have the same resolution, the same projection and overlap, does not mean that individual pixels overlap exactly with each other:

When requested to load two images above how the output pixel grid should look like? Should we pick pixel grid that aligns with orange or with blue image, or something else? We choose something else.

Say images above have pixel size of 100 units, orange one starts at X=130 and blue one at X=690. Image that will be produced in this case will default to starting at X=100 and so both images will be resampled into that common grid. We pick X=100 because this aligns pixel edges to integer multiples of pixel size.

A common assumption users have, is that instead, output image should start at X=130 as this is the left edge of available input data. It's a sensible assumption. Image like that can be produced by odc.stac, but requires specifying anchor= parameter, value of odc.geo.geobox.AnchorEnum.FLOATING, this turns off pixel snapping. This is not well reflected in the docs. Maybe worth adding snap=False or tight=True argument as a more obvious alias for that behaviour.

The advantage of snapping becomes apparent when combining data from different sources: just use the same resolution to load data from different sources and resulting images are guaranteed to have exactly overlapping pixels, so you can combine those arrays without needing further resampling.

References

• Add a snap_to method to GeoBoxes to enable coercing GeoBoxes to the same pixel alignment odc-geo#59
• https://odc-stac.readthedocs.io/en/latest/_api/odc.stac.load.html?highlight=anchor
• https://odc-geo.readthedocs.io/en/latest/intro-geobox.html
• https://odc-geo.readthedocs.io/en/latest/_api/odc.geo.geobox.GeoBox.from_bbox.html
• incorrect xarray size when downsampling? #94
• Unexpected results? Strange array shapes? Missing data? Read here first. gjoseph92/stackstac#152