MaskedImage

class menpo.image.masked.MaskedImage(image_data, mask=None, copy=True)

Bases: Image

Represents an n-dimensional k-channel image, which has a mask. Images can be masked in order to identify a region of interest. All images implicitly have a mask that is defined as the the entire image. The mask is an instance of BooleanImage.

Parameters:

image_data : ndarray

The pixel data for the image, where the last axis represents the number of channels.

mask : (M, N) np.bool ndarray or BooleanImage, optional

A binary array representing the mask. Must be the same shape as the image. Only one mask is supported for an image (so the mask is applied to every channel equally).

Default: BooleanImage covering the whole image

copy: bool, optional :

If False, the image_data will not be copied on assignment. If a mask is provided, this also won’t be copied. In general this should only be used if you know what you are doing.

Default False

Raises :

—— :

ValueError :

Mask is not the same shape as the image

as_PILImage()

Return a PIL copy of the image. Scales the image by 255 and converts to np.uint8. Image must only have 1 or 3 channels and be two dimensional.

Returns:

pil_image : PILImage

PIL copy of image as np.uint8

Raises:

ValueError if image is not 2D and 1 channel or 3 channels. :

as_greyscale(mode='luminosity', channel=None)

Returns a greyscale version of the image. If the image does not represent a 2D RGB image, then the ‘luminosity’ mode will fail.

Parameters:

mode : {‘average’, ‘luminosity’, ‘channel’}

‘luminosity’ - Calculates the luminance using the CCIR 601 formula

Y’ = 0.2989 R’ + 0.5870 G’ + 0.1140 B’

‘average’ - intensity is an equal average of all three channels ‘channel’ - a specific channel is used

Default ‘luminosity’

channel: int, optional :

The channel to be taken. Only used if mode is ‘channel’.

Default: None

Returns:

greyscale_image: :class:`MaskedImage` :

A copy of this image in greyscale.

as_histogram(keep_channels=True, bins='unique')

Histogram binning of the values of this image.

Parameters:

keep_channels : bool, optional

If set to False, it returns a single histogram for all the channels of the image. If set to True, it returns a list of histograms, one for each channel.

Default: True

bins : ‘unique’, positive int or sequence of scalars, optional

If set equal to ‘unique’, the bins of the histograms are centered on the unique values of each channel. If set equal to a positive integer, then this is the number of bins. If set equal to a sequence of scalars, these will be used as bins centres.

Default: ‘unique’

Returns:

hist : array or list with n_channels arrays

The histogram(s). If keep_channels=False, then hist is an array. If keep_channels=True, then hist is a list with len(hist)=n_channels.

bin_edges : array or list with n_channels arrays

An array or a list of arrays corresponding to the above histograms that store the bins’ edges. The result in the case of list of arrays can be visualized as:

for k in range(len(hist)):

plt.subplot(1,len(hist),k) width = 0.7 * (bin_edges[k][1] - bin_edges[k][0]) center = (bin_edges[k][:-1] + bin_edges[k][1:]) / 2 plt.bar(center, hist[k], align=’center’, width=width)

Raises:

ValueError :

Bins can be either ‘unique’, positive int or a sequence of scalars.

as_vector(**kwargs)

Returns a flattened representation of the object as a single vector.

Returns:

vector : (N,) ndarray

The core representation of the object, flattened into a single vector. Note that this is always a view back on to the original object, but is not writable.

classmethod blank(shape, n_channels=1, fill=0, dtype=<Mock object at 0x7f5c2e9e4950>, mask=None)

Returns a blank image

Parameters:

shape : tuple or list

The shape of the image. Any floating point values are rounded up to the nearest integer.

n_channels: int, optional :

The number of channels to create the image with

Default: 1

fill : int, optional

The value to fill all pixels with

Default: 0

dtype: numpy datatype, optional :

The datatype of the image.

Default: np.float

mask: (M, N) boolean ndarray or :class:`BooleanImage` :

An optional mask that can be applied to the image. Has to have a

shape equal to that of the image.

Default: all True BooleanImage

Returns:

blank_image : MaskedImage

A new masked image of the requested size.

Notes

Subclasses of MaskedImage need to overwrite this method and explicitly call this superclass method:

super(SubClass, cls).blank(shape,**kwargs)

in order to appropriately propagate the SubClass type to cls.

build_mask_around_landmarks(patch_size, group=None, label='all')

Restricts this image’s mask to be equal to the convex hull around the landmarks chosen.

Parameters:

patch_shape: tuple :

