class menpo.image.MaskedImage(image_data, mask=None, copy=True)[source]

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 ((C, M, N ..., Q) ndarray) – The pixel data for the image, where the first axis represents the number of channels.

• mask ((M, N) 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).

• 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.

Raises

ValueError – Mask is not the same shape as the image

_view_2d(figure_id=None, new_figure=False, channels=None, masked=True, interpolation='bilinear', cmap_name=None, alpha=1.0, render_axes=False, axes_font_name='sans-serif', axes_font_size=10, axes_font_style='normal', axes_font_weight='normal', axes_x_limits=None, axes_y_limits=None, axes_x_ticks=None, axes_y_ticks=None, figure_size=(7, 7))[source]

View the image using the default image viewer. This method will appear on the Image as view if the Image is 2D.

Returns

• figure_id (object, optional) – The id of the figure to be used.

• new_figure (bool, optional) – If True, a new figure is created.

• channels (int or list of int or all or None) – If int or list of int, the specified channel(s) will be rendered. If all, all the channels will be rendered in subplots. If None and the image is RGB, it will be rendered in RGB mode. If None and the image is not RGB, it is equivalent to all.

• masked (bool, optional) – If True, only the masked pixels will be rendered.

• interpolation (See Below, optional) – The interpolation used to render the image. For example, if bilinear, the image will be smooth and if nearest, the image will be pixelated. Example options

{none, nearest, bilinear, bicubic, spline16, spline36,
hanning, hamming, hermite, kaiser, quadric, catrom, gaussian,
bessel, mitchell, sinc, lanczos}

• cmap_name (str, optional,) – If None, single channel and three channel images default to greyscale and rgb colormaps respectively.

• alpha (float, optional) – The alpha blending value, between 0 (transparent) and 1 (opaque).

• render_axes (bool, optional) – If True, the axes will be rendered.

• axes_font_name (See Below, optional) – The font of the axes. Example options

{serif, sans-serif, cursive, fantasy, monospace}

• axes_font_size (int, optional) – The font size of the axes.

• axes_font_style ({normal, italic, oblique}, optional) – The font style of the axes.

• axes_font_weight (See Below, optional) – The font weight of the axes. Example options

{ultralight, light, normal, regular, book, medium, roman,
semibold, demibold, demi, bold, heavy, extra bold, black}

• axes_x_limits (float or (float, float) or None, optional) – The limits of the x axis. If float, then it sets padding on the right and left of the Image as a percentage of the Image’s width. If tuple or list, then it defines the axis limits. If None, then the limits are set automatically.

• axes_y_limits ((float, float) tuple or None, optional) – The limits of the y axis. If float, then it sets padding on the top and bottom of the Image as a percentage of the Image’s height. If tuple or list, then it defines the axis limits. If None, then the limits are set automatically.

• axes_x_ticks (list or tuple or None, optional) – The ticks of the x axis.

• axes_y_ticks (list or tuple or None, optional) – The ticks of the y axis.

• figure_size ((float, float) tuple or None, optional) – The size of the figure in inches.

Raises

ValueError – If Image is not 2D

_view_landmarks_2d(channels=None, masked=True, group=None, with_labels=None, without_labels=None, figure_id=None, new_figure=False, interpolation='bilinear', cmap_name=None, alpha=1.0, render_lines=True, line_colour=None, line_style='-', line_width=1, render_markers=True, marker_style='o', marker_size=5, marker_face_colour=None, marker_edge_colour=None, marker_edge_width=1.0, render_numbering=False, numbers_horizontal_align='center', numbers_vertical_align='bottom', numbers_font_name='sans-serif', numbers_font_size=10, numbers_font_style='normal', numbers_font_weight='normal', numbers_font_colour='k', render_legend=False, legend_title='', legend_font_name='sans-serif', legend_font_style='normal', legend_font_size=10, legend_font_weight='normal', legend_marker_scale=None, legend_location=2, legend_bbox_to_anchor=(1.05, 1.0), legend_border_axes_pad=None, legend_n_columns=1, legend_horizontal_spacing=None, legend_vertical_spacing=None, legend_border=True, legend_border_padding=None, legend_shadow=False, legend_rounded_corners=False, render_axes=False, axes_font_name='sans-serif', axes_font_size=10, axes_font_style='normal', axes_font_weight='normal', axes_x_limits=None, axes_y_limits=None, axes_x_ticks=None, axes_y_ticks=None, figure_size=(7, 7))[source]

Visualize the landmarks. This method will appear on the Image as view_landmarks if the Image is 2D.

Parameters
• channels (int or list of int or all or None) – If int or list of int, the specified channel(s) will be rendered. If all, all the channels will be rendered in subplots. If None and the image is RGB, it will be rendered in RGB mode. If None and the image is not RGB, it is equivalent to all.

• masked (bool, optional) – If True, only the masked pixels will be rendered.

• group (str orNone optionals) – The landmark group to be visualized. If None and there are more than one landmark groups, an error is raised.

• with_labels (None or str or list of str, optional) – If not None, only show the given label(s). Should not be used with the without_labels kwarg.

• without_labels (None or str or list of str, optional) – If not None, show all except the given label(s). Should not be used with the with_labels kwarg.

• figure_id (object, optional) – The id of the figure to be used.

• new_figure (bool, optional) – If True, a new figure is created.

• interpolation (See Below, optional) –

The interpolation used to render the image. For example, if bilinear, the image will be smooth and if nearest, the image will be pixelated. Example options

{none, nearest, bilinear, bicubic, spline16, spline36, hanning,
hamming, hermite, kaiser, quadric, catrom, gaussian, bessel,
mitchell, sinc, lanczos}


• cmap_name (str, optional,) – If None, single channel and three channel images default to greyscale and rgb colormaps respectively.

• alpha (float, optional) – The alpha blending value, between 0 (transparent) and 1 (opaque).

• render_lines (bool, optional) – If True, the edges will be rendered.

• line_colour (See Below, optional) –

The colour of the lines. Example options:

{r, g, b, c, m, k, w}
or
(3, ) ndarray


• line_style ({-, --, -., :}, optional) – The style of the lines.

• line_width (float, optional) – The width of the lines.

• render_markers (bool, optional) – If True, the markers will be rendered.

• marker_style (See Below, optional) –

The style of the markers. Example options

{., ,, o, v, ^, <, >, +, x, D, d, s, p, *, h, H, 1, 2, 3, 4, 8}


• marker_size (int, optional) – The size of the markers in points.

• marker_face_colour (See Below, optional) –

The face (filling) colour of the markers. Example options

{r, g, b, c, m, k, w}
or
(3, ) ndarray


