The vicpyx Python Module

The vicpyx python module permits loading and saving of VIC-3D data files in python. This allows custom post-processing and data reduction algorithms to be implemented very quickly and efficiently. Since the python module can write results in VIC-3D’s native output format, the post-processing results can then be used in VIC-3D for visualization.

Moreover, the vicpyx modules powers the Extensions found in VIC-3D.

Installation

The vicpyx module is available on The Python Package Index and can be installed with the following pip command:

pip install vicpyx

If you’d like to test the module, install the examples from this link: Python Examples. A short instruction file is in the ZIP.

Running vicpyx Scripts

1. If you are comfortable with the console you can simply use the console Python application to run .py and .pyw modules.
2. To run directly, you will have to associate .py and .pyw modules with the relevant applications. To do this, navigate to the file; right-click, and select Open with….
3. Select More apps.
4. Scroll all the way to the bottom, and select Look for another app on this PC
5. Navigate to the folder path\to\your\python.exe.
6. Select python.exe for .py files, and pythonw.exe for .pyw files. (For applications with a graphical interface, PYW files will show the application without the unnecessary console window.)
7. After this, if you double click on another script, it should run directly.

Example

To illustrate what can be done with the vicpyx module, here is a very simple example that loads a data file, computes the magnitude of the displacement for all data points, and saves the data file under a new filename.

import sys
from os import _exit as exit

import numpy as np
from vicpyx import *
if len(sys.argv) != 3:
    print(f"Usage: {sys.argv[0]} infile.out outfile.out\n")
    exit(-1)

dataset = VICDataSet()

if dataset.load(sys.argv[1]) == False:
    print("Could not load data set\n")
    exit(-1)

var_names = ["U", "V", "W"]
values = dataset.get_values(var_names)

D_values = np.sqrt(values["U"] ** 2 + values["V"] ** 2 + values["W"] ** 2)

vars = dataset.variables()

d_var = "D"
if d_var not in vars:
    d_var = dataset.add_variable("D", "Δ [mm]")

dataset.set_values({d_var: D_values})

if dataset.save(sys.argv[2]) == False:
    print("Could not save the dataset\n")
    exit(-1)

Breaking down the different parts of the script:

Imports

import sys
from os import _exit as exit

import numpy as np
from vicpyx import *

The beginning of the script imports the required modules for the script. The sys module provides access to the command-line arguments and the exit function is imported from the os module. The numpy module is imported so that the square-root function can be used and finally the vicpyx module is imported so that its classes become available for use.

Checking the arguments and loading the Dataset

if len(sys.argv) != 3:
    print(f"Usage: {sys.argv[0]} infile.out outfile.out\n")
    exit(-1)

dataset = VICDataSet()

if dataset.load(sys.argv[1]) == False:
    print("Could not load data set\n")
    exit(-1)

The program checks that an input and output file are specified on the command line and displays a usage message if not and then exits. If two arguments are given, a VICDataSet is created and the script attempts to read the specified input file. If an error occurs, the program displays an error message and exits.

Computing and adding the new variable to the Dataset

var_names = ["U", "V", "W"]
values = dataset.get_values(var_names)

D_values = np.sqrt(values["U"] ** 2 + values["V"] ** 2 + values["W"] ** 2)

vars = dataset.variables()

d_var = "D"
if d_var not in vars:
    d_var = dataset.add_variable("D", "Δ [mm]")

dataset.set_values({d_var: D_values})

Here, the values of the displacement on each axis are first retrieved from the dataset. Then the values for the new variable is calculated. This is done for all points in the dataset. Then, a check is performed to see if the dataset already contains a variable with the same name, and if not, it is then added. Note here, that the ‘add_variable’ method returns the name of the variable just added to the dataset. This ensures that all variable names in VIC data files remain be unique. The values for the new variable are then set in the dataset.

Writing the dataset

if dataset.save(sys.argv[2]) == False:
    print("Could not save the dataset\n")
    exit(-1)

Finally, the script saves the dataset in the output file specified on the command line.

Detailed vicpyx Python Module documentation

Module vicpyx.extensions.aoi_object

Class AOIObject

Represents an Area of Interest defined by one or more polygons on an image.

The image size must be set before serialization. Each polygon defines an AOI region with its own subset and step sizes, an outline, and optional cutouts.

def set_image_size(self, width, height)

Sets the image dimensions for this AOI.

Args:

• width: Image width in pixels. Must be positive.

• height: Image height in pixels. Must be positive.

def add_polygon(self, poly)

Adds an AOI polygon to this object.

Args:

• poly: A vicpy AOIPolygon defining an AOI region.

def as_dictionary(self)

Returns a dictionary representation of the AOI.

Returns:

• A dict with the image size and polygon definitions, suitable for JSON

• serialization.

Module vicpyx.extensions.extension_base

Class FullFieldExporter

Extension for exporting full-field data, one output file at a time.

Subclasses must implement process_data() to export a single DataSet. Unlike FullFieldProcessor, this does not set up an output file for saving.

def process(self)

def process_data(self, data)

Processes a single DataSet for export. Must be implemented by subclasses.

Args:

• data: The loaded DataSet to export.

Class FullFieldProcessor

Extension for processing full-field data, one output file at a time.

Subclasses must implement process_data() to operate on a single DataSet. The output file defaults to the input file unless –output is specified.

def process(self)

def process_data(self, data)

Processes a single DataSet. Must be implemented by subclasses.

Args:

• data: The loaded DataSet to process. Its file name is already set to the output path, so calling data.save() will write to the
• correct location.

Class LineSliceGenerator

Extension for generating line (slice) data from Vic output files.

Subclasses must implement process_data() to produce line data from a DataSet. A LineDataSet is created and passed to process_data() with the output path already configured.

def process(self)

def process_data(self, data, line_data)

Processes a DataSet to produce line data. Must be implemented by subclasses.

Args:

