Submodules¶

dic.dic_io module¶

dic.dic_io provides IO operations for DIC and associated files. This includes loading (and possibly modifying) DIC data from .MAT files and MTS data from .CSV files. In addition, the ability to find and sort image (or general) filenames is provided.

dic.dic_io.load_dic_data(filename, variable_names=None)[source]¶

Loads the DIC data specified by the given filename. Uncorrelated regions of the dataset are masked (i.e. removed) before the data is returned. Prior to loading the data must be exported into the Matlab (.mat) file format.

Parameters:	filename : str Name of the DIC data file to load. variable_names : None or sequence If None (the default) - read all variables in file. Otherwise variable_names should be a sequence of strings, giving names of the matlab variables to read from the file. The reader will skip any variable with a name not in this sequence, possibly saving some read processing.
Returns:	dict A dictionary of {key: value} pairs where each key is the variable name, e.g. X, U, Z, etc., and the value is a 2D numpy array containing the exported DIC results.

dic.dic_io.load_csv_data(filename, column, scale=None)[source]¶

Loads the specifed column of the csv data from the given filename. Values are multiplied by scale before the data is returned.

Parameters:	filename : str Name of the .csv file to load. column : int Column index to load from the file. scale : float, optional Value to scale the data by before returning. For example, when loading MTS data the scale variable can be used to change the native output (Volts) to force (N) by providing scale that is equal to the Newtons/Volts. Default is None.
Returns:	numpy.ndarray 1D array of data values.

dic.dic_io.get_filenames(directory, extension, prepend_directory=False)[source]¶

Retrieves a sorted list of file names in the specified directory with the given extension.

Parameters:	directory : str Directory to search. extension : str Extension to search for (including the period, if applicable). prepend_directory : bool, optional Whether to prepend the directory to the filenames. Default = False.
Returns:	List[str] Sorted list of file names that match the given extension

dic.dic_io.get_image_filenames(directory, extension='.tif', prepend_directory=False)[source]¶

Sorts and retrieves the camera images in the specified directory. This function assumes that the left camera images end in _0.ext, where .ext is the provided extension. Similarly, the right camera images are assumed to end in _1.ext.

Parameters:	directory : str Directory to search. extension : str, optional Image extension. Default = ".tif". prepend_directory : bool, optional Whether to prepend the directory to the filenames. Default = False.
Returns:	(left_camera_filenames, right_camera_filenames) : (List[str], List[str]) List of filenames belonging to each camera.

dic.dic_io.update_dic_data(input_directory, output_directory, function=None, args=(), compress=False, processes=None)[source]¶

Calls function on each DIC file and saves the new version into the output directory.

Parameters:

input_directory : str Path to uncompressed .mat files. output_directory : str Where to save the compressed files. function : callable, optional Function that accepts a dict and modifies the object in place. Default is None, i.e. no function is called. args : tuple, optional Extra arguments passed to function, i.e. f(dic_data, *args). output_directory : str Directory to store the results. compress : bool, optional Whether to compress the DIC files when saving to the output directory. processes : int, optional The number of processes to use when converting the files. Default is None. If None is provided then the number of processes will be set to the value returned by multiprocessing.cpu_count().

dic.dic_utils module¶

dic_utils contains several utility functions used when analyzing DIC data, e.g. determining the step size, going from pixel to millimeter coordinates, and determining deformations.

dic.dic_utils.get_step(dic_data)[source]¶

Returns the step size of the DIC data

Parameters:	dic_data : dict Dictionary containing the DIC data.
Returns:	int Step size.

dic.dic_utils.point_to_indices(dic_data, pt)[source]¶

Transforms (x, y) in pixel coordinates into the corresponding (row, col) to access the closest data point in the specified DIC data.

Parameters:	dic_data : dict Dictionary containing the DIC data. pt : (x, x) Two-dimensional coordinates of the pixel in global space.
Returns:	(row, col) : (int, int) The row and column in dic_data that corresponds to the given pixel point.

dic.dic_utils.get_initial_position(dic_data, row, col)[source]¶

Retrieves the initial position (in mm) held at the specified row and column.

