Image IO

This section describes how to load images, how to create examples, and how to perform basic image manipulations. Basic image io is done via ITK.

Contents

• Image IO
  • fileio
  • Example generation
  • Image sampling
  • Image manipulations

fileio

Helper functions to take care of all the file IO

class mermaid.fileio.FileIO

Abstract base class for file i/o.

datatype_conversion = None

Automatically convers the datatype to the default_data_type when loading or writing

replace_nans_with_zeros = None

If NaNs are detected they are automatically replaced by zeroes

turn_nan_to_zero_conversion_on()

turn_nan_to_zero_conversion_off()

is_turn_nan_to_zero_conversion_on()

turn_datatype_conversion_on()

Turns the automatic datatype conversion on :return: n/a

turn_datatype_conversion_off()

Turns the automatic datatype conversion off :return: n/a

is_datatype_conversion_on()

Returns True if automatic datatype conversion is on (default), otherwise False :return: True if dataype conversion is on otherwise False

set_default_datatype(dtype)

Sets the default data type that will be used if data_type_conversion is on :param dtype: standard dataype (e.g., ‘float16’, ‘float32’) :return: n/a

get_default_datatype()

Get the default data type :return: default data type

read(filename)

Abstract method to read a file

Parameters:filename – file to be read Returns:Will return the read file and its header information (as a tuple; im,hdr)

write(filename, data, hdr=None)

Abstract method to write a file

Parameters:

• filename – filename to write the data to
• data – data array that should be written (will be converted to numpy on the fly if necessary)
• hdr – optional header information for the file (in form of a dictionary)

Returns:

n/a

class mermaid.fileio.ImageIO

Class to read images. All the image reading should be performed via this class. In this way everything will be read and processed consistently.

intensity_normalize_image = None

False)