• data: The loaded DataSet to process.

• line_data: The LineDataSet to populate with results. Call line_data.save() when done.

Class PointDataGenerator

Extension for generating point data from Vic output files.

Subclasses must implement process_data() to produce point data from a DataSet. A PointDataSet is created and passed to process_data() with the output path already configured.

def process(self)

def process_data(self, data, point_data_set)

Processes a DataSet to produce point data. Must be implemented by subclasses.

Args:

• data: The loaded DataSet to process.

• point_data_set: The PointDataSet to populate with results. Call point_data_set.save() when done.

Class SingleProcessor

Extension that runs only once and can return a SingleObjectSet.

Subclasses must implement process_data() to populate a SingleObjectSet with AOI objects, inspector items, start points, transformation objects, and other output data.

def process(self)

def process_data(self, obj, data, image)

Processes input data and populates the SingleObjectSet. Must be implemented by subclasses.

Args:

• obj: The SingleObjectSet to populate with output objects.

• data: The loaded DataSet, or None if no data input was provided.

• image: The loaded PIL Image, or None if no image input was provided.

Class VicExtension

Base class for Vic extensions. Provides argument parsing.

def add_arguments(self, parser)

Add extra arguments to the extension. For instance, use

def add_arguments(self, pars):
    pars.add_argument('--radius', help='Circle radius', type=float, default=2.0)

The radius will be available as self.options.radius.

def enable_shuffle_data(self, enable)

Enables or disables data shuffling in the data sequence.

Args:

• enable: If False, the filter center is set to 0 (no shuffling).

def read_text_args(self, args)

Reads text arguments from a file or the VIC application socket.

Args:

• args: List of arguments in ‘key:value’ format. Supported keys are ‘port’ (port number for socket communication) and ‘filename’
• (path to a file containing the arguments).

Returns:

• The list of text arguments read from the source.

def run(self, args=None)

Run the extension.

def process(self)

Runs the main processing logic. Must be implemented by subclasses.

Module vicpyx.extensions.extension_mixins

Class AoiMaskAction

Argparse action that loads an AOI mask from the Vic socket or an image file.

Class AoiMaskMixin

Mixin for AOI mask. Adds –aoi-mask to the argument parser.

Class DataSequenceAction

Argparse action that creates a DataSequence from the provided file list.

Class DataSequenceMixin

Mixin for DataSequence. Adds –input to the argument parser.

Class FilterCenterMixin

Mixin for the –filter-center argument. Shared by DataSequenceMixin and ImageSequenceMixin.

Class ImageSequenceAction

Argparse action that creates an ImageSequence from the provided file list.

Class ImageSequenceMixin

Mixin for ImageSequence. Adds –image to the argument parser.

Class InspectorCircleMixin

Mixin for inspector circle. Adds –inspector-circle to the argument parser.

def read_inspector_circle(obj)

Class InspectorExtensometerMixin

Mixin for inspector extensometers. Adds –inspector-extensometer to the argument parser.

def read_inspector_extensometer(obj)

Class InspectorLineMixin

Mixin for inspector lines. Adds –inspector-line to the argument parser.

def read_inspector_line(obj)

Class InspectorPointMixin

Mixin for inspector points. Adds –inspector-point to the argument parser.

def read_inspector_point(obj)

Class InspectorPolygonMixin

Mixin for inspector polygons. Adds –inspector-polygon to the argument parser.

def read_inspector_polygon(obj)

Class InspectorRectangleMixin

Mixin for inspector rectangle. Adds –inspector-rect to the argument parser.

def read_inspector_rect(obj)

Class JsonOutputMixin

Mixin for JSON output. Adds –output to the argument parser.

Class ReferenceDataAction

Argparse action that loads reference data from the Vic socket or a file.

Class ReferenceDataMixin

Mixin for reference data. Adds –reference-data to the argument parser.

Class SubsetSizeMixin

Mixin for subset size. Adds –subset-size to the argument parser.

Class VariableListMixin

Mixin for variable list. Adds –variable-list to the argument parser.

def read_variable_list(vars)

Module vicpyx.extensions.extension_sequences

Class DataSequence

A sequence of Vic data files that can be iterated and accessed by index.

Each file in the sequence is loaded as a DataSet on access. The center file (index 0) can optionally allow saving back to disk.

Args: options: Parsed command-line options forwarded to FileSequence.

def data(self, index=0)

Loads and returns the DataSet at the given index relative to the filter center.

Args:

• index: Offset from the filter center. 0 returns the center file.

Returns:

• The loaded DataSet, or None if the index is out of range.

Class DataSet

A VicDataSet that can load and save data through a VIC application socket.

Extends VicDataSet with the ability to communicate with a running Vic instance for loading and saving data files. When no port is set, falls back to direct file I/O.

def set_port(self, port)

Sets the port for communicating with the VIC application.

Args:

• port: The TCP port number. Use -1 for direct file I/O.

def set_block_saving(self, block)

Enables or disables saving.

Args:

• block: If True, calls to save() will be silently ignored.

def load(self, filename)

Loads data from a file, using the Vic socket if a port is set.

Args:

• filename: The path to the data file.

def save(self, filename=None)

Saves the data to a file or through the Vic socket.

Does nothing if saving has been blocked via set_block_saving(). When a port is set, sends the data to the VIC application; otherwise writes directly to disk.

Args:

• filename: The output file path. Defaults to the current file name.

Class FileSequence

Base class for ordered sequences of files with a filter center.

The filter center defines the reference index (index 0) within the sequence. Files before and after the center are accessed with negative and positive indices respectively.

Args: options: Parsed command-line options. Must contain a port attribute and optionally filter_center and _shuffle_data.

def set_file_list(self, files)

Sets the list of files in this sequence.

If the filter center has not been set, it defaults to the middle of the list.

Args:

• files: Ordered list of file paths.

def file_list(self)

