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
andwhole
.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
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
isuint8
, 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.
- open(file_path=None)¶
- 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:
- whole(dtype=None, copy=True)¶
Convenience function to retrieve the whole stack.
Equivalent to call
zslice_idx
with dcimg module = 0 andframes_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 asslice(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
).