napari hook specification reference

All napari hook specifications for pluggable functionality are defined here.

A hook specification is a function signature (with documentation) that declares an API that plugin developers must adhere to when providing hook implementations. Hook implementations provided by plugins (and internally by napari) will then be invoked in various places throughout the code base.

When implementing a hook specification, pay particular attention to the number and types of the arguments in the specification signature, as well as the expected return type.

To allow for hook specifications to evolve over the lifetime of napari, hook implementations may accept fewer arguments than defined in the specification. (This allows for extending existing hook arguments without breaking existing implementations). However, implementations must not require more arguments than defined in the spec.

For more general background on the plugin hook calling mechanism, see the napari-plugin-manager documentation.

Note

Hook specifications are a feature borrowed from pluggy. In the pluggy documentation, hook specification marker instances are named hookspec by convention, and hook implementation marker instances are named hookimpl. The convention in napari is to name them more explicitly: napari_hook_specification and napari_hook_implementation, respectively.

IO hooks

napari_get_reader(path: Union[str, List[str]]) → Optional[Callable[[Union[str, List[str]]], List[Union[Tuple[Any], Tuple[Any, Dict], Tuple[Any, Dict, str]]]]][source]

Return a function capable of loading path into napari, or None.

This is the primary “reader plugin” function. It accepts a path or list of paths, and returns a list of data to be added to the Viewer.

The main place this hook is used is in Viewer.open(), via the read_data_with_plugins() function.

It will also be called on File -> Open... or when a user drops a file or folder onto the viewer. This function must execute quickly, and should return None if the filepath is of an unrecognized format for this reader plugin. If path is determined to be recognized format, this function should return a new function that accepts the same filepath (or list of paths), and returns a list of LayerData tuples, where each tuple is a 1-, 2-, or 3-tuple of (data,), (data, meta), or (data, meta, layer_type).

napari will then use each tuple in the returned list to generate a new layer in the viewer using the Viewer._add_layer_from_data() method. The first, (optional) second, and (optional) third items in each tuple in the returned layer_data list, therefore correspond to the data, meta, and layer_type arguments of the Viewer._add_layer_from_data() method, respectively.

Important

path may be either a str or a list of str. If a list, then each path in the list can be assumed to be one part of a larger multi-dimensional stack (for instance: a list of 2D image files that should be stacked along a third axis). Implementations should do their own checking for list or str, and handle each case as desired.

Parameters

path (str or list of str) – Path to file, directory, or resource (like a URL), or a list of paths.

Returns

A function that accepts the path, and returns a list of layer_data, where layer_data is one of (data,), (data, meta), or (data, meta, layer_type). If unable to read the path, must return None (not False!).

Return type

Callable or None

napari_get_writer(path: str, layer_types: List[str]) → Optional[Callable[[str, List[Tuple[Any, Dict, str]]], List[str]]][source]

Return function capable of writing napari layer data to path.

This function will be called whenever the user attempts to save multiple layers (e.g. via File -> Save Layers, or save_layers()). This function must execute quickly, and should return None if path has an unrecognized extension for the reader plugin or the list of layer types are incompatible with what the plugin can write. If path is a recognized format, this function should return a function that accepts the same path, and a list of tuples containing the data for each layer being saved in the form of (Layer.data, Layer._get_state(), Layer._type_string). The writer function should return a list of strings (the actual filepath(s) that were written).

Important

It is up to plugins to inspect and obey any extension in path (and return None if it is an unsupported extension).

An example function signature for a WriterFunction that might be returned by this hook specification is as follows:

def writer_function(
    path: str, layer_data: List[Tuple[Any, Dict, str]]
) -> List[str]:
    ...
Parameters
  • path (str) – Path to file, directory, or resource (like a URL). Any extensions in the path should be examined and obeyed. (i.e. if the plugin is incapable of returning a requested extension, it should return None).

  • layer_types (list of str) – List of layer types (e.g. “image”, “labels”) that will be provided to the writer function.

Returns

A function that accepts the path, a list of layer_data (where layer_data is (data, meta, layer_type)). If unable to write to the path or write the layer_data, must return None (not False).

Return type

Callable or None

Single Layers IO