Returns the full list of file paths in this sequence.

def number_of_files(self)

Returns the total number of files in this sequence.

def file_name(self, index=0)

Returns the file path at the given index relative to the filter center.

Args:

• index: Offset from the filter center. 0 returns the center file.

Returns:

• The file path, or None if the index is out of range.

Class ImageSequence

A sequence of image files that can be iterated and accessed by index.

Each file in the sequence is loaded as a PIL Image on access.

Args: options: Parsed command-line options forwarded to FileSequence.

def image(self, index=0)

Loads and returns the image at the given index relative to the filter center.

Args:

• index: Offset from the filter center. 0 returns the center image.

Returns:

• The loaded PIL Image, or None if the index is out of range.

Module vicpyx.extensions.extension_socket

Class ExtensionSocket

Socket client for communicating with the VIC application.

Sends requests to and receives responses from a running Vic instance over a TCP connection on localhost.

Args: port: The TCP port number for the VIC application socket.

def get_data(self, req)

Sends a request to the VIC application and returns the response.

Args:

• req: The raw request bytes to send.

Returns:

• A tuple of (content_type, body, headers) where content_type identifies

• the response kind (e.g. ‘OUTFILE’, ‘AOIMASK’, ‘IMAGE’, ‘TEXTARGS’),

• body is the raw response data, and headers is a dict of extra header fields.

Module vicpyx.extensions.inspector_item_set

Class InspectorItemSet

A collection of inspector items (points, lines, extensometers, polygons, discs, rectangles).

Inspector items are named geometric elements placed on the image for extracting data at specific locations. Names are auto-generated if not provided, and must be unique within the set.

def set_forbidden_names(self, ii_names)

Sets names that cannot be used for new inspector items.

Args:

• ii_names: Set of reserved names that must not be assigned to new items.

def enable_average(self, enable)

Enables or disables averaging for area inspector items.

Args:

• enable: If True, area items will include averaged values in the output.

def add_point(self, x, y, name=None)

Adds an inspector point.

Args:

• x: The x coordinate.

• y: The y coordinate.

• name: Optional name. Auto-generated with prefix ‘P’ if not provided.

Returns:

• The name assigned to the point.

def add_line(self, points, name=None)

Adds an inspector polyline.

Args:

• points: List of (x, y) coordinate pairs. At least 2 required.

• name: Optional name. Auto-generated with prefix ‘L’ if not provided.

Returns:

• The name assigned to the line.

def add_extensometer(self, x0, y0, x1, y1, name=None)

Adds an inspector extensometer defined by two endpoints.

Args:

• x0: X coordinate of the first endpoint.

• y0: Y coordinate of the first endpoint.

• x1: X coordinate of the second endpoint.

• y1: Y coordinate of the second endpoint.

• name: Optional name. Auto-generated with prefix ‘E’ if not provided.

Returns:

• The name assigned to the extensometer.

def add_polygon(self, points, name=None)

Adds an inspector polygon.

Args:

• points: List of (x, y) coordinate pairs defining the polygon vertices. At least 3 required.

• name: Optional name. Auto-generated with prefix ‘S’ if not provided.

Returns:

• The name assigned to the polygon.

def add_disc(self, x, y, radius, name=None)

Adds an inspector disc (circle).

Args:

• x: X coordinate of the center.

• y: Y coordinate of the center.

• radius: The radius. Must be positive.

• name: Optional name. Auto-generated with prefix ‘C’ if not provided.

Returns:

• The name assigned to the disc.

def add_rectangle(self, width, height, cx, cy, name=None)

Adds an inspector rectangle.

Args:

• width: The width. Must be positive.

• height: The height. Must be positive.

• cx: X coordinate of the center.

• cy: Y coordinate of the center.

• name: Optional name. Auto-generated with prefix ‘R’ if not provided.

Returns:

• The name assigned to the rectangle.

def as_dictionary(self)

Returns a dictionary representation of all inspector items.

Returns:

• A dict suitable for JSON serialization containing all non-empty item groups.

Module vicpyx.extensions.line_data

Class LineData

Holds a named set of 1-D variable arrays that share the same length.

Each variable is stored as a float32 numpy array. All arrays in a single LineData must have the same length.

def add_line(self, var_name, var_desc, data)

Adds a variable array to this line data.

Args:

• var_name: The variable name. Must be unique within this LineData.

• var_desc: A human-readable description of the variable.

• data: The 1-D array of values for this variable.

def variable_names(self)

Returns the list of variable names in this line data.

Class LineDataSet

A collection of LineData objects that can be saved to JSON or sent to Vic.

def set_port(self, port)

Sets the port for communicating with the VIC application.

Args:

• port: The TCP port number. Use -1 for direct file I/O.

def set_file_name(self, filename)

Sets the default output file name.

Args:

• filename: The output file path.

def append(self, line_data)

Appends a LineData object to this set.

Args:

• line_data: The LineData to add.

def as_dictionary(self)

Returns a dictionary representation of the line data set.

Line data arrays are base64-encoded in the output.

Returns:

• A dict suitable for JSON serialization.

def save(self, filename=None)

Saves the line data to a JSON file or through the Vic socket.

Args:

• filename: The output file path. Defaults to the file name set via set_file_name().

Class VicLineSliceEncoder

def default(self, obj)

Module vicpyx.extensions.point_data

Class PointData

Holds named variable data for a single point.

Stores parallel lists of variable names, descriptions, and values for one named data point.

def set_data(self, name, variables, descriptions, values)

Sets all data for this point.

Args:

• name: The name of this data point.

• variables: List of variable names.

• descriptions: List of variable descriptions, matching variables in length.

• values: List of values, matching variables in length.

Class PointDataSet

A collection of PointData objects that can be saved to JSON or sent to Vic.

def set_port(self, port)

Sets the port for communicating with the VIC application.

Args:

• port: The TCP port number. Use -1 for direct file I/O.

