Modules¶

Together with the scripts, a series of modules are provided. Each module contains a series of functions for image processing which are used during the script developing. The modules are the following, each of them provides a different kind of functions.

Utils¶

This modules provides all the functions to read and write images in a medical image format like ‘.nrrd’ or ‘.nifti’. All the formats supported by SimpleITK are allowed.

utils._read_dicom_series(filedir)[source]¶

Define and initialize the SimpleITK reader for the image series

Parameters: filedir (str) – path to the directory that contains the DICOM series
Returns: imgs – initialized, but not executed, reader for the DICOM series
Return type: SimpleITK image series reader

utils._read_image(filename)[source]¶

Define and initialize the SimpleITK image reader

Parameters: filename (str) – Path to the image file
Returns: image_array – initialized image reader
Return type: sitk reader

utils.deep_copy(image)[source]¶

Return a copy of the input image

Parameters: image (SimpleITK image) – Image to Copy
Returns: copy – copy of the input image
Return type: SimpleITK image

utils.load_pickle(filename)[source]¶

Load the pickle image file

Parameters: filename (str) – filename or path to load the file as pickle
Returns: data – array loaded from the given file
Return type: array_like

utils.normalize(image)[source]¶

Rescale each GL according to the mean and std of the whole image Will raise ZeroDivisionError if the provided image has constant pixel GL.

Parameters: image (SimpleITK image object) – image to normalize
Returns: normalized – normalized image
Return type: SimpleITK image

utils.read_image(filename)[source]¶

Read an image or a series from a format supported by SimpleITK.

Parameters: filename (str) – Path to the image file, each format supported by SimpleITK is allowed. To load a DICOM series, provide the path to the directory containing only the .dcm files for the single series
Returns: volume – Image red from the input file
Return type: SimpleITK image

Example

>>> from CTLungSeg.utils import read_image
>>>
>>> path = 'dicom/series/path/
>>> # load a DICOM series
>>> dicom = read_image(path)
>>> # load a Nifti image
>>> filename = 'path/to/nifti/file.nii'
>>> image = read_image(filename)

utils.save_pickle(filename, data)[source]¶

Save the image tensor as pickle

Parameters

filename (str) – file name or path to dump as pickle file
data (array-like) – image or stack to save

utils.shift_and_crop(image)[source]¶

Ensure that the air peak of HU is centerd on -1000 and shift it to reach 0. After that, ensure that the maximum HU value is +2048

Parameters: image (SimpleITK image) – image or stack of images, each pixel value must be expressed in hounsfield units (HU)
Returns: centered – image or stack of images in whch the air value in HU is shifted to zero
Return type: SimpleITK image

utils.shuffle_and_split(data, number_of_subarrays)[source]¶

Shuffle the input array and divide it into number_of_subarrays sub-arrays

Parameters

data (array-like) – input sample to divide
number_of_subarrays (int) – number of subsamples

Returns

out – list of random subsamples

Return type

list of array-like

utils.write_volume(image, output_filename)[source]¶

Write the image volume in a specified format. Each format supported by SimpleITK is supported. .. note: It does not write as .dcm series.

Parameters

image (SimpleITk image file) – image to write
output_filename (str) – output filename

Example

>>> from CTLungSeg.utils import read_image, write_volume
>>>
>>> input_file = 'path/ti/input/image'
>>> image = read_image(input_file)
>>> # process the image
>>> # write the image as nrrd
>>> output_name = 'path/to/output/filename.nrrd'
>>> write_volume(image, output_name)
>>> #or write the image as nifti
>>>  output_name = 'path/to/output/filename.nii'
>>> write_volume(image, output_name)

Method¶

This module contains the implementation of all the filter used for the processing of images inside the script. The functions are based on SimpleITK methods

method.adaptive_histogram_equalization(image, radius)[source]¶

Apply the histogram equalization in a neighbourhood of each voxel.

Parameters

image (SimpleITK image) –
radius (int > 0) – neighbourhood radius

Returns

equalized – equalized image or stack of images

Return type

SimpleITK image

method.adjust_gamma(image, gamma=1.0, image_type='HU')[source]¶

Apply a gamma correction on the input image: $GL_{out} = GL_{in}^{gamma}$

Parameters

image (SimpleITK image) – image stack to adjust
gamma (float) – power of the correction
image_type (str) – input data type: can be [‘uint8’, ‘uint16’, ‘HU’].

Returns

out – gamma corected image

Return type

SimpleITK image

method.apply_mask(image, mask, masking_value=0, outside_value=- 1500)[source]¶

Apply a mask to image

Parameters

image (SimpleITK image) – image to mask
mask (SimpleITK image) – image mask

Returns

masked

Return type

