API

The autodocumentation for the lsmgridtrack package is provided below.

Module: config

The config module contains functions and classes for defining analysis settings.

class lsmgridtrack.config.GridOptions(**data)

Options defining the grid used to output calculated results.

Parameters:
divisions: List[int]

Number of grid nodes in each direction

origin: List[int]

Voxel coordinates of grid origin.

upper_bound: List[int]

Voxel position of upper grid bound.

class lsmgridtrack.config.ImageOptions(**data)

Options to set image attributes and behavior.

Parameters:
resampling: Optional[List[float]]

Target physical voxel sizes for resampling.

spacing: List[float]

Physical voxel size of images.

surface_axis: Optional[SurfaceAxis2D]

Image axis to search for sample surface along

class lsmgridtrack.config.Options(**data)

Defines configuration parameters for registration and analysis.

Parameters:
class lsmgridtrack.config.RegMethodEnum(value)

Optimization method to employ in image registration.

class lsmgridtrack.config.RegMetricEnum(value)

Metric to be minimized during registration.

class lsmgridtrack.config.RegSamplingEnum(value)

Image sampling strategy to be used when evaluating metric.

class lsmgridtrack.config.RegistrationOptions(**data)

Options defining the registration procedure.

Parameters:
deformed_landmarks: List[List[int]]

Fiducial voxel coordinates in deformed image.

iterations: int

Maximum number of iterations to perform in optimization.

method: RegMethodEnum

Optimization method to employ for registration

metric: RegMetricEnum

Metric to minimize.

reference_landmarks: List[List[int]]

Fiducial voxel coordinates in reference image.

sampling_fraction: float

Fraction of image to sample when evaluating metric.

sampling_strategy: RegSamplingEnum

Volume sampling method to evaluate optimization metric.

shrink_levels: List[int]

Factors to resample image by in a pyramidal registration. If [1.0] then no pyramid is employed.

sigma_levels: List[float]

Gaussian variance to smooth by at each pyramid level.

class lsmgridtrack.config.SurfaceAxis2D(value)

Axis to search for sample surface along: P suffix indicates to search forwards. N suffix indicates to search backwards.

class lsmgridtrack.config.SurfaceAxis3D(value)

Axis to search for sample surface along: P suffix indicates to search forwards. N suffix indicates to search backwards.

lsmgridtrack.config.parse_config(configuration_file='')

Function to read configration options specified in a JSON file.

Parameters:

configuration_file (str) –

Return type:

Options

Returns:

Module: image

The image module contains functions and classes for reading and writing images, preprocessing the images for use in lsmgridtrack, and quantifying features like the the sample surface.

lsmgridtrack.image.convert_image_to_vtk(img)
Parameters:

img (Image) –

Return type:

vtkImageData

Returns:

lsmgridtrack.image.get_sample_surface2d(img, direction, threshold=0.25, stride=10)
Parameters:
Return type:

vtkPolyData

lsmgridtrack.image.get_sample_surface3d(img, direction, threshold=0.25, stride=10)
Parameters:
Return type:

vtkPolyData

lsmgridtrack.image.parse_image_file(filepath, options)
Parameters:
Return type:

Image

Returns:

lsmgridtrack.image.parse_image_sequence(filepath, options)
Parameters:
Return type:

Image

Returns:

lsmgridtrack.image.write_image_as_nii(img, name='image')
Parameters:

  • img (Image) –

  • name (str) –

Return type:

None

lsmgridtrack.image.write_image_as_vtk(img, name='image')
Parameters:

  • img (Image) –

  • name (str) –

Return type:

None

Module: registration

The registration module contains functions for defining and executing deformable image registration and saving the resulting transform.

lsmgridtrack.registration.create_registration(options, reference_image)
Return type:

ImageRegistrationMethod

Parameters:
Args:

options: Options for the image registration. reference_image: The reference image that will be registered.

Returns:

A SimpleITK ImageRegistrationMethod

lsmgridtrack.registration.register(reg, reference_image, deformed_image)
Return type:

BSplineTransform