def set_file_name(self, filename)

Sets the default output file name.

Args:

• filename: The output file path.

def append(self, point_data)

Appends a PointData object to this set.

Args:

• point_data: The PointData to add.

def as_dictionary(self)

Returns a dictionary representation of the point data set.

Returns:

• A dict suitable for JSON serialization.

def save(self, filename=None)

Saves the point data to a JSON file or through the Vic socket.

Args:

• filename: The output file path. Defaults to the file name set via set_file_name().

Class VicPointDataEncoder

def default(self, obj)

Module vicpyx.extensions.single_object

Class SingleObjectSet

A container for objects returned by a SingleProcessor extension.

Holds AOI objects, inspector items, start points, transformation objects, line data sets, point data sets, and file sequences. Can be serialized to JSON and sent to the VIC application or saved to a file.

def set_port(self, port)

Sets the port for communicating with the VIC application.

Args:

• port: The TCP port number. Use -1 for direct file I/O.

def set_file_name(self, filename)

Sets the default output file name.

Args:

• filename: The output file path.

def set_aoi(self, aoi)

Sets the Area of Interest object.

Args:

• aoi: The AOIObject to include in the output.

def set_inspector_forbidden_names(self, ii_names)

Sets names that cannot be used for new inspector items.

Args:

• ii_names: Set of reserved inspector item names.

def add_inspector_point(self, x, y, name=None)

Adds an inspector point.

Args:

• x: The x coordinate.

• y: The y coordinate.

• name: Optional name. Auto-generated if not provided.

Returns:

• The name assigned to the inspector point.

def add_inspector_line(self, points, name=None)

Adds an inspector line.

Args:

• points: List of (x, y) coordinate pairs defining the line. At least 2 required.

• name: Optional name. Auto-generated if not provided.

Returns:

• The name assigned to the inspector line.

def add_inspector_extensometer(self, x0, y0, x1, y1, name=None)

Adds an inspector extensometer defined by two endpoints.

Args:

• x0: X coordinate of the first endpoint.

• y0: Y coordinate of the first endpoint.

• x1: X coordinate of the second endpoint.

• y1: Y coordinate of the second endpoint.

• name: Optional name. Auto-generated if not provided.

Returns:

• The name assigned to the inspector extensometer.

def add_inspector_polygon(self, points, name=None)

Adds an inspector polygon.

Args:

• points: List of (x, y) coordinate pairs defining the polygon. At least 3 required.

• name: Optional name. Auto-generated if not provided.

Returns:

• The name assigned to the inspector polygon.

def add_inspector_disc(self, x, y, radius, name=None)

Adds an inspector disc (circle).

Args:

• x: X coordinate of the center.

• y: Y coordinate of the center.

• radius: The radius of the disc. Must be positive.

• name: Optional name. Auto-generated if not provided.

Returns:

• The name assigned to the inspector disc.

def add_inspector_rectangle(self, width, height, cx, cy, name=None)

Adds an inspector rectangle.

Args:

• width: The width of the rectangle. Must be positive.

• height: The height of the rectangle. Must be positive.

• cx: X coordinate of the center.

• cy: Y coordinate of the center.

• name: Optional name. Auto-generated if not provided.

Returns:

• The name assigned to the inspector rectangle.

def enable_inspector_average(self, enable)

Enables or disables averaging for inspector items.

Args:

• enable: If True, inspector items will include averaged values.

def set_transformation(self, transformation)

Sets the rigid transformation object.

Args:

• transformation: The TransformationObject to include in the output.

def add_startpoint(self, startpoint)

Adds a start point to the output.

Args:

• startpoint: The StartPoint to add.

def add_line_dataset(self, line_dataset)

Adds a line data set to the output.

Args:

• line_dataset: The LineDataSet to add.

def add_point_dataset(self, point_dataset)

Adds a point data set to the output.

Args:

• point_dataset: The PointDataSet to add.

def add_file_sequence(self, files)

Adds a file sequence to the output.

Args:

• files: List of file paths in the sequence.

def as_dictionary(self)

Returns a dictionary representation of all contained objects.

Returns:

• A dict suitable for JSON serialization containing all non-empty objects.

def save(self, filename=None)

Saves the object set as JSON to a file or through the Vic socket.

Args:

• filename: The output file path. Defaults to the file name set via set_file_name().

Module vicpyx.extensions.start_point_set

Enum GuessType

Type of initial guess for a start point.

• Reference
• User

Class StartPoint

A start point with one or more initial guesses for different images.

def add_guess(
    self,
    image,
    pos_x,
    pos_y,
    du_x=0.0,
    du_y=0.0,
    dv_x=0.0,
    dv_y=0.0,
    type=<GuessType.Reference: 0>,
)

Adds a guess for this start point.

Args:

• image: The image file name this guess applies to.

• pos_x: X coordinate of the start point position.

• pos_y: Y coordinate of the start point position.

• du_x: X component of the du displacement derivative. Defaults to 0.

• du_y: Y component of the du displacement derivative. Defaults to 0.

• dv_x: X component of the dv displacement derivative. Defaults to 0.

• dv_y: Y component of the dv displacement derivative. Defaults to 0.

• type: Whether this is a reference or user guess. Defaults to Reference.

def as_dictionary(self)

Returns a dictionary representation of this start point.

Returns:

• A dict containing all guesses for this start point.

Class StartPointGuess

An initial guess for correlation at a start point for a specific image.

Stores the position and displacement derivatives (du, dv) for the guess.

def set_guess(self, image, pos_x, pos_y, du_x, du_y, dv_x, dv_y, type)

Sets the guess parameters for this start point.

Args:

• image: The image file name this guess applies to.

• pos_x: X coordinate of the start point position.

• pos_y: Y coordinate of the start point position.

• du_x: X component of the du displacement derivative.

• du_y: Y component of the du displacement derivative.

