Metadata module

This module module stores comprehensive metadata related to microscopy images. Key data includes:

• Picture Planes: Descriptions of individual image components or channels, including their modalities and spectral properties.

  See PicturePlaneDesc class storing information about individual image plane.

  Or PictureMetadataPicturePlanes class storing information about all image planes.

• Sample settings: The SampleSettings class stores various settings and configurations related to the sample being imaged. One sample setting can be used by one or multiple image planes in PictureMetadataPicturePlanes.

  See SampleSettings dataclass for more information.

All data about planes and their settings are stored in PictureMetadata class.

PictureMetadata dataclass

PictureMetadata()

Dataclass for storing metadata associated with a captured picture.

Stores some attributes valid for whole image, metadata for individual channels can be retrieved using PictureMetadata.channels attribute.

Attributes:

Note

Only selected attributes are listed, for full list of attributes see class definition.

ATTRIBUTE	DESCRIPTION
dTimeAbsolute	The absolute time the picture was captured, specified as a Julian Day Number. TYPE: float
sPicturePlanes	Information about the picture's planes and their settings. TYPE: PictureMetadataPicturePlanes
dCalibration	Calibration factor specifying the conversion from microns to pixels. TYPE: float
dCalibPrecision	The precision of the calibration in microns. TYPE: float
bCalibrated	Indicates whether the calibration is valid. TYPE: bool
dAspect	The pixel aspect ratio. TYPE: float
dObjectiveMag	The magnification factor of the objective lens. TYPE: float
dObjectiveNA	The numerical aperture of the objective lens. TYPE: float
dRefractIndex1	The refractive index of the medium at the objective side. TYPE: float
dZoom	The zoom factor used during image capture. TYPE: float

channelNames property

channelNames: list[str]

Returns names of all channels (planes).

channels property

channels: list[PicturePlaneDesc]

Returns list of channels (planes) in the image.

componentColors property

componentColors: list[tuple[float, float, float]]

Returns colors of each component as normalized tuple in a list.

componentNames property

componentNames: list[str]

Returns names of all components.

isRgb property

isRgb: bool

Checks if image is an RGB image.

valid property

valid: bool

Checks if metadata have correct number of channels.

cameraName

cameraName(plane: int | PicturePlaneDesc = 0) -> str

Returns camera name using either PicturePlaneDesc instance or an index of channel.

makeValid

makeValid(comps: int, **kwargs) -> None

Attempts to fix info about channels using specified number of channels.

This function creates channel info basec on component count like this:

comps == 1: function creates one Mono channel
comps == 2: function creates channels Channel_1, Channel_2
comps == 3: function creates one RGB channel
comps >= 4: function creates channels Channel_1, ..., Channel_N

PARAMETER	DESCRIPTION
comps	The number of components in the image. TYPE: int
**kwargs	Additional parameters to pass to each plane. TYPE: dict DEFAULT: {}

microscopeName

microscopeName(plane: int | PicturePlaneDesc = 0) -> str

Returns microscope name using either PicturePlaneDesc instance or an index of channel.

objectiveMagnification

objectiveMagnification(plane: int | PicturePlaneDesc = 0) -> float

Returns objective magnification using either PicturePlaneDesc instance or an index of channel.

objectiveName

objectiveName(plane: int | PicturePlaneDesc = 0) -> str

Returns name of objective using either PicturePlaneDesc instance or an index of channel.

objectiveNumericAperture

objectiveNumericAperture(plane: int | PicturePlaneDesc = 0) -> float

Returns objective numeric aperture using either PicturePlaneDesc instance or an index of channel.

opticalConfigurations

opticalConfigurations(plane: int | PicturePlaneDesc = 0) -> list[str]

Returns list of optical configurations.

refractiveIndex

refractiveIndex(plane: int | PicturePlaneDesc = 0) -> float

Returns refractive index using either PicturePlaneDesc instance or an index of channel.

sampleSettings

sampleSettings(plane: int | PicturePlaneDesc = 0) -> SampleSettings | None

Returns an instance of SampleSettings using either PicturePlaneDesc instance or an index of channel.

PictureMetadataPicturePlanes dataclass

PictureMetadataPicturePlanes()

Stores metadata for the picture planes and their associated settings in a microscopy imaging experiment.

Attributes:

Note

Only selected attributes are listed, for full list of attributes see class definition.

