to_geotiff writes a PAM .aux.xml sidecar next to the output whenever the DataArray carries attrs['category_names']: a <CategoryNames> list plus a thematic RAT, with RGBA columns when category_colors is present. On the read side, open_geotiff merges category_names/category_colors back into attrs from that sidecar on every local string-path read, on all four paths (eager, dask, GPU, VRT).
None of that is in the docs:
open_geotiff's docstring never mentions the sidecar read, so a user who finds category_names in attrs has no documented explanation for where it came from.to_geotiff's docstring mentions the RAT sidecar only in passing, inside the color_ramp parameter entry. The categorical write is keyed on attrs alone (no kwarg) and drops an extra file next to the output, which matters if you upload or clean up the result by path.docs/source/user_guide/attrs_contract.rst, the page the reference docs point at for which attrs keys the reader sets and what round-trips, has no rows for category_names/category_colors.
The behavior landed in #3483 and is tested, including the dask and GPU write paths (#3519). Only the docs lag.
Found by the documentation sweep. Doc-only fix: docstring additions plus attrs-contract rows, no behavior changes.
Left out on purpose: neither the categorical RAT sidecar nor the color_ramp symbology sidecar has a SUPPORTED_FEATURES key or a release-contract table row. Adding those changes a runtime constant, so it does not belong in a doc-only PR.
to_geotiffwrites a PAM.aux.xmlsidecar next to the output whenever the DataArray carriesattrs['category_names']: a<CategoryNames>list plus a thematic RAT, with RGBA columns whencategory_colorsis present. On the read side,open_geotiffmergescategory_names/category_colorsback into attrs from that sidecar on every local string-path read, on all four paths (eager, dask, GPU, VRT).None of that is in the docs:
open_geotiff's docstring never mentions the sidecar read, so a user who findscategory_namesin attrs has no documented explanation for where it came from.to_geotiff's docstring mentions the RAT sidecar only in passing, inside thecolor_rampparameter entry. The categorical write is keyed on attrs alone (no kwarg) and drops an extra file next to the output, which matters if you upload or clean up the result by path.docs/source/user_guide/attrs_contract.rst, the page the reference docs point at for which attrs keys the reader sets and what round-trips, has no rows forcategory_names/category_colors.The behavior landed in #3483 and is tested, including the dask and GPU write paths (#3519). Only the docs lag.
Found by the documentation sweep. Doc-only fix: docstring additions plus attrs-contract rows, no behavior changes.
Left out on purpose: neither the categorical RAT sidecar nor the
color_rampsymbology sidecar has aSUPPORTED_FEATURESkey or a release-contract table row. Adding those changes a runtime constant, so it does not belong in a doc-only PR.