• dv_x: X component of the dv displacement derivative.

• dv_y: Y component of the dv displacement derivative.

• type: Whether this is a reference or user guess.

def as_dictionary(self)

Returns a dictionary representation of this guess.

Returns:

• A dict with image name, guess values, and guess type.

Module vicpyx.extensions.transformation_object

Class TransformationObject

A rigid transformation (rotation + translation) that can be serialized to JSON.

Extends RigidTransformation with dictionary serialization for use in extension output.

def as_dictionary(self)

Returns a dictionary representation of this transformation.

Returns:

• A dict with ‘t’ (translation) and ‘r’ (rotation angles).

Module vicpyx.vicpy

Function change_file_extension

def change_file_extension(full_file_name, extension)

Returns the Vic data file name with the requested extension.

Changes the file extension to the requested one. It supports file names for both out files and dataset saved in HDF5 files.

Args:

• full_file_name: The file name of the Vic data file. Also supports H5 name encoding

• extension: The desired file extension

Returns:

• The file name with the requested extension

Enum AngleType

• Rad
• Deg

Enum CsDataSystemType

• Type2d
• Type3d

Enum RTClientMessageType

• DATA
• ANALOG_DATA

Enum TensorType

• LagrangeStrainTensor
• HenckyStrainTensor
• EulerStrainTensor
• LogarithmicEulerTensor
• EngineeringStrain
• BiotStrainTensor

Enum VicDataVariableType

• PixelCoordinate
• GlobalCoordinate
• PixelDisplacement
• GlobalDisplacement
• Strain
• Correlation
• Unknown
• Disparity
• CylinderCoordinate
• CylinderDisplacement
• PixelVelocity
• GlobalVelocity
• StrainRate
• Curvature
• Angle
• AngularVelocity
• GlobalAcceleration
• PixelAcceleration
• Stress
• AngularAcceleration

Class AOIPolygon

Implements a polygon with cutouts used to define AOIs.

This class is used to define an AOI polygon that can include holes. It also defines the subset and step sizes used during correlation.

def set_outline(self, outline)

Sets the polygon outline.

Args:

• outline: A list of x, y coordinates that define a point in the outline of the polygon

def set_cutouts(self, cutouts)

Sets the polygon cutouts.

Args:

• cutouts: A list of lists of x, y coordinates that define a point in the outline of a cutout

def add_cutout(self, cutout)

Adds a cutout to the polygon.

Args:

• cutout: A list of x, y coordinates that define a point in the outline of a cutout

def set_subset_size(self, subset_size)

Sets the subset size for the AOI.

Args:

• subset_size: The subset size. Should be between 9 and 151

def set_step_size(self, step_size)

Sets the step size for the AOI.

Args:

• step_size: The step size. Should be between 1 and 30.

Class ProjectCalibration

Holds a Vic-3D project’s calibration data.

def read_calibration(self, project_file)

Reads the project calibration from an xml etree object

Args:

• project_file: The project file as an xml.etree.Element

def write_calibration(self, project_file)

Writes the project calibration to an xml etree object.

Args:

• project_file: The project file as an xml.etree Element

def triangulate(self, position_left, position_right)

Triangulates a 3D point from its image coordinates

Args:

• position_left: A tuple or a list of size 2 representing the pixel position in the left image

• position_right: A tuple or a list of size 2 representing the pixel position in the right image

Returns:

• A tuple or list of size 3 representing the triangulated position in world coordinates

def project(self, world_position)

Computes the projection of a 3D point into the camera coordinate systems

Args:

• world_position: A tuple or a list of size 3 representing a world position

Returns:

• A tuple or list of size (2, 2) representing the camera positions. Left camera first followed by the right

def ray(self, camera_id, pixel_position)

Computes the ray for a specific pixel position and camera

Args:

• camera_id: The camera id. Should be either 0 or 1

• pixel_position: A tuple or a list of size 2 representing the pixel position

Returns:

• A tuple or list of size (2, 3) representing the origin and direction of the ray

def intrinsic_matrix(self, camera_id)

Returns the intrinsic matrix for the selected camera

Args:

• camera_id: The camera id. Should be either 0 or 1

def extrinsic_matrix(self, camera_id)

Returns the extrinsic matrix for the selected camera

Args:

• camera_id: The camera id. Should be either 0 or 1

def radial_distortion(self, camera_id)

Returns the radial distrortion coefficients for the selected camera. Only valid for pinhole camera models

Args:

• camera_id: The camera id. Should be either 0 or 1

def tangential_distortion(self, camera_id)

Returns the tangential distrortion coefficients for the selected camera. Only valid for pinhole camera models

Args:

• camera_id: The camera id. Should be either 0 or 1

def prismatic_distortion(self, camera_id)

Returns the prismatic distrortion coefficients for the selected camera. Only valid for pinhole camera models

Args:

• camera_id: The camera id. Should be either 0 or 1

Class ProjectFile

Implements reading and writing some basic components of a Vic-3D project.

def reset(self)

Resets the state of the object.

def is_empty(self)

Checks if the object is initialized.

def create_project_file(self, file_name, project_directory=None)

Creates a new project file.

The file is only created in memory. Call save_project to save it.

Args:

• file_name: The file name for the project file

• project_directory: The porject directory. If not set, it will default to the directory of the file_name

def set_project_file_name(self, file_name)

Sets the project file name.

Args:

• file_name: The project file name.

def load(self, source)

Loads a project from a Vic-3D project file.

Args:

• source: The Vic-3D project file.

def save_project(self, file_name=None)

Saves the project file

Args:

• file_name: Optional file name used for saving. If not set it will use the existing file name.

def get_data_files(self)

Returns the list of data files.

def set_data_files(self, data_files)

Sets the list of data files.

Args:

• data_files: The data file list.

def get_deformed_images(self)

Returns the list of deformed images.

def set_deformed_images(self, deformed_images)