Parameters:

  • reg (ImageRegistrationMethod) –

  • reference_image (Image) –

  • deformed_image (Image) –

Args:

reg: The image registration method to execute. reference_image: The reference image to be registered. deformed_image: The deformed image to be registered.

Returns:

The resulting BSplineTransform from the registration.

lsmgridtrack.registration.save_transform(transform, name='transform')
Parameters:

  • transform (Transform) –

  • name (str) –

Return type:

None

Module: kinematics

The kinematics module provides functions for calculating the 3-D displacement field and subsequent kinematic variables on a specified rectilinear grid. These include the deformation gradient, Green-Lagrange strain, principal Green-Lagrange strains, and volumetric strains.

class lsmgridtrack.kinematics.Kinematics(x_coordinates, y_coordinates, z_coordinates, displacements, deformation_gradients, strains, first_principal_strains, second_principal_strains, third_principal_strains, first_principal_strain_directions, second_principal_strain_directions, third_principal_strain_directions, volumetric_strains)

The calculated kinematics.

Parameters:

  • x_coordinates (ndarray) –

  • y_coordinates (ndarray) –

  • z_coordinates (ndarray) –

  • displacements (ndarray) –

  • deformation_gradients (ndarray) –

  • strains (ndarray) –

  • first_principal_strains (ndarray) –

  • second_principal_strains (ndarray) –

  • third_principal_strains (ndarray) –

  • first_principal_strain_directions (ndarray) –

  • second_principal_strain_directions (ndarray) –

  • third_principal_strain_directions (ndarray) –

  • volumetric_strains (ndarray) –

lsmgridtrack.kinematics.convert_kinematics_to_pandas(results)
Parameters:

results (Kinematics) –

Raises:

ValueError –

Return type:

DataFrame

Returns:

lsmgridtrack.kinematics.convert_kinematics_to_vtk(kinematics)
Parameters:

kinematics (Kinematics) –

Raises:

ValueError –

Return type:

vtkRectilinearGrid

Returns:

lsmgridtrack.kinematics.get_kinematics(grid_options, image_options, transform)

Calculate kinematics based on registration transform. Calculates the deformation gradient at element centroids and interpolates to the VTK grid vertices. The Green-Lagrange strain can then be calculated from the deformation gradients. The principal strains are the eigenvalues of the strain tensors directed along the eigenvectors. Assuming Einstein’s summation convention unless explicitly indicated, these calculations are as follows:

Note

Capital and lowercase letters imply reference and deformed configurations, respectively.

\[F^i_{\,J} = \sum_{a=1}^{4} x^i_{\,a}\frac{\partial N_a}{\partial X^J}.\]

We therefore need to determine \(\frac{\partial N_a}{\partial X^J}\). From the chain rule,

\[\frac{\partial N_a}{\partial X^J} = \frac{\partial N_a}{\partial \eta^I} \left (\frac{\partial X^I}{\partial \eta^J} \right)^{-T}\]

where

\[\frac{\partial X^I}{\partial \eta^J} = \sum_{a=1}^{4} X^I_{\,a} \frac{\partial N_a}{\partial \eta^J}.\]

The Green-Lagrange strain tensor then follows as,

\[E_{IJ} = \frac{1}{2}\left(F_I^{\,i} g_{ij} F^j_{\,J} - G_{IJ}\right)\]

where \(g_{ij}\) is the spatial metric tensor and \(G_{IJ}\) is the material metric tensor (both are the identity in Cartesian).

The eigenvalues * eigenvectors of this tensor ordered decreasing by eigenvalue are the principal strains.

The areal strain is,

\[E_{areal} = \det{F^i_{\,J}} - 1.0.\]
Parameters:

  • grid_options (GridOptions) – Options defining properties of the grid.

  • image_options (ImageOptions) – Options defining properties of the registered images.

  • transform (Transform) – The transform calculated by the image registration.

Return type:

Kinematics

Returns:

The kinematics of the grid after deforming with the supplied transform.

lsmgridtrack.kinematics.write_kinematics_to_excel(results, name)

Write the calculated kinematics to an excel file.

