diff --git a/docs/guides/rendering.md b/docs/guides/rendering.md index afedac5c0..fe5a025f5 100644 --- a/docs/guides/rendering.md +++ b/docs/guides/rendering.md @@ -273,6 +273,10 @@ As a part of these calculations, {attr}`Layer.corner_pixels` on the layer. +When set, the layer always renders at that specific level and `corner_pixels` spans the full extent of that level, bypassing the automatic computation described above. +Setting it back to `None` restores automatic behavior. + ### Loading non-image data Other layer types, like {class}`Points` and {class}`Shapes`, have layer specific data structures. diff --git a/docs/howtos/layers/image.md b/docs/howtos/layers/image.md index 4b9bb6967..48d35e77e 100644 --- a/docs/howtos/layers/image.md +++ b/docs/howtos/layers/image.md @@ -221,6 +221,30 @@ layer to specify if your data is a multiscale image or not. If you don't provide this value, then napari will try and guess whether your data is or needs to be a multiscale image. +### Locking the multiscale level + +By default, napari automatically selects which resolution level to display based +on the current zoom and viewport. In 2D this means zooming in loads +higher-resolution data, while in 3D the coarsest level is used for performance. + +If you want to force a specific resolution level — for example, to keep a +consistent view while panning or to inspect a particular level — you can set +the `locked_data_level` property, or using the resolution dropdown in the layer controls: + +```python +# Lock rendering to level 0 (highest resolution) +layer.locked_data_level = 0 + +# Restore automatic level selection +layer.locked_data_level = None +``` + +When a level is locked, napari loads the full extent of that level on the currently +displayed dimensions regardless of zoom or display mode. The lock is automatically +reset to `None` when the layer's data is replaced. + +This property is available on both `Image` and `Labels` layers. + ## Loading multichannel images Each channel in a multichannel image can be displayed as an individual layer by