Sets the list of deformed images.

Args:

• deformed_images: The list of deformed images.

def get_reference_image(self)

Returns the reference image.

def set_reference_image(self, reference_image)

Sets the reference image.

Args:

• reference_image: The reference image.

def get_project_calibration(self)

Returns the project calibration.

def set_project_calibration(self, project_calibration)

Sets the project calibration.

Args:

• project_calibration: The project calibration as a ProjectCalibration object.

def get_startpoints(self)

Returns the list of startpoints.

def add_startpoint(self)

Adds a new startpoint.

Returns:

• The name of the new startpoint.

def set_startpoint_guess(
    self,
    start_point,
    image_name,
    position,
    du,
    dv,
)

Sets a startpoint guess for the image

Args:

• start_point: The name of the startpoint. This should be either from get_startpoints or add_startpoint.

• image_name: The image for the guess.

• position: The position of the guess in the image coordinates as a tuple or list.

• du: The u derivative as a tuple or list

• dv: The v derivative as a tuple or list

def get_aoi_polygon_masks(self)

Returns the list of AOIPolygon masks.

def set_aoi_polygon_masks(self, masks, width, height)

Sets the AOIPolygon masks

Args:

• masks: The list of AOIPolygon masks.

• width: The image width.

• height: The image height.

def get_analog_data_csv(self)

Returns the analog data csv as a dictionary.

The dictionary has a key ‘header’ that contains the csv header and then a key for each element in the header.

Class RTClient

Implements a real time server client.

This class is used to connect to a Vic-3D/Vic-2D instance working in realtime mode and forward the desired data to any connected handlers.

def register_handler(self, message_type, handler)

Register handler for different message type.

Usage example: client.register_handler(RTClientMessageType.DATA, lambda data_i, cs_data_set: print(f”Received data: {data_i}“))

Args:

• message_type: Message type to handle.

• handle: Function to handle the specified message type.

def connect(self)

Connects to the server.

def disconnect(self)

Disconnects from the server.

def request_start_data_streaming(self)

Request start streaming VicDataSet files.

def request_stop_data_streaming(self)

Request stop streaming VicDataSet files.

def request_analog_data_while_streaming(self)

Request streaming analog data (in JSON format) along with data files.

Class RigidTransformation

Implements a three dimensional rigid transformation.

def rotation(self)

Returns the rotation for this rigid transformation.

def translation(self)

Returns a tuple of the translation for this rigid transformation.

def set_rotation(self, rotation)

Sets the rotation for this rigid transformation.

Args:

• rotation: The rotation.

def set_translation(self, translation)

Sets the translation for this rigid transformation.

Args:

• translation: The translation as a tuple or list.

def matrix(self)

Returns the 4x4 rigid transformation matrix.

def apply(self, point)

Applies the rigid transformation to the point

Args:

• point: A tuple or list, with a size of 3.

Returns:

• A tuple or a list of the transformed point.

def invert(self)

Inverts this rigid transformation.

def plane_fit(self, dataset, ignore_displacement=False)

Computes the best plane fit for a dataset.

If successful, this rigid body transformation object will be set to the computed transformation.

Args:

• dataset: The VicDataSet to process.

• ignore_displacement: If True, the displacement will be ignored.

Returns:

• True if successful

def from_displacement(self, dataset)

Computes the rigid transformation between the reference and deformed state of the dataset.

If successful, this rigid body transformation object will be set to the computed transformation.

Args:

• dataset: The VicDataSet to process.

Returns:

• A tuple with a boolean to show operation success and the residual

Class Rotation

Implements a three dimensional rotation.

def angles(self, angle_type=AngleType.Deg)

Get the angles of the rotation object.

Args:

• angle_type: Type of angle output

Returns:

• A tuple of the Cardan-Bryant angles.

def set_angles(
    self,
    alpha=0,
    beta=0,
    gamma=0,
    angle_type=AngleType.Deg,
)

Sets the rotation angles.

Args:

• alpha: Rotation around x

• beta: Rotation around y

• gamma: Rotation around z

• angle_type: Type of angle input

def matrix(self)

Returns the 3x3 rotation matrix.

def set_matrix(self, mat)

Sets the rotation using a 3x3 rotation matrix.

Args:

• mat: The 3x3 rotation matrix

def load_identity(self)

Sets the rotation to identity.

def apply(self, point)

Applies the rotation to the point

Args:

• point: A tuple or list, with a size of 3.

Returns:

• A tuple or a list of the rotated point.

Class VicData

Holds all the data for an AOI in a VicDataSet.

This class should be used if you want to work on a specific AOI only. In most cases, working with a VicDataSet is prefered since that includes and affects the whole dataset.

def clear(self)

Clears this object of all data.

def copy(self)

Returns a copy of this.

def num_rows(self)

Returns the number of rows in the data matrix.

def num_columns(self)

Returns the number of columns in the data matrix.

def num_variables(self)

Returns the number of variables in the data matrix.

def matrix_size(self)

Returns the size of the data matrix.

def current_data_type(self)

Returns the type of the data.

def variable_name(self, n)

Returns the name of a variable.

Args:

• n: The index of the variable to look up.

Returns:

• The name of the variable.

def variable_description(self, n)

Returns the description of a variable.

Args:

• n: The index of the variable to look up.

Returns:

• The description of the variable.

def variable_type(self, n)

Returns the type of a variable.

Args:

• n: The index of the variable to look up.

Returns:

• The type of the variable.

def variable_index(self, variable)

Returns the index of a variable specified by its name.

Args:

variable: The variable to search for.

Returns:

• int : Position in the array if found, else -1.

def find_minimum(self, variable_index)

Returns the minimum value and its position for a given variable in the dataset.

Args:

• variable_index: The variable to search over. Can be the variable name or index.

Returns:

• A tuple with the minimum value and the position of the minimum for the variable.

def find_maximum(self, variable_index)

