dicstrain.py

strain_two_dimensional(data, window_size=5, window_element=4, input_binary=False, input_delimiter=',', output_basepath='./', output_binary=False, output_prefix='strain_', output_delimiter=',', output_at_end=False, strain_formulation='HENCKY')[source]

Compute strain fields from DIC displacement data using a finite element smoothing approach.

This function validates the input data and parameters, optionally loads DIC results from file, and passes the data to a C++-accelerated backend for strain computation.

Parameters:

  • data (pathlib.Path or str) – A pathlib.Path or str to files from which the data should be imported.

  • input_delimiter (str) – delimiter used for the input dic results files (default: “,”).

  • bool (input_binary) – whether input data is in human-readable or binary format (default: False).

  • window_size (int, optional) – The size of the local window over which to compute strain (must be odd), by default 5.

  • window_element (int, optional) – The type of finite element shape function used in the strain window: 4 (bilinear) or 9 (biquadratic), by default 4.

  • strain_formulation (str, optional) – The strain definition to use: one of ‘GREEN’, ‘ALMANSI’, ‘HENCKY’, ‘BIOT_EULER’, ‘BIOT_LAGRANGE’. Defaults to ‘HENCKY’.

  • output_basepath (str or pathlib.Path, optional) – Directory path where output files will be written (default: “./”).

  • output_binary (bool, optional) – Whether to write output in binary format (default: False).

  • output_prefix (str, optional) – Prefix for all output files (default: “strain_”). results will be named with output_prefix + original filename. THe extension will be changed to “.csv” or “.dic2d” depending on whether outputting as a binary.

  • output_delimiter (str, optional) – Delimiter used in text output files (default: “,”).

Raises:

ValueError – If any of the input parameters are invalid (e.g., unsupported strain formulation, even window size, or invalid element type).

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

Import strain 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:

StrainResults –

A named container with the following fields:

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

  • def_grad, eps (deformation gradient and strain 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.

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

read_binary(file, delimiter)[source]

Read a binary Strain result file and extract DIC fields.

Assumes a fixed binary structure with each row containing: - 2x int32 (subset coordinates) - 8x float64 (deformation matrix, strain matrix)

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: (window_x, window_y, def_grad, eps)

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, cost, ftol, xtol, niter]

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, cost, ftol, xtol, niter)

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:

  • data (np.ndarray) – Array of shape (n_frames, n_points) to be reshaped into (n_frames, height, width).

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

  • ss_x_ref (np.ndarray) – X coordinates of subset centers.

  • ss_y_ref (np.ndarray) – Y coordinates of subset centers.

  • x_unique (np.ndarray) – Sorted unique X coordinates in the grid.

  • y_unique (np.ndarray) – Sorted unique Y coordinates in the grid.

Returns:

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