Parameters:

  • results (Kinematics) – Calculated Kinematics data object.

  • name (str) – Filename without extension.

lsmgridtrack.kinematics.write_kinematics_to_vtk(data, name='output')
Parameters:
lsmgridtrack.kinematics.write_to_vtk(data, name='output')
Parameters:

  • data (vtkRectilinearGrid) –

  • name (str) –

Module: kinematics2d

The kinematics2d module provides functions for calculating the 2-D displacement field and subsequent kinematic variables on a specified rectilinear grid. These include the deformation gradient, Green-Lagrange strain, principal Green-Lagrange strains, and volumetric strains.

class lsmgridtrack.kinematics2d.Kinematics(x_coordinates, y_coordinates, displacements, deformation_gradients, strains, first_principal_strains, second_principal_strains, first_principal_strain_directions, second_principal_strain_directions, areal_strains)
Parameters:

  • x_coordinates (ndarray) –

  • y_coordinates (ndarray) –

  • displacements (ndarray) –

  • deformation_gradients (ndarray) –

  • strains (ndarray) –

  • first_principal_strains (ndarray) –

  • second_principal_strains (ndarray) –

  • first_principal_strain_directions (ndarray) –

  • second_principal_strain_directions (ndarray) –

  • areal_strains (ndarray) –

lsmgridtrack.kinematics2d.get_kinematics(grid_options, image_options, transform)

Calculate kinematics based on registration transform. Calculates the deformation gradient at element centroids and interpolates to the VTK grid vertices. The Green-Lagrange strain can then be calculated from the deformation gradients. The principal strains are the eigenvalues of the strain tensors directed along the eigenvectors. Assuming Einstein’s summation convention unless explicitly indicated, these calculations are as follows:

Note

Capital and lowercase letters imply reference and deformed configurations, respectively.

\[F^i_{\,J} = \sum_{a=1}^{8} x^i_{\,a}\frac{\partial N_a}{\partial X^J}.\]

We therefore need to determine \(\frac{\partial N_a}{\partial X^J}\). From the chain rule,

\[\frac{\partial N_a}{\partial X^J} = \frac{\partial N_a}{\partial \eta^I} \left (\frac{\partial X^I}{\partial \eta^J} \right)^{-T}\]

where

\[\frac{\partial X^I}{\partial \eta^J} = \sum_{a=1}^{8} X^I_{\,a} \frac{\partial N_a}{\partial \eta^J}.\]

The Green-Lagrange strain tensor then follows as,

\[E_{IJ} = \frac{1}{2}\left(F_I^{\,i} g_{ij} F^j_{\,J} - G_{IJ}\right)\]

where \(g_{ij}\) is the spatial metric tensor and \(G_{IJ}\) is the material metric tensor (both are the identity in Cartesian).

The eigenvalues * eigenvectors of this tensor ordered decreasing by eigenvalue are the principal strains.

The volumetric strain is,

\[E_{volumetric} = \det{F^i_{\,J}} - 1.0.\]
Parameters:

  • grid_options (GridOptions) – Options defining properties of the grid.

  • image_options (ImageOptions) – Options defining properties of the registered images.

  • transform (Transform) – The transform calculated by the image registration.

Return type:

Kinematics

Returns:

The kinematics of the grid after deforming with the supplied transform.

Module: postprocessing

The postprocessing module provides functions to rotate data to new coordinate systems aligned with a provided sample surface geometry.

lsmgridtrack.postprocessing.convert_vtk_to_dataframe(data)

Converts VTK grid to a Pandas dataframe.

Parameters:

data (Union[vtkImageData, vtkRectilinearGrid]) – VTK grid

Return type:

DataFrame

Returns:

Pandas dataframe with vertex coordinates and VTK data arrays.

lsmgridtrack.postprocessing.globally_transform_2d(data, surface)

Rotate tensors stored on VTK grid to align with average orientation of provided surface.

Parameters:

  • data (Union[vtkRectilinearGrid, vtkImageData]) – VTK grid with stored data arrays to rotate

  • surface (vtkPolyData) – Surface to align to.