Returns the maximum value and its position for a given variable in the dataset.

Args:

• variable_index: The variable to search over. Can be the variable name or index.

Returns:

• A tuple with the maximum value and the position of the maximum for the variable.

def value(self, n, variable_index)

Returns the value of a variable at a specific position.

Args:

• n: The position to look up.

• variable_index: The index of the variable.

Returns:

• The value of the variable at position n.

def as_array(self, variables)

def get_values(self, variables)

Returns a numpy array of a set of variables.

Args:

• variables: List of variable names.

Returns:

• A numpy array of the values found.

def values(self, n, variable_ids)

Returns the values of a set of variables at a specific position.

Args:

• n: The position to lookup.

• variable_ids: The variables to lookup specified by index.

Returns:

• A list of the values found.

def set_value(self, n, variable_index, value)

Sets the value of a variable at a specific position.

Args:

• n: The position to set the value.

• variable_index: The variable to change. Can be the variable name or index.

• value: The value to set

def set_values(self, variable_index, values)

Sets all the values of a variable.

Args:

• variable_index: The variable to change. Can be the variable name or index.

• values: The values to set.

def clear_search_trees(self)

Clears the search trees used in at_global_xy. Call this method if you edited any data in this VicData

def at_global_xy(self, x, y, variable_list, use_tree=False)

Returns the values of a set of variables at a specific global position.

Args:

• x: The x coordinate of the global position to lookup.

• y: The y coordinate of the global position to lookup.

• variable_list: The variables to lookup. Can be the variable name or index.

• use_tree: If true, the first call will construct a search tree to speed up future searches.

Returns:

• A list of the values found or None if nothing is found.

def lookup_variables(self, x, y, variable_list)

Returns the values of a set of variables at a specific pixel position.

Args:

• x: The x coordinate of the global position to lookup.

• y: The y coordinate of the global position to lookup.

• variable_list: The variables to lookup specified by their name.

Returns:

• A list of the values found or None if nothing is found.

Class VicDataSet

Holds all the Vic data in a data file.

This is the main data class. It has access and can modify all the different AOIs in a dataset. It is an iterable class that returns all VicData for each AOI in the dataset.

def copy(self)

Returns a copy of this.

def current_data_type(self)

Returns the type of the data.

def load_from_data(self, buffer, file_name)

Loads data from a byte array into this object.

Args:

• buffer: The memory buffer data to load from.

• file_name: Dataset file name.

def load(self, file_name)

Loads a Vic-3D data file into this object.

Args:

• file_name: The file to load. Can be the path to an out file or a dataset in an HDF5 file

def save(self, file_name=None)

Saves the VicDataSet to an out file or HDF5 dataset.

Args:

• file_name: The name of the file to save this VicDataSet. To save in an hdf5 file, the file name

• should follow the format ‘path/to/file.h5:out:index’, where index is the dataset index.

def variables(self)

Returns a list of variables.

def variable_descriptions(self)

Returns a list of variables descriptions.

def variable_types(self)

Returns a list of the variables types.

def set_variable_description(self, variable, variable_description)

Changes the description for the specified variable

Args:

• variable: The variable whose description to change

• variable_descritpion: The variable description

def export_raw(self)

Returns the raw data of the VicDataSet in the Vic-3D format.

def file_name(self)

Returns VicDataSet file name or None if empty.

def set_file_name(self, file_name)

Sets the file name of this VicDataSet.

def reference_image(self)

Returns the reference image file name.

def set_reference_image(self, file_name)

Sets the reference image file name.

def deformed_image(self)

Returns the deformed image file name.

def set_deformed_image(self, file_name)

Sets the deformed image file name.

def num_data(self)

Returns the number of AOI in the dataset.

def data(self, n)

Returns the data for the requested AOI.

Args:

• n: The index of the AOI to access.

Returns:

• A VicData object for the selected AOI in the dataset.

def matrix_size(self)

Returns the combined size of all AOIs.

def get_values(self, variables)

Returns a numpy array for the variables for all AOIs.

The triangulation() function returns indices into this array.

Args:

• variables: List of variable names.

Returns:

• A numpy array of the values found.

def set_values(self, variables)

Sets the values for an existing variable in the dataset.

Args:

• variables: Dictionary or numpy structured array of variables with the values to set

def triangulation(self, sub_sample=1)

Returns a triangulation for the dataset.

Args:

• sub_sample: Sub-sampling value for data reduction.

Returns:

• A n-by-3 numpy array of triangle indices, where n is the number of triangles.

def range(self, variable)

Returns the range of values for a variable.

def sum_range(self, variable_0, variable_1)

Returns the range of the sum of two variables.

def add_variables(self, variables)

Adds new variables to every AOI contained in the dataset.

Args:

• variables: Name to description dictionary of the variables to add.

Returns:

• A list of the unique variable names assigned to the variables.

def add_variable(
    self,
    variable_name,
    variable_description,
    variable_type=VicDataVariableType.Unknown,
    values=[],
)

Adds a variable to all AOIs in the dataset.

Args:

• variable_name: Name of the variable to add.

• variable_description: Description of the variable to add.

• variable_type: Variable type.

• values: List of values for the new variable.

Returns:

• The unique variable name assigned to the variable.

def delete_variable(self, variable_name)

Deletes variable from all AOIs in the dataset.

Cannot delete any of the required variables:

[‘X’, ‘Y’, ‘Z’,

‘U’, ‘V’, ‘W’,

‘sigma’,

‘x’, ‘y’,

‘u’, ‘v’,

‘q’, ‘r’,

‘q_ref’, ‘r_ref’,

‘x_c’, ‘y_c’,

‘u_c’, ‘v_c’]

Args:

• variable_name: Name of the variable to delete

