dcimg module¶

This module provides the DCIMGFile class for accessing Hamamatsu DCIMG files.

class dcimg.DCIMGFile(file_path=None)¶

Bases: object

A DCIMG file (Hamamatsu format), memory-mapped.

This class provides an interface for reading 3D Hamamatsu DCIMG files.

Usage is pretty straightforward. First of all, create a DCIMGFile object:

>>> my_file = DCIMGFile('input_file.dcimg')
>>> my_file
<DCIMGFile shape=2450x2048x2048 dtype=<class 'numpy.uint16'>file_name=input_file.dcimg>

Image data can then be accessed using NumPy’s basic indexing:

>>> my_file[-10, :5, :5]
array([[101, 104, 100,  99,  89],
       [103, 102, 103,  99, 102],
       [101, 104,  99, 108,  98],
       [102, 111,  99, 111,  95],
       [103,  98,  99, 104, 106]], dtype=uint16)

Other convenience methods for accessing image data are: zslice, zslice_idx, frame and whole.

DCIMGFile supports context managers:

>>> with DCIMGFile('input_file.dcimg') as f:
>>>     a = f[800, ...]

See also

NumPy’s basic indexing: Indexing routines

To access the whole file as a Dask Array, use as_dask_array():

>>> my_file = DCIMGFile('input_file.dcimg')
>>> da = my_file.as_dask_array()

Attributes:

byte_depth: Number of bytes per pixel.
bytes_per_img
bytes_per_row
deep_copy_enabled
dtype: NumPy numerical dtype.
file_size: File size in bytes.
framestamps: Framestamps of all frames.
nfrms: Number of frames (Z planes), same as zsize.
shape: Shape of the whole image stack.
timestamps: Timestamps of all frames.
xsize
ysize
zsize

Methods

`as_dask_array`()	Return the whole file as a Dask Array.
`frame`(index[, dtype, copy])	Convenience function to retrieve a single frame (Z plane).
`ts`(frame)	Timestamp of a single frame.
`whole`([dtype, copy])	Convenience function to retrieve the whole stack.
`zslice`(arg1[, arg2, step, dtype, copy])	Return a slice along `Z`, i.e. a substack of frames.
`zslice_idx`(index[, frames_per_slice, dtype, ...])	Return a slice, i.e. a substack of frames, by index.

close
compute_target_line
open

FILE_HDR_DTYPE = [('file_format', 'S8'), ('format_version', '<u4'), ('skip', '5<u4'), ('nsess', '<u4'), ('nfrms', '<u4'), ('header_size', '<u4'), ('skip2', '<u4'), ('file_size', '<u8'), ('skip3', '2<u4'), ('file_size2', '<u8')]¶

FMT_NEW = 2¶

FMT_OLD = 1¶

NEW_CROP_INFO = [('x0', '<u2'), ('xsize', '<u2'), ('y0', '<u2'), ('ysize', '<u2')]¶

NEW_FRAME_FOOTER_CAMLINK_DTYPE = [('progressive_number', '<u4'), ('timestamp', '<u4'), ('timestamp_frac', '<u4'), ('4px', '<u8'), ('zeros', '3<u4')]¶

NEW_FRAME_FOOTER_USB_DTYPE = [('progressive_number', '<u4'), ('timestamp', '<u4'), ('timestamp_frac', '<u4'), ('zeros', '<u4')]¶

NEW_SESSION_HEADER_DTYPE = [('session_size', '<u8'), ('skip1', '13<u4'), ('nfrms', '<u4'), ('byte_depth', '<u4'), ('skip2', '<u4'), ('xsize', '<u4'), ('ysize', '<u4'), ('bytes_per_row', '<u4'), ('bytes_per_img', '<u4'), ('skip3', '2<u4'), ('offset_to_data', '<u8'), ('skip4', '5<u4'), ('frame_footer_size', '<u4')]¶

SESSION_FOOTER2_DTYPE = [('offset_to_offset_to_timestamps', '<u8'), ('skip0', '2<u4'), ('offset_to_offset_to_frame_counts', '<u8'), ('skip1', '2<u4'), ('offset_to_offset_to_4px', '<u8'), ('skip2', '2<u4'), ('offset_to_frame_counts', '<u8'), ('skip3', '2<u4'), ('offset_to_timestamps', '<u8'), ('skip4', '4<u4'), ('offset_to_4px', '<u8'), ('skip5', '<u4'), ('4px_offset_in_frame', '<u4'), ('4px_size', '<u8')]¶