• marker_edge_colour (See Below, optional) –

The edge colour of the markers. Example options

{r, g, b, c, m, k, w}
or
(3, ) ndarray


• marker_edge_width (float, optional) – The width of the markers’ edge.

• render_numbering (bool, optional) – If True, the landmarks will be numbered.

• numbers_horizontal_align ({center, right, left}, optional) – The horizontal alignment of the numbers’ texts.

• numbers_vertical_align ({center, top, bottom, baseline}, optional) – The vertical alignment of the numbers’ texts.

• numbers_font_name (See Below, optional) –

The font of the numbers. Example options

{serif, sans-serif, cursive, fantasy, monospace}


• numbers_font_size (int, optional) – The font size of the numbers.

• numbers_font_style ({normal, italic, oblique}, optional) – The font style of the numbers.

• numbers_font_weight (See Below, optional) –

The font weight of the numbers. Example options

{ultralight, light, normal, regular, book, medium, roman,
semibold, demibold, demi, bold, heavy, extra bold, black}


• numbers_font_colour (See Below, optional) –

The font colour of the numbers. Example options

{r, g, b, c, m, k, w}
or
(3, ) ndarray


• render_legend (bool, optional) – If True, the legend will be rendered.

• legend_title (str, optional) – The title of the legend.

• legend_font_name (See below, optional) –

The font of the legend. Example options

{serif, sans-serif, cursive, fantasy, monospace}


• legend_font_style ({normal, italic, oblique}, optional) – The font style of the legend.

• legend_font_size (int, optional) – The font size of the legend.

• legend_font_weight (See Below, optional) –

The font weight of the legend. Example options

{ultralight, light, normal, regular, book, medium, roman,
semibold, demibold, demi, bold, heavy, extra bold, black}


• legend_marker_scale (float, optional) – The relative size of the legend markers with respect to the original

• legend_location (int, optional) –

The location of the legend. The predefined values are:

 ’best’ 0 ’upper right’ 1 ’upper left’ 2 ’lower left’ 3 ’lower right’ 4 ’right’ 5 ’center left’ 6 ’center right’ 7 ’lower center’ 8 ’upper center’ 9 ’center’ 10

• legend_bbox_to_anchor ((float, float) tuple, optional) – The bbox that the legend will be anchored.

• legend_border_axes_pad (float, optional) – The pad between the axes and legend border.

• legend_n_columns (int, optional) – The number of the legend’s columns.

• legend_horizontal_spacing (float, optional) – The spacing between the columns.

• legend_vertical_spacing (float, optional) – The vertical space between the legend entries.

• legend_border (bool, optional) – If True, a frame will be drawn around the legend.

• legend_border_padding (float, optional) – The fractional whitespace inside the legend border.

• legend_shadow (bool, optional) – If True, a shadow will be drawn behind legend.

• legend_rounded_corners (bool, optional) – If True, the frame’s corners will be rounded (fancybox).

• render_axes (bool, optional) – If True, the axes will be rendered.

• axes_font_name (See Below, optional) –

The font of the axes. Example options

{serif, sans-serif, cursive, fantasy, monospace}


• axes_font_size (int, optional) – The font size of the axes.

• axes_font_style ({normal, italic, oblique}, optional) – The font style of the axes.

• axes_font_weight (See Below, optional) –

The font weight of the axes. Example options

{ultralight, light, normal, regular, book, medium, roman,
semibold,demibold, demi, bold, heavy, extra bold, black}


• axes_x_limits (float or (float, float) or None, optional) – The limits of the x axis. If float, then it sets padding on the right and left of the Image as a percentage of the Image’s width. If tuple or list, then it defines the axis limits. If None, then the limits are set automatically.

• axes_y_limits ((float, float) tuple or None, optional) – The limits of the y axis. If float, then it sets padding on the top and bottom of the Image as a percentage of the Image’s height. If tuple or list, then it defines the axis limits. If None, then the limits are set automatically.

• axes_x_ticks (list or tuple or None, optional) – The ticks of the x axis.

• axes_y_ticks (list or tuple or None, optional) – The ticks of the y axis.

• figure_size ((float, float) tuple or None optional) – The size of the figure in inches.

Raises
• ValueError – If both with_labels and without_labels are passed.

• ValueError – If the landmark manager doesn’t contain the provided group label.

as_PILImage(out_dtype=<class 'numpy.uint8'>)

Return a PIL copy of the image scaled and cast to the correct values for the provided out_dtype.

Image must only have 1 or 3 channels and be 2 dimensional. Non uint8 floating point images must be in the range [0, 1] to be converted.

Parameters

out_dtype (np.dtype, optional) – The dtype the output array should be.

Returns

pil_image (PILImage) – PIL copy of image

Raises
• ValueError – If image is not 2D and has 1 channel or 3 channels.

• ValueError – If pixels data type is float32 or float64 and the pixel range is outside of [0, 1]

• ValueError – If the output dtype is unsupported. Currently uint8 is supported.

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}, optional) –

mode

Greyscale Algorithm

average

Equal average of all channels

luminosity

Calculates the luminance using the CCIR 601 formula:

$Y' = 0.2989 R' + 0.5870 G' + 0.1140 B'$

channel

A specific channel is chosen as the intensity value.

• channel (int, optional) – The channel to be taken. Only used if mode is channel.

Returns