ATTRIBUTE	DESCRIPTION
uiCount	The number of picture planes in sPlaneNew. TYPE: int
uiCompCount	The total number of components across all picture planes. It is the sum of uiCompCount values from all members of sPlaneNew. TYPE: int
sPlaneNew	A list of PicturePlaneDesc objects, each representing metadata for a single picture plane. TYPE: list[PicturePlaneDesc]
uiSampleCount	The number of sample settings in the file. TYPE: int
sSampleSetting	A list of SampleSettings objects, each containing the detailed configuration for a sample, one sample setting can be used for one or multiple planes. TYPE: list[SampleSettings]

valid property

valid: bool

Checks if PictureMetadataPicturePlanes insance has valid number of channels.

RETURNS	DESCRIPTION
bool	True if number of channels is valid, False otherwise.

makeValid

makeValid(comps: int, **kwargs) -> None

Attempts to fix info about channels using specified number of channels.

This function creates channel info basec on component count like this:

comps == 1: function creates one Mono channel
comps == 2: function creates channels Channel_1, Channel_2
comps == 3: function creates one RGB channel
comps >= 4: function creates channels Channel_1, ..., Channel_N

PARAMETER	DESCRIPTION
comps	The number of components in the image. TYPE: int
**kwargs	Additional parameters to pass to each plane. TYPE: dict DEFAULT: {}

PicturePlaneDesc dataclass

PicturePlaneDesc()

Metadata for a single plane in a picture, typically used in microscopy or imaging systems.

This class contains information about the image plane's calibration, modality, fluorescent probe, optical filter path, acquisition settings, and other relevant details that define how the image plane was captured and how it should be processed.

Some metadata is stored in this class directly, more information is stored in corresponding SampleSettings instance, this SampleSetting instance can be retvieved calling PictureMetadata.sampleSettings function with an instance of this class as a parameter.

Attributes:

Note

Only selected attributes are listed, for full list of attributes see class definition.

ATTRIBUTE	DESCRIPTION
uiCompCount	The number of components in the picture plane, usually it is 1, can be 3 for an RGB image. TYPE: int
uiSampleIndex	Hold index of sample settings used for this picture plane. See PictureMetadataPicturePlanes.sSampleSetting attribute storing sample settings. TYPE: int
dObjCalibration1to1	Calibration factor for the camera chip used during acquisition. TYPE: float
uiModalityMask	Bitmask indicating the modality of the picture plane, such as fluorescence. TYPE: PicturePlaneModalityFlags
pFluorescentProbe	Description of the fluorescent probe used in the picture plane. TYPE: FluorescentProbe
pFilterPath	Describes the optical filter path used in the picture plane. TYPE: OpticalFilterPath
uiColor	Color used for representing the picture plane. TYPE: int
sDescription	Name for the picture plane. TYPE: str
dAcqTime	Acquisition time for one single image plane. This can vary for different planes in a picture. TYPE: float
dPinholeDiameter	The diameter of the pinhole used in the optical setup, in micrometers. TYPE: float

colorAsClampedTuple property

colorAsClampedTuple

Get the color of the picture plane as an RGB tuple normalized to range [0.0, 1.0].

colorAsHtmlString property

colorAsHtmlString

Get the color of the picture plane as HTML string.

colorAsTuple property

colorAsTuple

Get the color of the picture plane as an RGB tuple.

emissionWavelengthNm cached property

emissionWavelengthNm: float

Returns the single emission wavelength for the picture plane, calculated from the fluorescent probe or optical filter path.

excitationWavelengthNm cached property

excitationWavelengthNm: float

Returns the single excitation wavelength for the picture plane, calculated from the fluorescent probe or optical filter path.

isBrightfield property

isBrightfield: bool

Returns whether the picture plane is a brightfield image.

isContrast property

isContrast: bool

Returns whether the picture plane is a contrast image.

isDarkfield property

isDarkfield: bool

Returns whether the picture plane is a darkfield image.

isFluorescence property

isFluorescence: bool

Returns whether the picture plane is a fluorescence image.

modalityList property

modalityList: list[str]

Returns a list of modalities present in the picture plane converted to strings.

SampleSettings dataclass

SampleSettings()

Stores settings related to the acquisition of an image, including information about the camera, device, objective lens, and optical configurations.

Attributes:

Note

Only selected attributes are listed, for full list of attributes see class definition.

ATTRIBUTE	DESCRIPTION
pCameraSetting	The camera settings used during image acquisition, including camera-specific properties such as name, type, and family. TYPE: CameraSetting
pDeviceSetting	Settings related to the device or microscope used for imaging, including microscope names, size, and usage. TYPE: DeviceSetting
pObjectiveSetting	Details of the objective lens used during acquisition, such as magnification, numerical aperture, and refractive index. TYPE: ObjectiveSetting
sOpticalConfigs	A list of optical configurations used during imaging, each represented as a SampleSettingsOC object. TYPE: list[SampleSettingsOC]