SESSION_FOOTER_DTYPE = [('format_version', '<u4'), ('skip0', '<u4'), ('offset_to_2nd_struct', '<u8'), ('skip1', '2<u4'), ('offset_to_offset_to_end_of_data', '<u8'), ('skip2', '2<u4'), ('footer_size', '<u4'), ('skip3', '<u4'), ('2nd_footer_size', '<u4'), ('skip4', '19<u4'), ('offset_to_end_of_data', '<u8'), ('skip5', '<u8'), ('offset_to_end_of_data_again', '<u8'), ('skip6', '<u8')]¶

SESS_HDR_DTYPE = [('session_size', '<u8'), ('skip1', '6<u4'), ('nfrms', '<u4'), ('byte_depth', '<u4'), ('skip2', '<u4'), ('xsize', '<u4'), ('bytes_per_row', '<u4'), ('ysize', '<u4'), ('bytes_per_img', '<u4'), ('skip3', '2<u4'), ('offset_to_data', '<u4'), ('session_data_size', '<u8')]¶

as_dask_array()¶

Return the whole file as a Dask Array.

Dask needs to be installed.

property byte_depth¶: Number of bytes per pixel.

property bytes_per_img¶

property bytes_per_row¶

close()¶

compute_target_line()¶

property deep_copy_enabled¶

property dtype¶: NumPy numerical dtype.

property file_size¶: File size in bytes.

first_4px_correction_enabled¶: For some reason, the first 4 pixels of each frame (or the first 4 pixels of line number 1023 of each frame) are stored in a different area in the file. This switch enables retrieving those 4 pixels. If False, those pixels are set to 0. If None, they are left unchanged. Actually, when the dtype is uint8, this affects the first 8 pixels. In any case this affects 8 bytes. Defaults to True.

frame(index, dtype=None, copy=True)¶

Convenience function to retrieve a single frame (Z plane).

Same as calling zslice_idx and squeezing.

Parameters:

indexint: frame index
dtype
copysee zslice

Returns:

numpy.ndarray: A numpy array of the original type or of dtype, if specified. The shape of the array is (ysize, xsize).

property framestamps¶

Framestamps of all frames.

Returns:

numpy.ndarray: A numpy array of dtype numpy.uint32 with framestamps.

mm¶: a numpy.memmap object with the raw contents of the DCIMG file.

mma¶: memory-mapped numpy.ndarray of the image data, without 4px correction.

property nfrms¶: Number of frames (Z planes), same as zsize.

open(file_path=None)¶

property shape¶

Shape of the whole image stack.

Returns:

tuple: (zsize, ysize, xsize)

property timestamps¶

Timestamps of all frames.

Returns:

numpy.ndarray: A numpy array of dtype numpy.datetime64 with frame timestamps.

ts(frame)¶

Timestamp of a single frame.

Parameters:

frameint: Frame index

Returns:

numpy.datetime64

whole(dtype=None, copy=True)¶

Convenience function to retrieve the whole stack.

Equivalent to call zslice_idx with index = 0 and frames_per_slice = nfrms

Parameters:

dtype
copysee zslice

Returns:

numpy.ndarray: A numpy array of the original type or of dtype, if specified. The shape of the array is shape.

property xsize¶

property ysize¶

property zsize¶

zslice(arg1, arg2=None, step=None, dtype=None, copy=True)¶

Return a slice along Z, i.e. a substack of frames.

Parameters:

arg1int: Mandatory argument, will be passed to slice If arg2 and step are both None, it will be passed as slice(arg1), i.e. it would act as the stop argument.
arg2int: If not null, will be passed as slice(arg1, arg2, step)
stepint: If not null, will be passed as slice(arg1, arg2, step)
dtype
copybool: If True, the requested slice is copied to memory. Otherwise a memory mapped array is returned.

Returns:

numpy.ndarray: A numpy array of the original type or of dtype, if specified. The shape of the array is (end_frame - start_frame, ysize, xsize).

zslice_idx(index, frames_per_slice=1, dtype=None, copy=True)¶

Return a slice, i.e. a substack of frames, by index.

Parameters:

indexint: slice index
frames_per_sliceint: number of frames per slice
dtype
copysee zslice

Returns:

numpy.ndarray: A numpy array of the original type or of dtype, if specified. The shape of the array is (frames_per_slice, ysize, xsize).