Image#

Base Image Interface#

Base interface shared by the interfaces that write a collection of image files to NWB.

class BaseImageInterface(file_paths: list[str | pathlib._local.Path] | None = None, folder_path: str | pathlib._local.Path | None = None, *, metadata_key: str = 'Images', verbose: bool = True)[source]#

Bases: BaseDataInterface

Base class for the interfaces that write a collection of image files into an Images container.

Subclasses declare the file suffixes they can write in associated_suffixes and implement _create_nwb_image, which turns a single file into the NWB image object placed in the container.

Initialize the image interface.

Parameters:

  • file_paths (list of str | Path, optional) – List of paths to image files to be converted

  • folder_path (str | Path, optional) – Path to folder containing images to be converted. Used if file_paths not provided.

  • metadata_key (str, default: “Images”) – Key to use in metadata[“Images”][metadata_key] for storing container metadata

  • verbose (bool, default: True) – Whether to print status messages

classmethod get_source_schema() → dict[source]#

Return the schema for the source_data.

get_metadata_schema() → dict[source]#

Return the schema for the metadata, declaring the Images container and its per-image blocks.

get_metadata() → DeepDict[source]#

Get metadata for the images.

This method returns a metadata structure that includes both container-level and per-image metadata. The per-image metadata allows customization of individual image properties such as name, resolution, and description.

Returns:

Metadata dictionary with the following structure:

{
    "Images": {
        "<metadata_key>": {
            "name": str,
                Name of the Images container (defaults to metadata_key)
            "description": str,
                Description of the Images container
            "images": {
                "<file_path_1>": {
                    "name": str,
                        Name for the individual image (defaults to file stem)
                    "resolution": float, optional
                        Resolution in pixels/cm (can be added by user, embedded images only)
                    "description": str, optional
                        Description of the individual image (can be added by user)
                },
                "<file_path_2>": {
                    ...
                }
            }
        }
    }
}

Return type:

DeepDict

Examples

Basic usage: >>> interface = ImageInterface(file_paths=[“/data/img1.png”, “/data/img2.jpg”]) >>> metadata = interface.get_metadata() >>> print(metadata[“Images”][“ImagesRGB”][“images”]) {“/data/img1.png”: {“name”: “img1”}, “/data/img2.jpg”: {“name”: “img2”}}

Customizing per-image metadata: >>> metadata = interface.get_metadata() >>> metadata[“Images”][“ImagesRGB”][“images”][“/data/img1.png”][“resolution”] = 2.5 >>> metadata[“Images”][“ImagesRGB”][“images”][“/data/img1.png”][“description”] = “Baseline image” >>> metadata[“Images”][“ImagesRGB”][“images”][“/data/img2.jpg”][“name”] = “treatment_image” >>> interface.add_to_nwbfile(nwbfile, metadata=metadata)

Notes

  • The “images” dictionary maps file paths (as strings) to individual image metadata

  • Users can modify the returned metadata to customize image properties before calling add_to_nwbfile()

  • Resolution should be specified in pixels/cm if provided

  • If resolution or description are not specified, they will not be passed to the NWB image objects

  • Image names default to the file stem but can be overridden in the metadata

add_to_nwbfile(nwbfile: NWBFile, metadata: DeepDict | None = None, *, parent_container: Literal['stimulus', 'acquisition'] | None = None) → None[source]#

Add the image data to an NWB file.

Parameters:

  • nwbfile (NWBFile) – The NWB file to add the images to

  • metadata (dict, optional) – Metadata for the images

  • parent_container ({“acquisition”, “stimulus”}, optional) – The group of the NWB file the Images container is written to, “acquisition” by default.

Image#

Interface for converting single or multiple images to NWB format.

class SingleImageIterator(file_path: str | pathlib._local.Path)[source]#

Bases: AbstractDataChunkIterator

Simple iterator to return a single image. This avoids loading the entire image into memory at initializing and instead loads it at writing time one by one

recommended_chunk_shape()[source]#

Recommend the chunk shape for the data array.

recommended_data_shape()[source]#

Recommend the initial shape for the data array.

property dtype#

Define the data type of the array

property maxshape#

Property describing the maximum shape of the data array that is being iterated over

property image_info#

Return dictionary with image information

class ImageInterface(file_paths: list[str | pathlib._local.Path] | None = None, folder_path: str | pathlib._local.Path | None = None, *args, images_location: Literal['stimulus', 'acquisition'] | None = None, metadata_key: str = 'Images', verbose: bool = True)[source]#

Bases: BaseImageInterface

Interface for converting single or multiple images to NWB format.

Initialize the ImageInterface.

Parameters:

  • file_paths (list of str | Path, optional) – List of paths to image files to be converted

  • folder_path (str | Path, optional) – Path to folder containing images to be converted. Used if file_paths not provided.

  • images_location (Literal[“acquisition”, “stimulus”], optional) – Deprecated. Pass parent_container to add_to_nwbfile instead. Will be removed in v0.12.0.

  • metadata_key (str, default: “Images”) – Key to use in metadata[“Images”][metadata_key] for storing container metadata

  • verbose (bool, default: True) – Whether to print status messages

display_name: str | None = 'Image Interface'#
keywords: tuple[str] = ('image',)#
associated_suffixes: tuple[str] = ('.png', '.jpg', '.jpeg', '.tiff', '.tif', '.webp')#
info: str | None = 'Interface for converting single or multiple images to NWB format.'#
IMAGE_MODE_TO_NWB_TYPE_MAP = {'I;16': <class 'pynwb.image.GrayscaleImage'>, 'L': <class 'pynwb.image.GrayscaleImage'>, 'LA': <class 'pynwb.image.RGBAImage'>, 'RGB': <class 'pynwb.image.RGBImage'>, 'RGBA': <class 'pynwb.image.RGBAImage'>}#

External Image#

Interface for writing images to NWB by reference, without embedding their pixel data.

class ExternalImageInterface(file_paths: list[str | pathlib._local.Path] | None = None, folder_path: str | pathlib._local.Path | None = None, *, metadata_key: str = 'Images', verbose: bool = True)[source]#

Bases: BaseImageInterface

Interface for writing images to NWB as paths pointing at the files on disk.

Initialize the image interface.

Parameters:

  • file_paths (list of str | Path, optional) – List of paths to image files to be converted

  • folder_path (str | Path, optional) – Path to folder containing images to be converted. Used if file_paths not provided.

  • metadata_key (str, default: “Images”) – Key to use in metadata[“Images”][metadata_key] for storing container metadata

  • verbose (bool, default: True) – Whether to print status messages

display_name: str | None = 'External Image Interface'#
keywords: tuple[str] = ('image', 'external')#
associated_suffixes: tuple[str] = ('.png', '.jpg', '.jpeg', '.gif')#
info: str | None = 'Interface for writing images to NWB by reference, leaving the pixel data in the source files.'#
SUPPORTED_IMAGE_FORMATS = ('PNG', 'JPEG', 'GIF')#
PIL_MODE_TO_NWB_IMAGE_MODE = {'I;16': 'grayscale', 'L': 'grayscale'}#