cameraName property

cameraName: str

Return name of the camera used to aquire given sample.

microscopeName property

microscopeName: str

Return name of the microscope used to aquire given sample.

objectiveCode property

objectiveCode: str

Return name of the camera used to aquire given sample.

objectiveMagnification property

objectiveMagnification: float

Return magification of used objective.

objectiveName property

objectiveName: str

Return name of the objective used to aquire given sample.

objectiveNumericAperture property

objectiveNumericAperture: float

Return numerical aperture of used objective lens.

opticalConfigurations property

opticalConfigurations: list[str]

Return list of all optical configurations.

refractiveIndex property

refractiveIndex: float

Return refractive index of the medium in given sample.

CameraSetting dataclass

CameraSetting()

Stores information about the camera used for image acquisition.

ATTRIBUTE	DESCRIPTION
CameraUniqueName	A unique name identifier for the camera. TYPE: str
CameraUserName	The user-assigned name for the camera. TYPE: str
CameraFamilyName	The name of the camera family or model group. TYPE: str

DeviceSetting dataclass

DeviceSetting()

Stores information about the microscope device settings.Stores information about the microscope device settings.

ATTRIBUTE	DESCRIPTION
m_sMicroscopeFullName	The full name of the microscope. TYPE: str
m_sMicroscopeShortName	A short name for the microscope. TYPE: str

FluorescentProbe dataclass

FluorescentProbe(*, m_sName: str = LV_field('', STRING), m_uiColor: int = LV_field(16777215, UINT32), m_ExcitationSpectrum: OpticalSpectrum = LV_field(OpticalSpectrum, LEVEL), m_EmissionSpectrum: OpticalSpectrum = LV_field(OpticalSpectrum, LEVEL))

A class representing a fluorescent probe.

ATTRIBUTE	DESCRIPTION
m_sName	The name of the fluorescent probe. TYPE: str
m_uiColor	The color of the probe. TYPE: int
m_ExcitationSpectrum	An object representing the excitation spectrum of the probe, typically defining the wavelengths at which the probe absorbs light. TYPE: OpticalSpectrum
m_EmissionSpectrum	An object representing the emission spectrum of the probe, typically defining the wavelengths at which the probe emits light after excitation. TYPE: OpticalSpectrum

ObjectiveSetting dataclass

ObjectiveSetting(*, wsObjectiveName: str = LV_field('', STRING), wsObjectiveCode: str = LV_field('', STRING), dObjectiveMag: float = LV_field(0.0, DOUBLE), dObjectiveNA: float = LV_field(0.0, DOUBLE), dRefractIndex: float = LV_field(0.0, DOUBLE), bTiltingNosepiece: bool = LV_field(False, BOOL), dHorizontalAngle: float = LV_field(0.0, DOUBLE), dVerticalAngle: float = LV_field(0.0, DOUBLE), dOpticalAxis: float = LV_field(0.0, DOUBLE))

Stores information about the objective lens used to acquire an image.

Attributes:

Note

Only selected attributes are listed, for full list of attributes see class definition.

ATTRIBUTE	DESCRIPTION
wsObjectiveName	The name of the objective lens (e.g., "40x Objective" or "100x Oil Immersion"). TYPE: str
dObjectiveMag	The magnification power of the objective lens (e.g., 10x, 40x, 100x). TYPE: float
dObjectiveNA	The numerical aperture (NA) of the objective lens. TYPE: float
dRefractIndex	The refractive index of the medium between the objective lens and the sample (e.g., air, water, oil). TYPE: float

OpticalFilter dataclass

OpticalFilter()

Represents an optical filter in an optical system, typically used in fluorescence microscopy.

ATTRIBUTE	DESCRIPTION
m_sName	The name of the optical filter. TYPE: str
m_sUserName	A user-defined name for the optical filter. TYPE: str
m_ePlacement	Specifies the position of the filter in the optical path (e.g., excitation, emission, filter turret, etc.). TYPE: OpticalFilterPlacement
m_eNature	Specifies the nature of the filter (e.g., wide-band, RGB, or specific color filters). TYPE: OpticalFilterNature
m_eSpctType	Defines the spectrum type of the filter (e.g., bandpass, narrow-bandpass, lowpass, etc.). TYPE: OpticalFilterSpectType
m_uiColor	The color of the filter. TYPE: int
m_ExcitationSpectrum	The spectrum of the filter that allows specific excitation wavelengths to pass through. TYPE: OpticalSpectrum
m_EmissionSpectrum	The spectrum of the filter that allows specific emitted wavelengths to pass through. TYPE: OpticalSpectrum
m_MirrorSpectrum	The spectrum related to the mirror spectrum. TYPE: OpticalSpectrum

