amsaf package

Submodules

amsaf.amsaf module

AMSAF is comprised of several utility functions which wrap SimpleITK and Elastix to facilitate easy registration, transformation, and segmentation of .nii images. It’s core functionality, amsaf_eval, allows for quicker development of Elastix parameter maps by generating and ranking the results of parameter map instances in a caller-defined search space.

amsaf.amsaf.amsaf_eval(unsegmented_image, ground_truth, segmented_image, segmentation, parameter_priors=None, verbose=False, memoize=False)[source]

Main AMSAF functionality

Generate and score new segmentations and corresponding Elastix parameter maps.

Parameters:
  • unsegmented_image (SimpleITK.Image) – The target for segmentation and scoring.
  • ground_truth (SimpleITK.Image) – The segmentation slice of unsegmented_image used as a ground truth to score images generated by AMSAF.
  • segmented_image (SimpleITK.Image) – The image we want to map a segmentation from.
  • segmentation (SimpleITK.Image) – The segmentation corresponding to segmented_image.
  • parameter_priors (dict) – An optional vector of 3 ParameterGrid-style dicts mapping Elastix parameter map keys to lists of values. Each value list will be substituted in for the corresponding key in a default dict so that the caller can specify specific combinations of values for some keys, usually to constrain the search space for testing or time consideration.
  • verbose (bool) – Optional boolean flag to toggle verbose stdout printing from Elastix.
  • memoize (bool) – Optional boolean flag to toggle memoized optimization. Warning: experimental
Returns:

A lazy stream of result (parameter map vector, result segmentation, segmentation score) lists.
Return type:

generator
amsaf.amsaf.crop(img, start, end, padding=False)[source]

Crops image along a bounding box specified by start and end

Parameters:
  • img (SimpleITK.Image) – Image to be cropped
  • start ((int, int, int)) – Tuple consisting of lower valued coordinates to define bounding box
  • end ((int, int, int)) – Tuple consisting of higher valued coordinates to define bounding box
  • padding (bool) – Optional boolean to specify zero padding
Return type:

SimpleITK.Image
amsaf.amsaf.init_affine_transform(img, transform, center=None)[source]

Initializes an affine transform parameter map for a given image.

The transform fits the following format: T(x) = A(x-c) + c + t

Parameters:
  • img (SimpleITK.Image) – Image to be transformed
  • transform (numpy.ndarray) – 4x3 numpy array consisting of affine matrix and a translational vector
  • center ((int, int, int)) – Center of rotation. If none given, geometric center is used
Return type:

dict
amsaf.amsaf.read_image(path, ultrasound_slice=False)[source]

Load image from filepath as SimpleITK.Image

Parameters:
  • path (str) – Path to .nii file containing image.
  • ultrasound_slice – Optional. If True, image will be cast as sitkUInt16 for ultrasound images.
Returns:

Image object from path
Return type:

SimpleITK.Image
amsaf.amsaf.register(fixed_image, moving_image, parameter_maps=None, auto_init=True, verbose=False)[source]

Register images using Elastix.

Parameters:
  • parameter_maps ([SimpleITK.ParameterMap]) – Optional vector of 3 parameter maps to be used for registration. If none are provided, a default vector of [rigid, affine, bspline] parameter maps is used.
  • auto_init (bool) – Auto-initialize images. This helps with flexibility when using images with little overlap.
  • verbose (bool) – Flag to toggle stdout printing from Elastix
Returns:

Tuple of (result_image, transform_parameter_maps)
Return type:

(SimpleITK.Image, [SimpleITK.ParameterMap])
amsaf.amsaf.register_indv(fixed_image, moving_image, transform_type, parameter_map=None, auto_init=True, verbose=False)[source]
Register images using Elastix. Used to perform transforms individually
Namely used for memoization to avoid redundant computation
Parameters:
  • transform_type (String) – Type of tranform to be performed
  • parameter_map (SimpleITK.ParameterMap) – Optional parameter map to be used for registration. If none is provided, a default map based on transform type is used.
  • auto_init (bool) – Auto-initialize images. This helps with flexibility when using images with little overlap.
  • verbose (bool) – Flag to toggle stdout printing from Elastix
Returns:

Tuple of (result_image, transform_parameter_maps)
Return type:

(SimpleITK.Image, [SimpleITK.ParameterMap])
amsaf.amsaf.seg_map(segmented_subject_dir, unsegmented_subject_dir, segmentation_dir, filenames, parameter_maps=None, strict=False)[source]

Intra-subject segmentation mappings from supplied filenames

Parameters:
  • segmented_subject_dir – Directory with data of segmented image
  • unsegmented_subject_dir – Directory with data of unsegmented_image
  • segmentation_dir – Directory with data of segmented image segmentation
  • filenames – Iterable of filenames to map
  • parameter_maps – Optional vector of 3 parameter maps to be used for registration. If none are provided, a default vector of [rigid, affine, bspline] parameter maps is used.
  • strict – Default False. If True, a ValueError will be raised when some filename is not present in every supplied directory.
Return type:

[SimpleITK.Image]

 
>>> us_data = os.path.join(os.path.sep, 'srv', 'ultrasound_data')
>>> sub1 = os.path.join(us_data, 'sub1')
>>> sub2 = os.path.join(us_data, 'sub2')
>>> sub1_trials = os.path.join(sub1, 'trials')
>>> sub2_trials = os.path.join(sub2, 'trials')
>>> sub1_seg = os.path.join(sub1, seg)
>>> sub2_hand_shoulder_seg = seg_map(sub1_trials, sub2_trials, sub1_seg, ['trial18_90_fs_volume.mha'])
amsaf.amsaf.seg_map_all(segmented_subject_dir, unsegmented_subject_dir, segmentation_dir, parameter_maps=None, image_type='volume', strict=False)[source]