Return type:

Union[vtkRectilinearGrid, vtkImageData]

Returns:

VTK grid with rotated data.

lsmgridtrack.postprocessing.globally_transform_3d(data, surface)

Rotate tensors stored on VTK grid to align with average orientation of provided surface.

Parameters:

  • data (Union[vtkRectilinearGrid, vtkImageData]) – VTK grid with stored data arrays to rotate

  • surface (vtkPolyData) – Surface to align to.

Return type:

Union[vtkRectilinearGrid, vtkImageData]

Returns:

VTK grid with rotated data.

lsmgridtrack.postprocessing.globally_transform_dataframe_3d(data, surface)

Rotate tensors to align with the average orientation of the provided surface PolyData.

Parameters:

  • data (dict) – Dictionary of Pandas dataframes

  • surface (vtkPolyData) – Surface to align to.

Return type:

dict

Returns:

Dictionary of rotated dataframes.

lsmgridtrack.postprocessing.globally_transform_polydata_coordinates_3d(data, surface)

Transform coordinates of each PolyData in list to align with average orientation of provided surface.

Parameters:

  • data (list[vtkPolyData]) – list of PolyData objects

  • surface (vtkPolyData) – surface to align to.

Return type:

list[vtkPolyData]

Returns:

list of rotated PolyData objects

lsmgridtrack.postprocessing.read_stl(filename)

Read STL file as vtkPolyData

Parameters:

filename (str) –

Return type:

vtkPolyData

Returns:

lsmgridtrack.postprocessing.read_vtk_grid(filename)

Read VTK grid from file.

Parameters:

filename (str) – Path to file.

Raises:

ValueError –

Return type:

Union[vtkRectilinearGrid, vtkImageData]

Returns:

lsmgridtrack.postprocessing.read_vtk_surface(filename)

Read vtkPolyData from file.

Parameters:

filename (str) – Path to file.

Return type:

vtkPolyData

Returns:

lsmgridtrack.postprocessing.transform_dataframe_to_local_csys_3d(data, surface)

Rotate tensors in dataframes to local coordinate systems constructed from the normals and tangent vectors of the nearest point on the provided surface.

Parameters:

  • data (dict) – Dictionary of Pandas dataframes.

  • surface (vtkPolyData) – Surface to align to.

Return type:

dict

Returns:

Dictionary of rotated dataframes.

lsmgridtrack.postprocessing.transform_to_local_csys_2d(data, surface)

Rotate tensors stored on VTK grid to align with orientation of nearest point on provided surface.

Parameters:

  • data (Union[vtkRectilinearGrid, vtkImageData]) – VTK grid with stored data arrays to rotate

  • surface (vtkPolyData) – Surface to align to.

Return type:

Union[vtkRectilinearGrid, vtkImageData]

Returns:

VTK grid with rotated data.

lsmgridtrack.postprocessing.transform_to_local_csys_3d(data, surface)

Rotate tensors stored on VTK grid to align with orientation of nearest point on provided surface.

Parameters:

  • data (Union[vtkRectilinearGrid, vtkImageData]) – VTK grid with stored data arrays to rotate

  • surface (vtkPolyData) – Surface to align to.

Return type:

Union[vtkRectilinearGrid, vtkImageData]

Returns:

VTK grid with rotated data.

lsmgridtrack.postprocessing.write_dataframe_to_excel(data, name)

Write Pandas dataframe or dictionary of dataframes to an Excel file. If dictionary provided each (key, value) will be a new sheet.

Parameters:
lsmgridtrack.postprocessing.write_to_vtk_grid(data, name)

Write VTK RectilinearGrid to file.

Parameters:

  • data (vtkRectilinearGrid) –

  • name (str) –

lsmgridtrack.postprocessing.write_to_vtk_image_data(data, name)

Write VTK ImageData to file

Parameters:

  • data (vtkImageData) –

  • name (str) –

lsmgridtrack.postprocessing.write_to_vtk_polydata(data, name)

Write VTK PolyData to file.

Parameters:

  • data (vtkPolyData) –

  • name (str) –