Type:Intensity normalizes an image after reading (default

squeeze_image = None

squeezes the image when reading; e.g., dimension 1x256x256 becomes 256x256

adaptive_padding = None

padding the img to favorable size default img.shape%adaptive_padding = 0

normalize_spacing = None

normalized spacing so that the aspect ratio remains and the largest extent is in [0,1]

scale_vectors_on_read_and_write = None

When writing vector fields (for example maps), the vectors in the field are scaled back to original world coordinates. When reading they are scaled if the spacing is being normalized. Should be turned off when trying to read or write vector-valued images that do not represent maps or displacement fields.

turn_scale_vectors_on_read_and_write_on()

turn_scale_vectors_on_read_and_write_off()

set_scale_vectors_on_read_and_write(val)

get_scale_vectors_on_read_and_write()

turn_normalize_spacing_on()

Turns the normalized spacing (to interval [0,1]) on. :return: n/a

turn_normalize_spacing_off()

Turns the normalized spacing (to interval [0,1]) off. :return: n/a

set_normalize_spacing(normalize_spacing)

Sets if spacing should be normalized [0,1] or not. :param norm_spacing: True/False :return: n/a

get_normalize_spacing()

Returns the setting if spacing should be normalized [0,1] or not. :return: n/a

turn_intensity_normalization_on()

Turns on intensity normalization on when loading an image

turn_intensity_normalization_off()

Turns on intensity normalization off when loading an image

set_intensity_normalization(int_norm)

Set if intensity normalization should be on (True) or off (False)

Parameters:int_norm – image intensity normalization on (True) or off (False)

set_adaptive_padding(adaptive_padding)

if adaptive_padding != -1 adaptive padding on padding the img to favorable size e.g img.shape%adaptive_padding = 0 padding size should be bigger than 3, to avoid confused with channel :param adaptive_padding: :return: n/a

get_intensity_normalization()

Returns if image will be intensity normalized when loading

Returns:Returns True if image will be intensity normalized when loading

turn_squeeze_image_on()

Squeezes the image when loading

turn_squeeze_image_off()

Does not squeeze image when loading

set_squeeze_image(squeeze_im)

Set if image should be squeezed (True) or not (False)

Parameters:squeeze_im – squeeze image on (True) or off (False)

get_squeeze_image()

Returns if image will be squeezed when loading

Returns:Returns True if image will be squeezed when loading

read(filename, intensity_normalize=False, squeeze_image=False, normalize_spacing=True, adaptive_padding=-1, verbose=False, silent_mode=False)

Reads the image assuming it is a single channel

Parameters:

• filename – filename to be read
• intensity_normalize – uses image intensity normalization
• squeeze_image – squeezes image first (e.g, from 1x128x128 to 128x128)
• normalize_spacing – normalizes spacing so largest extent is in [0,1]
• silent_mode – if True, suppresses output

Returns:

Will return the read file, its header information, the spacing, and the normalized spacing (as a tuple: im,hdr,spacing,squeezed_spacing)

read_batch_to_nc_format(filenames, intensity_normalize=False, squeeze_image=False, normalize_spacing=True, silent_mode=False)

Wrapper around read_to_nc_format which allows to read a whole batch of images at once (as specified in filenames) and returns the image in format NxCxXxYxZ. An individual image is assumed to have a single intensity channel.

Parameters:

• filenames – list of filenames to be read or expression with wildcard
• intensity_normalize – if set to True uses image intensity normalization
• squeeze_image – squeezed individual image first (e.g, from 1x128x128 to 128x128)
• normalize_spacing – normalizes the spacing so the largest extent is [0,1]
• silent_mode – if True, suppresses output

Return Will return the read files, their header information, their spacing, and their normalized spacing (as a tuple:  

im,hdr,spacing,squeezed_spacing). The assumption is that all files have the same header and spacing. So only one is returned for the entire batch.

read_to_nc_format(filename, intensity_normalize=False, squeeze_image=False, normalize_spacing=True, silent_mode=False)

Reads the image assuming it is single channel and of XxYxZ format and convert it to NxCxXxYxC format

Parameters:

• filename – filename to be read
• intensity_normalize – if set to True uses image intensity normalization
• squeeze_image – squeezes image first (e.g, from 1x128x128 to 128x128)
• normalize_spacing – normalizes the spacing to [0,1] in largest dimension
• silent_mode – if True, suppresses output

Returns:

Will return the read file, its header information, the spacing, and the normalized spacing (as a tuple: im,hdr,spacing,squeezed_spacing)

read_to_map_compatible_format(filename, map, intensity_normalize=False, squeeze_image=False, normalize_spacing=True)

Reads the image and makes sure it is compatible with the map. If it is not it tries to fix the format.

Parameters:

• filename – filename to be read
• map – map which is used to determine the format
• intensity_normalize – if set to True uses image intensity normalization
• squeeze_image – squeezes image first (e.g, from 1x128x128 to 128x128)
• normalize_spacing – normalizes the spacing to [0,1] in largest dimension

Returns:

Will return the read file, its header information, the spacing, and the normalized spacing (as a tuple: im,hdr,spacing,squeezed_spacing)

write_batch_to_individual_files(filenames, data, hdr=None)

Takes a batch of images in the NxCxXxYxZ format and writes them out as individual files. Currently an image can only have one channel, i,e., C=1. :param filenames: either a list of filenames (one for each N) or one filename which will then be written out with different indices. :param data: image data in NxCxXxYxZ format :param hdr: optional hrd, all images will get the same :return: n/a

write(filename, data, hdr=None)

Abstract method to write a file

Parameters:

• filename – filename to write the data to
• data – data array that should be written (will be converted to numpy on the fly if necessary)
• hdr – optional header information for the file (in form of a dictionary)

Returns:

n/a

class mermaid.fileio.GenericIO

Generic class to read nrrd images. More or less legacy. Use should be avoided if at all possible

read(filename)

Abstract method to read a file

Parameters:filename – file to be read Returns:Will return the read file and its header information (as a tuple; im,hdr)

write(filename, data, hdr=None)

Abstract method to write a file

Parameters:

• filename – filename to write the data to
• data – data array that should be written (will be converted to numpy on the fly if necessary)
• hdr – optional header information for the file (in form of a dictionary)

Returns:

n/a

class mermaid.fileio.MapIO

To read and write maps or displacement fields.

read_from_validation_map_format(filename)

write(filename, data, hdr)

Abstract method to write a file

Parameters:

• filename – filename to write the data to
• data – data array that should be written (will be converted to numpy on the fly if necessary)
• hdr – optional header information for the file (in form of a dictionary)

Returns:

n/a

write_to_validation_map_format(filename, data, hdr)

Example generation

Package to create example images to test the image registration algorithms

class mermaid.example_generation.CreateExample(dim)

Abstract base class.

dim = None

Spatial dimension

create_image_pair(sz=None, params=None)

Abstract method to create example image pairs

Parameters:params – Dictionary which contains parameters to create the images Returns:Will return two images

class mermaid.example_generation.CreateSquares(dim, add_noise_to_bg=False)

Class to create two example squares in arbitrary dimension as registration test cases

create_image_pair(sz, params)

Creates two square images in dimensions 1-3

Parameters:

• sz – Desired size, e.g., [5,10]
• params – Parameter dictionary. Uses ‘len_s’ and ‘len_l’ to define the side-length of the small and the large squares which will be generated

Returns:

Returns two images of squares and the spacing (I0,I1,spacing)

class mermaid.example_generation.CreateRealExampleImages(dim=2, s_path=None, t_path=None)

Class to create two example brain images. Currently only supported in 2D

create_image_pair(sz=None, params=None)

Loads the two brain images using SimpleITK, normalizes them so that the 95-th percentile is as 0.95 and returns them.

Parameters:

• sz – Ignored
• params – Ignored

Returns:

Returns the two brain slices.

Image sampling

Package to allow for resampling of images, for example to support multi-scale solvers.

Todo

skimage in version 0.14 (not officially released yet, supports 3D up- and downsampling. Should replace this class with the skimage functionality once officially available.

class mermaid.image_sampling.ResampleImage

This class supports image resampling, both based on a scale factor (implemented via skimage’s zoom functionality) and to a fixed size (via custom interpolation). For multi-scaling the fixed size option is preferred as it gives better control over the resulting image sizes. In particular using the scaling factors consistent image sizes cannot be guaranteed when down-/up-sampling multiple times.

set_iter(nrIter)

Sets the number of smoothing iterations done after upsampling and before downsampling. The default is 0, i.e., no smoothing at all.

Parameters:nrIter – number of iterations Returns:no return arguments

get_iter()

Returns the number of iterations

Returns:number of smoothing iterations after upsampling and before downsampling

upsample_image_to_size(I, spacing, desiredSize, spline_order, zero_boundary=False)

Upsamples an image to a given desired size

Parameters:

• I – Input image (expected to be of BxCxXxYxZ format)
• spacing – array describing the spatial spacing
• desiredSize – array for the desired size (excluding B and C, i.e, 1 entry for 1D, 2 for 2D, and 3 for 3D)

Returns:

returns a tuple: the upsampled image, the new spacing after upsampling

downsample_image_to_size(I, spacing, desiredSize, spline_order, zero_boundary=False)

Downsamples an image to a given desired size

Parameters:

• I – Input image (expected to be of BxCxXxYxZ format)
• spacing – array describing the spatial spacing
• desiredSize – array for the desired size (excluding B and C, i.e, 1 entry for 1D, 2 for 2D, and 3 for 3D)

Returns:

returns a tuple: the downsampled image, the new spacing after downsampling

upsample_image_by_factor(I, spacing, scalingFactor=0.5)

Upsamples an image based on a given scale factor

Parameters:

• I – Input image (expected to be of BxCxXxYxZ format)
• spacing – array describing the spatial spacing
• scalingFactor – scaling factor, e.g., 2 scales all dimensions by two

Returns:

returns a tuple: the upsampled image, the new spacing after upsampling

downsample_image_by_factor(I, spacing, scalingFactor=0.5)

Downsamples an image based on a given scale factor

Parameters:

• I – Input image (expected to be of BxCxXxYxZ format)
• spacing – array describing the spatial spacing
• scalingFactor – scaling factor, e.g., 0.5 scales all dimensions by half

Returns:

returns a tuple: the downsampled image, the new spacing after downsampling

upsample_vector_field_by_factor(v, spacing, scalingFactor=0.5)

Upsamples a vector field based on a given scale factor

Parameters:

• v – Input vector field (expected to be of BxCxXxYxZ format)
• spacing – array describing the spatial spacing
• scalingFactor – scaling factor, e.g., 2 scales all dimensions by two

Returns:

returns a tuple: the upsampled vector field, the new spacing after upsampling

downsample_vector_field_by_factor(v, spacing, scalingFactor=0.5)

Downsamples a vector field based on a given scale factor

Parameters:

• v – Input vector field (expected to be of BxCxXxYxZ format)
• spacing – array describing the spatial spacing
• scalingFactor – scaling factor, e.g., 0.5 scales all dimensions by half

Returns:

returns a tuple: the downsampled vector field, the new spacing after downsampling

mermaid.image_sampling.test_me()

Convenience testing function (to be converted to a test)

mermaid.image_sampling.test_me_2()

Convenience testing function (to be converted to a test)

Image manipulations

Various methods to manipulate images

class mermaid.image_manipulations.IntensityNormalizeImage

default_normalization_mode = None

Default intensity normalization method

max_normalization(I)

percentile_normalization(I, perc=99.0)

Linearly normalized image intensities so that the 95-th percentile gets mapped to 0.95; 0 stays 0 :param I: input image :param perc: desired percentile :return: returns the normalized image

default_intensity_normalization(I)

Intensity normalizes an image using the default intensity normalization method :param I: input image :return: intensity normalized image