Core

This section details the currently implemented base classes available in CAMP, including the Structured Grid and Triangle Mesh objects. The structured grids represent images, fields, look-up tables, or anything that is structured on a grid. The triangle mesh object inherits from an underlying unstructured grid object meant to represent different surfaces. Currently, the only mesh type supported is a triangle mesh, but the unstructured grid object could easily be expanded to include other mesh types, such as quads. This package also provides functions for displaying both structured grid data and triangle mesh objects.

Structured Grid

class StructuredGrid(size, spacing=None, origin=None, device='cpu', dtype=torch.float32, requires_grad=False, tensor=None, channels=1)

This is the base class for grid structured data such as images, look-up tables (luts), vector fields, etc. This class wraps a torch tensor (data attribute) to provide world coordinate system context.

Parameters

• size (list, tuple, tensor) – Size of the grid. Size is ordered [z],y,x ([] is optional).

• spacing (list, tuple, tensor, optional) – Spacing between the grid elements. Default is isotropic 1.0 spacing.

• origin (list, tuple, tensor, optional) – Real world location of the pixel (2D) or voxel (3D) with the minimum location value. The locations of the grid elements increase by the spacing in each relative direction from this voxel. Default pleaces the center of the grid at the origin.

• device (str, optional) – Memory location - one of ‘cpu’, ‘cuda’, or ‘cuda:X’ where X specifies the device identifier. Default: ‘cpu’

• dtype (str, optional) – Data type, specified from torch memory types. Default: ‘torch.float32’

• requires_grad (bool, optional) – Track tensor for gradient operations. Default: False

• tensor (torch.tensor, optional) – The underlying tensor for the data attribute. This allows StructuredGird to be wrapped around alread-exisiting tensors. This tensor must be of size C,[z],y,x where [z],y,x are the same as ‘size’ and C is equal to Channels. If not provided, the data attribute will be initialized to size C,[z],y,x with zeros.

• channels (int) – Number of channels for the grid. For example, black and white images must have 1 channel and RGB images have 3 channels. Channels can be any integer number.

static FromGrid(grid, tensor=None, channels=1)

Construct a new StructuredGrid from a reference StructuredGrid (for the size, spacing, origin, device, dtype, requires_grad) and a torch tensor.

Parameters

• grid (StructuredGrid) – Reference StructuredGrid with the reference attributes.

• tensor (tensor) – Torch tensor to wrap into the new StructuredGrid. Must have size [z],y,x from the reference StructuredGrid and the number of specific channels.

• channels (int) – Channels of the input tensor.

Returns

New StructuredGrid wrapped around the input tensor.

clone()

Create a copy of the StructuredGrid.

Returns

Copy of StructuredGrid.

copy()

Create a copy of the StructuredGrid.

Returns

Copy of StructuredGrid.

extract_slice(index, dim)

Extract a slice from a 3D volume. Updates the origin to maintain the world coordinate system location.

Parameters

• index (int) – Slice index to extract.

• dim (int) – Dimension along which to extract the slice.

Returns

Extracted slice.

get_subvol(zrng=None, yrng=None, xrng=None)

Extract a sub volume. The coordiantes for the sub volume are in index coordiantes. Updates the origin to maintain the world coordinate system location.

Parameters

• zrng (list, tuple, optional) – Tuple or list of 2 values between [0, size[0]]. If no range is provided, the size stays the same.

• yrng (list, tuple, optional) – Tuple or list of 2 values between [0, size[1]]. If no range is provided, the size stays the same.

• xrng (list, tuple, optional) – Tuple or list of 2 values between [0, size[2]]. If no range is provided, the size stays the same.

Returns

Sub volume with updated origin.

max()

Max of the data attribute.

Returns

data.max()

min()

Min of the data attribute.

Returns

data.min()

minmax()

Min and Max of the data attribute.

Returns

[data.min(), data.max()]

set_origin_(origin)

Set the origin. Does not change the spacing.

Parameters

origin (list, tuple, tensor) – New origin.

Returns

None

set_size(size, inplace=True)

Set the size of the StructuredGrid. This will update the spacing and origin of the StructuredGrid to maintain the original real world FOV.

Parameters

• size (torch.tensor) – New size for the StructuredGrid [z],y,x

• inplace (bool) – Perform the resize operation in place. Default=True.

Returns

If inplace==True then returns a new StructuredGrid.

set_spacing_(spacing)

Set the spacing. Does not change the origin.

Parameters

spacing (list, tuple, tensor,) – New spacing.

Returns

None

set_to_identity_lut_()

Set the tensor to an real world identity look-up table (LUT) using the spacing and origin of the StructuredGrid. The number of channels will be set to the number of dimensions in size.

Returns

StructuredGrid as a real world identity LUT.

shape()

Returns the shape of the data attribute, including the channels.

Returns

data.shape

sum()

Sum of the data attribute.

Returns

data.sum()

to_(device)

Change the memory device of the StructuredGrid.

