0
# Layers
1

2
Napari layers are the fundamental data visualization objects that represent different types of scientific data. Each layer type is optimized for specific data structures and visualization needs, from n-dimensional images to geometric annotations and measurements.
3

4
## Layer Base Class
5

6
```python { .api }
7
class Layer:
8
    """Base class for all napari layers."""
9
    
10
    @property
11
    def name(self) -> str:
12
        """Layer name displayed in the layer list."""
13
    
14
    @property
15
    def visible(self) -> bool:
16
        """Whether the layer is currently visible."""
17
    
18
    @property
19
    def opacity(self) -> float:
20
        """Layer opacity (0-1)."""
21
    
22
    @property
23
    def blending(self) -> str:
24
        """Blending mode for layer compositing."""
25
    
26
    @property
27
    def data(self):
28
        """The layer's data array or structure."""
29
```
30

31
## Capabilities
32

33
### Image Layer
34

35
Displays n-dimensional image data with support for multi-channel, time-series, and volumetric datasets. Optimized for scientific imaging with customizable colormaps and contrast settings.
36

37
```python { .api }
38
class Image(Layer):
39
    """Layer for displaying n-dimensional image data."""
40
    
41
    def __init__(
42
        self,
43
        data,
44
        *,
45
        rgb: bool = None,
46
        colormap: str = 'gray',
47
        contrast_limits: tuple = None,
48
        gamma: float = 1.0,
49
        name: str = None,
50
        **kwargs
51
    ):
52
        """
53
        Create an image layer.
54
        
55
        Parameters:
56
        - data: array-like, image data (2D, 3D, 4D, etc.)
57
        - rgb: Whether to interpret last dimension as RGB channels
58
        - colormap: Colormap name or Colormap object
59
        - contrast_limits: (min, max) contrast limits
60
        - gamma: Gamma correction factor
61
        - name: Layer name
62
        """
63
    
64
    @property
65
    def colormap(self):
66
        """Current colormap for the image."""
67
    
68
    @property
69
    def contrast_limits(self) -> tuple:
70
        """Current contrast limits (min, max)."""
71
    
72
    @property
73
    def gamma(self) -> float:
74
        """Current gamma correction value."""
75
```
76

77
### Labels Layer
78

79
Displays integer-valued label data for segmentation, annotation, and region identification. Supports editing, painting, and region-based analysis.
80

81
```python { .api }
82
class Labels(Layer):
83
    """Layer for displaying integer label data."""
84
    
85
    def __init__(
86
        self,
87
        data,
88
        *,
89
        num_colors: int = 50,
90
        seed: float = 0.5,
91
        name: str = None,
92
        **kwargs
93
    ):
94
        """
95
        Create a labels layer.
96
        
97
        Parameters:
98
        - data: array-like, integer label data
99
        - num_colors: Number of colors in the colormap
100
        - seed: Random seed for color generation
101
        - name: Layer name
102
        """
103
    
104
    @property
105
    def selected_label(self) -> int:
106
        """Currently selected label value for painting."""
107
    
108
    def paint(self, coord, new_label):
109
        """Paint a region with a new label value."""
110
    
111
    def fill(self, coord, new_label):
112
        """Fill connected region with new label value."""
113
```
114

115
### Points Layer
116

117
Displays and manages collections of points in n-dimensional space. Supports interactive editing, sizing, coloring, and symbol customization.
118

119
```python { .api }
120
class Points(Layer):
121
    """Layer for displaying point data."""
122
    
123
    def __init__(
124
        self,
125
        data,
126
        *,
127
        properties: dict = None,
128
        size: float = 10,
129
        edge_width: float = 1,
130
        face_color: str = 'white',
131
        edge_color: str = 'black',
132
        symbol: str = 'o',
133
        name: str = None,
134
        **kwargs
135
    ):
136
        """
137
        Create a points layer.
138
        
139
        Parameters:
140
        - data: array-like, point coordinates (N x D)
141
        - properties: Dictionary of point properties
142
        - size: Point size(s)
143
        - edge_width: Point border width
144
        - face_color: Point fill color(s)
145
        - edge_color: Point border color(s)
146
        - symbol: Point symbol ('o', 's', 't', etc.)
147
        - name: Layer name
148
        """
149
    
150
    def add(self, coord):
151
        """Add a new point at the given coordinate."""
152
    
153
    def remove_selected(self):
154
        """Remove currently selected points."""
155
    
156
    @property
157
    def selected_data(self) -> set:
158
        """Indices of currently selected points."""
159
```
160