def compute_strain(
    self,
    window_size=15,
    tensor_type=TensorType.LagrangeStrainTensor,
    compute_principal_strain=True,
    reuse_variables=True,
    compute_tresca=False,
    compute_von_mises=False,
    output_gradient=False,
    add_size_to_decription=True,
    displacement_variables=[],
    suffix=None,
)

Computes the strain over all AOIs in the dataset.

Args:

• window_size: The window size

• tensor_type: The tensor type

• compute_principal_strain: If True, principal strains will also be computed

• reuse_variables: If True and the dataset has the strain variables computed, the old ones will be replaced

• compute_tresca: If True, the Tresca strain will also be computed

• compute_von_mises: If True, the Von Mises strain will also be computed

• output_gradient: If True, the gradients will also be computed

• add_size_to_decription: If True, the window size is added to the description of the strain variables

• displacement_variables: A vector of two or three that defines the variables that should be used as the displacement variables. The order must be X, Y and Z-axis displacements

• suffix: Optional suffix to be used in variable names and descriptions. Should only contain alphanumericals and underscores Returns:

• A dictionary with all the variables created. The possible dictionary keys are

• [exx, exy, eyy, fxx, fxy, fyx, fyy, e1, e2, gamma, tresca, vonmises]

def compute_curvature(
    self,
    window_size=15,
    compute_principal_curvature=True,
    reuse_vars=True,
    weighted_filter=True,
)

Computes the curvature over all AOIs in the dataset.

Args:

• window_size: The window size

• compute_principal_curvature: If True, principal curvature will also be computed.

• reuse_variables: If True and the dataset has the curvature variables computed, the old ones will be replaced

• weighted_filter: If True, a weighted filter will be used

def smooth(self, variable, window_size=15, weighted=True)

Applies smoothing to a variable

Args:

• variable: The variable to smooth

• window_size: The window size

• weighted: If True, a weighted filter will be used

def transform(self, rigid_transformation, displacement_only=False)

Applies a transformation to all AOIs in the dataset.

Args:

• rigid_transformation: The transformation that will be applied

• displacement_only: If True, it will only apply the displacement and will ignore any rotation

def clear_search_trees(self)

Clears the search trees used in at_global_xy. Call this method if you edited any data in this VicDataSet

def at_global_xy(self, x, y, variable_list, use_tree=False)

Returns the values of a set of variables at a specific global position.

Args:

• x: The x coordinate of the global position to lookup.

• y: The y coordinate of the global position to lookup.

• variable_list: The variables to lookup. Can be the variable name or index.

• use_tree: If true, the first call will construct a search tree to speed up future searches.

Returns:

• A list of the values found or None if nothing is found.

def lookup_variables(self, x, y, variable_list)

Returns the values of a set of variables at a specific pixel position.

Args:

• x: The x coordinate of the pixel position to lookup.

• y: The y coordinate of the pixel position to lookup.

• variable_list: The variables to lookup specified by their name.

Returns:

• A list of the values found or None if nothing is found.

Class VicDataSetIO

Holds a pair of a VicDataSetReader and a VicDataSetWriter.

This class provides the functionality of both a VicDataSetReader and a VicDataSetWriter. By default, the writer will overwrite the data in the reader source.

def set_reader(self, reader)

def get_data_source(self)

Returns the data source.

def get_dataset_list(self)

Returns the list of all dataset in the source.

def load_from_hdf5(self, h5_file_name)

Loads all available dataset in an HDF5 file.

Args:

• h5_file_name: The path to the HDF5 file.

def load_from_directory(self, directory)

Loads all available dataset in a directory.

Args:

• directory: The path to the directory.

def load_from_project(self, project)

Loads all available dataset in a project.

Args:

• project: The path to the Vic-3D project file.

def dataset(self, dataset_id)

Returns the VicDataSet with the specified name.

Args:

• dataset_name: The dataset name as in the get_dataset_list().

Returns:

• A VicDataSet for the data file.

def set_output(self, output_dest)

Sets the output destination.

Args:

• output_dest: The output destination. It can be either a directory or an HDF5 file.

def set_output_prefix(self, output_prefix)

Sets a string to be used as prefix when saving data

Args:

• output_prefix : The prefix

def save(self, data)

Saves a VicDataSet

Args:

• data: The dataset to save

Class VicDataSetReader

Holds a set of VicDataSet from a source.

This class holds all available datasets from a supported source. Supported sources include directories with out files, HDF5 files, and project files. It also supports global patterns. If the source is a project file, the source will be set to either the directory or HDF5 holding the data.It is an iterable class that returns all VicDataSet in the source.

def get_data_source(self)

Returns the dataset source.

def get_dataset_list(self)

Returns the list of all dataset in the source.

def load_from_hdf5(self, h5_file_name)

Loads all available dataset in an HDF5 file.

Args:

• h5_file_name: The path to the HDF5 file.

def load_from_directory(self, directory)

Loads all available dataset in a directory.

Args:

• directory: The path to the directory.

def load_from_project(self, project)

Loads all available dataset in a project.

Args:

• project: The path to the Vic-3D project file.

def dataset(self, dataset_name)

Returns the VicDataSet with the specified name.

Args:

• dataset_name: The dataset name as in the get_dataset_list().

Returns:

• A VicDataSet for the data file.

Class VicDataSetWriter

Writes VicDataSet to a specified output.

This class provides some convenience methods to write a set of VicDataSet. The output directory or HDF5 file can be set here and will be applied to any VicDataSet saved through this class.

def set_reader(self, reader)

Sets a VicDataSetReader.

The VicDataSetWriter will overwrite the data in the reader.

Args:

• reader: A VicDataSetReader that will specify the output for this writer.

def set_output(self, output_dest)

Sets the output destination.

Args:

• output_dest: The output destination. It can be either a directory or an HDF5 file.

def set_output_prefix(self, output_prefix)

Sets a string to be used as prefix when saving data

Args:

• output_prefix : The prefix

def save(self, data)

Saves a VicDataSet

Args:

• data: The dataset to save