imagestructurefunction¶

Image structure function data class.

The ImageStructureFunction object is used to store and retrieve information about the image structure function computed in DDM.

The ImageStructureFunction.data contains the image structure function values in \((\Delta t, k_y, k_x)\) order. For instance, the image structure function at the 10th delay computed can be accessed via

dqt.data[9]

Note

Remember that Python uses zero-based indexing.

The ImageStructureFunction can then be saved into a binary file by using ImageStructureFunction.save() (it will have a .sf.ddm extension) and later retrieved from the memory using SFReader.load(), which you can call directly from fastddm as

# load image structure function
dqt = fastddm.load("path/to/my_dqt_file.sf.ddm")

In order to avoid reading and loading the entire file, we also provide a fast reader through the SFReader, which can be used to access directly from the disk the relevant data, for example:

from fastddm.imagestructurefunction import SFReader

# open file
r = SFReader("path/to/my_dqt_file.sf.ddm")

# access quantities in full plane representation
# access kx array
kx = r.get_kx()
# access 10th computed delay
frame = r.get_frame(index=9)

# access the same quantities in half plane representation
kx_half = r.get_kx(full=False)
frame_half = r.get_frame(index=9, full=False)

class fastddm.imagestructurefunction.ImageStructureFunction(_data: ndarray, _kx: ndarray, _ky: ndarray, _width: int, _height: int, _tau: ndarray, _pixel_size: float = 1.0, _delta_t: float = 1.0)¶

Image structure function container class.

Parameters:

_data (numpy.ndarray) – The packed data (2D image structure function, power spectrum, and variance).
_kx (numpy.ndarray) – The array of wavevector values over x.
_ky (numpy.ndarray) – The array of wavevector values over y.
_width (int) – The width of the full (symmetric) 2D image structure function.
_height (int) – The height of the full (symmetric) 2D image structure function.
_tau (numpy.ndarray) – The array of time delays.
_pixel_size (float, optional) – The effective pixel size. Default is 1.
_delta_t (float, optional) – The time delay between two consecutive frames. Default is 1.

__len__()¶

Length of the image structure function data. It coincides with the number of lags.

Returns:: The length of data.
Return type:: int

full_kx() → ndarray¶

Get the full array of wavevector values over x.

Returns:: The full kx array.
Return type:: numpy.ndarray

full_ky() → ndarray¶

Get the full array of wavevector values over y.

Returns:: The full ky array.
Return type:: numpy.ndarray

full_power_spec() → ndarray¶

Get the full (symmetric) average 2D power spectrum of the input images.

Returns:: The full 2D power spectrum.
Return type:: numpy.ndarray

full_shape() → Tuple[int, int, int]¶

Shape of the full (symmetric) 2D image structure function.

Returns:: The full shape.
Return type:: Tuple[int, int, int]

full_slice(idx: int) → ndarray¶

Get the full (symmetric) 2D image structure function at index idx.

Parameters:: idx (int) – The slice index.
Returns:: The full 2D image structure function slice.
Return type:: numpy.ndarray
Raises:: IndexError – If idx is out of bounds.

full_var() → ndarray¶

Get the full (symmetric) 2D variance (over time) of the Fourier transformed images.

Returns:: The full 2D variance.
Return type:: numpy.ndarray

save(fname: str = 'analysis_blob') → None¶

Save ImageStructureFunction to binary file.

Parameters:: fname (str, optional) – The full file name, by default “analysis_blob”.

save_as_tiff(seq: Sequence[int], fnames: Sequence[str]) → None¶

Save ImageStructureFunction frames as images.

Parameters:

seq (Optional[Sequence[int]]) – List of indices to export.
fnames (Optional[Sequence[str]], optional) – List of file names.

Raises:

RuntimeError – If number of elements in fnames and seq are different.

set_frame_rate(frame_rate: float) → None¶

Set the acquisition frame rate.

This will propagate also on the values of tau.

Parameters:: frame_rate (float) – The acquisition frame rate.

property data: ndarray¶

The 2D image structure function (in \((\Delta t, k_y, k_x)\) order).

Returns:: The 2D image structure function.
Return type:: numpy.ndarray

property delta_t: float¶

The time delay between to consecutive frames.

Returns:: Time delay.
Return type:: float

property height: int¶

The height of the full (symmetric) 2D image structure function.

Returns:: The full height.
Return type:: int

property kx: ndarray¶

The array of wave vector values over x.

Returns:: The array of kx.
Return type:: numpy.ndarray

property ky: ndarray¶

The array of wave vector values over y.

Returns:: The array of ky.
Return type:: numpy.ndarray

