nd2.structures ¶

Dataclasses and other structures used for metadata.

Classes:

AnimParam –

Parameters of ROI position/shape.
Attributes –

Primary attributes of an ND2 file.
BoxShape –

Size of a 3D box.
Channel –

Structure of a channel in an ND2 file.
ChannelMeta –

Metadata for a channel in an ND2 file.
Color –

RGB color with optional alpha channel.
Contents –

Contents of an ND2 file metadata.
CustomLoop –

Custom loop in an experiment.
ExperimentEvent –

An event in an experiment.
ExtrudedShape –

Shape of an extruded object.
FrameChannel –

Channel metadata for a frame.
FrameMetadata –

Metadata of a frame in an ND2 file.
InterpType –

The role that the ROI plays.
LoopIndices –

Indices of loops in an channel.
LoopType –

Type of loop in an experiment.
Metadata –

Metadata of an ND2 file.
Microscope –

Microscope metadata.
NETimeLoop –

The time dimension of an nD experiment.
NETimeLoopParams –

Parameters associated with a time loop in an nD experiment.
Period –

A phase in an nD experiment.
PeriodDiff –

Time difference between periods in a time loop.
Position –

A position in an XY position loop.
ROI –

ROI object from NIS Elements.
RoiInfo –

Info associated with an ROI.
RoiShapeType –

The type of ROI shape.
ScopeType –

Scope of an ROI.
StagePosition –

A position in stage coordinates.
StimulationEvent –

Stimulation parameters for an experiment event.
TextInfo –

Structure of dict returned by ND2File.text_info.
TimeLoop –

The time dimension of an experiment.
TimeLoopParams –

Parameters associated with a time loop.
TimeStamp –

Absolute and relative timestamp of a frame.
Volume –

Volume metadata.
XYPoint –

XY coordinate.
XYPosLoop –

A loop over XY positions in an experiment.
XYPosLoopParams –

Parameters associated with a XY position loop.
XYZPoint –

XYZ coordinate.
ZStackLoop –

A loop over Z positions in an experiment.
ZStackLoopParams –

Parameters associated with a Z stack loop.

Attributes:

ExpLoop –

Union of loop types in an experiment.
LoopParams –

Type of parameters associated with a loop in an experiment.
ModalityFlags –

Flags indicating the modality of a microscope.

ExpLoop `module-attribute` ¶

ExpLoop = Union[
    TimeLoop, NETimeLoop, XYPosLoop, ZStackLoop, CustomLoop
]

Union of loop types in an experiment.

ND2File.experiment returns a list of these.

LoopParams `module-attribute` ¶

LoopParams = Union[
    TimeLoopParams,
    NETimeLoopParams,
    XYPosLoopParams,
    ZStackLoopParams,
]

Type of parameters associated with a loop in an experiment.

ModalityFlags `module-attribute` ¶

ModalityFlags = Literal[
    "aux",
    "brightfield",
    "camera",
    "diContrast",
    "dsdConfocal",
    "fluorescence",
    "gaasp",
    "iSIM",
    "laserScanConfocal",
    "liveSR",
    "multiphoton",
    "nonDescannedDetector",
    "phaseContrast",
    "pmt",
    "RCM",
    "remainder",
    "SIM",
    "sora",
    "spectral",
    "spinningDiskConfocal",
    "sweptFieldConfocalPinhole",
    "sweptFieldConfocalSlit",
    "TIRF",
    "transmitDetector",
    "vaasIF",
    "vaasNF",
    "VCS",
    "virtualFilter",
]

Flags indicating the modality of a microscope.

AnimParam `dataclass` ¶

AnimParam(
    timeMs: float = 0,
    enabled: bool = True,
    centerX: float = 0,
    centerY: float = 0,
    centerZ: float = 0,
    rotationZ: float = 0,
    boxShape: BoxShape = BoxShape(),
    extrudedShape: ExtrudedShape = ExtrudedShape(),
)

Parameters of ROI position/shape.

Attributes:

center (XYZPoint) –

Center point as a named tuple (x, y, z).

center `property` ¶

center: XYZPoint

Center point as a named tuple (x, y, z).