OpticalFilterNature

Enumeration that defines the nature of an optical filter, indicating the type of spectra it handles.

ATTRIBUTE	DESCRIPTION
eOfnGeneric	A wide-band or unspecified spectrum filter, often used for general applications. TYPE: int
eOfnRGB	A triple-band filter suitable for use with RGB cameras or for human visual perception. TYPE: int
eOfnRed	A filter that passes the red part of the spectrum. TYPE: int
eOfnGreen	A filter that passes the green part of the spectrum. TYPE: int
eOfnBlue	A filter that passes the blue part of the spectrum. TYPE: int

OpticalFilterPath dataclass

OpticalFilterPath(*, m_sDescr: str = LV_field('', STRING), m_uiCount: int = LV_field(0, UINT32), m_pFilter: list[OpticalFilter] = LV_field(list, LEVEL))

Represents a path of optical filters within an optical system, typically in fluorescence microscopy setups.

ATTRIBUTE	DESCRIPTION
m_sDescr	A description of the optical filter path, typically used for identification or documentation. TYPE: str
m_uiCount	The number of filters in the optical filter path. TYPE: int
m_pFilter	A list of OpticalFilter objects, each representing an optical filter in the path. TYPE: list[OpticalFilter]

isValid property

isValid: bool

Returns whether the filter path is valid (has at least one filter).

closestExcitationWavelength

closestExcitationWavelength(emission: float) -> float

Finds the excitation wavelength that is closest to a given emission wavelength from the filters in the path.

meanEmissionWavelength

meanEmissionWavelength() -> float

Calculates the mean emission wavelength based on the emission spectra of the filters in the path.

OpticalFilterPlacement

Enumeration that defines the placement of an optical filter in an optical system.

ATTRIBUTE	DESCRIPTION
eOfpNoFilter	No filter applied. TYPE: int
eOfpExcitation	Position for the excitation filter, typically located near the light source (lamp). TYPE: int
eOfpEmission	Position for the emission filter, usually located near the camera. TYPE: int
eOfpFilterTurret	Position for the filter block, commonly used in fluorescence microscopy systems. TYPE: int
eOfpLamp	Position related to the lamp's spectrum. TYPE: int
eOfnCameraChip	Position related to the sensitivity of the camera chip. TYPE: int
eOfpUserOverride	User-defined emission wavelength position, allowing customization of the filter setup. TYPE: int

OpticalFilterSpectType

Enumeration that defines the types of optical spectra that an optical filter can handle.

ATTRIBUTE	DESCRIPTION
eOftBandpass	A bandpass filter defined by a lower (raising edge) and higher (falling edge) wavelength. TYPE: int
eOftNarrowBandpass	A narrow bandpass filter specified by a single wavelength (peak). TYPE: int
eOftLowpass	A lowpass filter specified by one wavelength (falling edge). TYPE: int
eOftHighpass	A highpass filter specified by one wavelength (raising edge). TYPE: int
eOftBarrier	A barrier filter defined by a lower (falling edge) and higher (raising edge) wavelength. TYPE: int
eOftMultiplepass	A filter allowing multiple passes, specified by a few edges. TYPE: int
eOftFull	The full position in a filterwheel, indicating that the filter allows all wavelengths to pass. TYPE: int
eOftEmpty	The empty position in a filterwheel, where no filter is present. TYPE: int

OpticalSpectrum dataclass

OpticalSpectrum(*, uiCount: int = LV_field(0, UINT32), bPoints: bool = LV_field(False, BOOL), pPoint: list[OpticalSpectrumPoint] = LV_field(list, LEVEL))

Class representing an optical spectrum, consisting of a series of spectrum points.

ATTRIBUTE	DESCRIPTION
uiCount	The number of points in the optical spectrum. TYPE: int
bPoints	A flag indicating whether the spectrum contains only points. (OpticalSpectrumPointType.eSptPoint) TYPE: bool
pPoint	A list of OpticalSpectrumPoint instances representing the spectrum. TYPE: list[OpticalSpectrumPoint]