161
### Shapes Layer
162

163
Displays and manages geometric shapes including rectangles, ellipses, polygons, lines, and paths. Supports interactive creation, editing, and styling.
164

165
```python { .api }
166
class Shapes(Layer):
167
    """Layer for displaying geometric shapes."""
168
    
169
    def __init__(
170
        self,
171
        data=None,
172
        *,
173
        shape_type: str = 'rectangle',
174
        edge_width: float = 1,
175
        edge_color: str = 'black',
176
        face_color: str = 'white',
177
        opacity: float = 0.7,
178
        name: str = None,
179
        **kwargs
180
    ):
181
        """
182
        Create a shapes layer.
183
        
184
        Parameters:
185
        - data: List of shape data arrays
186
        - shape_type: Default shape type for new shapes
187
        - edge_width: Shape border width
188
        - edge_color: Shape border color(s)
189
        - face_color: Shape fill color(s)
190
        - opacity: Shape opacity
191
        - name: Layer name
192
        """
193
    
194
    def add_rectangles(self, data):
195
        """Add rectangle shapes from coordinate data."""
196
    
197
    def add_ellipses(self, data):
198
        """Add ellipse shapes from coordinate data."""
199
    
200
    def add_polygons(self, data):
201
        """Add polygon shapes from coordinate data."""
202
    
203
    def add_lines(self, data):
204
        """Add line shapes from coordinate data."""
205
    
206
    def remove_selected(self):
207
        """Remove currently selected shapes."""
208
```
209

210
### Surface Layer
211

212
Displays 3D mesh surfaces defined by vertices and faces. Supports texture mapping, lighting, and scientific visualization of 3D structures.
213

214
```python { .api }
215
class Surface(Layer):
216
    """Layer for displaying 3D surface meshes."""
217
    
218
    def __init__(
219
        self,
220
        data,
221
        *,
222
        colormap: str = 'gray',
223
        contrast_limits: tuple = None,
224
        gamma: float = 1.0,
225
        name: str = None,
226
        **kwargs
227
    ):
228
        """
229
        Create a surface layer.
230
        
231
        Parameters:
232
        - data: Tuple of (vertices, faces, values) or (vertices, faces)
233
        - colormap: Colormap for surface values
234
        - contrast_limits: (min, max) contrast limits for values
235
        - gamma: Gamma correction factor
236
        - name: Layer name
237
        """
238
    
239
    @property
240
    def vertices(self):
241
        """Surface vertex coordinates."""
242
    
243
    @property
244
    def faces(self):
245
        """Surface face connectivity."""
246
    
247
    @property
248
    def values(self):
249
        """Per-vertex values for coloring."""
250
```
251

252
### Tracks Layer
253

254
Displays time-series point data with connections showing movement trajectories over time. Optimized for particle tracking and motion analysis.
255

256
```python { .api }
257
class Tracks(Layer):
258
    """Layer for displaying track data."""
259
    
260
    def __init__(
261
        self,
262
        data,
263
        *,
264
        properties: dict = None,
265
        graph: dict = None,
266
        tail_width: float = 2,
267
        tail_length: int = 30,
268
        head_length: float = 0,
269
        name: str = None,
270
        **kwargs
271
    ):
272
        """
273
        Create a tracks layer.
274
        
275
        Parameters:
276
        - data: Track data with time, track_id, and coordinates
277
        - properties: Dictionary of track properties
278
        - graph: Graph representation of track connections
279
        - tail_width: Width of track tails
280
        - tail_length: Length of visible track tails
281
        - head_length: Length of track heads (arrows)
282
        - name: Layer name
283
        """
284
    
285
    @property
286
    def graph(self) -> dict:
287
        """Graph representing track connectivity."""
288
    
289
    @property
290
    def tail_width(self) -> float:
291
        """Width of track tail lines."""
292
    
293
    @property
294
    def tail_length(self) -> int:
295
        """Number of time points to show in tails."""
296
```
297