Attributes ¶

Primary attributes of an ND2 file.

This is the return value of ND2File.attributes.

BoxShape ¶

Size of a 3D box.

Channel `dataclass` ¶

Channel(
    channel: ChannelMeta,
    loops: LoopIndices | None,
    microscope: Microscope,
    volume: Volume,
)

Structure of a channel in an ND2 file.

ChannelMeta `dataclass` ¶

ChannelMeta(
    name: str,
    index: int,
    color: Color,
    emissionLambdaNm: float | None = None,
    excitationLambdaNm: float | None = None,
)

Metadata for a channel in an ND2 file.

Attributes:

colorRGBA (int) –

Return color as unsigned 4-byte (32-bit) integer in ABGR format.

colorRGBA `property` ¶

colorRGBA: int

Return color as unsigned 4-byte (32-bit) integer in ABGR format.

Color ¶

RGB color with optional alpha channel.

Methods:

as_abgr_u4 –

Return color as an unsigned 4-byte (32-bit) integer in ABGR format.
as_hex –

Return color as a hex string.
from_abgr_u4 –

Create a color from an unsigned 4-byte (32-bit) integer in ABGR format.

as_abgr_u4 ¶

as_abgr_u4() -> int

Return color as an unsigned 4-byte (32-bit) integer in ABGR format.

This is the native format of NIS Elements.

Source code in src/nd2/structures.py

def as_abgr_u4(self) -> int:
    """Return color as an unsigned 4-byte (32-bit) integer in ABGR format.

    This is the native format of NIS Elements.
    """
    # for the sake of round-tripping, we'll assume that 1.0 alpha is 0
    alpha = 0 if self.a == 1.0 else int(self.a * 255)
    return (alpha << 24) + (self.b << 16) + (self.g << 8) + self.r

as_hex ¶

as_hex() -> str

Return color as a hex string.

Source code in src/nd2/structures.py

def as_hex(self) -> str:  # pragma: no cover
    """Return color as a hex string."""
    return f"#{self.r:02x}{self.g:02x}{self.b:02x}"

from_abgr_u4 `classmethod` ¶

from_abgr_u4(val: int) -> Color

Create a color from an unsigned 4-byte (32-bit) integer in ABGR format.

Source code in src/nd2/structures.py

@classmethod
def from_abgr_u4(cls, val: int) -> Color:
    """Create a color from an unsigned 4-byte (32-bit) integer in ABGR format."""
    return cls(
        r=val & 255,
        g=val >> 8 & 255,
        b=val >> 16 & 255,
        # it's not clear if the alpha channel is used in NIS Elements
        # so we default to 1.0 if it comes in as 0
        a=((val >> 24 & 255) / 255) or 1.0,
    )

Contents `dataclass` ¶

Contents(channelCount: int, frameCount: int)

Contents of an ND2 file metadata.

CustomLoop `dataclass` ¶

CustomLoop(
    count: int,
    nestingLevel: int = 0,
    parameters: None = None,
    type: Literal["CustomLoop"] = "CustomLoop",
)

Custom loop in an experiment.

ExperimentEvent `dataclass` ¶

ExperimentEvent(
    id: int = 0,
    time: float = 0.0,
    time2: float = 0.0,
    meaning: EventMeaning = Unspecified,
    description: str = "",
    data: str = "",
    stimulation: StimulationEvent | None = None,
)

An event in an experiment.

ExtrudedShape ¶

Shape of an extruded object.

FrameChannel `dataclass` ¶

FrameChannel(
    channel: ChannelMeta,
    loops: LoopIndices | None,
    microscope: Microscope,
    volume: Volume,
    position: Position,
    time: TimeStamp,
)

Channel metadata for a frame.

FrameMetadata `dataclass` ¶

FrameMetadata(
    contents: Contents, channels: list[FrameChannel]
)

Metadata of a frame in an ND2 file.

This is the return value of ND2File.frame_metadata.

InterpType ¶

The role that the ROI plays.

LoopIndices `dataclass` ¶

LoopIndices(
    NETimeLoop: int | None = None,
    TimeLoop: int | None = None,
    XYPosLoop: int | None = None,
    ZStackLoop: int | None = None,
    CustomLoop: int | None = None,
)