greyscale_image (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.

• bins ({unique}, positive int or sequence of scalars, optional) – If set equal to 'unique', the bins of the histograms are centred on the unique values of each channel. If set equal to a positive int, then this is the number of bins. If set equal to a sequence of scalars, these will be used as bins centres.

Returns

• hist (ndarray or list with n_channels ndarrays inside) – The histogram(s). If keep_channels=False, then hist is an ndarray. If keep_channels=True, then hist is a list with len(hist)=n_channels.

• bin_edges (ndarray or list with n_channels ndarrays inside) – An array or a list of arrays corresponding to the above histograms that store the bins’ edges.

Raises

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

Examples

Visualizing the histogram when a list of array bin edges is provided:

>>> hist, bin_edges = image.as_histogram()
>>> for k in range(len(hist)):
>>>     plt.subplot(1,len(hist),k)
>>>     width = 0.7 * (bin_edges[k][1] - bin_edges[k][0])
>>>     centre = (bin_edges[k][:-1] + bin_edges[k][1:]) / 2
>>>     plt.bar(centre, hist[k], align='center', width=width)

as_imageio(out_dtype=<class 'numpy.uint8'>)

Return an Imageio copy of the image scaled and cast to the correct values for the provided out_dtype.

Image must only have 1 or 3 channels and be 2 dimensional. Non uint8 floating point images must be in the range [0, 1] to be converted.

Parameters

out_dtype (np.dtype, optional) – The dtype the output array should be.

Returns

imageio_image (ndarray) – Imageio image (which is just a numpy ndarray with the channels as the last axis).

Raises
• ValueError – If image is not 2D and has 1 channel or 3 channels.

• ValueError – If pixels data type is float32 or float64 and the pixel range is outside of [0, 1]

• ValueError – If the output dtype is unsupported. Currently uint8 and uint16 are supported.

as_masked(mask=None, copy=True)

Return a copy of this image with an attached mask behavior.

A custom mask may be provided, or None. See the MaskedImage constructor for details of how the kwargs will be handled.

Parameters
• mask ((self.shape) ndarray or BooleanImage) – A mask to attach to the newly generated masked image.

• copy (bool, optional) – If False, the produced MaskedImage will share pixels with self. Only suggested to be used for performance.

Returns

masked_image (MaskedImage) – An image with the same pixels and landmarks as this one, but with a mask.

as_unmasked(copy=True, fill=None)[source]

Return a copy of this image without the masking behavior.

By default the mask is simply discarded. However, there is an optional kwarg, fill, that can be set which will fill the non-masked areas with the given value.

Parameters
• copy (bool, optional) – If False, the produced Image will share pixels with self. Only suggested to be used for performance.

• fill (float or (n_channels,) iterable or None, optional) – If None the mask is simply discarded. If a scalar or iterable, the unmasked regions are filled with the given value.

Returns

image (Image) – An image with the same pixels and landmarks as this one, but with no mask.

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.

bounds()

The bounds of the image, minimum is always (0, 0). The maximum is the maximum index that can be used to index into the image for each dimension. Therefore, bounds will be of the form: ((0, 0), (self.height - 1, self.width - 1)) for a 2D image.

Note that this is akin to supporting a nearest neighbour interpolation. Although the actual maximum subpixel value would be something like self.height - eps where eps is some value arbitrarily close to 0, this value at least allows sampling without worrying about floating point error.

Type

tuple

build_mask_around_landmarks(patch_shape, group=None)[source]

centre()

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

Useful for aligning shapes and images.

Type

(n_dims,) ndarray

clip_pixels(minimum=None, maximum=None)

A copy of this image with pixels linearly clipped to fit a range.

Parameters
• minimum (float, optional) – The minimal value of the clipped pixels. If None is provided, the default value will be 0.

• maximum (float, optional) – The maximal value of the clipped pixels. If None is provided, the default value will depend on the dtype.

Returns

rescaled_image (type(self)) – A copy of this image with pixels linearly rescaled to fit in the range provided.

constrain_landmarks_to_bounds()

Deprecated - please use the equivalent constrain_to_bounds method now on PointCloud, in conjunction with the new Image bounds() method. For example:

>>> im.constrain_landmarks_to_bounds()  # Equivalent to below
>>> im.landmarks['test'] = im.landmarks['test'].constrain_to_bounds(im.bounds())

constrain_mask_to_landmarks(group=None, batch_size=None, point_in_pointcloud='pwa')[source]

Returns a copy of this image whereby the mask is restricted to be equal to the convex hull around the chosen landmarks.

The choice of whether a pixel is inside or outside of the pointcloud is determined by the point_in_pointcloud parameter. By default a Piecewise Affine transform is used to test for containment, which is useful when building efficiently aligning images. For large images, a faster and pixel-accurate method can be used (‘convex_hull’). Alternatively, a callable can be provided to override the test. By default, the provided implementations are only valid for 2D images.

Parameters
• group (str, 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. If the landmarks in question are an instance of TriMesh, the triangulation of the landmarks will be used in the convex hull calculation. If the landmarks are an instance of PointCloud, Delaunay triangulation will be used to create a triangulation.

• batch_size (int or None, optional) – This should only be considered for large images. Setting this value will cause constraining to become much slower. This size indicates how many points in the image should be checked at a time, which keeps memory usage low. If None, no batching is used and all points are checked at once. By default, this is only used for the ‘pwa’ point_in_pointcloud choice.

• point_in_pointcloud ({‘pwa’, ‘convex_hull’} or callable) – The method used to check if pixels in the image fall inside the pointcloud or not. Can be accurate to a Piecewise Affine transform, a pixel accurate convex hull or any arbitrary callable. If a callable is passed, it should take two parameters, the PointCloud to constrain with and the pixel locations ((d, n_dims) ndarray) to test and should return a (d, 1) boolean ndarray of whether the pixels were inside (True) or outside (False) of the PointCloud.

Returns

constrained (MaskedImage) – A new image where the mask is constrained by the provided landmarks.

constrain_mask_to_patches_around_landmarks(patch_shape, group=None)[source]

Returns a copy of this image whereby the mask is restricted to be patches around each landmark in the chosen landmark group. The patch will be centred on the nearest pixel for each point in the chosen landmark group.

Parameters
• patch_shape (tuple) – The size of the patch.

• group (str, 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.

Returns

constrained (MaskedImage) – A new image where the mask is constrained as patches centred on each point in the provided landmarks.

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()

Generate an efficient copy of this object.

Note that Numpy arrays and other Copyable objects on self will be deeply copied. Dictionaries and sets will be shallow copied, and everything else will be assigned (no copy will be made).

Classes that store state other than numpy arrays and immutable types should overwrite this method to ensure all state is copied.

Returns

type(self) – A copy of this object

crop(min_indices, max_indices, constrain_to_boundary=False, return_transform=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 (bool, 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.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the cropping is also returned.

Returns

• cropped_image (type(self)) – A new instance of self, but cropped.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

Raises
• ValueErrormin_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=False, and an attempt is made to crop the image in a way that violates the image bounds.

crop_to_landmarks(group=None, boundary=0, constrain_to_boundary=True, return_transform=False)

Return a copy of this image cropped so that it is bounded around a set of landmarks with an optional n_pixel boundary

Parameters
• group (str, 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.

• boundary (int, optional) – An extra padding to be added all around the landmarks bounds.

• constrain_to_boundary (bool, optional) – If True the crop will be snapped to not go beyond this images boundary. If False, an :mapImageBoundaryError will be raised if an attempt is made to go beyond the edge of the image.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the cropping is also returned.

Returns

Raises

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

crop_to_landmarks_proportion(boundary_proportion, group=None, minimum=True, constrain_to_boundary=True, return_transform=False)

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 (str, 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.

• 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.

• constrain_to_boundary (bool, 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.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the cropping is also returned.

Returns

• image (Image) – This image, cropped to its landmarks with a border proportional to the landmark spread or range.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

Raises

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

crop_to_pointcloud(pointcloud, boundary=0, constrain_to_boundary=True, return_transform=False)

Return a copy of this image cropped so that it is bounded around a pointcloud with an optional n_pixel boundary.

Parameters
• pointcloud (PointCloud) – The pointcloud to crop around.

• boundary (int, optional) – An extra padding to be added all around the landmarks bounds.

• constrain_to_boundary (bool, optional) – If True the crop will be snapped to not go beyond this images boundary. If False, an :mapImageBoundaryError will be raised if an attempt is made to go beyond the edge of the image.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the cropping is also returned.

Returns

• image (Image) – A copy of this image cropped to the bounds of the pointcloud.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

Raises

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

crop_to_pointcloud_proportion(pointcloud, boundary_proportion, minimum=True, constrain_to_boundary=True, return_transform=False)

Return a copy of this image cropped so that it is bounded around a pointcloud with a border proportional to the pointcloud spread or range.

Parameters
• pointcloud (PointCloud) – The pointcloud to crop around.

• 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.

• minimum (bool, optional) – If True the specified proportion is relative to the minimum value of the pointclouds’ per-dimension range; if False w.r.t. the maximum value of the pointclouds’ per-dimension range.

• constrain_to_boundary (bool, 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.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the cropping is also returned.

Returns

• image (Image) – A copy of this image cropped to the border proportional to the pointcloud spread or range.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

Raises

ImageBoundaryError – Raised if constrain_to_boundary=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, return_transform=False)[source]

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.

• constrain_to_boundary (bool, 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. Note that is only possible if boundary != 0.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the cropping is also returned.

Returns

• cropped_image (type(self)) – A copy of this image, cropped to the true mask.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

Raises

ImageBoundaryError – Raised if 11constrain_to_boundary=False1, and an attempt is made to crop the image in a way that violates the image bounds.

diagonal()

The diagonal size of this image

Type

float

dilate(n_pixels=1)[source]

Returns a copy of this MaskedImage in which its mask has been expanded by n pixels along its boundary.

Parameters

n_pixels (int, optional) – The number of pixels by which we want to expand the mask along its own boundary.

Returns

dilated_image (MaskedImage) – The copy of the masked image in which the mask has been expanded by n pixels along its boundary.

erode(n_pixels=1)[source]

Returns a copy of this MaskedImage in which the mask has been shrunk by n pixels along its boundary.

Parameters

n_pixels (int, optional) – The number of pixels by which we want to shrink the mask along its own boundary.

Returns

eroded_image (MaskedImage) – The copy of the masked image in which the mask has been shrunk by n pixels along its boundary.

extract_channels(channels)

A copy of this image with only the specified channels.

Parameters

channels (int or [int]) – The channel index or list of channel indices to retain.

Returns

image (type(self)) – A copy of this image with only the channels requested.

extract_patches(patch_centers, patch_shape=(16, 16), sample_offsets=None, as_single_array=True, order=0, mode='constant', cval=0.0)

Extract a set of patches from an image. Given a set of patch centers and a patch size, patches are extracted from within the image, centred on the given coordinates. Sample offsets denote a set of offsets to extract from within a patch. This is very useful if you want to extract a dense set of features around a set of landmarks and simply sample the same grid of patches around the landmarks.

If sample offsets are used, to access the offsets for each patch you need to slice the resulting list. So for 2 offsets, the first centers offset patches would be patches[:2].

Currently only 2D images are supported.

Note that the default is nearest neighbour sampling for the patches which is achieved via slicing and is much more efficient than using sampling/interpolation. Note that a significant performance decrease will be measured if the order or mode parameters are modified from order = 0 and mode = 'constant' as internally sampling will be used rather than slicing.

Parameters
• patch_centers (PointCloud) – The centers to extract patches around.

• patch_shape ((1, n_dims) tuple or ndarray, optional) – The size of the patch to extract

• sample_offsets ((n_offsets, n_dims) ndarray or None, optional) – The offsets to sample from within a patch. So (0, 0) is the centre of the patch (no offset) and (1, 0) would be sampling the patch from 1 pixel up the first axis away from the centre. If None, then no offsets are applied.

• as_single_array (bool, optional) – If True, an (n_center, n_offset, n_channels, patch_shape) ndarray, thus a single numpy array is returned containing each patch. If False, a list of n_center * n_offset Image objects is returned representing each patch.

• order (int, optional) – The order of interpolation. The order has to be in the range [0,5]. See warp_to_shape for more information.

• mode ({constant, nearest, reflect, wrap}, optional) – Points outside the boundaries of the input are filled according to the given mode.

• cval (float, optional) – Used in conjunction with mode constant, the value outside the image boundaries.

Returns

patches (list or ndarray) – Returns the extracted patches. Returns a list if as_single_array=True and an ndarray if as_single_array=False.

Raises

ValueError – If image is not 2D

extract_patches_around_landmarks(group=None, patch_shape=(16, 16), sample_offsets=None, as_single_array=True)

Extract patches around landmarks existing on this image. Provided the group label and optionally the landmark label extract a set of patches.

Currently only 2D images are supported.

Parameters
• group (str or None, optional) – The landmark group to use as patch centres.

• patch_shape (tuple or ndarray, optional) – The size of the patch to extract

• sample_offsets ((n_offsets, n_dims) ndarray or None, optional) – The offsets to sample from within a patch. So (0, 0) is the centre of the patch (no offset) and (1, 0) would be sampling the patch from 1 pixel up the first axis away from the centre. If None, then no offsets are applied.

• as_single_array (bool, optional) – If True, an (n_center, n_offset, n_channels, patch_shape) ndarray, thus a single numpy array is returned containing each patch. If False, a list of n_center * n_offset Image objects is returned representing each patch.

Returns

patches (list or ndarray) – Returns the extracted patches. Returns a list if as_single_array=True and an ndarray if as_single_array=False.

Raises

ValueError – If image is not 2D

from_vector(vector, n_channels=None)[source]

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.

Returns

image (MaskedImage) – New image of same shape as this image and the number of specified channels.

from_vector_inplace(vector)

Deprecated. Use the non-mutating API, from_vector.

For internal usage in performance-sensitive spots, see _from_vector_inplace()

Parameters

vector ((n_parameters,) ndarray) – Flattened representation of this object

gaussian_pyramid(n_levels=3, downscale=2, sigma=None)

Return the gaussian pyramid of this image. The first image of the pyramid will be a copy of the original, unmodified, image, and counts as level 1.

Parameters
• n_levels (int, optional) – Total number of levels in the pyramid, including the original unmodified image

• downscale (float, optional) – Downscale factor.

• sigma (float, optional) – Sigma for gaussian filter. Default is downscale / 3. which corresponds to a filter mask twice the size of the scale factor that covers more than 99% of the gaussian distribution.

Yields

image_pyramid (generator) – Generator yielding pyramid layers as Image objects.

has_landmarks_outside_bounds()

Indicates whether there are landmarks located outside the image bounds.

Type

bool

has_nan_values()

Tests if the vectorized form of the object contains nan values or not. This is particularly useful for objects with unknown values that have been mapped to nan values.

Returns

has_nan_values (bool) – If the vectorized object contains nan values.

indices()[source]

Return the indices of all true pixels in this image.

Type

(n_dims, n_true_pixels) ndarray

classmethod init_blank(shape, n_channels=1, fill=0, dtype=<class 'float'>, mask=None)[source]

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.

• fill (int, optional) – The value to fill all pixels with.

• dtype (numpy datatype, optional) – The datatype of the image.

• mask ((M, N) bool ndarray or BooleanImage) – An optional mask that can be applied to the image. Has to have a shape equal to that of the image.

Notes

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

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


in order to appropriately propagate the subclass type to cls.

Returns

blank_image (MaskedImage) – A new masked image of the requested size.

classmethod init_from_channels_at_back(pixels, mask=None)[source]

Create an Image from a set of pixels where the channels axis is on the last axis (the back). This is common in other frameworks, and therefore this method provides a convenient means of creating a menpo Image from such data. Note that a copy is always created due to the need to rearrange the data.

Parameters
• pixels ((M, N ..., Q, C) ndarray) – Array representing the image pixels, with the last axis being channels.

• mask ((M, N) 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).

Returns

image (Image) – A new image from the given pixels, with the FIRST axis as the channels.

classmethod init_from_pointcloud(pointcloud, group=None, boundary=0, constrain_mask=True, n_channels=1, fill=0, dtype=<class 'float'>)[source]

Create an Image that is big enough to contain the given pointcloud. The pointcloud will be translated to the origin and then translated according to its bounds in order to fit inside the new image. An optional boundary can be provided in order to increase the space around the boundary of the pointcloud. The boundary will be added to all sides of the image and so a boundary of 5 provides 10 pixels of boundary total for each dimension.

By default, the mask will be constrained to the convex hull of the provided pointcloud.

Parameters
• pointcloud (PointCloud) – Pointcloud to place inside the newly created image.

• group (str, optional) – If None, the pointcloud will only be used to create the image. If a str then the pointcloud will be attached as a landmark group to the image, with the given string as key.

• boundary (float) – A optional padding distance that is added to the pointcloud bounds. Default is 0, meaning the max/min of tightest possible containing image is returned.

• n_channels (int, optional) – The number of channels to create the image with.

• fill (int, optional) – The value to fill all pixels with.

• dtype (numpy data type, optional) – The data type of the image.

• constrain_mask (bool, optional) – If True, the mask will be constrained to the convex hull of the provided pointcloud. If False, the mask will be all True.

Returns

image (MaskedImage) – A new image with the same size as the given pointcloud, optionally with the pointcloud attached as landmarks and the mask constrained to the convex hull of the pointcloud.

classmethod init_from_rolled_channels(pixels)

Deprecated - please use the equivalent init_from_channels_at_back method.

masked_pixels()[source]

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

Type

(n_channels, mask.n_true) ndarray

mirror(axis=1, order=1, warp_landmarks=True, return_transform=False)

Return a copy of this image, mirrored/flipped about a certain axis.

Parameters
• axis (int, optional) – The axis about which to mirror the image.

• order (int, optional) –

The order of interpolation. The order has to be in the range [0,5].

Order

Interpolation

0

Nearest-neighbor

1

Bi-linear (default)

2

3

Bi-cubic

4

Bi-quartic

5

Bi-quintic

• warp_landmarks (bool, optional) – If True, result will have the same landmark dictionary as self, but with each landmark updated to the warped position.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the mirroring is also returned.

Returns

• mirrored_image (type(self)) – The mirrored image.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

Raises
• ValueError – axis cannot be negative

• ValueError – axis={} but the image has {} dimensions

n_false_elements()[source]

The number of False elements of the image over all the channels.

Type

int

n_false_pixels()[source]

The number of False values in the mask.

Type

int

n_true_elements()[source]

The number of True elements of the image over all the channels.

Type

int

n_true_pixels()[source]

The number of True values in the mask.

Type

int

normalize_norm(mode='all', limit_to_mask=True, **kwargs)[source]

Returns a copy of this image normalized such that it’s pixel values have zero mean and its norm equals 1.

Parameters
• mode ({all, per_channel}, optional) – If all, the normalization is over all channels. If per_channel, each channel individually is mean centred and normalized in variance.

• limit_to_mask (bool, optional) – If True, the normalization is only performed wrt the masked pixels. If False, the normalization is wrt all pixels, regardless of their masking value.

Returns

image (type(self)) – A copy of this image, normalized.

normalize_std(mode='all', limit_to_mask=True)[source]

Returns a copy of this image normalized such that it’s pixel values have zero mean and unit variance.

Parameters
• mode ({all, per_channel}, optional) – If all, the normalization is over all channels. If per_channel, each channel individually is mean centred and normalized in variance.

• limit_to_mask (bool, optional) – If True, the normalization is only performed wrt the masked pixels. If False, the normalization is wrt all pixels, regardless of their masking value.

Returns

image (type(self)) – A copy of this image, normalized.

pixels_range()

The range of the pixel values (min and max pixel values).

Returns

min_max ((dtype, dtype)) – The minimum and maximum value of the pixels array.

pixels_with_channels_at_back(out_dtype=None)

Returns the pixels matrix, with the channels rolled to the back axis. This may be required for interacting with external code bases that require images to have channels as the last axis, rather than the Menpo convention of channels as the first axis.

If this image is single channel, the final axis is dropped.

Parameters

out_dtype (np.dtype, optional) – The dtype the output array should be.

Returns

rolled_channels (ndarray) – Pixels with channels as the back (last) axis. If single channel, the last axis will be dropped.

pyramid(n_levels=3, downscale=2)

Return a rescaled pyramid of this image. The first image of the pyramid will be a copy of the original, unmodified, image, and counts as level 1.

Parameters
• n_levels (int, optional) – Total number of levels in the pyramid, including the original unmodified image

• downscale (float, optional) – Downscale factor.

Yields

image_pyramid (generator) – Generator yielding pyramid layers as Image objects.

rasterize_landmarks(group=None, render_lines=True, line_style='-', line_colour='b', line_width=1, render_markers=True, marker_style='o', marker_size=1, marker_face_colour='b', marker_edge_colour='b', marker_edge_width=1, backend='matplotlib')[source]

This method provides the ability to rasterize 2D landmarks onto the image. The returned image has the specified landmark groups rasterized onto the image - which is useful for things like creating result examples or rendering videos with annotations.

Since multiple landmark groups can be specified, all arguments can take lists of parameters that map to the provided groups list. Therefore, the parameters must be lists of the correct length or a single parameter to apply to every landmark group.

Multiple backends are provided, all with different strengths. The ‘pillow’ backend is very fast, but not very flexible. The matplotlib backend should be feature compatible with other Menpo rendering methods, but is much slower due to the overhead of creating a figure to render into.

Images will always be rendered masked with a black background. If an unmasked image is required, please use as_unmasked().

Parameters
• group (str or list of str, optional) – The landmark group key, or a list of keys.

• render_lines (bool, optional) – If True, and the provided landmark group is a PointDirectedGraph, the edges are rendered.

• line_style (str, optional) – The style of the edge line. Not all backends support this argument.

• line_colour (str or tuple, optional) – A Matplotlib style colour or a backend dependant colour.

• line_width (int, optional) – The width of the line to rasterize.

• render_markers (bool, optional) – If True, render markers at the coordinates of each landmark.

• marker_style (str, optional) – A Matplotlib marker style. Not all backends support all marker styles.

• marker_size (int, optional) – The size of the marker - different backends use different scale spaces so consistent output may by difficult.

• marker_face_colour (str, optional) – A Matplotlib style colour or a backend dependant colour.

• marker_edge_colour (str, optional) – A Matplotlib style colour or a backend dependant colour.

• marker_edge_width (int, optional) – The width of the marker edge. Not all backends support this.

• backend ({'matplotlib', 'pillow'}, optional) – The backend to use.

Returns

rasterized_image (Image) – The image with the landmarks rasterized directly into the pixels.

Raises
• ValueError – Only 2D images are supported.

• ValueError – Only RGB (3-channel) or Greyscale (1-channel) images are supported.

rescale(scale, round='ceil', order=1, warp_landmarks=True, return_transform=False)

Return a copy of this image, rescaled by a given factor. Landmarks are rescaled appropriately.

Parameters
• scale (float or tuple of floats) – 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}, optional) – Rounding function to be applied to floating point shapes.

• order (int, optional) –

The order of interpolation. The order has to be in the range [0,5]

Order

Interpolation

0

Nearest-neighbor

1

Bi-linear (default)

2

3

Bi-cubic

4

Bi-quartic

5

Bi-quintic

• warp_landmarks (bool, optional) – If True, result will have the same landmark dictionary as self, but with each landmark updated to the warped position.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the rescale is also returned.

Returns

• rescaled_image (type(self)) – A copy of this image, rescaled.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

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, round='ceil', order=1, warp_landmarks=True, return_transform=False)

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 ((n_dims,) ndarray) – The diagonal_range range that we want the landmarks of the returned image to have.

• group (str, 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.

• round ({ceil, floor, round}, optional) – Rounding function to be applied to floating point shapes.

• order (int, optional) –

The order of interpolation. The order has to be in the range [0,5]

Order

Interpolation

0

Nearest-neighbor

1

Bi-linear (default)

2

3

Bi-cubic

4

Bi-quartic

5

Bi-quintic

• warp_landmarks (bool, optional) – If True, result will have the same landmark dictionary as self, but with each landmark updated to the warped position.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the rescale is also returned.

Returns

• rescaled_image (type(self)) – A copy of this image, rescaled.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

rescale_pixels(minimum, maximum, per_channel=True)

A copy of this image with pixels linearly rescaled to fit a range.

Note that the only pixels that will be considered and rescaled are those that feature in the vectorized form of this image. If you want to use this routine on all the pixels in a MaskedImage, consider using as_unmasked() prior to this call.

Parameters
• minimum (float) – The minimal value of the rescaled pixels

• maximum (float) – The maximal value of the rescaled pixels

• per_channel (boolean, optional) – If True, each channel will be rescaled independently. If False, the scaling will be over all channels.

Returns

rescaled_image (type(self)) – A copy of this image with pixels linearly rescaled to fit in the range provided.

rescale_to_diagonal(diagonal, round='ceil', warp_landmarks=True, return_transform=False)

Return a copy of this image, rescaled so that the it’s diagonal is a new size.

Parameters
• diagonal (int) – The diagonal size of the new image.

• round ({ceil, floor, round}, optional) – Rounding function to be applied to floating point shapes.

• warp_landmarks (bool, optional) – If True, result will have the same landmark dictionary as self, but with each landmark updated to the warped position.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the rescale is also returned.

Returns

• rescaled_image (type(self)) – A copy of this image, rescaled.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

rescale_to_pointcloud(pointcloud, group=None, round='ceil', order=1, warp_landmarks=True, return_transform=False)

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

Parameters
• pointcloud (PointCloud) – The reference pointcloud to which the landmarks specified by group will be scaled to match.

• group (str, 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.

• round ({ceil, floor, round}, optional) – Rounding function to be applied to floating point shapes.

• order (int, optional) –

The order of interpolation. The order has to be in the range [0,5]

Order

Interpolation

0

Nearest-neighbor

1

Bi-linear (default)

2

3

Bi-cubic

4

Bi-quartic

5

Bi-quintic

• warp_landmarks (bool, optional) – If True, result will have the same landmark dictionary as self, but with each landmark updated to the warped position.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the rescale is also returned.

Returns

• rescaled_image (type(self)) – A copy of this image, rescaled.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

resize(shape, order=1, warp_landmarks=True, return_transform=False)

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

Parameters
• shape (tuple) – The new shape to resize to.

• order (int, optional) –

The order of interpolation. The order has to be in the range [0,5]

Order

Interpolation

0

Nearest-neighbor

1

Bi-linear (default)

2

3

Bi-cubic

4

Bi-quartic

5

Bi-quintic

• warp_landmarks (bool, optional) – If True, result will have the same landmark dictionary as self, but with each landmark updated to the warped position.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the resize is also returned.

Returns

• resized_image (type(self)) – A copy of this image, resized.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

Raises

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

rolled_channels()

Deprecated - please use the equivalent pixels_with_channels_at_back method.

rotate_ccw_about_centre(theta, degrees=True, retain_shape=False, mode='constant', cval=0.0, round='round', order=1, warp_landmarks=True, return_transform=False)

Return a copy of this image, rotated counter-clockwise about its centre.

Note that the retain_shape argument defines the shape of the rotated image. If retain_shape=True, then the shape of the rotated image will be the same as the one of current image, so some regions will probably be cropped. If retain_shape=False, then the returned image has the correct size so that the whole area of the current image is included.

Parameters
• theta (float) – The angle of rotation about the centre.

• degrees (bool, optional) – If True, theta is interpreted in degrees. If False, theta is interpreted as radians.

• retain_shape (bool, optional) – If True, then the shape of the rotated image will be the same as the one of current image, so some regions will probably be cropped. If False, then the returned image has the correct size so that the whole area of the current image is included.

• mode ({constant, nearest, reflect, wrap}, optional) – Points outside the boundaries of the input are filled according to the given mode.

• cval (float, optional) – The value to be set outside the rotated image boundaries.

• round ({'ceil', 'floor', 'round'}, optional) – Rounding function to be applied to floating point shapes. This is only used in case retain_shape=True.

• order (int, optional) –

The order of interpolation. The order has to be in the range [0,5]. This is only used in case retain_shape=True.

Order

Interpolation

0

Nearest-neighbor

1

Bi-linear (default)

2

3

Bi-cubic

4

Bi-quartic

5

Bi-quintic

• warp_landmarks (bool, optional) – If True, result will have the same landmark dictionary as self, but with each landmark updated to the warped position.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the rotation is also returned.

Returns

• rotated_image (type(self)) – The rotated image.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

Raises

ValueError – Image rotation is presently only supported on 2D images

sample(points_to_sample, order=1, mode='constant', cval=0.0, verify_mask=False)[source]

Sample this image at the given sub-pixel accurate points. The input PointCloud should have the same number of dimensions as the image e.g. a 2D PointCloud for a 2D multi-channel image. A numpy array will be returned the has the values for every given point across each channel of the image.

If verify_mask is True and the points to sample are outside of the mask (fall on a False value in the mask), an exception is raised. This exception contains the information of which points were outside of the mask (False) and also returns the sampled points. Note this is more expensive and thus may be disabled by setting verify_mask to False.

Parameters
• points_to_sample (PointCloud) – Array of points to sample from the image. Should be (n_points, n_dims)

• order (int, optional) – The order of interpolation. The order has to be in the range [0,5]. See warp_to_shape for more information.

• mode ({constant, nearest, reflect, wrap}, optional) – Points outside the boundaries of the input are filled according to the given mode.

• cval (float, optional) – Used in conjunction with mode constant, the value outside the image boundaries.

• verify_mask (bool, optional) – If True, also sample the mask at the given points and check the mask is valid at all points. Note that sampling masks with higher order splines may cause interpolated mask values that are rounded to zero and thus cause false positives.

Returns

sampled_pixels ((n_points, n_channels) ndarray) – The interpolated values taken across every channel of the image.

Raises

OutOfMaskSampleError – One of the points to sample was outside of the valid area of the mask (False in the mask). This exception contains both the mask of valid sample points, as well as the sampled points themselves, in case you want to ignore the error. Only raised if verify_mask is True.

set_boundary_pixels(value=0.0, n_pixels=1)[source]

Returns a copy of this MaskedImage for which n pixels along the its mask boundary have been set to a particular value. This is useful in situations where there is absent data in the image which can cause, for example, erroneous computations of gradient or features.

Parameters
• value (float or (n_channels, 1) ndarray) –

• n_pixels (int, optional) – The number of pixels along the mask boundary that will be set to 0.

Returns

new_image (MaskedImage) – The copy of the image for which the n pixels along its mask boundary have been set to a particular value.

set_masked_pixels(pixels, copy=True)[source]

Deprecated - please use the equivalent from_vector

set_patches(patches, patch_centers, offset=None, offset_index=None)

Set the values of a group of patches into the correct regions of a copy of this image. Given an array of patches and a set of patch centers, the patches’ values are copied in the regions of the image that are centred on the coordinates of the given centers.

The patches argument can have any of the two formats that are returned from the extract_patches() and extract_patches_around_landmarks() methods. Specifically it can be:

1. (n_center, n_offset, self.n_channels, patch_shape) ndarray

2. list of n_center * n_offset Image objects

Currently only 2D images are supported.

Parameters
• patches (ndarray or list) – The values of the patches. It can have any of the two formats that are returned from the extract_patches() and extract_patches_around_landmarks() methods. Specifically, it can either be an (n_center, n_offset, self.n_channels, patch_shape) ndarray or a list of n_center * n_offset Image objects.

• patch_centers (PointCloud) – The centers to set the patches around.

• offset (list or tuple or (1, 2) ndarray or None, optional) – The offset to apply on the patch centers within the image. If None, then (0, 0) is used.

• offset_index (int or None, optional) – The offset index within the provided patches argument, thus the index of the second dimension from which to sample. If None, then 0 is used.

Raises
• ValueError – If image is not 2D

• ValueError – If offset does not have shape (1, 2)

set_patches_around_landmarks(patches, group=None, offset=None, offset_index=None)

Set the values of a group of patches around the landmarks existing in a copy of this image. Given an array of patches, a group and a label, the patches’ values are copied in the regions of the image that are centred on the coordinates of corresponding landmarks.

The patches argument can have any of the two formats that are returned from the extract_patches() and extract_patches_around_landmarks() methods. Specifically it can be:

1. (n_center, n_offset, self.n_channels, patch_shape) ndarray

2. list of n_center * n_offset Image objects

Currently only 2D images are supported.

Parameters
• patches (ndarray or list) – The values of the patches. It can have any of the two formats that are returned from the extract_patches() and extract_patches_around_landmarks() methods. Specifically, it can either be an (n_center, n_offset, self.n_channels, patch_shape) ndarray or a list of n_center * n_offset Image objects.

• group (str or None optional) – The landmark group to use as patch centres.

• offset (list or tuple or (1, 2) ndarray or None, optional) – The offset to apply on the patch centers within the image. If None, then (0, 0) is used.

• offset_index (int or None, optional) – The offset index within the provided patches argument, thus the index of the second dimension from which to sample. If None, then 0 is used.

Raises
• ValueError – If image is not 2D

• ValueError – If offset does not have shape (1, 2)

transform_about_centre(transform, retain_shape=False, mode='constant', cval=0.0, round='round', order=1, warp_landmarks=True, return_transform=False)

Return a copy of this image, transformed about its centre.

Note that the retain_shape argument defines the shape of the transformed image. If retain_shape=True, then the shape of the transformed image will be the same as the one of current image, so some regions will probably be cropped. If retain_shape=False, then the returned image has the correct size so that the whole area of the current image is included.

Note

This method will not work for transforms that result in a transform chain as TransformChain is not invertible.

Note

Be careful when defining transforms for warping imgaes. All pixel locations must fall within a valid range as expected by the transform. Therefore, your transformation must accept ‘negative’ pixel locations as the pixel locations provided to your transform will have the object centre subtracted from them.

Parameters
• transform (ComposableTransform and VInvertible type) – A composable transform. pseudoinverse will be invoked on the resulting transform so it must implement a valid inverse.

• retain_shape (bool, optional) – If True, then the shape of the sheared image will be the same as the one of current image, so some regions will probably be cropped. If False, then the returned image has the correct size so that the whole area of the current image is included.

• mode ({constant, nearest, reflect, wrap}, optional) – Points outside the boundaries of the input are filled according to the given mode.

• cval (float, optional) – The value to be set outside the sheared image boundaries.

• round ({'ceil', 'floor', 'round'}, optional) – Rounding function to be applied to floating point shapes. This is only used in case retain_shape=True.

• order (int, optional) –

The order of interpolation. The order has to be in the range [0,5]. This is only used in case retain_shape=True.

Order

Interpolation

0

Nearest-neighbor

1

Bi-linear (default)

2

3

Bi-cubic

4

Bi-quartic

5

Bi-quintic

• warp_landmarks (bool, optional) – If True, result will have the same landmark dictionary as self, but with each landmark updated to the warped position.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the shearing is also returned.

Returns

• transformed_image (type(self)) – The transformed image.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

Examples

This is an example for rotating an image about its center. Let’s first load an image, create the rotation transform and then apply it

import matplotlib.pyplot as plt
import menpo.io as mio
from menpo.transform import Rotation

im = mio.import_builtin_asset.lenna_png()

# Create shearing transform
rot_tr = Rotation.init_from_2d_ccw_angle(45)

# Render original image
plt.subplot(131)
im.view_landmarks()
plt.title('Original')

# Render rotated image
plt.subplot(132)
plt.title('Rotated')

# Render rotated image that has shape equal as original image
plt.subplot(133)
plt.title('Rotated (Retain original shape)')


Similarly, in order to apply a shear transform

import matplotlib.pyplot as plt
import menpo.io as mio
from menpo.transform import Affine

im = mio.import_builtin_asset.lenna_png()

# Create shearing transform
shear_tr = Affine.init_from_2d_shear(25, 10)

# Render original image
plt.subplot(131)
im.view_landmarks()
plt.title('Original')

# Render sheared image
plt.subplot(132)
plt.title('Sheared')

# Render sheared image that has shape equal as original image
plt.subplot(133)
retain_shape=True).view_landmarks()
plt.title('Sheared (Retain original shape)')

warp_to_mask(template_mask, transform, warp_landmarks=False, order=1, mode='constant', cval=0.0, batch_size=None, return_transform=False)[source]

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, result will have the same landmark dictionary as self, but with each landmark updated to the warped position.

• order (int, optional) –

The order of interpolation. The order has to be in the range [0,5]

Order

Interpolation

0

Nearest-neighbor

1

Bi-linear (default)

2

3

Bi-cubic

4

Bi-quartic

5

Bi-quintic

• mode ({constant, nearest, reflect, wrap}, optional) – Points outside the boundaries of the input are filled according to the given mode.

• cval (float, optional) – Used in conjunction with mode constant, the value outside the image boundaries.

• batch_size (int or None, optional) – This should only be considered for large images. Setting this value can cause warping to become much slower, particular for cached warps such as Piecewise Affine. This size indicates how many points in the image should be warped at a time, which keeps memory usage low. If None, no batching is used and all points are warped at once.

• return_transform (bool, optional) – This argument is for internal use only. If True, then the Transform object is also returned.

Returns

• warped_image (type(self)) – A copy of this image, warped.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

warp_to_shape(template_shape, transform, warp_landmarks=False, order=1, mode='constant', cval=0.0, batch_size=None, return_transform=False)[source]

Return a copy of this MaskedImage warped into a different reference space.

Parameters
• template_shape (tuple or ndarray) – Defines the shape of the result, and what pixel indices should be sampled (all of them).

• transform (Transform) – Transform from the template_shape space back to this image. Defines, for each index on template_shape, which pixel location should be sampled from on this image.

• warp_landmarks (bool, optional) – If True, result will have the same landmark dictionary as self, but with each landmark updated to the warped position.

• order (int, optional) –

The order of interpolation. The order has to be in the range [0,5]

Order

Interpolation

0

Nearest-neighbor

1

Bi-linear (default)

2

3

Bi-cubic

4

Bi-quartic

5

Bi-quintic

• mode ({constant, nearest, reflect, wrap}, optional) – Points outside the boundaries of the input are filled according to the given mode.

• cval (float, optional) – Used in conjunction with mode constant, the value outside the image boundaries.

• batch_size (int or None, optional) – This should only be considered for large images. Setting this value can cause warping to become much slower, particular for cached warps such as Piecewise Affine. This size indicates how many points in the image should be warped at a time, which keeps memory usage low. If None, no batching is used and all points are warped at once.

• return_transform (bool, optional) – This argument is for internal use only. If True, then the Transform object is also returned.

Returns

zoom(scale, order=1, warp_landmarks=True, return_transform=False)

Return a copy of this image, zoomed about the centre point. scale values greater than 1.0 denote zooming in to the image and values less than 1.0 denote zooming out of the image. The size of the image will not change, if you wish to scale an image, please see rescale().

Parameters
• scale (float) – scale > 1.0 denotes zooming in. Thus the image will appear larger and areas at the edge of the zoom will be ‘cropped’ out. scale < 1.0 denotes zooming out. The image will be padded by the value of cval.

• order (int, optional) –

The order of interpolation. The order has to be in the range [0,5]

Order

Interpolation

0

Nearest-neighbor

1

Bi-linear (default)

2

3

Bi-cubic

4

Bi-quartic

5

Bi-quintic

• warp_landmarks (bool, optional) – If True, result will have the same landmark dictionary as self, but with each landmark updated to the warped position.

• return_transform (bool, optional) – If True, then the Transform object that was used to perform the zooming is also returned.

Returns

• zoomed_image (type(self)) – A copy of this image, zoomed.

• transform (Transform) – The transform that was used. It only applies if return_transform is True.

property has_landmarks

Whether the object has landmarks.

Type

bool

property height

The height of the image.

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

Type

int

property landmarks

The landmarks object.

Type

LandmarkManager

property n_channels

The number of channels on each pixel in the image.

Type

int

property n_dims

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

Type

int

property n_elements

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

Type

int

property n_landmark_groups

The number of landmark groups on this object.

Type

int

property n_parameters

The length of the vector that this object produces.

Type

int

property n_pixels

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

Type

int

property shape

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

Type

tuple

property width`

The width of the image.

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

Type

int