Parameters

device (str, optional) – New memory location - one of ‘cpu’, ‘cuda’, or ‘cuda:X’ where X specifies the device identifier.

Returns

None

to_type_(new_type)

Change the data type of the StructuredGrid attributes.

Parameters

dtype (str, optional) – Data type, specified from torch memory types. Default: ‘torch.float32’

Returns

None

Triangle Mesh

class TriangleMesh(vertices, indices, per_vert_values=None, per_index_values=None)

Triangle mesh class that inherits from the unstructured grid class.

Parameters

• vertices (tensor) – Vertices of the mesh object (x,y,z)

• indices (long tensor) – Indices of the mesh object

• per_vert_values (tensor, optional) – Values associated with each vertex of the triangle mesh.

• per_index_values (str, optional) – Values associated with the indices (or faces) of the triangle mesh.

add_surface_(verts, indices)

Concatenate two triangle mesh objects. This does not connect the two objects with faces, it just concatenates the vertices and indices of the two surfaces into one.

Returns

None

calc_centers(**kwargs)

Caluclate the face centers of the triangle mesh using the vertices and indices to populate the centers attribute.

Returns

None

calc_normals()

Caluclate the face normals of the triangle mesh using the vertices and indices to populate the normals attribute.

Returns

None

flip_normals_()

Flip the face normals.

Returns

None

Display

DispFieldGrid(Field, grid_size=None, title=None, newFig=True, dim='z', slice_index=None)

Displays a grid of the input field. Field is assumed to be a look-up table (LUT) of type StructuredGrid.

Parameters

• Field (StructuredGrid) – Assumed to be a StructuredGrid LUT that defines a transformation.

• grid_size (int) – Number of grid lines to plot in each direction.

• title (str) – Figure Title.

• newFig (bool) – Create a new figure. Default True.

• dim (str) – Dimension along which to plot 3D image. Default is 0 (‘z’).

• slice_index (int) – Slice index along ‘dim’ to plot

Returns

None

DispImage(Image, rng=None, cmap='gray', title=None, new_figure=True, color=False, colorbar=True, axis='default', dim=0, slice_index=None)

Display an image default with a colorbar. If the input image is 3D, it will be sliced along the dim argument. If no slice index is provided then it will be the center slice along dim.

Parameters

• Image (StructuredGrid) – Input Image ([RGB[A]], [Z], Y, X)

• rng (list, tuple) – Display intensity range. Defaults to data intensity range.

• cmap (str) – Matplotlib colormap. Default ‘gray’.

• title (str) – Figure Title.

• new_figure (bool) – Create a new figure. Default True.

• colorbar (bool) – Display colorbar. Default True.

• axis (str) – Axis direction. ‘default’ has (0,0) in the upper left hand corner and the x direction is vertical ‘cart’ has (0,0) in the lower left hand corner and the x direction is horizontal

• dim (int) – Dimension along which to plot 3D image. Default is 0 (z).

• slice_index (int) – Slice index along ‘dim’ to plot

Returns

None

exception DisplayException

exception for this class

DisplayJacobianDeterminant(Field, rng=None, cmap='jet', title=None, new_figure=True, colorbar=True, slice_index=None, dim='z')

Calculated and display the jacobian determinant of a field.

Parameters

• Field (StructuredGrid) – Assumed to be a StructuredGrid LUT that defines a transformation.

• rng (list, tuple) – Display intensity range. Defaults to jacobian determinant intensity range.

• cmap (str) – Matplotlib colormap. Default ‘jet’.

• title (str) – Figure Title.

• new_figure (bool) – Create a new figure. Default True.

• colorbar (bool) – Display colorbar. Default True.

• dim (int) – Dimension along which to plot 3D image. Default is 0 (z).

• slice_index (int) – Slice index along ‘dim’ to plot

Returns

None

EnergyPlot(energy, title='Energy', new_figure=True, legend=None)

Plot energies from registration functions.

Parameters

• energy (list, tuple) – The energies should be in the form [E1list, E2list, E3list, …]

• title (str) – Figure Title.

• new_figure (bool) – Create a new figure. Default True.

• legend (list) – List of strings to be added to the legend in the form [E1legend, E2legend, E3legend, …]

Returns

None

PlotSurface(verts, faces, fig=None, norms=None, cents=None, ax=None, color=(0, 0, 1))

Plot a triangle mesh object.

Parameters

• verts (tensor) – Vertices of the mesh object.

• faces (tensor) – Indices of the mesh object.

• fig (Maplotlib figure object) – Matplotlib figure object to plot the surface on. If one is not provided, and new one is created.

• norms (tensor, optional) – Normals of the mesh object.

• cents (tensor, optional) – Centers of the mesh object.

• ax (Maplotlib axis object) – Matplotlib axis object to plot the surface on. If one is not provided, and new one is created.

• color (tuple) – Plotted color of the surface. Tuple of three floats between 0 and 1 specifying RGB values.

Returns

None