Metadata factory module¶

This module contains helper classes and functions for creating PictureMetadata instances using simplified parameters for channels and microscope settings. Those instances should be used with Nd2Writer instance for altering / creating .nd2 files.

Info

Since this module is used to creating metadata data structures, you should not use any part of this module if you only read an .nd2 file.

For creating metadata, you should use MetadataFactory class.

MetadataFactory ¶

MetadataFactory(planes: list[dict[str, Any] | Plane] | None = None, *, pixel_calibration: float = -1.0, **kwargs: Any)

pixel_calibration `instance-attribute` ¶

pixel_calibration: float = pixel_calibration

Helper class for creating metadata, see examples below on how to create metadata witch channels and microscope settings.

To actually create metadata instance, make sure to call either .createMetadata() method or use call operator.

Sample usage¶

Make sure to import MetadataFactory class before using it, optionally you can use Plane dataclass if you wish to use it.

from limnd2.metadata_factory import MetadataFactory, Plane

You can create channels and microscope settings on MetadataFactory constructor, or add them later using .addPlane() method.

When you add microscope settings to MetadataFactory constructor, those settings will be used for all channels, unless you overwrite them by providing replacement values when creating individual channel.

In following example objective_magnification is applied to all channels, immersion_refractive_index however is only applied to Channel2.

To see whole list of microscope settings that can be applied per channel or per whole factory, see Plane dataclass.

# Create all data on constructor (miscroscope settings and channels)
factory = MetadataFactory([{"name": "Channel1", "color": "red"},
                           {"name": "Channel2", "color": "blue", "immersion_refractive_index" : 1.2}],
                          pixel_calibration = 50,
                          objective_magnification = 40.0)

print(factory.createMetadata())

You can also create factory instance with global microscope settings and add channels later.

# Create factory instance with global microscope settings
factory = MetadataFactory(immersion_refractive_index= 1.5,
                        objective_magnification= 40.0, pixel_calibration=20)

You can add channel using named arguments.

factory.addPlane(name = "Channel 1",
                 emission_wavelength = 500,
                 color = "blue")

You can add channel using Plane dataclass.

factory.addPlane(Plane(name = "Channel 2",
                       excitation_wavelength = 600,
                       emission_wavelength = 700,
                       color = "blue"))

Or you can add channels using a dictionary.

factory.addPlane({"name": "Channel 3",
                "immersion_refractive_index": 1.6,
                "objective_magnification": 20.0})

You can also create channel, store it in a variable and modify it.

plane = factory.addPlane({"name": "Channel 4"})

plane.color = "green"
plane.camera_name = "Camera channel 4"
plane.modality = "Brightfield"

Or you can access existing channel using its index

factory.getChannel(2).pinhole_diameter = 50
factory.getChannel(2).microscope_name = "Microscope for channel 3"
factory.getChannel(2).color = "green"

Or you can access existing channel using its channel name

factory.getChannel("Channel 1").color = "red"
factory.getChannel("Channel 1").immersion_refractive_index = 1.6

Finally create metadata using createMetadata method

print(factory.createMetadata())

call ¶

__call__() -> PictureMetadata

Creates a new PictureMetadata instance from the factory settings.

addPlane ¶

addPlane(plane: Plane | dict[str, Any] | None = None, **kwargs) -> Plane

Adds a new channel to the factory, see examples on how to use this method and Plane dataclass to see what settings can be applied.

PARAMETER	DESCRIPTION
`plane`	A `Plane` object or a dictionary with plane settings. TYPE: `Plane \| dict[str, Any]` DEFAULT: `None`
`**kwargs`	Additional settings for the plane. TYPE: `dict` DEFAULT: `{}`

createMetadata ¶

createMetadata(*, number_of_channels_fallback: int = 1, is_rgb_fallback: bool = False) -> PictureMetadata

Creates a new PictureMetadata instance from the factory settings.

Plane `dataclass` ¶

Plane(*, name: Optional[str] = None, modality: Optional[str | PicturePlaneModality | PicturePlaneModalityFlags] = None, excitation_wavelength: Optional[int] = None, emission_wavelength: Optional[int] = None, color: Optional[str] = None, objective_magnification: Optional[float] = None, objective_numerical_aperture: Optional[float] = None, zoom_magnification: Optional[float] = None, immersion_refractive_index: Optional[float] = None, pinhole_diameter: Optional[float] = None, camera_name: Optional[str] = None, microscope_name: Optional[str] = None, filter_name: Optional[str] = None, acquisition_time: Optional[datetime] = None)

A class to represent a plane in metadata, see attributes list to see what settings can be applied.

ATTRIBUTE	DESCRIPTION
`name`	The name of the plane. TYPE: `str`
`modality`	The modality of the plane, can be a string (e.g., fluorescence, brightfield) or an instance of PicturePlaneModality or PicturePlaneModalityFlags. TYPE: `str \| PicturePlaneModality \| PicturePlaneModalityFlags`
`excitation_wavelength`	The excitation wavelength in nanometers. TYPE: `int`
`emission_wavelength`	The emission wavelength in nanometers. TYPE: `int`
`filter_name`	The name of the filter used. TYPE: `str`
`color`	The color associated with the plane. TYPE: `str`
`objective_magnification`	The magnification of the objective lens. (overrides setting from MetadataFactory) TYPE: `float`
`objective_numerical_aperture`	The numerical aperture of the objective lens. (overrides setting from MetadataFactory) TYPE: `float`
`zoom_magnification`	The zoom magnification. (overrides setting from MetadataFactory) TYPE: `float`
`immersion_refractive_index`	The refractive index of the immersion medium. (overrides setting from MetadataFactory) TYPE: `float`
`pinhole_diameter`	The diameter of the pinhole. (overrides setting from MetadataFactory) TYPE: `float`
`camera_name`	The name of the camera used. (overrides setting from MetadataFactory) TYPE: `str`
`microscope_name`	The name of the microscope used. (overrides setting from MetadataFactory) TYPE: `str`
`acquisition_time`	Acquistion time of the plane. TYPE: `datetime`