API

Documentation for directly using the Python functions.

class tbpcxr.model.Model(reference_size=64, reference_crop=6)

This class is a base class for models of image representations.

The images are registered to an atlas and resampled onto a reference image to make each image a comparable observation vector.

Four states of the image data need to be defined:

  • normalized image: An sitk.Image which has been registered to the image_atlas, resampled onto the space of the image_reference then the intensities normalized.

  • observation vector : A normalized image converted into an array ( np.ndarray ).

  • feature vector: A representation of an image that has been converted into an observation then further reduced.

abstract compute(observation_arr, **kwargs)
Return type:

None

image_atlas

The atlas image which input images are registered too.

This image must have the same physical extent as image_reference

Type:

sitk.Image or None

property image_atlas_cropped
static load_model(name)

Loads a model named in tbpcxr.model_list or a provided filename of a pickled Model object.

This method provides a unified interface for loading Model objects.

Parameters:

name (str) – The name of a model from the tbpcxr module or a path of a pkl file.

Return type:

Model

Returns:

A restored Model object.

static load_outlier_pcamodel()
Return type:

Model

Returns:

A pre-trained PCAModel object to detect outliers or abnormal CXR images.

reference_crop

The reference image, image atlas, and input images are cropped by this amount on each edge for registration, and the PCA feature vector.

property reference_size

The reference image is defined as this number of pixels in each dimension.

register_to_atlas_and_resample(image, verbose=0)

Register to the input images to the atlas image, and resample to the reference image coordinates.

Parameters:

  • image (Image)

  • verbose (int)

Return type:

Image

Returns:

The registered and resampled image.

to_observations(images, verbose=0)
Return type:

ndarray

class tbpcxr.model.PCAModel(reference_size=64, reference_crop=6)

The PCAModel uses Principal Components Analysis to represent a feature space of images.

This class represents a model of an expected image to detect if another image conforms to the model or is an outlier.

compute(observation_arr, **kwargs)

Computes the PCA decomposition, and outlier classifier from the input feature array.

Parameters:

  • observation_arr (ndarray) – A set of images converted to an array of image observation vectors.

  • components

  • contamination

Return type:

None

Returns:

outlier_detector

The trained object used to classify a fitted image as a PCA feature vector.

outlier_predictor(observation_arr, decision=False)

Use the trained PCA and outlier classifier from the compute() to determine if an array of observation vectors are outliers when compared to the input data set.

Parameters:

  • observation_arr (ndarray) – An array of image observations+

  • decision – Returns the results of the decision function, with 0 being the threshold for an outlier.

Return type:

List[int]

Returns:

An array of results of outlier classification, 1 is an inlier and -1 is a classifier.

pca

The PCA decomposition of the cropped input image as a vector.

pca_cov

The object used to estimate the covariance of the training data in the PCA feature space.

residual_images(observation_arr)

Compute the difference between the input observations and reduced PCA representation.

Parameters:

observation_arr (ndarray)

Return type:

List[Image]

Returns:

residuals(observation_arr)

Compute the root mean squared of the difference between the original observation and the restored observation. :type observation_arr: ndarray :param observation_arr: :rtype: float :return:

restored_images(observation_arr)

Compute the reduced PCA representation, then restore observation as an image representation.

Parameters:

observation_arr (ndarray)

Return type:

List[Image]

Returns:

robust_distance(observation_arr)

Compute the Mahalanobis distance in the PCA space for observations

Parameters:

observation_arr (ndarray)

Return type:

float

Returns:

tbpcxr.registration.avg_resample(fixed, images)

Resamples all images onto the fixed image’s a coordinate frame, ignoring the fixed image’s values. The resampled images are accumulated and averaged for the results.

Parameters:

  • fixed (Image)

  • images (Iterable[Image])

Return type:

Image

Returns:

tbpcxr.registration.build_atlas(fixed, images, fixed_crop_percent=0.1, verbose=0, max_iterations=500, register_repeat=2)

Builds an CXR atlas ( average ) by repeatedly registering a list of images to an average, then updating the average.

Parameters:

  • fixed (Image)

  • images (Iterable[Image])

  • fixed_crop_percent

  • verbose

  • max_iterations – The maximum number of iterations per image stage

  • register_repeat – The number of time all the images are registered to the average.

Return type:

Image

Returns:

tbpcxr.registration.cxr_affine(fixed, moving, verbose=0, max_iterations=500)

Perform affine registration between two CXR images. First a 2D similarity transform is optimized then an affine transform.

Parameters:

  • fixed (Image) – The fixed image, sample points are mapped from the fixed image to the moving

  • moving (Image) – The moving image.

  • verbose (int) – 0 - no output, 1 - staged registration results, 2 - output each iteration

  • max_iterations (int) – The maximum number of optimization iteration to perform at each phase.

Return type:

Tuple[Transform, float]

Returns:

Returns tuple of the optimized affine transform mapping points from the fixed image to the moving image, and the final optimized metric value.

tbpcxr.utilities.normalize_img(image, sample_size=64, smoothing_sigma_in_output_pixels=0.75, auto_crop=True)

The input image is resampled with translation and scaling to fit into a unit square centered at the origin. The physical extend of the output is within [-0.5, 0.5]. The aspect ratio of the input image is preserved. The input’s direction cosine matrix is ignored. The image intensities are normalized to a have a mean of 0, and a standard deviation of 1.

Parameters:

  • image (Image) – The input image

  • sample_size (int) – The maximum number of pixels in an axis. It will be less if input’s physical size is not 1:1.

  • smoothing_sigma_in_output_pixels (float) – Before resample Gaussian smoothing is performed, with a sigma equivalent to

  • auto_crop (bool) – If True, the image is cropped to the bounding box of the foreground defined by OtsuThreshold.

Return type:

Image

Returns:

An image

tbpcxr.utilities.read_dcm(filename)

Read an x-ray DICOM file with GDCMImageIO, reducing it to 2D from 3D as needed. Only the SimpleITK GDCM reader is tried.

Parameters:

filename (str) – A DICOM filename

Return type:

Image

Returns:

a 2D SimpleITK Image