count property

count: int

Returns number of points in the optical spectrum.

isValid property

isValid: bool

Check whether the optical spectrum is valid (has at least one point).

combine staticmethod

combine(a: OpticalSpectrum | None, b: OpticalSpectrum | None) -> OpticalSpectrum | None

Combines two optical spectra into a single spectrum.

findmaxtvalue

findmaxtvalue() -> tuple[int, float]

Finds the index and value of the maximum dTValue in the spectrum.

peakAndFWHM

peakAndFWHM() -> tuple[float, float, float]

Calculates the peak wavelength and Full Width at Half Maximum (FWHM) for the spectrum.

RETURNS	DESCRIPTION
tuple[float, float, float]	Wavelegth of lower edge of the FWHM, peak wavelegth and upper edge of the FWHM.

singleWavelength

singleWavelength() -> float

Returns the single representative wavelength for the spectrum, calculated as the peak wavelength or weighted average of wavelengths.

wavelengthRange

wavelengthRange() -> tuple[float, float]

Returns the minimum and maximum wavelengths of the spectrum.

OpticalSpectrumPoint dataclass

OpticalSpectrumPoint()

Class representing a single point in an optical spectrum.

Attributes:

Note

Only selected attributes are listed, for full list of attributes see class definition.

ATTRIBUTE	DESCRIPTION
eType	Type of the point (most commonly OpticalSpectrumPointType.eSptPeak storing peak value). TYPE: OpticalSpectrumPointType
dWavelength	Wavelength of the point. TYPE: float
dTValue	Intensity value of the point. TYPE: float

OpticalSpectrumPointType

Enum class representing different types of optical spectrum points.

ATTRIBUTE	DESCRIPTION
eSptInvalid	Represents an invalid spectrum point.
eSptPoint	Represents a standard spectrum point.
eSptRaisingEdge	Represents a raising edge in the spectrum.
eSptFallingEdge	Represents a falling edge in the spectrum.
eSptPeak	Represents a peak point in the spectrum.
eSptRange	Represents a range or span of spectrum points.

PicturePlaneModality

Enum for modality of given plane.

Warning

In modern .nd2 files this modality enum should be converted to PicturePlaneModalityFlags instance using from_modality() function.

PicturePlaneModalityFlags

Enum for modality flags of given plane.

from_modality staticmethod

from_modality(mod: PicturePlaneModality) -> PicturePlaneModalityFlags

Converts modality enum to PicturePlaneModalityFlags.

PARAMETER	DESCRIPTION
mod	modality enum instance TYPE: PicturePlaneModality

RETURNS	DESCRIPTION
PicturePlaneModalityFlags	Modalify flag for given modality

from_modality_string staticmethod

from_modality_string(modality: str) -> PicturePlaneModalityFlags

Converts modality string to PicturePlaneModalityFlags.

PARAMETER	DESCRIPTION
modality	modality string (for example "Wide-field", "Brightfield", "Phase", ...) TYPE: string

RETURNS	DESCRIPTION
PicturePlaneModalityFlags	Modalify flag for given modality, 0 for "undefined"

modality_OME_map staticmethod

modality_OME_map() -> dict[str, PicturePlaneModalityFlags]

Returns mapping of modality strings of OME-XML AcquisitionMode and ContrastMethod attributes to PicturePlaneModalityFlags.

Note

When parsing OME-XML, you must convert AcquisitionMode and ContrastMethod attributes separately and use binary or with the flags.

modality_list staticmethod

modality_list() -> list[str]

Returns list of known modality strings ("Wide-field", "Brightfield", ...).

modality_string_map staticmethod

modality_string_map() -> dict[str, PicturePlaneModalityFlags]

Returns mapping of known modality strings ("Wide-field", "Brightfield", ...) to PicturePlaneModalityFlags.

to_str_list staticmethod

to_str_list(flags: PicturePlaneModalityFlags) -> list[str]

Converts modality flags to list of human readable strings.

PARAMETER	DESCRIPTION
flags	odality flags TYPE: PicturePlaneModalityFlags

RETURNS	DESCRIPTION
list[str]	human readable string list, for example ["Brightfield", "Phase"]

SampleSettingsOC dataclass

SampleSettingsOC(*, uiOCTypeKey: int = LV_field(0, UINT32), sOpticalConfigName: str = LV_field('', STRING))

Stores optical configuration settings for a sample.

ATTRIBUTE	DESCRIPTION
sOpticalConfigName	The name of the optical configuration being used for the sample. TYPE: str