Step 1 helper functions

Contains a set of functions used to assist with the preprocessing and computation steps in step1_atlas_registration.py

step1_help.clip(I)

Any pixel greater than 1, set to 1 and any pixel less than 0, set to 0

Parameters:

I (numpy.ndarray) – An image whose pixel values are expected to lie in the range [0,1], but may have some pixels slightly out of that range

Returns:

I – An image whose pixel values lie in the range [0,1]

Return type:

numpy.ndarray

step1_help.draw_stack(Js, xJs, fig=None, **kwargs)

This function generates a matplotlib.pyplot.fig of size len(xJs) x 3 where the ith row shows the coronal, axial, and sagittal planes of the data stored in xJs[i].

Parameters:

  • Js (list) – A list of N 3D images, where the ith image is size N(slices)_i x N(row)_i x N(col)_i

  • xJs (list) – A list of the voxel locations for every image in the list Js, where the ith element is a list of 3 elements. The first element of the triple of the triple contains the location of each slice, in a 1D array of length N(slices)_i. The second element of the triple contains the location of each row, in a 1D array of lengt N(rows)_i. The third element of the triple contains the location of each col, in a 1D array of lengt N(cols)_i

  • fig (matplotlib.pyplot.fig) – A figure on which to overlay additional visualizations.

  • kwargs (list) – Additional arguments to modify how xJs and Js are visualized on fig; These arguments are passed on to ax.imshow()

Returns:

A figure of size len(xJs) x 3 displaying the coronal, axial, and sagittal planes of the data stored in xJs

Return type:

matplotlib.pyplot.fig

step1_help.gA_from_gid(gid, A)

This is a helper function that computes a metric tensor on the space of affine transformation matrices at the location, A, as a function of the metric tensor at the location, Identity. This approach allows us to perform natural gradient descent and choose a single stepp size for linear and translation parameters during optimization. See “An optical flow based left-invariant metric for natural gradient descent in affine image registration” (https://doi.org/10.3389/fams.2021.718607)

Parameters:

  • gid (torch.tensor) – A 12x12 matrix representing an inner product between tangent vectors to the affine transformation group at Identity

  • A (torch.tensor) – A 4x4 affine transformation matrix describing the point on the affine transformation group that we want to pull back our inner product to

Returns:

gA – A 12x12 matrix representing an inner product between tangent vectors to the affine transformation group at the point, A

Return type:

torch.tensor

step1_help.small_to_big(a)

The composition of two affine transforms A and B as 4x4 matrices with 12 parameters each, can be written as matrix multiplication A@B. i.e., the matrix B can be vectorized into a 12x1 vector, and the matrix A can be matrixized into a 12x12 matrix. Then the same operation could be written as A_big @ B_vector. This is used when computing the components of a metric tesor for affine transformations, which is a 12x12 matrix.

Parameters:

a (torch.tensor) – A 4x4 affine transformation matrix

Returns:

A – A 12x12 affine transformation matrix, written in the alternative format (As described above)

Return type:

torch.tensor

step1_help.str_to_2D_mat(mat)

Converts a string of the form [[x,x,x,x],[x,x,x,x],[x,x,x,x],[x,x,x,x]] into a 4x4 matrix, where each x represents a number

Parameters:

mat (str) – A string of the form [[x,x,x,x],[x,x,x,x],[x,x,x,x],[x,x,x,x]], where each x is a scalar

Returns:

out_arr – A 4x4 matrix whose elements were extracted from ‘mat’

Return type:

torch.tensor

step1_help.trapezoid(x, i, J, dI, dslice)

Models the cutting of a big piece of tissue into a thin slab. In order to make the operation differentiable, we multiply the image by a trapezoid instead of a rectangle. This function defines the trapezoid by which we will multiply the image. This is an example of a processing step described in projective LDDMM. See “Projective diffeomorphic mapping of molecular digital pathology with tissue MRI” (https://doi.org/10.1038/s44172-022-00044-1)

Parameters:

  • x (torch.tensor) – An nd-array that stores the slice location of each voxel in a volume

  • i (int) – The index of the slice to be processed

  • J (numpy.ndarray) – An array of all the 3D slice data in Anterior-Posterior order

  • dI (numpy.ndarray) – The resolution of the atlas along each of the 3 axes

  • dslice (float) – The thickness of the slice to be processed in microns

Returns:

out – The trapezoid by which we will multiply an image

Return type:

torch.tensor