0
# Core Viewer Management
1
2
The core viewer functionality provides the main interface for creating and controlling napari viewers, managing the visualization window, and coordinating the display of multi-dimensional scientific data.
3
4
## Capabilities
5
6
### Viewer Class
7
8
The main viewer class that serves as the primary interface for napari applications. Manages the display window, layer stack, and user interactions.
9
10
```python { .api }
11
class Viewer:
12
def __init__(
13
self,
14
*,
15
title: str = 'napari',
16
ndisplay: int = 2,
17
order: tuple = (),
18
axis_labels: tuple = (),
19
show: bool = True,
20
**kwargs
21
):
22
"""
23
Create a new napari viewer.
24
25
Parameters:
26
- title: Window title
27
- ndisplay: Number of displayed dimensions (2 or 3)
28
- order: Order of dimension display
29
- axis_labels: Labels for each dimension
30
- show: Whether to show the viewer window immediately
31
"""
32
33
def add_image(self, data, **kwargs):
34
"""
35
Add an image layer to the viewer.
36
37
Parameters:
38
- data: array-like, image data
39
- kwargs: Layer-specific parameters
40
41
Returns:
42
Image layer object
43
"""
44
45
def add_labels(self, data, **kwargs):
46
"""
47
Add a labels layer for segmentation/annotation.
48
49
Parameters:
50
- data: array-like, integer label data
51
- kwargs: Layer-specific parameters
52
53
Returns:
54
Labels layer object
55
"""
56
57
def add_points(self, data, **kwargs):
58
"""
59
Add a points layer for coordinate data.
60
61
Parameters:
62
- data: array-like, point coordinates
63
- kwargs: Layer-specific parameters
64
65
Returns:
66
Points layer object
67
"""
68
69
def add_shapes(self, data, **kwargs):
70
"""
71
Add a shapes layer for geometric annotations.
72
73
Parameters:
74
- data: list of shape data
75
- kwargs: Layer-specific parameters
76
77
Returns:
78
Shapes layer object
79
"""
80
81
def add_surface(self, data, **kwargs):
82
"""
83
Add a surface layer for 3D mesh data.
84
85
Parameters:
86
- data: tuple of (vertices, faces, values)
87
- kwargs: Layer-specific parameters
88
89
Returns:
90
Surface layer object
91
"""
92
93
def add_tracks(self, data, **kwargs):
94
"""
95
Add a tracks layer for time-series point data.
96
97
Parameters:
98
- data: array-like, track data with time information
99
- kwargs: Layer-specific parameters
100
101
Returns:
102
Tracks layer object
103
"""
104
105
def add_vectors(self, data, **kwargs):
106
"""
107
Add a vectors layer for directional data.
108
109
Parameters:
110
- data: array-like, vector data (positions and directions)
111
- kwargs: Layer-specific parameters
112
113
Returns:
114
Vectors layer object
115
"""
116
117
def open(self, path, **kwargs):
118
"""
119
Open file(s) and add as layer(s) using plugin system.
120
121
Parameters:
122
- path: str or list of str, file path(s) to open
123
- kwargs: Additional parameters for layer creation
124
125
Returns:
126
List of created layers
127
"""
128
129
@property
130
def layers(self):
131
"""Access the LayerList containing all viewer layers."""
132
133
@property
134
def dims(self):
135
"""Access the Dims object controlling dimensional navigation."""
136
137
@property
138
def camera(self):
139
"""Access the Camera object controlling view parameters."""
140
141
@property
142
def window(self):
143
"""Access to the main application window."""
144
145
def screenshot(self, path=None, *, size=None, scale=None, canvas_only=True, flash=False):
146
"""
147
Take screenshot of current view.
148
149
Parameters:
150
- path: Optional path to save screenshot
151
- size: Output size tuple (width, height)
152
- scale: Scale factor for high-resolution output
153
- canvas_only: If True, only capture the canvas area
154
- flash: If True, briefly flash the widget
155
156
Returns:
157
numpy.ndarray: Screenshot as RGBA array
158
"""
159
160
def export_figure(self, path=None, *, scale_factor=1, flash=False):
161
"""
162
Export high-resolution figure of the full data extent.
163
164
Parameters:
165
- path: Optional path to save figure
166
- scale_factor: Scale factor for high-resolution output
167
- flash: If True, briefly flash the widget
168
169
Returns:
170
numpy.ndarray: Figure as RGBA array
171
"""
172
173
def reset_view(self, *, margin=0.05, reset_camera_angle=True):
174
"""
175
Reset camera and fit layers to canvas.
176
177
Parameters:
178
- margin: Margin around data as fraction of canvas
179
- reset_camera_angle: Whether to reset 3D camera angles
180
"""
181
182
def update_console(self, variables):
183
"""
184
Update console namespace with variables.
185
186
Parameters:
187
- variables: Dictionary of variables to add to console
188
"""
189
190
def open_sample(self, plugin, sample, reader_plugin=None, **kwargs):
191
"""
192
Open sample data from plugins.
193
194
Parameters:
195
- plugin: Plugin name providing sample data
196
- sample: Sample data identifier
197
- reader_plugin: Optional specific reader plugin
198
- kwargs: Additional parameters for layer creation
199
200
Returns:
201
List of created layers
202
"""
203
204
@classmethod
205
def close_all(cls):
206
"""
207
Close all viewer instances.
208
Useful for cleanup in scripts and testing.
209
210
Returns:
211
int: Number of closed viewers
212
"""
213
```
214
215
### Viewer Management Functions
216
217
Global functions for managing viewer instances and the napari application lifecycle.
218
219
```python { .api }
220
def current_viewer():
221
"""
222
Get the currently active viewer instance.
223
224
Returns:
225
Viewer or None: The active viewer, or None if no viewer exists
226
"""
227
228
def run(
229
*,
230
force: bool = False,
231
gui_exceptions: bool = False,
232
max_loop_level: int = 1,
233
_func_name: str = 'run'
234
):
235
"""
236
Start the Qt event loop for napari GUI applications.
237
238
Parameters:
239
- force: Force running even if event loop exists
240
- gui_exceptions: Show GUI dialog for unhandled exceptions
241
- max_loop_level: Maximum nesting level for event loop
242
"""
243
```
244
245
### View Creation Functions
246
247
Convenience functions that create a viewer and add a specific type of layer in one call.
248
249
```python { .api }
250
def view_image(*args, **kwargs):
251
"""
252
Create a viewer and add an image layer.
253
254
Returns:
255
Viewer: The newly-created viewer with image layer
256
"""
257
258
def view_labels(*args, **kwargs):
259
"""
260
Create a viewer and add a labels layer.
261
262
Returns:
263
Viewer: The newly-created viewer with labels layer
264
"""
265
266
def view_points(*args, **kwargs):
267
"""
268
Create a viewer and add a points layer.
269
270
Returns:
271
Viewer: The newly-created viewer with points layer
272
"""
273
274
def view_shapes(*args, **kwargs):
275
"""
276
Create a viewer and add a shapes layer.
277
278
Returns:
279
Viewer: The newly-created viewer with shapes layer
280
"""
281
282
def view_surface(*args, **kwargs):
283
"""
284
Create a viewer and add a surface layer.
285
286
Returns:
287
Viewer: The newly-created viewer with surface layer
288
"""
289
290
def view_tracks(*args, **kwargs):
291
"""
292
Create a viewer and add a tracks layer.
293
294
Returns:
295
Viewer: The newly-created viewer with tracks layer
296
"""
297
298
def view_vectors(*args, **kwargs):
299
"""
300
Create a viewer and add a vectors layer.
301
302
Returns:
303
Viewer: The newly-created viewer with vectors layer
304
"""
305
306
def view_path(path, **kwargs):
307
"""
308
Create a viewer and open file(s) from path.
309
310
Parameters:
311
- path: str or list of str, file path(s) to open
312
- kwargs: Additional parameters for layer creation
313
314
Returns:
315
Viewer: The newly-created viewer with opened data
316
"""
317
318
def imshow(*args, **kwargs):
319
"""
320
Create a viewer and display an image (matplotlib-style interface).
321
322
Returns:
323
Viewer: The newly-created viewer with image layer
324
"""
325
```
326
327
## Usage Examples
328
329
### Basic Viewer Creation
330
331
```python
332
import napari
333
import numpy as np
334
335
# Create empty viewer
336
viewer = napari.Viewer(title="My Analysis", ndisplay=2)
337
338
# Add data
339
image_data = np.random.random((100, 100))
340
viewer.add_image(image_data, name="Sample Image")
341
342
# Start the GUI
343
napari.run()
344
```
345
346
### Multi-dimensional Data
347
348
```python
349
import napari
350
import numpy as np
351
352
# Create 4D time-lapse data (time, z, y, x)
353
data_4d = np.random.random((10, 20, 100, 100))
354
355
# Create viewer with appropriate axis labels
356
viewer = napari.Viewer(
357
title="Time-lapse Z-stack",
358
axis_labels=['time', 'z', 'y', 'x']
359
)
360
361
viewer.add_image(data_4d, name="Time-lapse")
362
napari.run()
363
```
364
365
### Using View Functions
366
367
```python
368
import napari
369
import numpy as np
370
371
# Quick image viewing
372
image = np.random.random((100, 100))
373
viewer = napari.view_image(image, title="Quick View")
374
375
# Equivalent to matplotlib's imshow
376
viewer = napari.imshow(image, title="Matplotlib Style")
377
378
napari.run()
379
```