From b59b40edaef792b955bf0bdf7aa9ad828f9fae87 Mon Sep 17 00:00:00 2001
From: Caroline Malin-Mayor <malinmayorc@janelia.hhmi.org>
Date: Wed, 29 Apr 2026 14:35:19 -0400
Subject: [PATCH 1/2] Update multiscale documentation to describe new level
 selection

---
 docs/guides/rendering.md    |  4 ++++
 docs/howtos/layers/image.md | 24 ++++++++++++++++++++++++
 2 files changed, 28 insertions(+)

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<napari.layers.Layer.
 This means that whenever the canvas' camera is panned or zoomed, napari fetches all the data needed to draw the current field of view.
 While this can work well with local data, it will be slow with remote or other high latency data.
 
+This automatic level selection can be overridden by setting {attr}`locked_data_level<napari.layers.Image.locked_data_level>` 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<napari.layers.Points>` and {class}`Shapes<napari.layers.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

From 763c264e06bee31254f8ff821c2fb471bed57906 Mon Sep 17 00:00:00 2001
From: Caroline Malin-Mayor <cmalinmayor@gmail.com>
Date: Fri, 1 May 2026 15:27:01 -0400
Subject: [PATCH 2/2] Update docs/howtos/layers/image.md

Co-authored-by: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com>
---
 docs/howtos/layers/image.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/howtos/layers/image.md b/docs/howtos/layers/image.md
index 48d35e77e..a086899af 100644
--- a/docs/howtos/layers/image.md
+++ b/docs/howtos/layers/image.md
@@ -214,7 +214,7 @@ multiscale image and the part of the image that needs to be displayed:
 This example had precomputed multiscale images stored in a `zarr` file, which is
 best for performance. If you don't have a precomputed multiscale image but try
 and show an exceptionally large image, napari will try and compute the
-multiscale image for you unless you tell it not to.
+best for performance.
 
 You can use the boolean `multiscale` keyword argument when creating an image
 layer to specify if your data is a multiscale image or not. If you don't provide