dicdataimport.py

data_import(data, binary=False, layout='matrix', delimiter=',')[source]

Import DIC result data from human readable text or binary files.

Parameters:

  • data (str or pathlib.Path) – Path pattern to the data files (can include wildcards). Default is “./”.

  • layout (str, optional) – Format of the output data layout: “column” (flat array per frame) or “matrix” (reshaped grid per frame). Default is “column”.

  • binary (bool, optional) – If True, expects files in a specific binary format. If False, expects text data. Default is False.

  • delimiter (str, optional) – Delimiter used in text data files. Ignored if binary=True. Default is a single space.

Returns:

Results –

A named container with the following fields:

  • ss_x, ss_y (grid arrays if layout==”matrix”; otherwise, 1D integer arrays)

  • u, v, m, converged, cost, ftol, xtol, niter (arrays with shape depending on layout)

  • filenames (python list)

Raises:

  • ValueError: – If layout is not “column” or “matrix”, or text data has insufficient columns, or binary rows are malformed. import cython module

  • FileNotFoundError: – If no matching data files are found.

read_binary(file, delimiter)[source]

Read a binary DIC result file and extract DIC fields.

Assumes a fixed binary structure with each row containing: - 2 × int32 (subset coordinates) - 6 × float64 (u, v, match quality, cost, ftol, xtol) - 1 × int32 (number of iterations) - 1 × uint8 (convergence flag) - 2 or 6 × float64 (shape parameters)

Parameters:

  • file (str) – Path to the binary result file.

  • delimiter (str) – Ignored for binary data (included for API consistency).

Returns:

tuple of np.ndarray – Arrays corresponding to: (ss_x, ss_y, u, v, m, cost, ftol, xtol, niter)

Raises:

ValueError – If the binary file size does not align with expected row size.

read_text(file, delimiter)[source]

Read a human-readable text DIC result file and extract DIC fields.

Expects at least 9 columns: [ss_x, ss_y, u, v, m, conv, cost, ftol, xtol, niter] Could also include shape parameters if present.

Parameters:

  • file (str) – Path to the text result file.

  • delimiter (str) – Delimiter used in the text file (e.g., space, tab, comma).

Returns:

tuple of np.ndarray – Arrays corresponding to: (ss_x, ss_y, u, v, m, conv, cost, ftol, xtol, niter, shape_params)

Raises:

ValueError – If the text file has fewer than 9 columns.

to_grid(data, shape, ss_x_ref, ss_y_ref, x_unique, y_unique)[source]

Reshape a 2D DIC field from flat (column) format into grid (matrix) format.

This is used when output layout is specified as “matrix”. Maps values using reference subset coordinates (ss_x_ref, ss_y_ref).

Parameters ol ———- data : np.ndarray

Array of shape (n_frames, n_points) to be reshaped into (n_frames, height, width).

shapetuple

Target shape of output array: (n_frames, height, width).

ss_x_refnp.ndarray

X coordinates of subset centers.

ss_y_refnp.ndarray

Y coordinates of subset centers.

x_uniquenp.ndarray

Sorted unique X coordinates in the grid.

y_uniquenp.ndarray

Sorted unique Y coordinates in the grid.

Returns:

np.ndarray – Reshaped array with shape shape, filled with NaNs where no data exists.