Parameters:	dic_data : dict Dictionary containing the DIC data. row : int Row in the DIC data to access. col : int Column in the DIC data to access.
Returns:	numpy.ndarray Initial (x, y, z) position in mm.

dic.dic_utils.get_displacement(dic_data, row, col)[source]¶

Retrieves the displacement (in mm) held at the specified row and column.

Parameters:	dic_data : dict Dictionary containing the DIC data. row : int Row in the DIC data to access. col : int Column in the DIC data to access.
Returns:	numpy.ndarray Displacements (u, v, w) in mm.

dic.dic_utils.point_to_position(dic_data, pt, add_displacement=True)[source]¶

Transforms a point in pixel space into its displaced coordinates in mm.

Parameters:	dic_data : dict Dictionary containing the DIC data. pt : (x, y) Two-dimensional coordinates of the pixel in global space. add_displacement : bool, optional Whether to add deformation to the undeformed position. Default is True.
Returns:	numpy.ndarray (x, y, z) position in mm of the point.

dic.extensometer module¶

The dic.extensometer module provides a means of easily creating and analyzing extensometers. An extensometer is defined by two nodal locations connected by a straight line. Metrics can be extracted from extensometers such as the length, angle, strain, etc. If the same metric needs to be extracted from the same extensometer for several DIC files, then the dic.extensometer.extensometer_sequence() function allows a set of DIC filenames, extensometers and metric to be provided, and the relevant metric will be extracted for the given extensometers for all the DIC files. Placing extensometers can be accomplished by using the dic.extensometers.place_extensometers() function which, when given the reference image and DIC filenames, allows extensometer placement by clicking on a Matplotlib figure.

class dic.extensometer.Extensometer[source]¶

Bases: dic.extensometer.Extensometer

An extensometer that is defined between two points in pixel space.

Attributes

pt1	Alias for field number 0
pt2	Alias for field number 1

Methods

