0
# Components
1
2
Napari components are the core functional elements that manage viewer state, coordinate layer interactions, and control the visualization experience. These components handle dimensional navigation, camera positioning, layer management, and the overall viewer model.
3
4
## Capabilities
5
6
### Dimension Management
7
8
Controls dimensional navigation, slicing, and display parameters for multi-dimensional data visualization.
9
10
```python { .api }
11
class Dims:
12
"""
13
Manages dimension indices, display order, and navigation for multi-dimensional data.
14
Controls which dimensions are displayed, sliced, or projected.
15
"""
16
17
@property
18
def ndim(self) -> int:
19
"""Total number of dimensions across all layers."""
20
21
@property
22
def ndisplay(self) -> int:
23
"""Number of displayed dimensions (2 or 3)."""
24
25
@property
26
def current_step(self) -> tuple:
27
"""Current position along each dimension."""
28
29
@property
30
def order(self) -> tuple:
31
"""Order of dimension display."""
32
33
@property
34
def axis_labels(self) -> list:
35
"""Labels for each dimension axis."""
36
37
def set_current_step(self, axis: int, value: int):
38
"""
39
Set the current step along a specific axis.
40
41
Parameters:
42
- axis: Dimension axis index
43
- value: Step value to set
44
"""
45
46
def set_range(self, axis: int, range_: tuple):
47
"""
48
Set the range of values for a dimension.
49
50
Parameters:
51
- axis: Dimension axis index
52
- range_: (min, max) range tuple
53
"""
54
```
55
56
### Camera Control
57
58
Manages the camera/view parameters including position, zoom, rotation, and perspective settings for 2D and 3D visualization.
59
60
```python { .api }
61
class Camera:
62
"""
63
Controls camera position, zoom, rotation, and perspective for viewer display.
64
Handles both 2D and 3D viewing parameters.
65
"""
66
67
@property
68
def center(self) -> tuple:
69
"""Camera center position in data coordinates."""
70
71
@property
72
def zoom(self) -> float:
73
"""Current zoom level."""
74
75
@property
76
def angles(self) -> tuple:
77
"""Camera rotation angles (for 3D viewing)."""
78
79
@property
80
def perspective(self) -> float:
81
"""Perspective projection strength (0=orthographic, >0=perspective)."""
82
83
def set_center(self, center: tuple):
84
"""
85
Set camera center position.
86
87
Parameters:
88
- center: (y, x) or (z, y, x) center coordinates
89
"""
90
91
def set_zoom(self, zoom: float):
92
"""
93
Set camera zoom level.
94
95
Parameters:
96
- zoom: Zoom factor (1.0 = fit to window)
97
"""
98
99
def set_angles(self, angles: tuple):
100
"""
101
Set camera rotation angles for 3D viewing.
102
103
Parameters:
104
- angles: (x_angle, y_angle, z_angle) in degrees
105
"""
106
```
107
108
### Layer Management
109
110
Container and management system for all layers in the viewer, providing list-like interface with layer-specific functionality.
111
112
```python { .api }
113
class LayerList:
114
"""
115
Container for managing layers in the viewer.
116
Provides list-like interface with layer-specific operations.
117
"""
118
119
def __len__(self) -> int:
120
"""Number of layers in the list."""
121
122
def __iter__(self):
123
"""Iterate over layers."""
124
125
def __getitem__(self, key):
126
"""Get layer by index or name."""
127
128
def append(self, layer):
129
"""
130
Add a layer to the end of the list.
131
132
Parameters:
133
- layer: Layer object to add
134
"""
135
136
def insert(self, index: int, layer):
137
"""
138
Insert a layer at a specific position.
139
140
Parameters:
141
- index: Position to insert at
142
- layer: Layer object to insert
143
"""
144
145
def remove(self, layer):
146
"""
147
Remove a layer from the list.
148
149
Parameters:
150
- layer: Layer object to remove
151
"""
152
153
def clear(self):
154
"""Remove all layers from the list."""
155
156
def move(self, src_index: int, dest_index: int):
157
"""
158
Move layer from one position to another.
159
160
Parameters:
161
- src_index: Source position
162
- dest_index: Destination position
163
"""
164
165
@property
166
def selection(self):
167
"""Currently selected layers."""
168
```
169
170
### Viewer Model
171
172
Core data model that coordinates all viewer components and manages the overall state of the napari viewer.
173
174
```python { .api }
175
class ViewerModel:
176
"""
177
Core viewer data model that coordinates layers, dimensions, camera, and other components.
178
Serves as the central state manager for napari viewers.
179
"""
180
181
def __init__(
182
self,
183
*,
184
title: str = 'napari',
185
ndisplay: int = 2,
186
order: tuple = (),
187
axis_labels: tuple = ()
188
):
189
"""
190
Initialize the viewer model.
191
192
Parameters:
193
- title: Viewer window title
194
- ndisplay: Number of displayed dimensions (2 or 3)
195
- order: Dimension display order
196
- axis_labels: Labels for dimension axes
197
"""
198
199
@property
200
def layers(self) -> LayerList:
201
"""LayerList containing all viewer layers."""
202
203
@property
204
def dims(self) -> Dims:
205
"""Dims object managing dimensional navigation."""
206
207
@property
208
def camera(self) -> Camera:
209
"""Camera object controlling view parameters."""
210
211
@property
212
def title(self) -> str:
213
"""Viewer window title."""
214
215
@property
216
def cursor(self) -> dict:
217
"""Current cursor state and information."""
218
219
@property
220
def help(self) -> str:
221
"""Help text for current viewer state."""
222
223
def reset_view(self):
224
"""Reset camera to fit all layer data."""
225
226
def screenshot(self, path: str = None, **kwargs):
227
"""
228
Take a screenshot of the viewer.
229
230
Parameters:
231
- path: File path to save screenshot
232
- kwargs: Additional screenshot parameters
233
234
Returns:
235
Array or path: Screenshot data or saved file path
236
"""
237
```
238
239
## Usage Examples
240
241
### Working with Dimensions
242
243
```python
244
import napari
245
import numpy as np
246
247
# Create 4D data (time, z, y, x)
248
data_4d = np.random.random((10, 20, 100, 100))
249
250
viewer = napari.Viewer()
251
viewer.add_image(data_4d, name='4D Data')
252
253
# Access dimensions component
254
dims = viewer.dims
255
256
# Navigate through time dimension (axis 0)
257
dims.set_current_step(0, 5) # Go to time point 5
258
259
# Set custom axis labels
260
dims.axis_labels = ['time', 'z', 'y', 'x']
261
262
print(f"Current position: {dims.current_step}")
263
print(f"Total dimensions: {dims.ndim}")
264
```
265
266
### Camera Control
267
268
```python
269
import napari
270
import numpy as np
271
272
data = np.random.random((100, 100, 100)) # 3D data
273
274
viewer = napari.Viewer(ndisplay=3) # 3D viewer
275
viewer.add_image(data, name='3D Volume')
276
277
# Access camera
278
camera = viewer.camera
279
280
# Set camera position
281
camera.set_center((50, 50, 50))
282
camera.set_zoom(2.0)
283
284
# For 3D viewing, set rotation angles
285
camera.set_angles((30, 45, 0)) # Rotate for better 3D view
286
287
print(f"Camera center: {camera.center}")
288
print(f"Zoom level: {camera.zoom}")
289
```
290
291
### Layer Management
292
293
```python
294
import napari
295
import numpy as np
296
297
viewer = napari.Viewer()
298
299
# Add multiple layers
300
image1 = np.random.random((100, 100))
301
image2 = np.random.random((100, 100))
302
points_data = np.random.random((50, 2)) * 100
303
304
viewer.add_image(image1, name='Background')
305
viewer.add_image(image2, name='Overlay', opacity=0.5)
306
viewer.add_points(points_data, name='Points')
307
308
# Access layer list
309
layers = viewer.layers
310
311
print(f"Number of layers: {len(layers)}")
312
313
# Access layers by index or name
314
first_layer = layers[0]
315
points_layer = layers['Points']
316
317
# Reorder layers (move points to bottom)
318
layers.move(2, 0) # Move from index 2 to index 0
319
320
# Remove a layer
321
layers.remove(layers['Overlay'])
322
```
323
324
### Viewer Model Integration
325
326
```python
327
import napari
328
import numpy as np
329
330
# Create viewer with custom settings
331
viewer = napari.Viewer(
332
title='My Analysis',
333
ndisplay=2,
334
axis_labels=['Y', 'X']
335
)
336
337
# Add data
338
data = np.random.random((100, 100))
339
viewer.add_image(data, name='Sample Data')
340
341
# Access viewer model properties
342
print(f"Title: {viewer.title}")
343
print(f"Number of layers: {len(viewer.layers)}")
344
print(f"Current dimensions: {viewer.dims.current_step}")
345
346
# Reset view to fit all data
347
viewer.reset_view()
348
349
# Take screenshot
350
screenshot = viewer.screenshot()
351
print(f"Screenshot shape: {screenshot.shape}")
352
```
353
354
### Coordinated Component Usage
355
356
```python
357
import napari
358
import numpy as np
359
360
# Create time-lapse 3D data
361
data_5d = np.random.random((5, 10, 50, 50, 3)) # (t, z, y, x, c)
362
363
viewer = napari.Viewer(
364
title='Time-lapse Analysis',
365
ndisplay=2,
366
axis_labels=['time', 'z', 'y', 'x', 'channel']
367
)
368
369
# Add as RGB image
370
viewer.add_image(data_5d, rgb=True, name='Time-lapse')
371
372
# Coordinate all components
373
# Set time point
374
viewer.dims.set_current_step(0, 2) # Time point 2
375
376
# Set z-slice
377
viewer.dims.set_current_step(1, 5) # Z-slice 5
378
379
# Center camera on region of interest
380
viewer.camera.set_center((25, 25))
381
viewer.camera.set_zoom(2.0)
382
383
# Add annotation layer at current time/z position
384
points = np.array([[20, 20], [30, 30]])
385
viewer.add_points(points, name='Annotations', size=10)
386
387
napari.run()
388
```