298
### Vectors Layer
299

300
Displays vector data showing direction and magnitude at specific positions. Used for flow fields, gradients, and directional measurements.
301

302
```python { .api }
303
class Vectors(Layer):
304
    """Layer for displaying vector data."""
305
    
306
    def __init__(
307
        self,
308
        data,
309
        *,
310
        edge_width: float = 1,
311
        edge_color: str = 'red',
312
        length: float = 1,
313
        name: str = None,
314
        **kwargs
315
    ):
316
        """
317
        Create a vectors layer.
318
        
319
        Parameters:
320
        - data: Vector data (positions and directions)
321
        - edge_width: Width of vector arrows
322
        - edge_color: Color of vector arrows
323
        - length: Scaling factor for vector lengths
324
        - name: Layer name
325
        """
326
    
327
    @property
328
    def edge_width(self) -> float:
329
        """Width of vector lines."""
330
    
331
    @property
332
    def length(self) -> float:
333
        """Vector length scaling factor."""
334
    
335
    @property
336
    def edge_color(self):
337
        """Color of vector arrows."""
338
```
339

340
## Layer Names Set
341

342
```python { .api }
343
NAMES: set[str]
344
"""
345
Set containing lowercase names of all available layer types.
346
Includes: 'image', 'labels', 'points', 'shapes', 'surface', 'tracks', 'vectors'
347
"""
348
```
349

350
## Usage Examples
351

352
### Image Layer Examples
353

354
```python
355
import napari
356
import numpy as np
357

358
# 2D grayscale image
359
image_2d = np.random.random((100, 100))
360
viewer = napari.Viewer()
361
viewer.add_image(image_2d, colormap='viridis', name='2D Image')
362

363
# 3D RGB image
364
image_rgb = np.random.random((100, 100, 3))
365
viewer.add_image(image_rgb, rgb=True, name='RGB Image')
366

367
# 4D time-series
368
image_4d = np.random.random((10, 20, 100, 100))
369
viewer.add_image(image_4d, name='Time Series')
370
```
371

372
### Labels Layer Examples
373

374
```python
375
import napari
376
import numpy as np
377

378
# Create label data
379
labels = np.zeros((100, 100), dtype=int)
380
labels[25:75, 25:75] = 1
381
labels[10:40, 10:40] = 2
382

383
viewer = napari.Viewer()
384
viewer.add_labels(labels, name='Segmentation')
385
```
386

387
### Points Layer Examples
388

389
```python
390
import napari
391
import numpy as np
392

393
# Random points
394
points_data = np.random.random((100, 2)) * 100
395

396
viewer = napari.Viewer()
397
viewer.add_points(
398
    points_data,
399
    size=10,
400
    face_color='red',
401
    edge_color='white',
402
    name='Random Points'
403
)
404
```
405

406
### Multiple Layer Example
407

408
```python
409
import napari
410
import numpy as np
411

412
# Create different data types
413
image = np.random.random((100, 100))
414
labels = np.zeros((100, 100), dtype=int)
415
labels[25:75, 25:75] = 1
416
points = np.array([[25, 25], [75, 75], [25, 75], [75, 25]])
417

418
# Add all layers to viewer
419
viewer = napari.Viewer()
420
viewer.add_image(image, colormap='gray', name='Background')
421
viewer.add_labels(labels, name='Regions')  
422
viewer.add_points(points, size=15, face_color='cyan', name='Landmarks')
423

424
napari.run()
425
```