nd2: A Python library for reading and writing ND2 files.
+ + + +ND2File
+
+
+¶Main objecting for opening and extracting data from an nd2 file.
+with nd2.ND2File("path/to/file.nd2") as nd2_file:
+ ...
+The key metadata outputs are:
+ +Some files may also have:
+Tip
+For a simple way to read nd2 file data into an array, see nd2.imread.
+Parameters:
+path
+ (Path | str)
+ –
+ Filename of an nd2 file.
+validate_frames
+ (bool, default:
+ False
+)
+ –
+ Whether to verify (and attempt to fix) frames whose positions have been +shifted relative to the predicted offset (i.e. in a corrupted file). +This comes at a slight performance penalty at file open, but may "rescue" +some corrupt files. by default False.
+search_window
+ (int, default:
+ 100
+)
+ –
+ When validate_frames is true, this is the search window (in KB) that will +be used to try to find the actual chunk position. by default 100 KB
+attributes: Attributes
+
+
+ cached
+ property
+
+
+¶Core image attributes.
+Example Output
+Attributes(
+ bitsPerComponentInMemory=16,
+ bitsPerComponentSignificant=16,
+ componentCount=2,
+ heightPx=32,
+ pixelDataType="unsigned",
+ sequenceCount=60,
+ widthBytes=128,
+ widthPx=32,
+ compressionLevel=None,
+ compressionType=None,
+ tileHeightPx=None,
+ tileWidthPx=None,
+ channelCount=2,
+)
+Returns:
+attrs ( Attributes
+) –
+ Core image attributes
+binary_data: BinaryLayers | None
+
+
+ cached
+ property
+
+
+¶Return binary layers embedded in the file.
+The returned BinaryLayers object is an immutable sequence of BinaryLayer
+objects, one for each binary layer in the file (there will usually be a binary
+layer associated with each channel in the dataset).
Each BinaryLayer object in the sequence has a name attribute, and a data
+attribute which is list of numpy arrays (or None if there was no binary mask
+for that frame). The length of the list will be the same as the number of
+sequence frames in this file (i.e. self.attributes.sequenceCount).
+BinaryLayers can be indexed directly with an integer corresponding to the
+frame index.
Both the BinaryLayers and individual BinaryLayer objects can be cast to a
+numpy array with np.asarray(), or by using the .asarray() method
Returns:
+BinaryLayers | None
+ –
+ The binary layers embedded in the file, or None if there are no binary +layers.
+Examples:
+>>> f = ND2File("path/to/file.nd2")
+>>> f.binary_data
+<BinaryLayers with 4 layers>
+>>> first_layer = f.binary_data[0] # the first binary layer
+>>> first_layer
+BinaryLayer(name='attached Widefield green (green color)',
+comp_name='Widefield Green', comp_order=2, color=65280, color_mode=0,
+state=524288, file_tag='RleZipBinarySequence_1_v1', layer_id=2)
+>>> first_layer.data # list of arrays
+# you can also index in to the BinaryLayers object itself
+>>> first_layer[0] # get binary data for first frame (or None if missing)
+>>> np.asarray(first_layer) # cast to array matching shape of full sequence
+>>> np.asarray(f.binary_data).shape # cast all layers to array
+(4, 3, 4, 5, 32, 32)
+closed: bool
+
+
+ property
+
+
+¶Return True if the file is closed.
components_per_channel: int
+
+
+ property
+
+
+¶Number of components per channel (e.g. 3 for rgb).
+custom_data: dict[str, Any]
+
+
+ cached
+ property
+
+
+¶Dict of various unstructured custom metadata.
+dtype: np.dtype
+
+
+ cached
+ property
+
+
+¶Image data type.
+experiment: list[ExpLoop]
+
+
+ cached
+ property
+
+
+¶Loop information for each axis of an nD acquisition.
+[
+ TimeLoop(
+ count=3,
+ nestingLevel=0,
+ parameters=TimeLoopParams(
+ startMs=0.0,
+ periodMs=1.0,
+ durationMs=0.0,
+ periodDiff=PeriodDiff(
+ avg=3674.199951171875,
+ max=3701.219970703125,
+ min=3647.179931640625,
+ ),
+ ),
+ type="TimeLoop",
+ ),
+ ZStackLoop(
+ count=5,
+ nestingLevel=1,
+ parameters=ZStackLoopParams(
+ homeIndex=2,
+ stepUm=1.0,
+ bottomToTop=True,
+ deviceName="Ti2 ZDrive",
+ ),
+ type="ZStackLoop",
+ ),
+]
+Returns:
+ +is_legacy: bool
+
+
+ property
+
+
+¶Whether file is a legacy nd2 (JPEG2000) file.
+is_rgb: bool
+
+
+ property
+
+
+¶Whether the image is rgb (i.e. it has 3 or 4 components per channel).
+loop_indices: tuple[dict[str, int], ...]
+
+
+ cached
+ property
+
+
+¶Return a tuple of dicts of loop indices for each frame.
+ + +Examples:
+>>> with nd2.ND2File("path/to/file.nd2") as f:
+... f.loop_indices
+(
+ {'Z': 0, 'T': 0, 'C': 0},
+ {'Z': 0, 'T': 0, 'C': 1},
+ {'Z': 0, 'T': 0, 'C': 2},
+ ...
+)
+metadata: Metadata
+
+
+ cached
+ property
+
+
+¶Various metadata (will be dict only if legacy format).
Metadata(
+ contents=Contents(channelCount=2, frameCount=15),
+ channels=[
+ Channel(
+ channel=ChannelMeta(
+ name="Widefield Green",
+ index=0,
+ color=Color(r=91, g=255, b=0, a=1.0),
+ emissionLambdaNm=535.0,
+ excitationLambdaNm=None,
+ ),
+ loops=LoopIndices(
+ NETimeLoop=None, TimeLoop=0, XYPosLoop=None, ZStackLoop=1
+ ),
+ microscope=Microscope(
+ objectiveMagnification=10.0,
+ objectiveName="Plan Fluor 10x Ph1 DLL",
+ objectiveNumericalAperture=0.3,
+ zoomMagnification=1.0,
+ immersionRefractiveIndex=1.0,
+ projectiveMagnification=None,
+ pinholeDiameterUm=None,
+ modalityFlags=["fluorescence"],
+ ),
+ volume=Volume(
+ axesCalibrated=[True, True, True],
+ axesCalibration=[0.652452890023035, 0.652452890023035, 1.0],
+ axesInterpretation=["distance", "distance", "distance"],
+ bitsPerComponentInMemory=16,
+ bitsPerComponentSignificant=16,
+ cameraTransformationMatrix=[
+ -0.9998932296054086,
+ -0.014612644841559427,
+ 0.014612644841559427,
+ -0.9998932296054086,
+ ],
+ componentCount=1,
+ componentDataType="unsigned",
+ voxelCount=[32, 32, 5],
+ componentMaxima=[0.0],
+ componentMinima=[0.0],
+ pixelToStageTransformationMatrix=None,
+ ),
+ ),
+ Channel(
+ channel=ChannelMeta(
+ name="Widefield Red",
+ index=1,
+ color=Color(r=255, g=85, b=0, a=1.0),
+ emissionLambdaNm=620.0,
+ excitationLambdaNm=None,
+ ),
+ loops=LoopIndices(
+ NETimeLoop=None, TimeLoop=0, XYPosLoop=None, ZStackLoop=1
+ ),
+ microscope=Microscope(
+ objectiveMagnification=10.0,
+ objectiveName="Plan Fluor 10x Ph1 DLL",
+ objectiveNumericalAperture=0.3,
+ zoomMagnification=1.0,
+ immersionRefractiveIndex=1.0,
+ projectiveMagnification=None,
+ pinholeDiameterUm=None,
+ modalityFlags=["fluorescence"],
+ ),
+ volume=Volume(
+ axesCalibrated=[True, True, True],
+ axesCalibration=[0.652452890023035, 0.652452890023035, 1.0],
+ axesInterpretation=["distance", "distance", "distance"],
+ bitsPerComponentInMemory=16,
+ bitsPerComponentSignificant=16,
+ cameraTransformationMatrix=[
+ -0.9998932296054086,
+ -0.014612644841559427,
+ 0.014612644841559427,
+ -0.9998932296054086,
+ ],
+ componentCount=1,
+ componentDataType="unsigned",
+ voxelCount=[32, 32, 5],
+ componentMaxima=[0.0],
+ componentMinima=[0.0],
+ pixelToStageTransformationMatrix=None,
+ ),
+ ),
+ ],
+)
+Returns:
+ +nbytes: int
+
+
+ property
+
+
+¶Total bytes of image data.
+ndim: int
+
+
+ cached
+ property
+
+
+¶Number of dimensions (i.e. len(self.shape)).
path: str
+
+
+ property
+
+
+¶Path of the image.
+rois: dict[int, ROI]
+
+
+ cached
+ property
+
+
+¶shape: tuple[int, ...]
+
+
+ cached
+ property
+
+
+¶Size of each axis.
+ + +Examples:
+>>> ndfile.shape
+(3, 5, 2, 512, 512)
+size: int
+
+
+ property
+
+
+¶Total number of voxels in the volume (the product of the shape).
+sizes: Mapping[str, int]
+
+
+ cached
+ property
+
+
+¶Names and sizes for each axis.
+This is an ordered dict, with the same order +as the corresponding shape
+ + +Examples:
+>>> ndfile.sizes
+{'T': 3, 'Z': 5, 'C': 2, 'Y': 512, 'X': 512}
+>>> ndfile.shape
+(3, 5, 2, 512, 512)
+text_info: TextInfo
+
+
+ cached
+ property
+
+
+¶Miscellaneous text info.
+{
+ 'description': 'Metadata:\r\nDimensions: T(3) x XY(4) x λ(2) x Z(5)...'
+ 'capturing': 'Flash4.0, SN:101412\r\nSample 1:\r\n Exposure: 100 ms...'
+ 'date': '9/28/2021 9:41:27 AM',
+ 'optics': 'Plan Fluor 10x Ph1 DLL'
+}
+Returns:
+ +version: tuple[int, ...]
+
+
+ cached
+ property
+
+
+¶Return the file format version as a tuple of ints.
+Likely values are:
+(1, 0) = a legacy nd2 file (JPEG2000)(2, 0), (2, 1) = non-JPEG2000 nd2 with xml metadata(3, 0) = new format nd2 file with lite variant metadata(-1, -1) =Returns:
+ + + +Raises:
+ValueError
+ –
+ If the file is not a valid nd2 file.
+asarray(position: int | None = None) -> np.ndarray
+
+¶Read image into a numpy.ndarray.
+For a simple way to read a file into a numpy array, see nd2.imread.
+ + +Parameters:
+position
+ (int, default:
+ None
+)
+ –
+ A specific XY position to extract, by default (None) reads all.
+Returns:
+array ( ndarray
+) –
+ Raises:
+ValueError
+ –
+ if position is a string and is not a valid position name
IndexError
+ –
+ if position is provided and is out of range
close() -> None
+
+¶Close file.
+Note
+Files are best opened using a context manager:
+with nd2.ND2File("path/to/file.nd2") as nd2_file:
+ ...
+This will automatically close the file when the context exits.
+events(*, orient: Literal['records', 'list', 'dict'] = 'records', null_value: Any = float('nan')) -> ListOfDicts | DictOfLists | DictOfDicts
+
+¶Return tabular data recorded for each frame and/or event of the experiment.
+This method returns tabular data in the format specified by the orient
+argument:
+ - 'records' : list of dict - [{column -> value}, ...] (default)
+ - 'dict' : dict of dict - {column -> {index -> value}, ...}
+ - 'list' : dict of list - {column -> [value, ...]}
All return types are passable to pd.DataFrame(). It matches the tabular data +reported in the Image Properties > Recorded Data tab of the NIS Viewer.
+There will be a column for each tag in the CustomDataV2_0 section of
+ND2File.custom_data, as well columns for any events recorded in the
+data. Not all cells will be populated, and empty cells will be filled
+with null_value (default float('nan')).
Legacy ND2 files are not supported.
+ + +Parameters:
+orient
+ (('records', 'dict', 'list'), default:
+ 'records'
+)
+ –
+ The format of the returned data. See pandas.DataFrame
+ - 'records' : list of dict -[{column -> value}, ...](default)
+ - 'dict' : dict of dict -{column -> {index -> value}, ...}- 'list' : dict of list -{column -> [value, ...]}`
null_value
+ (Any, default:
+ float('nan')
+)
+ –
+ The value to use for missing data.
+Returns:
+ListOfDicts | DictOfLists | DictOfDicts
+ –
+ Tabular data in the format specified by orient.
frame_metadata(seq_index: int | tuple) -> FrameMetadata | dict
+
+¶Metadata for specific frame.
+
See also: metadata
This includes the global metadata from the metadata function. +(will be dict if legacy format).
+FrameMetadata(
+ contents=Contents(channelCount=2, frameCount=15),
+ channels=[
+ FrameChannel(
+ channel=ChannelMeta(
+ name="Widefield Green",
+ index=0,
+ color=Color(r=91, g=255, b=0, a=1.0),
+ emissionLambdaNm=535.0,
+ excitationLambdaNm=None,
+ ),
+ loops=LoopIndices(
+ NETimeLoop=None, TimeLoop=0, XYPosLoop=None, ZStackLoop=1
+ ),
+ microscope=Microscope(
+ objectiveMagnification=10.0,
+ objectiveName="Plan Fluor 10x Ph1 DLL",
+ objectiveNumericalAperture=0.3,
+ zoomMagnification=1.0,
+ immersionRefractiveIndex=1.0,
+ projectiveMagnification=None,
+ pinholeDiameterUm=None,
+ modalityFlags=["fluorescence"],
+ ),
+ volume=Volume(
+ axesCalibrated=[True, True, True],
+ axesCalibration=[0.652452890023035, 0.652452890023035, 1.0],
+ axesInterpretation=["distance", "distance", "distance"],
+ bitsPerComponentInMemory=16,
+ bitsPerComponentSignificant=16,
+ cameraTransformationMatrix=[
+ -0.9998932296054086,
+ -0.014612644841559427,
+ 0.014612644841559427,
+ -0.9998932296054086,
+ ],
+ componentCount=1,
+ componentDataType="unsigned",
+ voxelCount=[32, 32, 5],
+ componentMaxima=[0.0],
+ componentMinima=[0.0],
+ pixelToStageTransformationMatrix=None,
+ ),
+ position=Position(
+ stagePositionUm=StagePosition(
+ x=26950.2, y=-1801.6000000000001, z=494.3
+ ),
+ pfsOffset=None,
+ name=None,
+ ),
+ time=TimeStamp(
+ absoluteJulianDayNumber=2459486.0682717753,
+ relativeTimeMs=580.3582921028137,
+ ),
+ ),
+ FrameChannel(
+ channel=ChannelMeta(
+ name="Widefield Red",
+ index=1,
+ color=Color(r=255, g=85, b=0, a=1.0),
+ emissionLambdaNm=620.0,
+ excitationLambdaNm=None,
+ ),
+ loops=LoopIndices(
+ NETimeLoop=None, TimeLoop=0, XYPosLoop=None, ZStackLoop=1
+ ),
+ microscope=Microscope(
+ objectiveMagnification=10.0,
+ objectiveName="Plan Fluor 10x Ph1 DLL",
+ objectiveNumericalAperture=0.3,
+ zoomMagnification=1.0,
+ immersionRefractiveIndex=1.0,
+ projectiveMagnification=None,
+ pinholeDiameterUm=None,
+ modalityFlags=["fluorescence"],
+ ),
+ volume=Volume(
+ axesCalibrated=[True, True, True],
+ axesCalibration=[0.652452890023035, 0.652452890023035, 1.0],
+ axesInterpretation=["distance", "distance", "distance"],
+ bitsPerComponentInMemory=16,
+ bitsPerComponentSignificant=16,
+ cameraTransformationMatrix=[
+ -0.9998932296054086,
+ -0.014612644841559427,
+ 0.014612644841559427,
+ -0.9998932296054086,
+ ],
+ componentCount=1,
+ componentDataType="unsigned",
+ voxelCount=[32, 32, 5],
+ componentMaxima=[0.0],
+ componentMinima=[0.0],
+ pixelToStageTransformationMatrix=None,
+ ),
+ position=Position(
+ stagePositionUm=StagePosition(
+ x=26950.2, y=-1801.6000000000001, z=494.3
+ ),
+ pfsOffset=None,
+ name=None,
+ ),
+ time=TimeStamp(
+ absoluteJulianDayNumber=2459486.0682717753,
+ relativeTimeMs=580.3582921028137,
+ ),
+ ),
+ ],
+)
+Parameters:
+ + + +Returns:
+FrameMetadata | dict
+ –
+ dict if legacy format, else FrameMetadata
+is_supported_file(path: StrOrPath) -> bool
+
+
+ staticmethod
+
+
+¶Return True if the file is supported by this reader.
ome_metadata(*, include_unstructured: bool = True, tiff_file_name: str | None = None) -> OME
+
+¶Return ome_types.OME metadata object for this file.
See the ome_types.OME documentation for details on this object.
Parameters:
+include_unstructured
+ (bool, default:
+ True
+)
+ –
+ Whether to include all available metadata in the OME file. If True,
+(the default), the unstructured_metadata method is used to fetch
+all retrievable metadata, and the output is added to
+OME.structured_annotations, where each key is the chunk key, and the
+value is a JSON-serialized dict of the metadata. If False, only metadata
+which can be directly added to the OME data model are included.
tiff_file_name
+ (str | None, default:
+ None
+)
+ –
+ If provided, ome_types.model.TiffData block entries are added for
+each ome_types.model.Plane in the OME object, with the
+TiffData.uuid.file_name set to this value. (Useful for exporting to
+tiff.)
Examples:
+import nd2
+
+with nd2.ND2File("path/to/file.nd2") as f:
+ ome = f.ome_metadata()
+ xml = ome.to_xml()
+open() -> None
+
+¶Open file for reading.
+Note
+Files are best opened using a context manager:
+with nd2.ND2File("path/to/file.nd2") as nd2_file:
+ ...
+This will automatically close the file when the context exits.
+read_frame(frame_index: SupportsInt) -> np.ndarray
+
+¶Read a single frame from the file, indexed by frame number.
+ +to_dask(wrapper: bool = True, copy: bool = True) -> dask.array.core.Array
+
+¶Create dask array (delayed reader) representing image.
+This generally works well, but it remains to be seen whether performance
+is optimized, or if we're duplicating safety mechanisms. You may try
+various combinations of wrapper and copy, setting both to False
+will very likely cause segmentation faults in many cases. But setting
+one of them to False, may slightly improve read speed in certain
+cases.
Parameters:
+wrapper
+ (bool, default:
+ True
+)
+ –
+ If True (the default), the returned object will be a thin subclass of a
+dask.array.Array (a ResourceBackedDaskArray) that manages the
+opening and closing of this file when getting chunks via compute(). If
+wrapper is False, then a pure dask.array.core.Array will be returned.
+However, when that array is computed, it will incur a file open/close on
+every chunk that is read (in the _dask_block method). As such wrapper
+will generally be much faster, however, it may fail (i.e. result in
+segmentation faults) with certain dask schedulers.
copy
+ (bool, default:
+ True
+)
+ –
+ If True (the default), the dask chunk-reading function will return
+an array copy. This can avoid segfaults in certain cases, though it
+may also add overhead.
Returns:
+dask_array ( Array
+) –
+ A dask array representing the image data.
+to_xarray(delayed: bool = True, squeeze: bool = True, position: int | None = None, copy: bool = True) -> xr.DataArray
+
+¶Return a labeled xarray.DataArray representing image.
+Xarrays are a powerful way to label and manipulate n-dimensional data with +axis-associated coordinates.
+array.dims will be populated according to image metadata, and coordinates
+will be populated based on pixel spacings. Additional metadata is available
+in array.attrs['metadata'].
Parameters:
+delayed
+ (bool, default:
+ True
+)
+ –
+ Whether the DataArray should be backed by dask array or numpy array, +by default True (dask).
+squeeze
+ (bool, default:
+ True
+)
+ –
+ Whether to squeeze singleton dimensions, by default True
+position
+ (int, default:
+ None
+)
+ –
+ A specific XY position to extract, by default (None) reads all.
+copy
+ (bool, default:
+ True
+)
+ –
+ Only applies when delayed==True. See to_dask for details.
Returns:
+DataArray
+ –
+ xarray with all axes labeled.
+unstructured_metadata(*, strip_prefix: bool = True, include: set[str] | None = None, exclude: set[str] | None = None) -> dict[str, Any]
+
+¶Exposes, and attempts to decode, each metadata chunk in the file.
+This is provided as a experimental fallback in the event that
+ND2File.experiment does not contain all of the information you need. No
+attempt is made to parse or validate the metadata, and the format of various
+sections, may change in future versions of nd2. Consumption of this metadata
+should use appropriate exception handling!
The 'ImageMetadataLV' chunk is the most likely to contain useful information, +but if you're generally looking for "hidden" metadata, it may be helpful to +look at the full output.
+ + +Parameters:
+strip_prefix
+ (bool, default:
+ True
+)
+ –
+ Whether to strip the type information from the front of the keys in the
+dict. For example, if True: uiModeFQ becomes ModeFQ and bUsePFS
+becomes UsePFS, etc... by default True
include
+ (set[str] | None, default:
+ None
+)
+ –
+ If provided, only include the specified keys in the output. by default, +all metadata sections found in the file are included.
+exclude
+ (set[str] | None, default:
+ None
+)
+ –
+ If provided, exclude the specified keys from the output. by default None
Returns:
+ + +voxel_size(channel: int = 0) -> _util.VoxelSize
+
+¶XYZ voxel size in microns.
+ + +Parameters:
+channel
+ (int, default:
+ 0
+)
+ –
+ Channel for which to retrieve voxel info, by default 0. +(Not yet implemented.)
+Returns:
+VoxelSize
+ –
+ Named tuple with attrs x, y, and z.
write_tiff(dest: str | PathLike, *, include_unstructured_metadata: bool = True, progress: bool = False, on_frame: Callable[[int, int, dict[str, int]], None] | None | None = None, modify_ome: Callable[[ome_types.OME], None] | None = None) -> None
+
+¶Export to an (OME)-TIFF file.
+To include OME-XML metadata, use extension .ome.tif or .ome.tiff.
Parameters:
+dest
+ (str | PathLike)
+ –
+ The destination TIFF file.
+include_unstructured_metadata
+ ( bool, default:
+ True
+)
+ –
+ Whether to include unstructured metadata in the OME-XML.
+This includes all of the metadata that we can find in the ND2 file in the
+StructuredAnnotations section of the OME-XML (as mapping of
+metadata chunk name to JSON-encoded string). By default True.
progress
+ (bool, default:
+ False
+)
+ –
+ Whether to display progress bar. If True and tqdm is installed, it will
+be used. Otherwise, a simple text counter will be printed to the console.
+By default False.
on_frame
+ (Callable[[int, int, dict[str, int]], None] | None, default:
+ None
+)
+ –
+ A function to call after each frame is written. The function should accept
+three arguments: the current frame number, the total number of frames, and
+a dictionary of the current frame's indices (e.g. {"T": 0, "Z": 1})
+(Useful for integrating custom progress bars or logging.)
modify_ome
+ (Callable[[OME], None], default:
+ None
+)
+ –
+ A function to modify the OME metadata before writing it to the file.
+Accepts an ome_types.OME object and should modify it in place.
+(reminder: OME-XML is only written if the file extension is .ome.tif or
+.ome.tiff)
imread(file: Path | str, *, dask: bool = False, xarray: bool = False, validate_frames: bool = False) -> np.ndarray | xr.DataArray | dask.array.core.Array
+
+¶Open file, return requested array type, and close file.
Parameters:
+file
+ (Path | str)
+ –
+ Filepath (str) or Path object to ND2 file.
dask
+ (bool, default:
+ False
+)
+ –
+ If True, returns a (delayed) dask.array.Array. This will avoid reading
+any data from disk until specifically requested by using .compute() or
+casting to a numpy array with np.asarray(). By default False.
xarray
+ (bool, default:
+ False
+)
+ –
+ If True, returns an xarray.DataArray, array.dims will be populated
+according to image metadata, and coordinates will be populated based on pixel
+spacings. Additional metadata is available in array.attrs['metadata'].
+If dask is also True, will return an xarray backed by a delayed dask array.
+By default False.
validate_frames
+ (bool, default:
+ False
+)
+ –
+ Whether to verify (and attempt to fix) frames whose positions have been +shifted relative to the predicted offset (i.e. in a corrupted file). +This comes at a slight performance penalty at file open, but may "rescue" +some corrupt files. by default False.
+Returns:
+ + +is_legacy(path: StrOrPath) -> bool
+
+¶is_supported_file(path: FileOrBinaryIO, open_: Callable[[StrOrPath], BinaryIO] = _open_binary) -> bool
+
+¶Return True if path can be opened as an nd2 file.
Parameters:
+path
+ (Union[str, bytes, PathLike])
+ –
+ A path to query
+open_
+ (Callable[[StrOrBytesPath, str], BinaryIO], default:
+ _open_binary
+)
+ –
+ Filesystem opener, by default builtins.open
Returns:
+bool
+ –
+ Whether the can be opened.
+nd2_to_tiff(source: str | PathLike | ND2File, dest: str | PathLike, *, include_unstructured_metadata: bool = True, progress: bool = False, on_frame: Callable[[int, int, dict[str, int]], None] | None = None, modify_ome: Callable[[ome_types.OME], None] | None = None) -> None
+
+¶Export an ND2 file to an (OME)-TIFF file.
+To include OME-XML metadata, use extension .ome.tif or .ome.tiff.
https://docs.openmicroscopy.org/ome-model/6.3.1/ome-tiff/specification.html
+ + +Parameters:
+source
+ (str | PathLike | ND2File)
+ –
+ The ND2 file path or an open ND2File object.
+dest
+ (str | PathLike)
+ –
+ The destination TIFF file.
+include_unstructured_metadata
+ ( bool, default:
+ True
+)
+ –
+ Whether to include unstructured metadata in the OME-XML. This includes all of
+the metadata that we can find in the ND2 file in the StructuredAnnotations
+section of the OME-XML (as mapping of metadata chunk name to JSON-encoded
+string). By default True.
progress
+ (bool, default:
+ False
+)
+ –
+ Whether to display progress bar. If True and tqdm is installed, it will
+be used. Otherwise, a simple text counter will be printed to the console.
+By default False.
on_frame
+ (Callable[[int, int, dict[str, int]], None] | None, default:
+ None
+)
+ –
+ A function to call after each frame is written. The function should accept
+three arguments: the current frame number, the total number of frames, and
+a dictionary of the current frame's indices (e.g. {"T": 0, "Z": 1})
+(Useful for integrating custom progress bars or logging.)
modify_ome
+ (Callable[[OME], None], default:
+ None
+)
+ –
+ A function to modify the OME metadata before writing it to the file.
+Accepts an ome_types.OME object and should modify it in place.
+(reminder: OME-XML is only written if the file extension is .ome.tif or
+.ome.tiff)
rescue_nd2(handle: BinaryIO | str, frame_shape: tuple[int, ...] = (), dtype: DTypeLike = 'uint16', max_iters: int | None = None, verbose: bool = True, chunk_start: bytes = _default_chunk_start) -> Iterator[np.ndarray]
+
+¶Iterator that yields all discovered frames in a file handle.
+In nd2 files, each "frame" contains XY and all channel info (both true
+channels as well as RGB components). Frames are laid out as (Y, X, C),
+and the frame_shape should match the expected frame size. If
+frame_shape is not provided, a guess will be made about the vector shape
+of each frame, but it may be incorrect.
Parameters:
+handle
+ (BinaryIO | str)
+ –
+ Filepath string, or binary file handle (For example
+handle = open('some.nd2', 'rb'))
frame_shape
+ (Tuple[int, ...], default:
+ ()
+)
+ –
+ expected shape of each frame, by default a 1 dimensional array will +be yielded for each frame, which can be reshaped later if desired. +NOTE: nd2 frames are generally ordered as +(height, width, true_channels, rgbcomponents). +So unlike numpy, which would use (channels, Y, X), you should use +(Y, X, channels)
+dtype
+ (dtype, default:
+ 'uint16'
+)
+ –
+ Data type, by default np.uint16
+max_iters
+ (Optional[int], default:
+ None
+)
+ –
+ A maximum number of frames to yield, by default will yield until the +end of the file is reached
+verbose
+ (bool, default:
+ True
+)
+ –
+ whether to print info
+chunk_start
+ (bytes, default:
+ _default_chunk_start
+)
+ –
+ The bytes that start each chunk, by default 0x0ABECEDA.to_bytes(4, "little")
+Yields:
+ndarray
+ –
+ each discovered frame in the file
+Examples:
+>>> with open('some_bad.nd2', 'rb') as fh:
+>>> frames = rescue_nd2(fh, (512, 512, 4), 'uint16')
+>>> ary = np.stack(frames)
+You will likely want to reshape ary after that.
nd2: A Python library for reading and writing ND2 files.
+ + + +BinaryLayers
+
+
+¶Sequence of Binary Layers found in an ND2 file.
+This object is a sequence of BinaryLayer objects, one for each binary layer in the
+file. Each layer has a name attribute, and a data attribute that is list of
+numpy arrays - one for each frame in the experiment - or None if the layer was not
+present in that frame.
The wrapper can be cast to a numpy array (with BinaryLayers.asarray() or
+np.asarray(BinaryLayers)) to stack all the layers into a single array. The output
+array will have shape (n_layers, *coord_shape, *frame_shape).
asarray() -> np.ndarray
+
+¶Stack all the layers/frames into a single array.
+The output array will have shape (n_layers, coord_shape, frame_shape).
+ +BinaryLayer
+
+
+
+ dataclass
+
+
+¶Wrapper for data from a single binary layer in an nd2.ND2File.
A "layer" is a set of binary data that can be associated with a +specific component in an ND2 file, such as a single channel.
+This object behaves like a list[numpy.ndarray] | None.
+It will have a length matching the number of frames in the file, with None for
+any frames that lack binary data.
Attributes:
+data
+ (list[ndarray] | None)
+ –
+ The data for each frame. If a frame has no binary data, the value +will be None. Data will have the same length as the number of sequences +in the file.
+name
+ (str)
+ –
+ The name of the binary layer.
+comp_name
+ (str)
+ –
+ The name of the associated component, if Any.
+comp_order
+ (int)
+ –
+ The order of the associated component, if Any.
+color
+ (int)
+ –
+ The color of the binary layer.
+color_mode
+ (int)
+ –
+ The color mode of the binary layer. I believe this is related to how colors +are chosen in NIS-Elements software. Where "0" is direct color (i.e. use, +the color value), "8" is color by 3D ... and I'm not sure about the rest :)
+state
+ (int)
+ –
+ The state of the binary layer. (meaning still unclear)
+file_tag
+ (str)
+ –
+ The key for the binary layer in the CustomData metadata,
+e.g. RleZipBinarySequence_1_v1
layer_id
+ (int)
+ –
+ The ID of the binary layer.
+coordinate_shape
+ (tuple[int, ...])
+ –
+ The shape of the coordinates for the associated nd2 file. This is used
+to reshape the data into a 3D array in asarray.
ExpLoop = Union[TimeLoop, NETimeLoop, XYPosLoop, ZStackLoop, CustomLoop]
+
+
+ module-attribute
+
+
+¶LoopParams = Union[TimeLoopParams, NETimeLoopParams, XYPosLoopParams, ZStackLoopParams]
+
+
+ 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']
+
+
+ module-attribute
+
+
+¶AnimParam
+
+
+
+ dataclass
+
+
+¶Parameters of ROI position/shape.
+ + + + +boxShape: BoxShape = field(default_factory=BoxShape)
+
+
+ class-attribute
+ instance-attribute
+
+
+¶center: XYZPoint
+
+
+ property
+
+
+¶Center point as a named tuple (x, y, z).
+centerX: float = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶centerY: float = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶centerZ: float = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶enabled: bool = True
+
+
+ class-attribute
+ instance-attribute
+
+
+¶extrudedShape: ExtrudedShape = field(default_factory=ExtrudedShape)
+
+
+ class-attribute
+ instance-attribute
+
+
+¶rotationZ: float = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶timeMs: float = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Attributes
+
+
+¶bitsPerComponentInMemory: int
+
+
+ instance-attribute
+
+
+¶bitsPerComponentSignificant: int
+
+
+ instance-attribute
+
+
+¶channelCount: int | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶componentCount: int
+
+
+ instance-attribute
+
+
+¶compressionLevel: float | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶compressionType: Literal['lossless', 'lossy', 'none'] | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶heightPx: int
+
+
+ instance-attribute
+
+
+¶pixelDataType: Literal['float', 'unsigned']
+
+
+ instance-attribute
+
+
+¶sequenceCount: int
+
+
+ instance-attribute
+
+
+¶tileHeightPx: int | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶tileWidthPx: int | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶widthBytes: int | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶widthPx: int | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶BoxShape
+
+
+¶sizeX: float = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶sizeY: float = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶sizeZ: float = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Channel
+
+
+
+ dataclass
+
+
+¶channel: ChannelMeta
+
+
+ instance-attribute
+
+
+¶loops: LoopIndices | None
+
+
+ instance-attribute
+
+
+¶microscope: Microscope
+
+
+ instance-attribute
+
+
+¶volume: Volume
+
+
+ instance-attribute
+
+
+¶ChannelMeta
+
+
+
+ dataclass
+
+
+¶color: Color
+
+
+ instance-attribute
+
+
+¶colorRGBA: int
+
+
+ property
+
+
+¶Return color as unsigned 4-byte (32-bit) integer in ABGR format.
+emissionLambdaNm: float | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶excitationLambdaNm: float | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶index: int
+
+
+ instance-attribute
+
+
+¶name: str
+
+
+ instance-attribute
+
+
+¶Color
+
+
+¶a: float = 1.0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶b: int
+
+
+ instance-attribute
+
+
+¶g: int
+
+
+ instance-attribute
+
+
+¶r: int
+
+
+ instance-attribute
+
+
+¶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.
+ +as_hex() -> str
+
+¶Return color as a hex string.
+ +from_abgr_u4(val: int) -> Color
+
+
+ classmethod
+
+
+¶Create a color from an unsigned 4-byte (32-bit) integer in ABGR format.
+ +Contents
+
+
+
+ dataclass
+
+
+¶Coordinate
+
+
+¶CustomLoop
+
+
+
+ dataclass
+
+
+¶count: int
+
+
+ instance-attribute
+
+
+¶nestingLevel: int = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶parameters: None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶type: Literal['CustomLoop'] = 'CustomLoop'
+
+
+ class-attribute
+ instance-attribute
+
+
+¶ExperimentEvent
+
+
+
+ dataclass
+
+
+¶data: str = ''
+
+
+ class-attribute
+ instance-attribute
+
+
+¶description: str = ''
+
+
+ class-attribute
+ instance-attribute
+
+
+¶id: int = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶meaning: EventMeaning = EventMeaning.Unspecified
+
+
+ class-attribute
+ instance-attribute
+
+
+¶stimulation: StimulationEvent | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶time: float = 0.0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶time2: float = 0.0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶ExtrudedShape
+
+
+¶FrameChannel
+
+
+
+ dataclass
+
+
+¶FrameMetadata
+
+
+
+ dataclass
+
+
+¶ImageInfo
+
+
+¶bits_per_pixel: int
+
+
+ instance-attribute
+
+
+¶components: int
+
+
+ instance-attribute
+
+
+¶height: int
+
+
+ instance-attribute
+
+
+¶width: int
+
+
+ instance-attribute
+
+
+¶InterpType
+
+
+¶The role that the ROI plays.
+ + + + +AnyROI = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶BackgroundROI = 2
+
+
+ class-attribute
+ instance-attribute
+
+
+¶ReferenceROI = 3
+
+
+ class-attribute
+ instance-attribute
+
+
+¶StandardROI = 1
+
+
+ class-attribute
+ instance-attribute
+
+
+¶StimulationROI = 4
+
+
+ class-attribute
+ instance-attribute
+
+
+¶LoopIndices
+
+
+
+ dataclass
+
+
+¶CustomLoop: int | None = field(default=None, repr=False, compare=False)
+
+
+ class-attribute
+ instance-attribute
+
+
+¶NETimeLoop: int | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶TimeLoop: int | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶XYPosLoop: int | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶ZStackLoop: int | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶LoopType
+
+
+¶CustomLoop = 7
+
+
+ class-attribute
+ instance-attribute
+
+
+¶ManTimeLoop = 9
+
+
+ class-attribute
+ instance-attribute
+
+
+¶NETimeLoop = 8
+
+
+ class-attribute
+ instance-attribute
+
+
+¶PolarLoop = 5
+
+
+ class-attribute
+ instance-attribute
+
+
+¶SpectLoop = 6
+
+
+ class-attribute
+ instance-attribute
+
+
+¶TimeLoop = 1
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Unknown = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶XYDiscrLoop = 3
+
+
+ class-attribute
+ instance-attribute
+
+
+¶XYPosLoop = 2
+
+
+ class-attribute
+ instance-attribute
+
+
+¶ZStackLoop = 4
+
+
+ class-attribute
+ instance-attribute
+
+
+¶ZStackLoopAccurate = 10
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Metadata
+
+
+
+ dataclass
+
+
+¶Microscope
+
+
+
+ dataclass
+
+
+¶immersionRefractiveIndex: float | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶modalityFlags: list[ModalityFlags] = field(default_factory=list)
+
+
+ class-attribute
+ instance-attribute
+
+
+¶objectiveMagnification: float | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶objectiveName: str | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶objectiveNumericalAperture: float | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶pinholeDiameterUm: float | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶projectiveMagnification: float | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶zoomMagnification: float | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶NETimeLoop
+
+
+
+ dataclass
+
+
+¶NETimeLoopParams
+
+
+
+ dataclass
+
+
+¶periods: list[Period]
+
+
+ instance-attribute
+
+
+¶Period
+
+
+
+ dataclass
+
+
+¶count: int
+
+
+ instance-attribute
+
+
+¶PeriodDiff
+
+
+
+ dataclass
+
+
+¶Position
+
+
+
+ dataclass
+
+
+¶name: str | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶pfsOffset: float | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶stagePositionUm: StagePosition
+
+
+ instance-attribute
+
+
+¶ROI
+
+
+
+ dataclass
+
+
+¶ROI object from NIS Elements.
+ + + + +animParams: list[AnimParam] = field(default_factory=list)
+
+
+ class-attribute
+ instance-attribute
+
+
+¶guid: str
+
+
+ instance-attribute
+
+
+¶id: int
+
+
+ instance-attribute
+
+
+¶info: RoiInfo
+
+
+ instance-attribute
+
+
+¶RoiInfo
+
+
+
+ dataclass
+
+
+¶Info associated with an ROI.
+ + + + +appData: int = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶autodetected: bool = False
+
+
+ class-attribute
+ instance-attribute
+
+
+¶bpc: int = 16
+
+
+ class-attribute
+ instance-attribute
+
+
+¶color: int = 255
+
+
+ class-attribute
+ instance-attribute
+
+
+¶compCount: int = 2
+
+
+ class-attribute
+ instance-attribute
+
+
+¶cookie: int = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶gradientStimulation: bool = False
+
+
+ class-attribute
+ instance-attribute
+
+
+¶gradientStimulationBitDepth: int = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶gradientStimulationHi: float = 0.0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶gradientStimulationLo: float = 0.0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶interpType: InterpType
+
+
+ instance-attribute
+
+
+¶label: str = ''
+
+
+ class-attribute
+ instance-attribute
+
+
+¶locked: bool = False
+
+
+ class-attribute
+ instance-attribute
+
+
+¶multiFrame: bool = False
+
+
+ class-attribute
+ instance-attribute
+
+
+¶scope: ScopeType = ScopeType.Global
+
+
+ class-attribute
+ instance-attribute
+
+
+¶shapeType: RoiShapeType
+
+
+ instance-attribute
+
+
+¶stimulationGroup: int = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶RoiShapeType
+
+
+¶The type of ROI shape.
+ + + + +Any = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Bezier = 6
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Circle = 9
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Ellipse = 4
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Line = 7
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Point = 2
+
+
+ class-attribute
+ instance-attribute
+
+
+¶PolyLine = 8
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Polygon = 5
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Raster = 1
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Rectangle = 3
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Ring = 11
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Spiral = 12
+
+
+ class-attribute
+ instance-attribute
+
+
+¶Square = 10
+
+
+ class-attribute
+ instance-attribute
+
+
+¶ScopeType
+
+
+¶SpectLoop
+
+
+
+ dataclass
+
+
+¶StagePosition
+
+
+¶StimulationEvent
+
+
+
+ dataclass
+
+
+¶description: str = ''
+
+
+ class-attribute
+ instance-attribute
+
+
+¶loop_index: int = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶position: int = 0
+
+
+ class-attribute
+ instance-attribute
+
+
+¶type: StimulationType = StimulationType.NoStimulation
+
+
+ class-attribute
+ instance-attribute
+
+
+¶T
+
+
+¶AnimParams_Size: int
+
+
+ instance-attribute
+
+
+¶GUID: str
+
+
+ instance-attribute
+
+
+¶Id: int
+
+
+ instance-attribute
+
+
+¶Info: dict
+
+
+ instance-attribute
+
+
+¶TextInfo
+
+
+¶appVersion: str
+
+
+ instance-attribute
+
+
+¶author: str
+
+
+ instance-attribute
+
+
+¶capturing: str
+
+
+ instance-attribute
+
+
+¶conclusion: str
+
+
+ instance-attribute
+
+
+¶date: str
+
+
+ instance-attribute
+
+
+¶description: str
+
+
+ instance-attribute
+
+
+¶group: str
+
+
+ instance-attribute
+
+
+¶imageId: str
+
+
+ instance-attribute
+
+
+¶info1: str
+
+
+ instance-attribute
+
+
+¶info2: str
+
+
+ instance-attribute
+
+
+¶location: str
+
+
+ instance-attribute
+
+
+¶optics: str
+
+
+ instance-attribute
+
+
+¶sampleId: str
+
+
+ instance-attribute
+
+
+¶sampling: str
+
+
+ instance-attribute
+
+
+¶type: str
+
+
+ instance-attribute
+
+
+¶TimeLoop
+
+
+
+ dataclass
+
+
+¶TimeLoopParams
+
+
+
+ dataclass
+
+
+¶durationMs: float
+
+
+ instance-attribute
+
+
+¶periodDiff: PeriodDiff
+
+
+ instance-attribute
+
+
+¶periodMs: float
+
+
+ instance-attribute
+
+
+¶startMs: float
+
+
+ instance-attribute
+
+
+¶TimeStamp
+
+
+
+ dataclass
+
+
+¶Volume
+
+
+
+ dataclass
+
+
+¶axesCalibrated: tuple[bool, bool, bool]
+
+
+ instance-attribute
+
+
+¶axesCalibration: tuple[float, float, float]
+
+
+ instance-attribute
+
+
+¶axesInterpretation: tuple[AxisInterpretation, AxisInterpretation, AxisInterpretation]
+
+
+ instance-attribute
+
+
+¶bitsPerComponentInMemory: int
+
+
+ instance-attribute
+
+
+¶bitsPerComponentSignificant: int
+
+
+ instance-attribute
+
+
+¶cameraTransformationMatrix: tuple[float, float, float, float]
+
+
+ instance-attribute
+
+
+¶componentCount: int
+
+
+ instance-attribute
+
+
+¶componentDataType: Literal['unsigned', 'float']
+
+
+ instance-attribute
+
+
+¶componentMaxima: list[float] | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶componentMinima: list[float] | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶pixelToStageTransformationMatrix: tuple[float, float, float, float, float, float] | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶voxelCount: tuple[int, int, int]
+
+
+ instance-attribute
+
+
+¶XYPoint
+
+
+¶XYPosLoop
+
+
+
+ dataclass
+
+
+¶XYPosLoopParams
+
+
+
+ dataclass
+
+
+¶XYZPoint
+
+
+¶ZStackLoop
+
+
+
+ dataclass
+
+
+¶ZStackLoopParams
+
+
+
+ dataclass
+
+
+¶bottomToTop: bool
+
+
+ instance-attribute
+
+
+¶deviceName: str | None = None
+
+
+ class-attribute
+ instance-attribute
+
+
+¶homeIndex: int
+
+
+ instance-attribute
+
+
+¶stepUm: float
+
+
+ instance-attribute
+
+
+¶