0
# Napari
1

2
Napari is a fast, interactive, multi-dimensional image viewer for Python designed for browsing, annotating, and analyzing large multi-dimensional scientific images. Built on Qt for the GUI, vispy for performant GPU-based rendering, and the scientific Python stack, it provides a comprehensive platform for scientific image visualization and analysis with support for n-dimensional arrays, plugin architecture for extensibility, and integration with the broader scientific Python ecosystem.
3

4
## Package Information
5

6
- **Package Name**: napari
7
- **Language**: Python
8
- **Installation**: `pip install napari`
9
- **Requirements**: Python ≥3.10
10

11
## Core Imports
12

13
```python
14
import napari
15
```
16

17
Common patterns for direct access to specific functionality:
18

19
```python
20
from napari import Viewer, view_image, view_labels
21
from napari.layers import Image, Labels, Points, Shapes
22
from napari.components import Dims, LayerList
23
```
24

25
## Basic Usage
26

27
### Creating and Using a Viewer
28

29
```python
30
import napari
31
import numpy as np
32

33
# Create sample image data
34
image_data = np.random.random((100, 100))
35

36
# Method 1: Create viewer then add layers
37
viewer = napari.Viewer()
38
viewer.add_image(image_data, name='Random Image')
39

40
# Method 2: Create viewer with image directly  
41
viewer = napari.view_image(image_data, title='My Image Viewer')
42

43
# Show the viewer (starts Qt event loop)
44
napari.run()
45
```
46

47
### Working with Multiple Layers
48

49
```python
50
import napari
51
import numpy as np
52

53
# Create different types of data
54
image = np.random.random((100, 100))
55
labels = np.zeros((100, 100), dtype=int)
56
labels[25:75, 25:75] = 1
57
points = np.array([[50, 50], [25, 75]])
58

59
# Create viewer and add multiple layers
60
viewer = napari.Viewer()
61
viewer.add_image(image, name='Image')
62
viewer.add_labels(labels, name='Segmentation')
63
viewer.add_points(points, name='Points', size=10)
64

65
napari.run()
66
```
67

68
## Architecture
69

70
Napari's architecture centers around a layered approach to multi-dimensional visualization:
71

72
- **Viewer**: The main application window and controller managing the visual display and user interactions
73
- **Layers**: Data visualization objects representing different types of scientific data (images, annotations, measurements)
74
- **Components**: Core functional components managing viewer state (dimensions, camera, layer list)
75
- **Qt Interface**: GUI widgets, event handling, and visual controls built on the Qt framework
76
- **Plugin System**: Extensible architecture supporting reader/writer plugins and custom widgets via npe2
77

78
This design enables napari to serve as both a standalone scientific image viewer and a platform for building domain-specific visualization applications in fields like microscopy, medical imaging, and scientific data analysis.
79

80
## Capabilities
81

82
### Core Viewer Management
83

84
Main viewer class and viewer management functionality for creating and controlling napari viewers, including window management and viewer lifecycle.
85

86
```python { .api }
87
class Viewer:
88
    def __init__(self, *, title='napari', ndisplay=2, order=(), axis_labels=(), show=True, **kwargs): ...
89
    def add_image(self, data, **kwargs): ...
90
    def add_labels(self, data, **kwargs): ...
91
    def add_points(self, data, **kwargs): ...
92
    def add_shapes(self, data, **kwargs): ...
93
    def add_surface(self, data, **kwargs): ...
94
    def add_tracks(self, data, **kwargs): ...
95
    def add_vectors(self, data, **kwargs): ...
96
    def open(self, path, **kwargs): ...
97

98
def current_viewer(): ...
99
def run(*, force=False, gui_exceptions=False, max_loop_level=1): ...
100
```
101

102
[Core Viewer](./core-viewer.md)
103

104
### Layer Types and Data Visualization
105

106
Complete set of layer types for visualizing different kinds of scientific data, from n-dimensional images to geometric annotations and measurements.
107

108
```python { .api }
109
class Layer: ...
110
class Image(Layer): ...
111
class Labels(Layer): ...
112
class Points(Layer): ...
113
class Shapes(Layer): ...
114
class Surface(Layer): ...
115
class Tracks(Layer): ...
116
class Vectors(Layer): ...
117
```
118

119
[Layers](./layers.md)
120

121
### Viewer Components
122

123
Core components that manage viewer state including dimensional navigation, camera controls, and layer management.
124

125
```python { .api }
126
class Dims: ...
127
class Camera: ...
128
class LayerList: ...
129
class ViewerModel: ...
130
```
131

132
[Components](./components.md)
133

134
### Qt Interface and GUI
135

136
Qt-based graphical user interface components, widgets, threading utilities, and event loop management for desktop applications.
137

138
```python { .api }
139
class QtViewer: ...
140
class Window: ...
141
def get_qapp(): ...
142
def create_worker(func): ...
143
def thread_worker(func): ...
144
```
145

146
[Qt Interface](./qt-interface.md)
147

148
### Utilities and Helpers
149

150
Utility functions for colormaps, progress indicators, system information, notifications, and other helper functionality.
151

152
```python { .api }
153
class Colormap: ...
154
def sys_info(): ...
155
def progress(iterable): ...
156
def progrange(n): ...
157
```
158

159
[Utilities](./utilities.md)
160

161
### Data Types and Type Definitions
162

163
Comprehensive type definitions for arrays, layer data, plugin interfaces, and configuration objects used throughout the napari ecosystem.
164

165
```python { .api }
166
ArrayLike = Union[np.ndarray, 'dask.array.Array', 'zarr.Array']
167
LayerData = Union[tuple[Any], tuple[Any, Mapping], FullLayerData]
168
PathLike = Union[str, Path]
169
ReaderFunction = Callable[[PathOrPaths], list[LayerData]]
170
```
171

172
[Types](./types.md)
173

174
## View Functions
175

176
Convenience functions for creating viewers with specific layer types:
177

178
```python { .api }
179
# Create viewers with specific layer types
180
# NOTE: These view_* functions are deprecated as of napari 0.7.0
181
# Use Viewer().add_* methods instead
182
napari.view_image(data, **kwargs) -> napari.Viewer  # Deprecated
183
napari.view_labels(data, **kwargs) -> napari.Viewer  # Deprecated
184
napari.view_points(data, **kwargs) -> napari.Viewer  # Deprecated
185
napari.view_shapes(data, **kwargs) -> napari.Viewer  # Deprecated
186
napari.view_surface(data, **kwargs) -> napari.Viewer  # Deprecated
187
napari.view_tracks(data, **kwargs) -> napari.Viewer  # Deprecated
188
napari.view_vectors(data, **kwargs) -> napari.Viewer  # Deprecated
189
napari.imshow(data, **kwargs) -> tuple[napari.Viewer, list[napari.layers.Image]]  # matplotlib-style
190
```
191

192
## Plugin Integration
193

194
```python { .api }
195
# Save layers using plugin system
196
napari.save_layers(path, layers, plugin=None)
197

198
# Access experimental features  
199
from napari.experimental import link_layers, unlink_layers, layers_linked
200

201
def link_layers(layers, attributes=()) -> list:
202
    """Link attributes between all layers in layers."""
203
    
204
def unlink_layers(layers, attributes=()) -> None:
205
    """Unlink previously linked attributes between layers."""
206
    
207
def layers_linked(layers, attributes=()):
208
    """Context manager that temporarily links attributes on layers."""
209

210
# Access notification system
211
napari.notification_manager
212
```