The size of the patch. Any floating point values are rounded up to the nearest integer.

group : string, Optional

The key of the landmark set that should be used. If None, and if there is only one set of landmarks, this set will be used.

Default: None

label: string, Optional :

The label of of the landmark manager that you wish to use. If ‘all’ all landmarks are used.

Default: ‘all’

constrain_landmarks_to_bounds()

Move landmarks that are located outside the image bounds on the bounds.

constrain_mask_to_landmarks(group=None, label='all', trilist=None)

Restricts this image’s mask to be equal to the convex hull around the landmarks chosen.

Parameters:

group : string, Optional

The key of the landmark set that should be used. If None, and if there is only one set of landmarks, this set will be used.

Default: None

label: string, Optional :

The label of of the landmark manager that you wish to use. If no label is passed, the convex hull of all landmarks is used.

Default: None

trilist: (t, 3) ndarray, Optional :

Triangle list to be used on the landmarked points in selecting the mask region. If None defaults to performing Delaunay triangulation on the points.

Default: None

constrain_points_to_bounds(points)

Constrains the points provided to be within the bounds of this image.

Parameters:

points: (d,) ndarray :

points to be snapped to the image boundaries

Returns:

bounded_points: (d,) ndarray :

points snapped to not stray outside the image edges

copy()

Return a new image with copies of the pixels, landmarks, and masks of this image.

This is an efficient copy method. If you need to copy all the state on the object, consider deepcopy instead.

Returns:

image: :map:`MaskedImage` :

A new image with the same pixels, mask and landmarks as this one, just copied.

crop(min_indices, max_indices, constrain_to_boundary=False)

Return a cropped copy of this image using the given minimum and maximum indices. Landmarks are correctly adjusted so they maintain their position relative to the newly cropped image.

Parameters:

min_indices : (n_dims, ) ndarray

The minimum index over each dimension

max_indices : (n_dims, ) ndarray

The maximum index over each dimension

constrain_to_boundary : boolean, optional

If True the crop will be snapped to not go beyond this images boundary. If False, an ImageBoundaryError will be raised if an attempt is made to go beyond the edge of the image.

Default: True

Returns:

cropped_image : type(self)

A new instance of self, but cropped.

Raises:

ValueError :

min_indices and max_indices both have to be of length n_dims. All max_indices must be greater than min_indices.

ImageBoundaryError :

Raised if constrain_to_boundary is False, and an attempt is made to crop the image in a way that violates the image bounds.

crop_inplace(min_indices, max_indices, constrain_to_boundary=True)

Crops this image using the given minimum and maximum indices. Landmarks are correctly adjusted so they maintain their position relative to the newly cropped image.

Parameters:

min_indices: (n_dims, ) ndarray :

The minimum index over each dimension

max_indices: (n_dims, ) ndarray :

The maximum index over each dimension

constrain_to_boundary: boolean, optional :

If True the crop will be snapped to not go beyond this images boundary. If False, a ImageBoundaryError will be raised if an attempt is made to go beyond the edge of the image.

Default: True

Returns:

cropped_image : type(self)

This image, but cropped.

Raises:

ValueError :

min_indices and max_indices both have to be of length n_dims. All max_indices must be greater than min_indices.

ImageBoundaryError :

Raised if constrain_to_boundary is False, and an attempt is made to crop the image in a way that violates the image bounds.

crop_to_landmarks_inplace(group=None, label='all', boundary=0, constrain_to_boundary=True)

Crop this image to be bounded around a set of landmarks with an optional n_pixel boundary

Parameters:

group : string, Optional

The key of the landmark set that should be used. If None, and if there is only one set of landmarks, this set will be used.

Default: None

label : string, Optional

The label of of the landmark manager that you wish to use. If ‘all’ all landmarks in the group are used.

Default: ‘all’

boundary : int, Optional

An extra padding to be added all around the landmarks bounds.

Default: 0

constrain_to_boundary : boolean, optional