Intra-subject segmentation mappings

Like seg_map, but selects all files of image_type in supplied directories as filename selection.

Parameters:
  • segmented_subject_dir – Directory with data of segmented image
  • unsegmented_subject_dir – Directory with data of unsegmented_image
  • segmentation_dir – Directory with data of segmented image segmentation
  • parameter_maps – Optional vector of 3 parameter maps to be used for registration. If none are provided, a default vector of [rigid, affine, bspline] parameter maps is used.
  • image_type – Either ‘volume’ or ‘slice’ corresponding to extensions ‘.mha’ or ‘.nii’, respectively
  • strict – Default False. If True, a ValueError will be raised when some filename is not present in every supplied directory.
Return type:

[SimpleITK.Image]

 
>>> us_data = os.path.join(os.path.sep, 'srv', 'ultrasound_data')
>>> sub1 = os.path.join(us_data, 'sub1')
>>> sub2 = os.path.join(us_data, 'sub2')
>>> sub1_trials = os.path.join(sub1, 'trials')
>>> sub2_trials = os.path.join(sub2, 'trials')
>>> sub1_seg = os.path.join(sub1, seg)
>>> sub2_segs = seg_map_all(sub1_trials, sub2_trials, sub1_seg)
amsaf.amsaf.segment(unsegmented_image, segmented_image, segmentation, parameter_maps=None, verbose=False)[source]

Segment image using Elastix

Parameters:
  • segmented_image (SimpleITK.Image) – Image with corresponding segmentation passed as the next argument
  • segmentation (SimpleITK.Image) – Segmentation to be mapped from segmented_image to unsegmented_image
  • parameter_maps ([SimpleITK.ParameterMap]) – Optional vector of 3 parameter maps to be used for registration. If none are provided, a default vector of [rigid, affine, bspline] parameter maps is used.
  • verbose (bool) – Flag to toggle stdout printing from Elastix
Returns:

Segmentation mapped from segmented_image to unsegmented_image
Return type:

SimpleITK.Image
amsaf.amsaf.split_x(img, midpoint_x, padding=False)[source]

Splits image into two separate images along an x-plane Returns both halves of the image, returning the image with lower x values first

Parameters:
  • img (SimpleITK.Image) – Image to be split
  • midpoint_x (int) – x value specifying plane to split image along
  • padding (bool) – Optional boolean to specify zero padding
Return type:

(SimpleITK.Image, SimpleITK.Image)
amsaf.amsaf.split_y(img, midpoint_y, padding=False)[source]

Splits image into two separate images along an y-plane Returns both halves of the image, returning the image with lower y values first

Parameters:
  • img (SimpleITK.Image) – Image to be split
  • midpoint_y (int) – y value specifying plane to split image along
  • padding (bool) – Optional boolean to specify zero padding
Return type:

(SimpleITK.Image, SimpleITK.Image)
amsaf.amsaf.split_z(img, midpoint_z, padding=False)[source]

Splits image into two separate images along an z-plane Returns both halves of the image, returning the image with lower z values first

Parameters:
  • img (SimpleITK.Image) – Image to be split
  • midpoint_z (int) – z value specifying plane to split image along
  • padding (bool) – Optional boolean to specify zero padding
Return type:

(SimpleITK.Image, SimpleITK.Image)
amsaf.amsaf.top_k(k, amsaf_results)[source]

Get top k results of amsaf_eval

Parameters:
  • k (int) – Number of results to return. If k == 0, returns all results
  • amsaf_results – Results in the format of amsaf_eval return value
Returns:

Top k result groups ordered by score
Return type:

[[SimpleITK.ParameterMap, SimpleITK.Image, float]]
amsaf.amsaf.transform(image, parameter_maps, verbose=False)[source]

Transform an image according to some vector of parameter maps

Parameters:
  • image (SimpleITK.Image) – Image to be transformed
  • parameter_maps ([SimpleITK.ParameterMap]) – Vector of 3 parameter maps used to dictate the image transformation
Returns:

Transformed image
Return type:

SimpleITK.Image
amsaf.amsaf.write_image(image, path)[source]

Write an image to file

Parameters:
  • image (SimpleITK.Image) – Image to be written
  • path (str) – Destination where image will be written to
Return type:

None
amsaf.amsaf.write_result(amsaf_result, path)[source]

Write single amsaf_eval result to path

Writes parameter maps, segmentation, and score of AMSAF result as individual files at path.

Parameters:
  • amsaf_results – Results in the format of amsaf_eval return value
  • path (str) – Filepath to write results at
Return type:

None
amsaf.amsaf.write_top_k(k, amsaf_results, path)[source]

Write top k results to filepath

Results are written as subdirectories “result-i” for 0 < i <= k. Each subdirectory contains the result’s corresponding parameter maps, segmentation, and score.

Parameters:
  • k (int) – Number of results to write. If k == 0, returns all results
  • amsaf_results – Results in the format of amsaf_eval return value
  • path (str) – Filepath to write results at
Return type:

None

amsaf.cli module

Console script for amsaf.

Module contents

Top-level package for amsaf.