API

The autodocumentation for the lsmgridtrack module is provided below.

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:

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

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

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) –