Route sidecar georef tags through the sidecar's bytes (#2315)

[brendancol]

Summary

Closes #2315.

• Add an optional sidecar_origin mapping to extract_geo_info_with_overview_inheritance. When a sidecar IFD declares its own GeoKeyDirectory, ModelPixelScale, ModelTiepoint, or ModelTransformation, the helper parses those tags against the sidecar's bytes and byte order instead of the base file's.
• Wire the mapping through both call sites (_reader.py and _read_geo_info in __init__.py) so the eager and metadata-only paths agree.
• Conservative gate: a sidecar IFD with no georef tags (the GDAL convention) keeps today's behavior and inherits from the base file's level-0 IFD.

Backend coverage

Read-side only. The fix applies to every read backend that shares the metadata parse: numpy eager, dask+numpy via _read_geo_info, and cupy / dask+cupy which call back into the same metadata helper. No GPU or dask-specific code changes.

Test plan

• New regression test test_sidecar_own_geokeys_2315.py covers both branches:
  • Sidecar with its own ModelPixelScale, ModelTiepoint, and GeoKeyDirectory: the sidecar's georef wins.
  • Sidecar with georef tags stripped (GDAL convention): the base file's georef is inherited.
• Both open_geotiff (eager) and _read_geo_info (metadata-only / dask graph builder) exercised.
• Existing test_sidecar_ovr_2112.py suite still passes (28 tests).
• Wider sidecar / overview / geo_info selection (648 tests) passes.

[brendancol]

PR Review: Route sidecar georef tags through the sidecar's bytes (#2315)

Blockers

• None.

Suggestions

• xrspatial/geotiff/_cog_http.py:242 -- the HTTP / fsspec metadata path calls extract_geo_info_with_overview_inheritance(ifd, ifds, header_bytes, header.byte_order, ...) without the new sidecar_origin kwarg. A sidecar IFD over HTTP that declares its own georef payload still parses against the base file's bytes here. A sibling rockout is reportedly handling the HTTP / byte-order side of this finding; if that is the plan, leave a cross-reference comment in the source so future maintainers see the symmetry argument. Otherwise the one-line fix is to thread the sidecar's IFD ids and (sidecar.data, sidecar.header.byte_order) through discover_remote_sidecar's return into a mapping and pass it through.

Nits

• xrspatial/geotiff/_geotags.py extract_geo_info_with_overview_inheritance body -- the inheritance branch (~line 1174) still calls extract_geo_info(base_ifd, data, byte_order, ...). If base_ifd somehow comes from the sidecar (uncommon: the base file would need to have no full-res IFD of its own), the inherited georef parses against the wrong buffer. The new sidecar_origin map is the natural place to fix it -- the same lookup you do for ifd would work for base_ifd. Low priority, but a 3-line guard is cheap.

• xrspatial/geotiff/tests/test_sidecar_own_geokeys_2315.py _mark_first_ifd_as_overview assumes the new NewSubfileType entry (tag 254) sorts before every existing tag in the IFD, so it inserts at position 0. True for to_geotiff output today (smallest tag emitted is 256 / ImageWidth). Brittle if a future writer change adds a tag with id <= 254. Worth an assert that the first existing tag id is > 254, or a bisect-style insert.

What looks good

• The fix is conservatively gated on _ifd_has_georef_payload(ifd). The GDAL-convention case (sidecar with no geokeys) is unchanged.
• Both eager and metadata-only call sites are updated symmetrically.
• The regression test exercises both branches: sidecar wins when it has its own geokeys, base inherits when the sidecar has none.
• Signature change is backward compatible (new kwarg defaults to None).

Checklist

• Algorithm matches reference
• NaN handling: not applicable (metadata path, no array ops)
• Edge cases covered (sidecar with vs without geokeys)
• Dask: the _read_geo_info path used by the dask graph builder is exercised
• No premature materialization (metadata-only changes)
• Benchmark coverage: not applicable
• README feature matrix: not applicable (bug fix, no new function)
• Docstrings present and updated

[brendancol]

Follow-up review

Disposition of the round-1 findings:

• Suggestion (_cog_http.py:242, HTTP sidecar): deferred to the sibling HTTP / dask sidecar-byte-order rockout that already owns this surface. Added a cross-reference comment in the source so the symmetry argument is visible to future maintainers.
• Nit (base_ifd inheritance): fixed in commit 9d8a3e3. The inheritance branch now applies the same sidecar_origin lookup to base_ifd that the main branch applies to ifd.
• Nit (test fixture insert assumption): fixed in commit 9d8a3e3. _mark_first_ifd_as_overview now asserts the first existing IFD tag id is > 254 before inserting NewSubfileType at position 0, so a future writer change that emits a tag <= 254 fails loudly instead of silently producing an out-of-order IFD.

All 34 sidecar-focused tests still pass after the follow-up.