AutoLandmarking.jl Documentation

load_imgs(path, dims, numerical)

Reads all the volume images of an entire directory. Data must be stored as follows: The required input "path" is the path to a directory containing one sub-directory for every volume that has to be read. Each sub-directory contains the images making up one volume in .tif format. if the image names contain alphabetical characters (e.g. image001.tif, image002.tif ect.) the variable "numerical" has to be set to false, if the image names are just numerical values (e.g 1.tif, 2.tif, 3.tif, ect), it has to be set to true. Any file not ending in .tif will not be read.

Data will be stored in a 4D array [a x b c x n] with n being the number of sub-directories, a and b the resolution of the .tif images and c the number of images. The the resolution of the images has to be the same over all the volumes.

read_landmarks(path, num_landmarks, group)

Specific function to read avizo landmark data into an array. Reads all the files ending in .Ascii in the directory specified as "path". Data will be stored in a 2D array [c x n] with c being the number of individual 3D coordinates (30 coordinates in the case of 10 landmarks) and n being the number of landmark files read.

The variable Group specifies the group of landmarks in the Avizo file that has to be read (e.g "@1" in the case of group 1)

flip_volume_front(x, y)

Flip a volume so that the longitudinal (x) axis becomes the vertical (z) axis and adjust the landmakr coordinates accordingly.

flip_volume_side(x, y)

Flip a volume so that the lateral (y) axis becomes the vertical (z) axis and adjust the landmark coordinates accordingly.

function mirror_vol(x, y)

A form of data augmentation. Mirrors a volume (exchanges x and y axis) and returns concatenation of original data and mirrored data.

flip_2D(x, y)

Takes 2D images in a 4D tensor and landmark data in 2D tensor and returns the original images together with the flipped (clockwise) images, aswell as the coordinates for the original and the flipped images.

flip_3D(x, y)

Takes 3D volumes in a 4D tensor and landmark data in 2D tensor and returns the original volumes together with the flipped (clockwise) volumes, aswell as the coordinates for the original and the flipped volumes.

jitter_3D(volumes, landmarks, padding)

Jitters around binarized volumes based on their corresponding x/y landmarks, so that the relevant object (smaller voxel value) will still be fully inside the volume but moved around randomly inside the volume.

rotate_images(img, lms, deg)

Takes a 3d tensor [res1 x res1 x n] with n images and rotates all of them in a counterclockwise direction around their center by deg degrees. Will adjust the 2d coordinates of the landmark array [coords x n]. Returns rotated images and adjusted landmarks.

rotate_volumes(vols, lms, deg)

Takes a 4d tensor [res1 x res2 x res3 x n] with n volumes and rotates all of them around their center by deg degrees. The rotation is along the z-axis, so the z-coordinates will not be affected. x- and y coordinates of the landmark array [coords x n] will be adjusted. Returns rotated volumes and adjusted landmarks.

swap_xy(lms)

Swaps x and y coordinates of a landmark array.

train_test_split_3d(X, y, train_ratio)

Randomly split features and labels with ratio 'train_ratio' and return training and testing set. Takes a 5d tensor as X.

regular_train_test_split_3d(X, y)

split features and labels so that every fifth entry in the original dataset is in the testin set (80/20 split) and return training and testing set. Takes a 5d tensor as X.

landmark_to_surface(volumes, landmarks, radius)

Moves landmarks that are not already on the volume to the closest point to them on the surface of the volume.

image_gradients(x)

Adds the sum of the image gradients in x and y direction for each channel of each image in a 4-dimensional tensor as a new channel.

align_principal(volumes, landmarks, output_size)

Aligns all volumes in tensor "volumes" along their principal axis (new z-axis) and transforms respective landmark data alongside. The output size can be specified with outputsize (a cube with size outputsize^3 will be returned), but must be large enough to contain the largest aligned volume. a median filter will be applied to handle caused by transformation. Also returns a reconstruction array used to translate predicted landmarks back to their original volume.

resize_relevant(vols, lms, out_size)

Takes the output from align_principal and resizes the relevant part (part containing the actual item) to a cube of specified size. Also returns the ratio between resized and original volume size. Adjusts landmarks.

translate_lms_back(lms, reconstruction_array)

Takes an array of predicted landmarks and a reconstruction array as returned by align_principal() and translates the landmarks back to their respective original volume.

choose_dims(y, dims)

choose which dimensions of x,y and z should be included in the labels and return a new array containing only the specified dims.

give_z_value(x)

sets every value outside of the actual volume to 0 and changes the voxel-values of every voxel within the volume to its corresponding z-coordinate. Returns the new tensor with all values normalized between -1 and 1.

make_elevation_map(x)

Returns a 2d image for every volume in tensor x and sets the pixel values to the maximum value within each column of voxels in dimension z as returned by the function givezvalue().

depth_map_all_sides(x)

returns a 4d image tensor with 6 channels per image, each representing a depthmap from one side of the volume.

accuracy(x, y, modell)

calculate euclidean distances between points in y and y' for all samples

print_accuracy(x, y, modell)

calculate and print euclidean distances between points in y and y' for all samples

cost_whole_data(x, y)

calculates cost (as defined by function 'cost') over an entire 5d tensor containing 3d image data.

cost_whole_data_2D(x, y)

calculates cost (as defined by function 'cost') over an entire 4d tensor containing 2d image data.

avg_accuracy_per_point(modelo, x, y, dims)

calculates average, min and max distance between predicted and actual landmarks.

predict_single(model, x)

Returns the output of 'model' in testing mode given input x and applies the relu function to each output. Takes a single sample.

predict_set(X, model)

Returns the output of 'model' in testing mode given input x and applies the relu function to each output. Takes multiple samples.

save_vols_to_folder(folder, vols, names)

Save a 4D tensor containing 3D volumes to a folder, each in its own sub folder, in .tif format.

array_to_lm_file(output_path, coordinates)

Create an avizo landmark file (output_path) with one set of landmarks. The coordinates to these landmarks need to be passed in the form of a one-dimensional array as returned by a network when one volume is given as the input.

response_distribution(model, X, samples)

Takes one sample and returns a distribution of responses for this sample by setting the model to trainmode! and thus enabling the dropout layers.

to_3d_array(arr)

Takes a 2D landmark array for 3 dimensions as input and outputs a 3D array with dimensions [npoints x 3 x nindividuals]

align_all(arr)

Performs procrustes alignment on all the landmarks over all the individuals in a 3D landmark array as returned by the function to3darray().

to_2d_array(arr)

converts a 3D landmark array to a 2D landmark array with dimensions [coordinates x individuals] where coordinates are x,y,z coordinates repeated as many times as there are landmarks.

mean_shape(arr)

finds the mean shape of all teh individuals in a 3D landmark array. Procrustes alignment should be performed before finding the mean.

proc_distance(ref, arr)

returns the procrustes distances to a reference (e.g. the mean shape) for every individual in a 3D landmark array.

procrustes_distance_list(arr, names, exclude_highest=false)

returns the procrustes distances to a reference (e.g. the mean shape) for every individual in a 3D landmark array.

function align(x,y)

aligns two structures [sets of points in 3D space]. Solves the "Procrustes" problem. Structures are expected to be of the same size, and the correspondence is assumed from the vector indices.

Returns x aligned, by performing the rigid body transformation [rotation and translation that minimizes the RMSD between x and y].

x, y, and xnew (return) are matrices of dimensions (n,3) (n is the number of points, 3 is the dimension of the space).

L. Martinez, Institute of Chemistry - University of Campinas Jan 04, 2019