SimpleITK image

method.cast_image(image, new_pixel_type)[source]¶

Cast image pixels type to new_pixel_type

Parameters

image (SimpleITK image) – image to cast
new_pixel_type (SimpleITK PixelIDValueEnum) – new pixel type

Returns

casted – image with new pixel type

Return type

SimpleITK image

method.gauss_smooth(image, sigma=1.0)[source]¶

Apply a gaussian smoothing to the input image

Parameters

image (SimpleITK image) – image to smooth
sigma (float) – noise sigma

Returns

smoothed – smoothed image

Return type

SimpleITK image

method.median_filter(img, radius)[source]¶

Apply median blurring filter on the specified image.

Parameters

img (SimleITK image) – image or stack of images to filter
radius (int) – neighbourhood radius. must be greater or equal than 1.

Returns

blurred – median blurred image

Return type

SimpleITK image

Examples

>>> from CTLungSeg.utils import read_image
>>> from CTLungSeg.method import median_filter
>>> # load the DICOM series
>>> seriesname = 'path/to/input/series/'
>>> volume = read_image(seriesname)
>>> # define the kernel size and apply the median filter
>>> radius = 5
>>> filtered = median_blur(volume, radius)

method.std_filter(image, radius)[source]¶

Replace each pixel value with the standard deviation computed on a circular neighbourhood with specified radius

Parameters

image (SimpleITK image) – image to filter
radius (int) – radius of the neighborhood

Returns

filtered – filtered image

Return type

SimpleITK image

method.threshold(image, upper, lower, inside=1, outside=0)[source]¶

Apply an interval threshold to the image

Parameters

image (SimpeITK image) – input image
upper (int) – upper threshold value
lower (int) – lower threshold value
inside (int) – value to assign to the voxels with GL in [lower, upper]
outside (int) – value to assign to the voxels with GL outside [lower, upper]

Returns

thr – thresholded image

Return type

SimpleITK image

method.vesselness(image)[source]¶

Apply Frangi filter to find the likelihood of image regions to contains vessels (tubular structures)

Parameters: image (SimpleITK image) –
Returns: vesseness_map
Return type: SimpleITK image

Segmentation¶

This module contains the implementation of the functions used to perform the tasks on each script.

Metrics¶

This module contains the implementation of some metrics used to perform the segmentation evaluation.

metrics.accuracy(y_true, y_pred, eps=1e-09)[source]¶

Compute the accuracy score between two samples. Each sample must be a binary numpy array containing only 0 and 1 values. y_true and y_pred must have tha same shape

Parameters

y_true (np.array) – binary array containing the ground truth
y_pred (np.array) – binary array containing the prediction
eps (float) – small floating point value to avoid zero division error

Returns

accuracy – precision score (in [0, 1])

Return type

float

metrics.dice(y_true, y_pred, eps=1e-09)[source]¶

Compute the dice score between two samples.

Each sample must be a binary numpy array containing only 0 and 1 values. y_true and y_pred must have tha same shape

Parameters

y_true (np.array) – binary array containing the ground truth
y_pred (np.array) – binary array containing the prediction
eps (float) – small floating point value to avoid zero division error

Returns

dice – dice score (in [0, 1])

Return type

float

metrics.precision(y_true, y_pred, eps=1e-09)[source]¶

Compute the precision score between two samples as the ratio of true positive and the sum of true positive and false positives.

Each sample must be a binary numpy array containing only 0 and 1 values. y_true and y_pred must have tha same shape

Parameters

y_true (np.array) – binary array containing the ground truth
y_pred (np.array) – binary array containing the prediction
eps (float) – small floating point value to avoid zero division error

Returns

precision – precision score (in [0, 1])

Return type

float

metrics.recall(y_true, y_pred, eps=1e-09)[source]¶

Compute the recall score between two samples as the ratio of true positive and the sum of true positive and false negatives.

Each sample must be a binary numpy array containing only 0 and 1 values. y_true and y_pred must have tha same shape

Parameters

y_true (np.array) – binary array containing the ground truth
y_pred (np.array) – binary array containing the prediction
eps (float) – small floating point value to avoid zero division error

Returns

recall – precision score (in [0, 1])

Return type

float

metrics.specificity(y_true, y_pred, eps=1e-09)[source]¶

Compute the specificity score between two samples as the ratio of true negative and the sum of true negative and false positives.

Each sample must be a binary numpy array containing only 0 and 1 values. y_true and y_pred must have tha same shape

Parameters

y_true (np.array) – binary array containing the ground truth
y_pred (np.array) – binary array containing the prediction
eps (float) – small floating point value to avoid zero division error

Returns

specificity – specificity score (in [0, 1])

Return type

float