property pixel_size: float¶

The effective pixel size.

Returns:: Pixel size.
Return type:: float

property power_spec: ndarray¶

The average 2D power spectrum of the input images.

Returns:: The average 2D power spectrum of the input images.
Return type:: numpy.ndarray

property shape: Tuple[int, int, int]¶

Shape of image structure function data.

Returns:: The shape of the data.
Return type:: Tuple[int, int, int]

property tau: ndarray¶

The array of time delays.

Returns:: The array of tau.
Return type:: numpy.ndarray

property var: ndarray¶

The variance (over time) of the Fourier transformed input images.

Returns:: The variance (over time) of the Fourier transformed input images.
Return type:: numpy.ndarray

property width: int¶

The width of the full (symmetric) 2D image structure function.

Returns:: The full width.
Return type:: int

class fastddm.imagestructurefunction.SFParser(fh: BinaryIO)¶

Image structure function file parser class.

Inherits from Parser.

read_metadata() → dict¶

Read metadata from the binary file.

Returns:: The metadata dictionary.
Return type:: dict

class fastddm.imagestructurefunction.SFReader(file: str)¶

FastDDM image structure function reader class.

Inherits from Reader.

get_frame(index: int, full: bool | None = True) → ndarray¶

Read data slice array from file.

Parameters:

index (int) – The frame index.
full (Optional[bool]) – If True, return the full (symmetric) 2D image structure function. Default is True.

Returns:

The data slice array.

Return type:

numpy.ndarray

Raises:

IndexError – If index is out of range.

get_kx(full: bool | None = True) → ndarray¶

Read kx array from file.

Parameters:: full (Optional[bool]) – If True, return the full (symmetric) kx array. Default is True.
Returns:: The kx array.
Return type:: numpy.ndarray

get_ky(full: bool | None = True) → ndarray¶

Read ky array from file.

Parameters:: full (Optional[bool]) – If True, return the full (symmetric) ky array. Default is True. This flag has in fact no effect on the output since ky is already full.
Returns:: The ky array.
Return type:: numpy.ndarray

get_power_spec(full: bool | None = True) → ndarray¶

Read power spectrum array from file.

Parameters:: full (Optional[bool]) – If True, return the full (symmetric) power spectrum. Default is True.
Returns:: The power spectrum array.
Return type:: numpy.ndarray

get_tau() → ndarray¶

Read tau array from file.

Returns:: The tau array.
Return type:: numpy.ndarray

get_var(full: bool | None = True) → ndarray¶

Read variance array from file.

Parameters:: full (Optional[bool]) – If True, return the full (symmetric) variance. Default is True.
Returns:: The variance array.
Return type:: numpy.ndarray

load() → ImageStructureFunction¶

Load image structure function from file.

Returns:: ImageStructureFunction object.
Return type:: ImageStructureFunction
Raises:: IOError – If file version not supported.

class fastddm.imagestructurefunction.SFWriter(file: str)¶

Image structure function writer class.

Inherits from Writer. It adds the unique method write_obj. Defines the functions to write ImageStructureFunction object to binary file.

The structure of the binary file is the following:

Header:

bytes 0-1: endianness, string, utf-8 encoding ["LL" = ‘little’, "BB" = ‘big’]
bytes 2-3: file identifier, 16-bit integer, unsigned short [73 for image structure function]
bytes 4-5: file version, pair of 8-bit integers as (major_version, minor_version), unsigned char
byte 6: dtype, string, utf-8 encoding ["d" = float64, "f" = float32]
bytes 7-14: data length, 64-bit integer, unsigned long long
bytes 15-22: data height, 64-bit integer, unsigned long long
bytes 23-30: data width, 64-bit integer, unsigned long long
bytes 31-38: extra slices, 64-bit integer, unsigned long long
bytes 39-46: full width, 64-bit integer, unsigned long long
bytes 47-54: full height, 64-bit integer, unsigned long long

The data is stored in ‘C’ order and dtype format as follows:

from byte data_offset: _data
from byte extra_offset: extra data
from byte kx_offset: kx array
from byte ky_offset: ky array
from byte tau_offset: tau array
from byte pixel_size_offset: pixel_size value
from byte delta_t_offset: delta_t value

From the end of the file, the byte offsets are stored as unsigned long long 64-bit integers in this order:

data_offset
kx_offset
ky_offset
tau_offset
pixel_size_offset
delta_t_offset
extra_offset

write_obj(obj: ImageStructureFunction) → None¶

Write ImageStructureFunction object to binary file.

Parameters:: obj (ImageStructureFunction) – ImageStructureFunction object.