Indices of loops in an channel.

LoopType ¶

Type of loop in an experiment.

Metadata `dataclass` ¶

Metadata(
    contents: Contents | None = None,
    channels: list[Channel] | None = None,
)

Metadata of an ND2 file.

This is the return value of ND2File.metadata.

Microscope `dataclass` ¶

Microscope(
    objectiveMagnification: float | None = None,
    objectiveName: str | None = None,
    objectiveNumericalAperture: float | None = None,
    zoomMagnification: float | None = None,
    immersionRefractiveIndex: float | None = None,
    projectiveMagnification: float | None = None,
    pinholeDiameterUm: float | None = None,
    modalityFlags: list[ModalityFlags] = list(),
)

Microscope metadata.

NETimeLoop `dataclass` ¶

NETimeLoop(
    count: int,
    nestingLevel: int,
    parameters: NETimeLoopParams,
    type: Literal["NETimeLoop"] = "NETimeLoop",
)

The time dimension of an nD experiment.

NETimeLoopParams `dataclass` ¶

NETimeLoopParams(periods: list[Period])

Parameters associated with a time loop in an nD experiment.

Period `dataclass` ¶

Period(
    startMs: float,
    periodMs: float,
    durationMs: float,
    periodDiff: PeriodDiff,
    count: int,
)

A phase in an nD experiment.

PeriodDiff `dataclass` ¶

PeriodDiff(avg: float = 0, max: float = 0, min: float = 0)

Time difference between periods in a time loop.

Position `dataclass` ¶

Position(
    stagePositionUm: StagePosition,
    pfsOffset: float | None = None,
    name: str | None = None,
)

A position in an XY position loop.

ROI `dataclass` ¶

ROI(
    id: int,
    info: RoiInfo,
    guid: str,
    animParams: list[AnimParam] = list(),
)

ROI object from NIS Elements.

RoiInfo `dataclass` ¶

RoiInfo(
    shapeType: RoiShapeType,
    interpType: InterpType,
    cookie: int = 0,
    color: int = 255,
    label: str = "",
    stimulationGroup: int = 0,
    scope: ScopeType = Global,
    appData: int = 0,
    multiFrame: bool = False,
    locked: bool = False,
    compCount: int = 2,
    bpc: int = 16,
    autodetected: bool = False,
    gradientStimulation: bool = False,
    gradientStimulationBitDepth: int = 0,
    gradientStimulationLo: float = 0.0,
    gradientStimulationHi: float = 0.0,
)

Info associated with an ROI.

RoiShapeType ¶

The type of ROI shape.

ScopeType ¶

Scope of an ROI.

StagePosition ¶

A position in stage coordinates.

StimulationEvent `dataclass` ¶

StimulationEvent(
    type: StimulationType = NoStimulation,
    loop_index: int = 0,
    position: int = 0,
    description: str = "",
)

Stimulation parameters for an experiment event.

TextInfo ¶

Structure of dict returned by ND2File.text_info.

TimeLoop `dataclass` ¶

TimeLoop(
    count: int,
    nestingLevel: int,
    parameters: TimeLoopParams,
    type: Literal["TimeLoop"] = "TimeLoop",
)

The time dimension of an experiment.

TimeLoopParams `dataclass` ¶

TimeLoopParams(
    startMs: float,
    periodMs: float,
    durationMs: float,
    periodDiff: PeriodDiff,
)

Parameters associated with a time loop.

TimeStamp `dataclass` ¶

TimeStamp(
    absoluteJulianDayNumber: float, relativeTimeMs: float
)

Absolute and relative timestamp of a frame.

Volume `dataclass` ¶

Volume(
    axesCalibrated: tuple[bool, bool, bool],
    axesCalibration: tuple[float, float, float],
    axesInterpretation: tuple[
        AxisInterpretation,
        AxisInterpretation,
        AxisInterpretation,
    ],
    bitsPerComponentInMemory: int,
    bitsPerComponentSignificant: int,
    cameraTransformationMatrix: tuple[
        float, float, float, float
    ],
    componentCount: int,
    componentDataType: Literal["unsigned", "float"],
    voxelCount: tuple[int, int, int],
    componentMaxima: list[float] | None = None,
    componentMinima: list[float] | None = None,
    pixelToStageTransformationMatrix: tuple[
        float, float, float, float, float, float
    ]
    | None = None,
)

