From b792f4aeb024eaa57c1ea167c6692e62b79cd7f3 Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Tue, 18 Aug 2026 17:25:14 -0500 Subject: [PATCH 1/4] demystify Xarray in Image guide --- docs/howtos/layers/image.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/howtos/layers/image.md b/docs/howtos/layers/image.md index c17f92e20..e6b020f81 100644 --- a/docs/howtos/layers/image.md +++ b/docs/howtos/layers/image.md @@ -176,6 +176,17 @@ The great thing about napari support of array-like objects is that you get to keep on using your favorite array libraries without worrying about any conversions. napari handles all of that for you. +```{note} +If you pass an [Xarray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) +`DataArray` to napari, it automatically inherits metadata from it: dimension +names become the layer's axis labels, coordinate values are used for `scale` +and `translate`, and CF-convention `units` attributes on coordinates (validated +with [pint](https://pint.readthedocs.io/)) become the layer units. Even +`datetime64` coordinates are converted to a sensible time unit. See the +[xarray example]({ref}`sphx_glr_gallery_xarray-latlon-timeseries.py`) for a +full demonstration. +``` + napari will also wait until just before it displays data onto the screen to actually generate a NumPy array from your data, and so if you're using a library like `dask` or `zarr` that supports lazy loading and lazy evaluation, we won't From 0f1bc1adfc3fbb935b3cf9004aa5a763362c342c Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Wed, 19 Aug 2026 16:17:48 -0500 Subject: [PATCH 2/4] move bulk to units guide, keep mention in image --- docs/guides/units.md | 11 +++++++++++ docs/howtos/layers/image.md | 10 +++------- 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/guides/units.md b/docs/guides/units.md index 735236769..6b179edbf 100644 --- a/docs/guides/units.md +++ b/docs/guides/units.md @@ -46,6 +46,17 @@ Pint also has logic to disambiguate unit names, for example, If you do not set units, napari assumes pixels. To set *no* units, use `layer.units = ('dimensionless',...)`. +## Inheriting scale and units from xarray + +If you pass an [Xarray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) +`DataArray` to napari, it automatically inherits metadata from it: dimension +names become the layer's axis labels, coordinate values are used for `scale` +and `translate`, and CF-convention `units` attributes on coordinates (validated +with [pint](https://pint.readthedocs.io/)) become the layer units. Even +`datetime64` coordinates are converted to a sensible time unit. See the +[xarray example]({ref}`sphx_glr_gallery_xarray-latlon-timeseries.py`) for a +full demonstration. + ## When units are consistent across layers napari can use units to render layers in the same physical space even when the diff --git a/docs/howtos/layers/image.md b/docs/howtos/layers/image.md index e6b020f81..03450a53f 100644 --- a/docs/howtos/layers/image.md +++ b/docs/howtos/layers/image.md @@ -178,13 +178,9 @@ conversions. napari handles all of that for you. ```{note} If you pass an [Xarray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) -`DataArray` to napari, it automatically inherits metadata from it: dimension -names become the layer's axis labels, coordinate values are used for `scale` -and `translate`, and CF-convention `units` attributes on coordinates (validated -with [pint](https://pint.readthedocs.io/)) become the layer units. Even -`datetime64` coordinates are converted to a sensible time unit. See the -[xarray example]({ref}`sphx_glr_gallery_xarray-latlon-timeseries.py`) for a -full demonstration. +`DataArray` to napari, it automatically inherits metadata from it, such as axis +labels, `scale`, `translate`, and units. For details on how this metadata is +used for rendering, see the [units guide]({ref}`units-guide`). ``` napari will also wait until just before it displays data onto the screen to From e1a16fc37be2fb1f94b4303ec4a054e6f135d074 Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Wed, 19 Aug 2026 16:21:42 -0500 Subject: [PATCH 3/4] fix rst ref --- docs/guides/units.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/units.md b/docs/guides/units.md index 6b179edbf..2809dcc1c 100644 --- a/docs/guides/units.md +++ b/docs/guides/units.md @@ -54,7 +54,7 @@ names become the layer's axis labels, coordinate values are used for `scale` and `translate`, and CF-convention `units` attributes on coordinates (validated with [pint](https://pint.readthedocs.io/)) become the layer units. Even `datetime64` coordinates are converted to a sensible time unit. See the -[xarray example]({ref}`sphx_glr_gallery_xarray-latlon-timeseries.py`) for a +[xarray example](:ref:`sphx_glr_gallery_xarray-latlon-timeseries.py`) for a full demonstration. ## When units are consistent across layers From 29ad54cf5db9b716251c89fd4ac5a50eb4d77b57 Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Wed, 19 Aug 2026 17:45:05 -0500 Subject: [PATCH 4/4] fix xrefs --- docs/guides/units.md | 2 +- docs/howtos/layers/image.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/units.md b/docs/guides/units.md index 2809dcc1c..4614dfb6d 100644 --- a/docs/guides/units.md +++ b/docs/guides/units.md @@ -54,7 +54,7 @@ names become the layer's axis labels, coordinate values are used for `scale` and `translate`, and CF-convention `units` attributes on coordinates (validated with [pint](https://pint.readthedocs.io/)) become the layer units. Even `datetime64` coordinates are converted to a sensible time unit. See the -[xarray example](:ref:`sphx_glr_gallery_xarray-latlon-timeseries.py`) for a +[xarray example](sphx_glr_gallery_xarray-latlon-timeseries.py) for a full demonstration. ## When units are consistent across layers diff --git a/docs/howtos/layers/image.md b/docs/howtos/layers/image.md index 03450a53f..5c98dd14a 100644 --- a/docs/howtos/layers/image.md +++ b/docs/howtos/layers/image.md @@ -180,7 +180,7 @@ conversions. napari handles all of that for you. If you pass an [Xarray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) `DataArray` to napari, it automatically inherits metadata from it, such as axis labels, `scale`, `translate`, and units. For details on how this metadata is -used for rendering, see the [units guide]({ref}`units-guide`). +used for rendering, see the [units guide](units-guide). ``` napari will also wait until just before it displays data onto the screen to