count(...)
index((value, [start, ...)	Raises ValueError if the value is not present.

dic.extensometer.extensometer_length(dic_data, extensometer, add_displacement=True)[source]¶

Calculates the length of the extensometer.

Parameters:	dic_data : dict Dictionary containing the DIC data. extensometer : :class:.`Extensometer` (x, y) coordinates of the extensometer points in pixel space. add_displacement : bool, optional Whether to add displacement to the undeformed position. Default is True.
Returns:	float Length of the extensometer.

dic.extensometer.extensometer_transverse_displacement(dic_data, extensometer, fractional_points=10)[source]¶

Calculates the displacement transverse to the deformed end-points of the extensometer.

Parameters:

dic_data : dict Dictionary containing the DIC data. extensometer : :class:.`Extensometer` (x, y) coordinates of the extensometer points in pixel space. fractional_points : int or List[float], optional If int, the transverse displacement will be calculated in uniformly spaced intervals on the interval [0, 1] with the number of sample points determined by fractional_points. If List[float], then the given items in the list will be used directly to compute displacement. If a List is given, a value of 0 corresponds to pt1 of the extensometer and 1 corresponds to pt2 of the extensometer, i.e. the fractional coordinates are the fraction along the extensometer’s length at which the transverse displacement should be calculated. Default is 10.

Returns:

List[float] List of transverse displacements.

dic.extensometer.extensometer_strain(dic_data, extensometer)[source]¶

Calculates the strain between the specified points. Points should be specified by their pixel location.

Parameters:	dic_data : dict Dictionary containing the DIC data. extensometer : :class:.`Extensometer` (x, y) coordinates of the extensometer points in pixel space.
Returns:	float Strain, i.e. deformed_length / initial_length - 1.0.

dic.extensometer.extensometer_angle(dic_data, extensometer)[source]¶

Calculates the angle (in radians) between the specified extensometer and the x-axis.

Parameters:	dic_data : dict Dictionary containing the DIC data. extensometer : :class:.`Extensometer` (x, y) coordinates of the extensometer points in pixel space.
Returns:	float Angle in radians.

dic.extensometer.extensometer_curvature(dic_data, extensometer)[source]¶

Calculates the curvature of the given extensometer. Curvature is calculated by fitting a circle to the data points that are within a distance of +/- extensometer_length / 4 of the point with the maximum transverse displacement.

Parameters:	dic_data : dict Dictionary containing the DIC data. extensometer : :class:.`Extensometer` (x, y) coordinates of the extensometer points in pixel space.
Returns:	float Curvature.

dic.extensometer.extensometer_sequence(dic_filenames, extensometers, metric, description='Processing extensometers')[source]¶

Extracts the specified metric from the extensometers for all DIC files.

Parameters:

dic_filenames : str Names of DIC files to analyze. extensometers : List[Extensometer] List of extensometers to metric : callable A callable object that provides the signature metric(dict, Extensometer) -> float, i.e. takes as input a dict of dic_data and an Extensometer and returns a float. description : str, optional Description of the computation that will be printed along with the progress bar. Default is "Processing extensometers".

Returns:

numpy.ndarray Array of size len(dic_filenames) by len(extensometers)

dic.extensometer.place_extensometers(reference_image_filename, reference_dic_filename)[source]¶

Places extensometers on the given set of reference data. Clicking the figure will add a point. Adding two points will create an extensometer.

Parameters:	reference_image_filename : str Name of the file containing the reference image, e.g. the first image of the DIC data. reference_dic_filename : str Name of the file containing the reference DIC data, e.g. the DIC data calculated from the reference image.
Returns:	List[Extensometer] List of extensometers added by the user.

dic.frame_creators module¶

This submodule holds the frame creators that produce an image sequence that will be converted into a movie. A frame creator is an object that when called with the frame number will return the corresponding frame as a matplotlib.figure.Figure object and has a length (i.e. __len__) equal to the number of frames it intends to create.

Feel free to add you own frame creator. I will periodically update this to include more as I (or others) need them.

class dic.frame_creators.OverlayWithStressStrainFrameCreator(image_filenames, dic_filenames, variable, xy_data, figure_width=10.0, fractional_padding=0.5, overlay_contour_options=None, xy_axes_options=None, xy_plot_options=None, colorbar_options=None, point_plot_options=None)[source]¶

Bases: object

This class creates a frames of a contour overlay, colorbar and stress-strain plot.

Attributes

image_filenames	(List[str]) List of filenames containing the background images for the overlay plots.
dic_filenames	(str) List of filenames containing the DIC data files.
variable	(str) Variable from the DIC data to plot on the overlay.
xy_data	(List[T], List[T]) Tuple of (xdata, ydata) to plot on the 2D plot. The length of xdata and ydata must be equal and the same as the number of images and DIC files.
figure_width	(float, optional) Width of the figure in inches. The height will be chosen automatically based on the aspect ratio of the overlays. Default is 10.0.
fractional_padding	(float, optional) Fraction of the image width to pad between the right of the colorbar and the left of the x-y data plot. Default is 0.5
overlay_contour_options	(dict, optional) Keyword arguments to use when calling matplotlib.pyplot.contourf. Default is None Valid keys are corner_mask, alpha, cmap, levels, extend, etc. See matplotlib.pyplot.contourf for all valid keys.
xy_axes_options	(dict, optional) Keyword arguments to the x-y data axes. Default is None. Valid keys are legal matplotlib.axes.Axes kwargs plus projection, which chooses a projection type for the axes.
xy_plot_options	(dict, optional) Keyword arguments to use when plotting the data on the x-y data axis. Default is None. Valid keys are matplotlib.lines.Line2D properties, e.g. alpha, color, label, etc.
colorbar_options	(dict, optional) Keyword arguments to the colorbar axes. Default is None. Valid keys are legal matplotlib.axes.Axes kwargs plus projection, which chooses a projection type for the axes.
point_plot_options	(dict, optional) Keyword arguments to use when plotting the current data point in the x-y data series on the x-y axes. If None is supplied a purple circle is used.

Methods

__call__(i)	Returns the ``i``th figure.
__len__()	Returns the total number of frames to create.

dic.geometry_utils module¶

The dic.geometry_utils module contain utility functions (not specific to DIC) that aid in applying geometric transformations or determining spatial relationships between data point, usually in 3D space.

dic.geometry_utils.norm[source]¶

Calculates the norm of a vector.

Parameters:	x : array_like Input vector.
Returns:	float Norm of the vector.

dic.geometry_utils.apply_rotation[source]¶

Rotates the given (x, y) indices by an amount theta.

Parameters:	x : int Coordinate with respect to the x-axis. y : int Coordinate with respect to the y-axis. theta : T Angle in radians.
Returns:	(x_new, y_new) : (int, int) Rotated coordinates.

dic.geometry_utils.distance_between(pt1, pt2)[source]¶

Calculates the distance between the given points.

Parameters:	pt1 : List[T] Coordinate of the first point. pt2 : List[T] Coordinate of the second point.
Returns:	float Distance

dic.geometry_utils.distance_to(pt0, pt1, pt2)[source]¶

Computes the distance between pt0 and the line that passes through pt1 and pt2.

Parameters:	pt0 : numpy.ndarray Point to calculate distance to. pt1 : numpy.ndarray First point that defines the line. pt2 : numpy.ndarray Second point that defines the line.
Returns:	float Distance.

dic.geometry_utils.get_angle(pt1, pt2)[source]¶

Calculates the angle between the given two-dimensional points and the x-axis.

Parameters:	pt1 : List[T] (x, y) coordinate of the first point. pt2 : List[T] (x, y) coordinate of the second point.
Returns:	float Angle in radians.

dic.geometry_utils.get_transformation_matrix(axis, theta, translation, scale)[source]¶

Returns the 4x4 transformation matrix that applies the specified scale, translation, and rotation.

Parameters:	axis : array_like Axis of rotation. theta : float Angle of rotation in radians. translation : array_like Translation vector. scale : float Uniform scale factor.
Returns:	numpy.ndarray 4x4 transformation matrix.

dic.geometry_utils.apply_transformation(pt, transformation_matrix, offset)[source]¶

Applies the affine transformation to the point.

Parameters:	pt : array_like (x, y, z) coordinate. transformation_matrix : array_like 4x4 transformation_matrix. offset : array_like Offset from the origin.
Returns:	numpy.ndarray Tranformed (x, y, z) coordinate.

dic.geometry_utils.cross3d[source]¶

Calculates the cross product between two 3D vectors.

Parameters:	a : array_like (x, y, z) components of the first vector. b : array_like (x, y, z) components of the second vector.
Returns:	numpy.ndarray Vector cross product.

dic.plot module¶

The dic.plot module contains the functions needed to display DIC overlays using dic.plot.plot_overlay() and (x,y) data using dic.plot.plot_overlay(). Because the default colorbars from Matplotlib can be somewhat underwhelming (and produce unintended effects when adding them to an existing figure) the dic.plot.plot_colorbar() function allows explicit creation of the desired colorbar.

dic.plot.plot_overlay(image_filename, dic_data, key, fig=None, ax=None, contour_options=None, add_colorbar=False, colorbar_title=None, colorbar_options=None)[source]¶

Plots a filled contour overlay on top of the specified image.

Parameters:

image_filename : str Name of file containing the background image. dic_data : dict Dictionary containing the DIC data (usually loaded from a .mat file). key : str Name of the key to use as the overlay variable. The key must be present in the data loaded from dic_filename. fig : matplotlib.figure.Figure, optional Figure to add overlay to. If not specified, the figure will be taken from the specified axes. If neither this nor ax is specified, a new figure and axis will be created. ax : matplotlib.axes.Axes, optional Axes object to add the overlay to. If not specified the axes will be taken from the given figure’s current axes. If neither this nor fig is specified a new axes object will be created. contour_options : dict, optional Keyword arguments to use when calling matplotlib.pyplot.contourf. Default is None Valid keys are corner_mask, alpha, cmap, levels, extend, etc. See matplotlib.pyplot.contourf for all valid keys. add_colorbar : bool, optional Whether to add a colorbar to the overlay axes. Default is False. colorbar_title : str, optional Title to add to the colorbar. Default is None. If None is provided, the title is set to the key. colorbar_options : dict, optional Keyword arguments to use when adding a colorbar to the overlay. Default is None. If None is provided the colorbar will be shrunk slightly such that the color bar is roughly the same height as the overlay. Valid key word arguments include ticks, format, orientation, etc. See matplotlib.figure.colorbar for all options.

Returns:

matplotlib.figure.Figure, matplotlib.axes.Axes Figure and axes containing the background image and contour overlay.

dic.plot.plot_xy(x, y, fig=None, ax=None, figure_options=None, axes_options=None, plot_options=None)[source]¶

Plots the given x, y data.

Parameters:

x : List[T] X data points. y : List[T] Y data points. fig : matplotlib.figure.Figure, optional Figure to add overlay to. If not specified, the figure will be taken from the specified axes. If neither this nor ax is specified, a new figure and axis will be created. ax : matplotlib.axes.Axes, optional Axes object to add the overlay to. If not specified the axes will be taken from the given figure’s current axes. If neither this nor fig is specified a new axes object will be created. figure_options : dict, optional Keyword arguments to use when creating the figure. Default is None. Valid keys are figsize, dpi, facecolor, edgecolor, linewidth, frameon, subplotpars, and tight_layout. axes_options : dict, optional Keyword arguments to use when adding an axis to the figure. Default is None. Valid keys are legal matplotlib.axes.Axes kwargs plus projection, which chooses a projection type for the axes. plot_options : dict, optional Keyword arguments to use when plotting the data on the axis. Default is None. Valid keys are matplotlib.lines.Line2D properties, e.g. alpha, color, label, etc.

Returns:

matplotlib.figure.Figure, matplotlib.axes.Axes Figure and axes containing the x-y data.

dic.plot.plot_colorbar(cmap, vmin, vmax, fig=None, ax=None, figure_options=None, axes_options=None, colorbar_options=None)[source]¶

Creates a colorbar of the specified name and normalization.

Parameters:

cmap : str Name of the Matplotlib colorbar. vmin : float Lower limit of the normalization. vmax : float Upper limit of the normalization. fig : matplotlib.figure.Figure, optional Figure to add overlay to. If not specified, the figure will be taken from the specified axes. If neither this nor ax is specified, a new figure and axis will be created. ax : matplotlib.axes.Axes, optional Axes object to add the overlay to. If not specified the axes will be taken from the given figure’s current axes. If neither this nor fig is specified a new axes object will be created. figure_options : dict, optional Keyword arguments to use when creating the figure. Default is None. Valid keys are figsize, dpi, facecolor, edgecolor, linewidth, frameon, subplotpars, and tight_layout. axes_options : dict, optional Keyword arguments to use when adding an axis to the figure. Default is None. Valid keys are legal matplotlib.axes.Axes kwargs plus projection, which chooses a projection type for the axes. colorbar_options : dict, optional Keyword arguments to use when adding the colorbar to the axes. Valid keys are orientation, ticks, etc. See matplotlib.colorbar.ColorbarBase for more valid keyword arguments.

Returns:

matplotlib.figure.Figure, matplotlib.axes.Axes Figure and axes containing the colorbar.

dic.plot.show(*args, **kw)[source]¶

Display a figure. When running in ipython with its pylab mode, display all figures and return to the ipython prompt.

In non-interactive mode, display all figures and block until the figures have been closed; in interactive mode it has no effect unless figures were created prior to a change from non-interactive to interactive mode (not recommended). In that case it displays the figures but does not block.

A single experimental keyword argument, block, may be set to True or False to override the blocking behavior described above.

dic.plot.savefig(*args, **kwargs)[source]¶

Save the current figure.

Call signature:

savefig(fname, dpi=None, facecolor='w', edgecolor='w',
        orientation='portrait', papertype=None, format=None,
        transparent=False, bbox_inches=None, pad_inches=0.1,
        frameon=None)

The output formats available depend on the backend being used.

Arguments:

fname:

A string containing a path to a filename, or a Python file-like object, or possibly some backend-dependent object such as PdfPages.

If format is None and fname is a string, the output format is deduced from the extension of the filename. If the filename has no extension, the value of the rc parameter savefig.format is used.

If fname is not a string, remember to specify format to ensure that the correct backend is used.

Keyword arguments:

dpi: [ None | scalar > 0 | ‘figure’]

The resolution in dots per inch. If None it will default to the value savefig.dpi in the matplotlibrc file. If ‘figure’ it will set the dpi to be the value of the figure.

facecolor, edgecolor:

the colors of the figure rectangle

orientation: [ ‘landscape’ | ‘portrait’ ]

not supported on all backends; currently only on postscript output

papertype:

One of ‘letter’, ‘legal’, ‘executive’, ‘ledger’, ‘a0’ through ‘a10’, ‘b0’ through ‘b10’. Only supported for postscript output.

format:

One of the file extensions supported by the active backend. Most backends support png, pdf, ps, eps and svg.

transparent:

If True, the axes patches will all be transparent; the figure patch will also be transparent unless facecolor and/or edgecolor are specified via kwargs. This is useful, for example, for displaying a plot on top of a colored background on a web page. The transparency of these patches will be restored to their original values upon exit of this function.

frameon:

If True, the figure patch will be colored, if False, the figure background will be transparent. If not provided, the rcParam ‘savefig.frameon’ will be used.

bbox_inches:

Bbox in inches. Only the given portion of the figure is saved. If ‘tight’, try to figure out the tight bbox of the figure.

pad_inches:

Amount of padding around the figure when bbox_inches is ‘tight’.

bbox_extra_artists:

A list of extra artists that will be considered when the tight bbox is calculated.

dic.scale module¶

The dic.scale module provides functions that will determine the millimeters per pixel (or pixels per millimeter) for a given DIC data file.

dic.scale.px_per_mm(dic_data)[source]¶

Calculates the average pixels per millimeter.

Parameters:	dic_data : dict Dictionary containing the DIC data. The dictionary must contain the keys x, y, X and Y.
Returns:	float Pixels per millimeter.

dic.scale.mm_per_px(dic_data)[source]¶

Calculates the average millimeters per pixel.

Parameters:	dic_data : dict Dictionary containing the DIC data. The dictionary must contain the keys x, y, X and Y.
Returns:	flost Millimeters per pixel.

dic.smooth module¶

The dic.smooth module allows a vector of data to be smoothed, often alleviating some of the undesired spikes that occurs during data acquisition.

dic.smooth.smooth(x, window_len=10, window='hanning')[source]¶

Smooth the data using a window with requested size.

This method is based on the convolution of a scaled window with the signal. The signal is prepared by introducing reflected copies of the signal (with the window size) at both ends of the data so that transient parts are minimized in the beginning and end of the output signal.

Parameters:	x : List[T] The input signal. window_len : int, optional The dimension of the smoothing window. Default is 10. window : {‘moving_average’, ‘hanning’, ‘hamming’, ‘bartlett’, ‘blackman’}, optional The type of window. Default is 'hanning'.
Returns:	numpy.ndarray The smoothed signal.

References

This function was modified from this source.

Examples

>>> import numpy as np
>>> t = np.linspace(-2, 2, 10)
>>> x = np.sin(t) + np.random.randn(len(t)) * 0.1
>>> smooth(x)
array([-0.97986086, -0.76226712, -0.51086275, -0.22217585,  0.08607285,
        0.37779472,  0.61419799,  0.772406  ,  0.85738291])

dic.stress_strain module¶

The dic.stress_strain module provides a function that will calculate the stress-strain response from a set of DIC files and the corresponding extensometers and test parameters force as measured from the MTS and sample area. The latter two are required to calculate stress, and the extensometers are used to calculate an average strain.

dic.stress_strain.stress_strain(dic_filenames, force, area, extensometers)[source]¶

Calculates the stress-strain response using the force data and the strain data calculated from the DIC files in the specified directory. Strain in calculated for each of the given extensometers, and the average at each data point is returned.

Parameters:	dic_filenames : List[str] List of filenames containing the DIC data. force : List[float] List of force data points. Number of data points must eq area : float Area of the sample. extensometers : List[Extensometer] List of pixel coordinates for each extensometer.
Returns:	(stress, strain) : (numpy.ndarray, numpy.ndarray) Stress-strain data.

dic.strut_metrics module¶

The dic.strut_metrics implements metrics useful when analyzing lattices or strut-like structures.

These will be added as needed.

dic.strut_metrics.nodal_rotation(dic_filenames, extensometers)[source]¶

Calculates the rotation of each extensometer for every DIC file.

Parameters:	dic_filenames : List[str] List of filenames containing the DIC data. extensometers : List[Extensometer] List of pixel coordinates for each extensometer.
Returns:	numpy.ndarray Nodal rotation. Shape of the returned array is (len(dic_filenames), len(extensometers)).

dic.variables module¶

The dic.variables module provides custom variables that can be added to DIC data as a {key: value} pair to an existing dictionary.

dic.variables.add_transverse_displacement(dic_data, nodes, elems, strut_radius)[source]¶

Adds the transverse_displacement key to the DIC data. Transverse displacement is defined as displacement perpendicular to the strut axis. Data near the nodal regions is removed from the correlated data. Strut axis is determined by the data points that are within +/- the strut radius along the vector between nodal locations. DIC data is updated in-place.

Parameters:	dic_data : dict Dictionary containing the DIC data. nodes : List[(T, T)] List of (x, y) nodal coordinates in pixel space. elems : List[(int, int)] List of indices into nodes strut_radius : int Radius of each strut in pixels.
Returns:	dic_data : dict DIC data with transverse displacement added.

dic.video module¶

The dic.video module provides functions to export video frames and convert an image sequence to a video. The latter assumes the FFMPEG is installed and available on your path.

dic.video.export_frames(frame_creator, output_directory=None, output_filename='frame.png', savefig_options=None)[source]¶

Exports video frames by calling frame_creator(i) where i is the iteration number belonging to the range [0, len(frame_creator)]. Therefore, the frame_creator must be callable and accept a single argument i. The frame_creator must also define the __len__ method that returns the number frames that the creator intends to create.

Parameters:

frame_creator : callable Object responsible for creating the frame. As input the frame_creator will be called with the frame number i and is expected to return a figure of type matplotlib.figure.Figure. The object must define __call__(self, i) and __len(self)__ methods. output_directory : str, optional Directory to place the frames into, If None is specified the frames will be placed in the current working directory. output_filename : str, optional Filename to save the frames as. The frame number will be appending to the output automatically. savefig_options : dict, optional Keyword arguments to pass to matplotlib.pyplot.savefig.

dic.video.image_sequence_to_video(input_template, output_filename, crf=23, scale=None)[source]¶

Converts an image sequence into a video using FFMPEG.

Parameters:

input_template : str The -i parameter passed to FFMPEG. This should specify the naming convention of the image sequence, e.g. frame_%03d.png. output_filename : str Name of file to save the movie to, e.g. movie.mp4. scale : (int, int), optional Video scale in the format (width, height) in pixels. If you’d like to keep the aspect ratio and scale only one dimension, set the value for the direction desired and use the value -1 for the other dimension, e.g. (720, -1) for 720p video resolution. The default is None which resizes the image such that the width and height are divisible by 2 (a requirement of the video encoder) but tries to keep the resolution as close to the original image as possible. crf : int [0-51], optional The range of the quantizer scale is 0-51: where 0 is lossless, 23 is default, and 51 is worst possible. A lower value is a higher quality and a subjectively sane range is 18-28. Consider 18 to be visually lossless or nearly so: it should look the same or nearly the same as the input but it isn’t technically lossless. The range is exponential, so increasing the CRF value +6 is roughly half the bitrate while -6 is roughly twice the bitrate. General usage is to choose the highest CRF value that still provides an acceptable quality. If the output looks good, then try a higher value and if it looks bad then choose a lower value. (credit: https://trac.ffmpeg.org/wiki/Encode/H.264)