Volume metadata.

XYPoint ¶

XY coordinate.

XYPosLoop `dataclass` ¶

XYPosLoop(
    count: int,
    nestingLevel: int,
    parameters: XYPosLoopParams,
    type: Literal["XYPosLoop"] = "XYPosLoop",
)

A loop over XY positions in an experiment.

XYPosLoopParams `dataclass` ¶

XYPosLoopParams(isSettingZ: bool, points: list[Position])

Parameters associated with a XY position loop.

XYZPoint ¶

XYZ coordinate.

ZStackLoop `dataclass` ¶

ZStackLoop(
    count: int,
    nestingLevel: int,
    parameters: ZStackLoopParams,
    type: Literal["ZStackLoop"] = "ZStackLoop",
)

A loop over Z positions in an experiment.

ZStackLoopParams `dataclass` ¶

ZStackLoopParams(
    homeIndex: int,
    stepUm: float,
    bottomToTop: bool,
    deviceName: str | None = None,
)

Parameters associated with a Z stack loop.

nd2.structures ¶

ExpLoop module-attribute ¶

LoopParams module-attribute ¶

ModalityFlags module-attribute ¶

AnimParam dataclass ¶

center property ¶

Attributes ¶

BoxShape ¶

Channel dataclass ¶

ChannelMeta dataclass ¶

colorRGBA property ¶

Color ¶

as_abgr_u4 ¶

as_hex ¶

from_abgr_u4 classmethod ¶

Contents dataclass ¶

CustomLoop dataclass ¶

ExperimentEvent dataclass ¶

ExtrudedShape ¶

FrameChannel dataclass ¶

FrameMetadata dataclass ¶

InterpType ¶

LoopIndices dataclass ¶

LoopType ¶

Metadata dataclass ¶

Microscope dataclass ¶

NETimeLoop dataclass ¶

NETimeLoopParams dataclass ¶

Period dataclass ¶

PeriodDiff dataclass ¶

Position dataclass ¶

ROI dataclass ¶

RoiInfo dataclass ¶

RoiShapeType ¶

ScopeType ¶

StagePosition ¶

StimulationEvent dataclass ¶

TextInfo ¶

TimeLoop dataclass ¶

TimeLoopParams dataclass ¶

TimeStamp dataclass ¶

Volume dataclass ¶

XYPoint ¶

XYPosLoop dataclass ¶

XYPosLoopParams dataclass ¶

XYZPoint ¶

ZStackLoop dataclass ¶

ZStackLoopParams dataclass ¶

ExpLoop `module-attribute` ¶

LoopParams `module-attribute` ¶

ModalityFlags `module-attribute` ¶

AnimParam `dataclass` ¶

center `property` ¶

Channel `dataclass` ¶

ChannelMeta `dataclass` ¶

colorRGBA `property` ¶

from_abgr_u4 `classmethod` ¶

Contents `dataclass` ¶

CustomLoop `dataclass` ¶

ExperimentEvent `dataclass` ¶

FrameChannel `dataclass` ¶

FrameMetadata `dataclass` ¶

LoopIndices `dataclass` ¶

Metadata `dataclass` ¶

Microscope `dataclass` ¶

NETimeLoop `dataclass` ¶

NETimeLoopParams `dataclass` ¶

Period `dataclass` ¶

PeriodDiff `dataclass` ¶

Position `dataclass` ¶

ROI `dataclass` ¶

RoiInfo `dataclass` ¶

StimulationEvent `dataclass` ¶

TimeLoop `dataclass` ¶

TimeLoopParams `dataclass` ¶

TimeStamp `dataclass` ¶

Volume `dataclass` ¶

XYPosLoop `dataclass` ¶

XYPosLoopParams `dataclass` ¶

ZStackLoop `dataclass` ¶

ZStackLoopParams `dataclass` ¶