If True the crop will be snapped to not go beyond this images boundary. If False, an :map`ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.

Default: True

Returns:

image : Image

This image, cropped to it’s landmarks.

Raises:

ImageBoundaryError :

Raised if constrain_to_boundary is False, and an attempt is made to crop the image in a way that violates the image bounds.

crop_to_landmarks_proportion_inplace(boundary_proportion, group=None, label='all', minimum=True, constrain_to_boundary=True)

Crop this image to be bounded around a set of landmarks with a border proportional to the landmark spread or range.

Parameters:

boundary_proportion : float

Additional padding to be added all around the landmarks bounds defined as a proportion of the landmarks’ range. See the minimum parameter for a definition of how the range is calculated.

group : string, Optional

The key of the landmark set that should be used. If None, and if there is only one set of landmarks, this set will be used.

Default: None

label : string, Optional

The label of of the landmark manager that you wish to use. If ‘all’ all landmarks in the group are used.

Default: ‘all’

minimum : bool, Optional

If True the specified proportion is relative to the minimum value of the landmarks’ per-dimension range; if False w.r.t. the maximum value of the landmarks’ per-dimension range.

Default: True

constrain_to_boundary : boolean, optional

If True, the crop will be snapped to not go beyond this images boundary. If False, an ImageBoundaryError will be raised if an attempt is made to go beyond the edge of the image.

Default: True

Returns:

image : Image

This image, cropped to it’s landmarks with a border proportional to the landmark spread or range.

Raises:

ImageBoundaryError :

Raised if constrain_to_boundary is False, and an attempt is made to crop the image in a way that violates the image bounds.

crop_to_true_mask(boundary=0, constrain_to_boundary=True)

Crop this image to be bounded just the True values of it’s mask.

Parameters:

boundary: int, Optional :

An extra padding to be added all around the true mask region.

Default: 0

constrain_to_boundary: boolean, optional :

If True the crop will be snapped to not go beyond this images boundary. If False, a ImageBoundaryError will be raised if an attempt is made to go beyond the edge of the image. Note that is only possible if boundary != 0.

Default: True

Raises:

ImageBoundaryError :

Raised if constrain_to_boundary is False, and an attempt is made to crop the image in a way that violates the image bounds.

from_vector(vector, n_channels=None)

Takes a flattened vector and returns a new image formed by reshaping the vector to the correct pixels and channels. Note that the only region of the image that will be filled is the masked region.

On masked images, the vector is always copied.

The n_channels argument is useful for when we want to add an extra channel to an image but maintain the shape. For example, when calculating the gradient.

Note that landmarks are transferred in the process.

Parameters:

vector : (n_pixels,)

A flattened vector of all pixels and channels of an image.

n_channels : int, optional

If given, will assume that vector is the same shape as this image, but with a possibly different number of channels

Default: Use the existing image channels

Returns:

image : MaskedImage

New image of same shape as this image and the number of specified channels.

from_vector_inplace(vector, copy=True)

Takes a flattened vector and updates this image by reshaping the vector to the correct pixels and channels. Note that the only region of the image that will be filled is the masked region.

Parameters:

vector : (n_parameters,)

A flattened vector of all pixels and channels of an image.

copy: `bool`, optional :

If False, the vector will be set as the pixels with no copy made. If True a copy of the vector is taken.

Default: True

Raises:

Warning : If copy=False cannot be honored.

gaussian_pyramid(n_levels=3, downscale=2, sigma=None, order=1, mode='reflect', cval=0)

Return the gaussian pyramid of this image. The first image of the pyramid will be the original, unmodified, image.

Parameters:

n_levels : int

Number of levels in the pyramid. When set to -1 the maximum number of levels will be build.

Default: 3

downscale : float, optional

Downscale factor.

Default: 2

sigma : float, optional

Sigma for gaussian filter. Default is 2 * downscale / 6.0 which corresponds to a filter mask twice the size of the scale factor that covers more than 99% of the gaussian distribution.

Default: None

order : int, optional

Order of splines used in interpolation of downsampling. See scipy.ndimage.map_coordinates for detail.

Default: 1

mode : {‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’}, optional

The mode parameter determines how the array borders are handled, where cval is the value when mode is equal to ‘constant’.

Default: ‘reflect’

cval : float, optional

Value to fill past edges of input if mode is ‘constant’.

Default: 0

Returns:

image_pyramid: :

Generator yielding pyramid layers as menpo image objects.

glyph(vectors_block_size=10, use_negative=False, channels=None)

Create glyph of a feature image. If feature_data has negative values, the use_negative flag controls whether there will be created a glyph of both positive and negative values concatenated the one on top of the other.

Parameters:

vectors_block_size: int :

Defines the size of each block with vectors of the glyph image.

use_negative: bool :

Defines whether to take into account possible negative values of feature_data.

gradient(nullify_values_at_mask_boundaries=False)

Returns a MaskedImage which is the gradient of this one. In the case of multiple channels, it returns the gradient over each axis over each channel as a flat list.

Parameters:

nullify_values_at_mask_boundaries : bool, optional

If True a one pixel boundary is set to 0 around the edge of the True mask region. This is useful in situations where there is absent data in the image which will cause erroneous gradient settings.

Default: False :

Returns:

gradient : MaskedImage

The gradient over each axis over each channel. Therefore, the gradient of a 2D, single channel image, will have length 2. The length of a 2D, 3-channel image, will have length 6.

normalize_norm_inplace(mode='all', limit_to_mask=True, **kwargs)

Normalizes this image such that it’s pixel values have zero mean and its norm equals 1.

Parameters:

mode: {‘all’, ‘per_channel’} :

If ‘all’, the normalization is over all channels. If ‘per_channel’, each channel individually is mean centred and normalized in variance.

limit_to_mask: Boolean :

If True, the normalization is only performed wrt the masked pixels. If False, the normalization is wrt all pixels, regardless of their masking value.

normalize_std_inplace(mode='all', limit_to_mask=True)

Normalizes this image such that it’s pixel values have zero mean and unit variance.

Parameters:

mode: {‘all’, ‘per_channel’} :

If ‘all’, the normalization is over all channels. If ‘per_channel’, each channel individually is mean centred and normalized in variance.

limit_to_mask: Boolean :

If True, the normalization is only performed wrt the masked pixels. If False, the normalization is wrt all pixels, regardless of their masking value.

rescale(scale, interpolator='scipy', round='ceil', **kwargs)

A copy of this MaskedImage, rescaled by a given factor.

All image information (landmarks and mask) are rescaled appropriately.

Parameters:

scale : float or tuple

The scale factor. If a tuple, the scale to apply to each dimension. If a single float, the scale will be applied uniformly across each dimension.

round: {‘ceil’, ‘floor’, ‘round’} :

Rounding function to be applied to floating point shapes.

Default: ‘ceil’

kwargs : dict

Passed through to the interpolator. See menpo.interpolation for details.

Returns:

rescaled_image : type(self)

A copy of this image, rescaled.

Raises:

ValueError: :

If less scales than dimensions are provided. If any scale is less than or equal to 0.

rescale_landmarks_to_diagonal_range(diagonal_range, group=None, label='all', interpolator='scipy', round='ceil', **kwargs)

Return a copy of this image, rescaled so that the diagonal_range of the bounding box containing its landmarks matches the specified diagonal_range range.

Parameters:

diagonal_range: :class:`menpo.shape.pointcloud` :

The diagonal_range range that we want the landmarks of the returned image to have.

group : string, Optional

The key of the landmark set that should be used. If None, and if there is only one set of landmarks, this set will be used.

Default: None

label: string, Optional :

The label of of the landmark manager that you wish to use. If ‘all’ all landmarks in the group are used.

Default: ‘all’

interpolator : ‘scipy’, optional

The interpolator that should be used to perform the warp.

round: {‘ceil’, ‘floor’, ‘round’} :

Rounding function to be applied to floating point shapes.

Default: ‘ceil’

kwargs : dict

Passed through to the interpolator. See menpo.interpolation for details.

Returns:

rescaled_image : type(self)

A copy of this image, rescaled.

rescale_to_reference_shape(reference_shape, group=None, label='all', interpolator='scipy', round='ceil', **kwargs)

Return a copy of this image, rescaled so that the scale of a particular group of landmarks matches the scale of the passed reference landmarks.

Parameters:

reference_shape: :class:`menpo.shape.pointcloud` :

The reference shape to which the landmarks scale will be matched against.

group : string, Optional

The key of the landmark set that should be used. If None, and if there is only one set of landmarks, this set will be used.

Default: None

label: string, Optional :

The label of of the landmark manager that you wish to use. If ‘all’ all landmarks in the group are used.

Default: ‘all’

interpolator : ‘scipy’ or ‘c’, optional

The interpolator that should be used to perform the warp.

round: {‘ceil’, ‘floor’, ‘round’} :

Rounding function to be applied to floating point shapes.

Default: ‘ceil’

kwargs : dict

Passed through to the interpolator. See menpo.interpolation for details.

Returns:

rescaled_image : type(self)

A copy of this image, rescaled.

resize(shape, interpolator='scipy', **kwargs)

Return a copy of this image, resized to a particular shape. All image information (landmarks, the mask in the case of MaskedImage) is resized appropriately.

Parameters:

shape : tuple

The new shape to resize to.

interpolator : ‘scipy’ or ‘c’, optional

The interpolator that should be used to perform the warp.

Default: ‘scipy’

kwargs : dict

Passed through to the interpolator. See menpo.interpolation for details.

Returns:

resized_image : type(self)

A copy of this image, resized.

Raises:

ValueError: :

If the number of dimensions of the new shape does not match the number of dimensions of the image.

set_masked_pixels(pixels, copy=True)

Update the masked pixels only to new values.

Parameters:

pixels: ndarray :

The new pixels to set.

copy: `bool`, optional :

If False a copy will be avoided in assignment. This can only happen if the mask is all True - in all other cases it will raise a warning.

Raises:

Warning : If the copy=False flag cannot be honored.

smoothing_pyramid(n_levels=3, downscale=2, sigma=None, mode='reflect', cval=0)

Return the smoothing pyramid of this image. The first image of the pyramid will be the original, unmodified, image.

Parameters:

n_levels : int

Number of levels in the pyramid. When set to -1 the maximum number of levels will be build.

Default: 3

downscale : float, optional

Downscale factor.

Default: 2

sigma : float, optional

Sigma for gaussian filter. Default is 2 * downscale / 6.0 which corresponds to a filter mask twice the size of the scale factor that covers more than 99% of the gaussian distribution.

Default: None

mode : {‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’}, optional

The mode parameter determines how the array borders are handled, where cval is the value when mode is equal to ‘constant’.

Default: ‘reflect’

cval : float, optional

Value to fill past edges of input if mode is ‘constant’.

Default: 0

Returns:

image_pyramid: :

Generator yielding pyramid layers as menpo image objects.

view(**kwargs)

View the object using the default rendering engine figure handling. For example, the default behaviour for Matplotlib is that all draw commands are applied to the same figure object.

Parameters:

kwargs : dict

Passed through to specific rendering engine.

Returns:

viewer : Renderer

The renderer instantiated.

view_new(**kwargs)

View the object on a new figure.

Parameters:

kwargs : dict

Passed through to specific rendering engine.

Returns:

viewer : Renderer

The renderer instantiated.

view_on(figure_id, **kwargs)

View the object on a a specific figure specified by the given id.

Parameters:

figure_id : object

A unique identifier for a figure.

kwargs : dict

Passed through to specific rendering engine.

Returns:

viewer : Renderer

The renderer instantiated.

warp_to(template_mask, transform, warp_landmarks=False, warp_mask=False, interpolator='scipy', **kwargs)

Warps this image into a different reference space.

Parameters:

template_mask : BooleanImage

Defines the shape of the result, and what pixels should be sampled.

transform : Transform

Transform from the template space back to this image. Defines, for each pixel location on the template, which pixel location should be sampled from on this image.

warp_landmarks : bool, optional

If True, warped_image will have the same landmark dictionary as self, but with each landmark updated to the warped position.

Default: False

warp_mask : bool, optional

If True, sample the image.mask at all template_image points, setting the returned image mask to the sampled value within the masked region of `template_image`.

Default: False

Note

This is most commonly set True in combination with an all True template_mask, as this is then a warp of the image and it’s full mask. If template_mask has False mask values, only the True region of the mask will be updated, which is rarely the desired behavior, but is possible for completion.

interpolator : ‘scipy’, optional

The interpolator that should be used to perform the warp.

Default: ‘scipy’

kwargs : dict

Passed through to the interpolator. See menpo.interpolation for details.

Returns:

warped_image : type(self)

A copy of this image, warped.

centre

The geometric centre of the Image - the subpixel that is in the middle.

Useful for aligning shapes and images.

Type:(n_dims,) ndarray

has_landmarks_outside_bounds

Indicates whether there are landmarks located outside the image bounds.

Type:bool

height

The height of the image.

This is the height according to image semantics, and is thus the size of the first dimension.

Type:int

indices

Return the indices of all true pixels in this image.

Type:(n_dims, n_true_pixels) ndarray

masked_pixels

Get the pixels covered by the True values in the mask.

Type:(mask.n_true, n_channels) ndarray

n_channels

The number of channels on each pixel in the image.

Type:int

n_dims

The number of dimensions in the image. The minimum possible n_dims is 2.

Type:int

n_elements

Total number of data points in the image (prod(shape) x n_channels)

Type:int

n_landmark_groups

The number of landmark groups on this object.

Type:int

n_parameters

The length of the vector that this object produces.

Type:int

n_pixels

Total number of pixels in the image (prod(shape))

Type:int

shape

The shape of the image (with n_channel values at each point).

Type:tuple

width

The width of the image.

This is the width according to image semantics, and is thus the size of the second dimension.

Type:int