The following hook specifications will be called when a user saves a single layer in napari, and should save the layer to the requested format and return the save path if the data are successfully written. Otherwise, if nothing was saved, return None. They each accept a path. It is up to plugins to inspect and obey the extension of the path (and return False if it is an unsupported extension). The data argument will come from Layer.data, and a meta dict that will correspond to the layer’s _get_state() method.

napari_write_image(path: str, data: Any, meta: dict) → Optional[str][source]

Write image data and metadata into a path.

It is the responsibility of the implementation to check any extension on path and return None if it is an unsupported extension. If path has no extension, implementations may append their preferred extension.

Parameters
  • path (str) – Path to file, directory, or resource (like a URL).

  • data (array or list of array) – Image data. Can be N dimensional. If meta[‘rgb’] is True then the data should be interpreted as RGB or RGBA. If meta[‘multiscale’] is True, then the data should be interpreted as a multiscale image.

  • meta (dict) – Image metadata.

Returns

path – If data is successfully written, return the path that was written. Otherwise, if nothing was done, return None.

Return type

str or None

napari_write_labels(path: str, data: Any, meta: dict) → Optional[str][source]

Write labels data and metadata into a path.

It is the responsibility of the implementation to check any extension on path and return None if it is an unsupported extension. If path has no extension, implementations may append their preferred extension.

Parameters
  • path (str) – Path to file, directory, or resource (like a URL).

  • data (array or list of array) – Integer valued label data. Can be N dimensional. Every pixel contains an integer ID corresponding to the region it belongs to. The label 0 is rendered as transparent. If a list and arrays are decreasing in shape then the data is from a multiscale image.

  • meta (dict) – Labels metadata.

Returns

path – If data is successfully written, return the path that was written. Otherwise, if nothing was done, return None.

Return type

str or None

napari_write_points(path: str, data: Any, meta: dict) → Optional[str][source]

Write points data and metadata into a path.

It is the responsibility of the implementation to check any extension on path and return None if it is an unsupported extension. If path has no extension, implementations may append their preferred extension.

Parameters
  • path (str) – Path to file, directory, or resource (like a URL).

  • data (array (N, D)) – Coordinates for N points in D dimensions.

  • meta (dict) – Points metadata.

Returns

path – If data is successfully written, return the path that was written. Otherwise, if nothing was done, return None.

Return type

str or None

napari_write_shapes(path: str, data: Any, meta: dict) → Optional[str][source]

Write shapes data and metadata into a path.

It is the responsibility of the implementation to check any extension on path and return None if it is an unsupported extension. If path has no extension, implementations may append their preferred extension.

Parameters
  • path (str) – Path to file, directory, or resource (like a URL).

  • data (list) – List of shape data, where each element is an (N, D) array of the N vertices of a shape in D dimensions.

  • meta (dict) – Shapes metadata.

Returns

path – If data is successfully written, return the path that was written. Otherwise, if nothing was done, return None.

Return type

str or None

napari_write_surface(path: str, data: Any, meta: dict) → Optional[str][source]

Write surface data and metadata into a path.

It is the responsibility of the implementation to check any extension on path and return None if it is an unsupported extension. If path has no extension, implementations may append their preferred extension.

Parameters
  • path (str) – Path to file, directory, or resource (like a URL).

  • data (3-tuple of array) – The first element of the tuple is an (N, D) array of vertices of mesh triangles. The second is an (M, 3) array of int of indices of the mesh triangles. The third element is the (K0, …, KL, N) array of values used to color vertices where the additional L dimensions are used to color the same mesh with different values.

  • meta (dict) – Surface metadata.

Returns

path – If data is successfully written, return the path that was written. Otherwise, if nothing was done, return None.

Return type

str or None

napari_write_vectors(path: str, data: Any, meta: dict) → Optional[str][source]

Write vectors data and metadata into a path.

It is the responsibility of the implementation to check any extension on path and return None if it is an unsupported extension. If path has no extension, implementations may append their preferred extension.

Parameters
  • path (str) – Path to file, directory, or resource (like a URL).

  • data ((N, 2, D) array) – The start point and projections of N vectors in D dimensions.

  • meta (dict) – Vectors metadata.

Returns

path – If data is successfully written, return the path that was written. Otherwise, if nothing was done, return None.

Return type

str or None