MaskedImage¶
-
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 (
(M, N ..., Q, C)
ndarray) – The pixel data for the image, where the last axis represents the number of channels. - mask (
(M, N)
bool ndarray orBooleanImage
, 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
, theimage_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', 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, figure_size=(10, 8))[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
orNone
) – If int or list of int, the specified channel(s) will be rendered. Ifall
, all the channels will be rendered in subplots. IfNone
and the image is RGB, it will be rendered in RGB mode. IfNone
and the image is not RGB, it is equivalent toall
. - 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 ifnearest
, the image will be pixelated. Example options{none, nearest, bilinear, bicubic, spline16, spline36, hanning, hamming, hermite, kaiser, quadric, catrom, gaussian, bessel, mitchell, sinc, lanczos}
- 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, float) tuple or
None
, optional) – The limits of the x axis. - axes_y_limits ((float, float) tuple or
None
, optional) – The limits 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', alpha=1.0, render_lines=True, line_colour=None, line_style='-', line_width=1, render_markers=True, marker_style='o', marker_size=20, 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, figure_size=(10, 8))[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
orNone
) – If int or list of int, the specified channel(s) will be rendered. Ifall
, all the channels will be rendered in subplots. IfNone
and the image is RGB, it will be rendered in RGB mode. IfNone
and the image is not RGB, it is equivalent toall
. - masked (bool, optional) – If
True
, only the masked pixels will be rendered. - group (str or``None`` 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 notNone
, only show the given label(s). Should not be used with thewithout_labels
kwarg. - without_labels (
None
or str or list of str, optional) – If notNone
, show all except the given label(s). Should not be used with thewith_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 ifnearest
, the image will be pixelated. Example options{none, nearest, bilinear, bicubic, spline16, spline36, hanning, hamming, hermite, kaiser, quadric, catrom, gaussian, bessel, mitchell, sinc, lanczos}
- 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^2.
- 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, float) tuple or
None
optional) – The limits of the x axis. - axes_y_limits ((float, float) tuple or
None
optional) – The limits of the y axis. - figure_size ((float, float) tuple or
None
optional) – The size of the figure in inches.
Raises: ValueError
– If bothwith_labels
andwithout_labels
are passed.ValueError
– If the landmark manager doesn’t contain the provided group label.
- channels (int or list of int or
-
as_PILImage
()¶ Return a PIL copy of the image. Depending on the image data type, different operations are performed:
dtype Processing uint8 No processing, directly converted to PIL bool Scale by 255, convert to uint8 float32 Scale by 255, convert to uint8 float64 Scale by 255, convert to uint8 OTHER Raise ValueError Image must only have 1 or 3 channels and be 2 dimensional. Non uint8 images must be in the rage
[0, 1]
to be converted.Returns: pil_image (PILImage) – PIL copy of image
Raises: ValueError
– If image is not 2D and 1 channel or 3 channels.ValueError
– If pixels data type is not float32, float64, bool or uint8ValueError
– If pixels data type is float32 or float64 and the pixel range is outside of[0, 1]
-
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.- mode (
-
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 toTrue
, 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). Ifkeep_channels=False
, then hist is an ndarray. Ifkeep_channels=True
, then hist is a list withlen(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)
- keep_channels (bool, optional) – If set to
-
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 theMaskedImage
constructor for details of how the kwargs will be handled.Parameters: - mask (
(self.shape)
ndarray orBooleanImage
) – A mask to attach to the newly generated masked image. - copy (bool, optional) – If
False
, the producedMaskedImage
will share pixels withself
. 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.- mask (
-
as_unmasked
(copy=True)[source]¶ Return a copy of this image without the masking behavior.
By default the mask is simply discarded. In the future more options may be possible.
Parameters: copy (bool, optional) – If False
, the producedImage
will share pixels withself
. Only suggested to be used for performance.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.
-
classmethod
blank
(shape, n_channels=1, fill=0, dtype=<Mock object at 0x7f5b96962b50>, mask=None)[source]¶ 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.
- fill (int, optional) – The value to fill all pixels with.
- dtype (numpy datatype, optional) – The datatype of the image.
- mask (
(M, N)
bool ndarray orBooleanImage
) – 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 methodsuper(SubClass, cls).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.
-
build_mask_around_landmarks
(patch_size, group=None, label=None)[source]¶ Restricts this images mask to be patches around each landmark in the chosen landmark group. This is useful for visualizing patch based methods.
Parameters: - patch_shape (tuple) – The size of the patch. Any floating point values are rounded up to the nearest integer.
- 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. - label (str, 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.
-
constrain_landmarks_to_bounds
()¶ Move landmarks that are located outside the image bounds on the bounds.
-
constrain_mask_to_landmarks
(group=None, label=None, trilist=None)[source]¶ Restricts this image’s mask to be equal to the convex hull around the landmarks chosen. This is not a per-pixel convex hull, but is instead estimated by a triangulation of the points that contain the convex hull.
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. - label (str, 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.
- 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.
- group (str, optional) – The key of the landmark set that should be used. If
-
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 onself
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 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. IfFalse
, anImageBoundaryError
will be raised if an attempt is made to go beyond the edge of the image.
Returns: cropped_image (type(self)) – A new instance of self, but cropped.
Raises: ValueError
–min_indices
andmax_indices
both have to be of lengthn_dims
. Allmax_indices
must be greater thanmin_indices
.ImageBoundaryError
– Raised ifconstrain_to_boundary=False
, and an attempt is made to crop the image in a way that violates the image bounds.
- min_indices (
-
crop_inplace
(min_indices, max_indices, constrain_to_boundary=True)[source]¶ 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 (bool, optional) – If
True
the crop will be snapped to not go beyond this images boundary. IfFalse
, anImageBoundaryError
will be raised if an attempt is made to go beyond the edge of the image.
Returns: cropped_image (type(self)) – This image, but cropped.
Raises: ValueError
–min_indices
andmax_indices
both have to be of lengthn_dims
. Allmax_indices
must be greater thanmin_indices
.- map`ImageBoundaryError` –
Raised if
constrain_to_boundary=False
, and an attempt is made to crop the image in a way that violates the image bounds.
- min_indices (
-
crop_to_landmarks_inplace
(group=None, label=None, boundary=0, constrain_to_boundary=True)¶ Crop this image to be bounded around a set of landmarks with an optional
n_pixel
boundaryParameters: - 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. - label (str, optional) – The label of of the landmark manager that you wish to use. If
None
all landmarks in the group are 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. IfFalse
, an :map`ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.
Returns: image (
Image
) – This image, cropped to its landmarks.Raises: ImageBoundaryError
– Raised ifconstrain_to_boundary=False
, and an attempt is made to crop the image in a way that violates the image bounds.- group (str, optional) – The key of the landmark set that should be used. If
-
crop_to_landmarks_proportion_inplace
(boundary_proportion, group=None, label=None, 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 (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. - label (str, optional) – The label of of the landmark manager that you wish to use. If
None
all landmarks in the group are used. - minimum (bool, optional) – If
True
the specified proportion is relative to the minimum value of the landmarks’ per-dimension range; ifFalse
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. IfFalse
, anImageBoundaryError
will be raised if an attempt is made to go beyond the edge of the image.
Returns: image (
Image
) – This image, cropped to its landmarks with a border proportional to the landmark spread or range.Raises: ImageBoundaryError
– Raised ifconstrain_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)[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. IfFalse
, anImageBoundaryError
will be raised if an attempt is made to go beyond the edge of the image. Note that is only possible ifboundary != 0
.
Raises: ImageBoundaryError
– Raised if 11constrain_to_boundary=False`1, and an attempt is made to crop the image in a way that violates the image bounds.
-
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_size=(16, 16), sample_offsets=None, as_single_array=False)¶ 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.
Parameters: - patch_centers (
PointCloud
) – The centers to extract patches around. - patch_size (tuple or ndarray, optional) – The size of the patch to extract
- sample_offsets (
PointCloud
, 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. - as_single_array (bool, optional) – If
True
, an(n_center * n_offset, self.shape...)
ndarray, thus a single numpy array is returned containing each patch. IfFalse
, a list ofImage
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 ifas_single_array=False
.Raises: ValueError
– If image is not 2D- patch_centers (
-
extract_patches_around_landmarks
(group=None, label=None, patch_size=(16, 16), sample_offsets=None, as_single_array=False)¶ Extract patches around landmarks existing on this image. Provided the group label and optionally the landmark label extract a set of patches.
See extract_patches for more information.
Currently only 2D images are supported.
Parameters: - group (str or
None
optional) – The landmark group to use as patch centres. - label (str or
None
optional) – The landmark label within the group to use as centres. - patch_size (tuple or ndarray, optional) – The size of the patch to extract
- sample_offsets (
PointCloud
, 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. - as_single_array (bool, optional) – If
True
, an(n_center * n_offset, self.shape...)
ndarray, thus a single numpy array is returned containing each patch. IfFalse
, a list ofImage
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 ifas_single_array=False
.Raises: ValueError
– If image is not 2D- group (str or
-
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.- vector (
-
from_vector_inplace
(vector, copy=True)[source]¶ 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. IfTrue
a copy of the vector is taken.
Raises: Warning
– Ifcopy=False
cannot be honored.- vector (
-
gaussian_pyramid
(n_levels=3, downscale=2, sigma=None)¶ Return the gaussian pyramid of this image. The first image of the pyramid will be 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.
-
gradient
(nullify_values_at_mask_boundaries=False)[source]¶ 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 theTrue
mask region. This is useful in situations where there is absent data in the image which will cause erroneous gradient settings.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.
-
indices
()[source]¶ Return the indices of all true pixels in this image.
Type: (n_dims, n_true_pixels)
ndarray
-
masked_pixels
()[source]¶ Get the pixels covered by the True values in the mask.
Type: (mask.n_true, n_channels)
ndarray
-
n_false_elements
()[source]¶ The number of
False
elements of the image over all the channels.Type: int
-
normalize_norm_inplace
(mode='all', limit_to_mask=True, **kwargs)[source]¶ Normalizes this image such that it’s pixel values have zero mean and its norm equals 1.
Parameters: - mode (
{all, per_channel}
, optional) – Ifall
, the normalization is over all channels. Ifper_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. IfFalse
, the normalization is wrt all pixels, regardless of their masking value.
- mode (
-
normalize_std_inplace
(mode='all', limit_to_mask=True)[source]¶ Normalizes this image such that it’s pixel values have zero mean and unit variance.
Parameters: - mode (
{all, per_channel}
, optional) – Ifall
, the normalization is over all channels. Ifper_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. IfFalse
, the normalization is wrt all pixels, regardless of their masking value.
- mode (
-
pyramid
(n_levels=3, downscale=2)¶ Return a rescaled pyramid of this image. The first image of the pyramid will be 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.
-
rescale
(scale, round='ceil', order=1)¶ 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 Bi-quadratic 3 Bi-cubic 4 Bi-quartic 5 Bi-quintic
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=None, round='ceil', order=1)¶ 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. - label (str, optional) – The label of of the landmark manager that you wish to use. If
None
all landmarks in the group are 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 Bi-quadratic 3 Bi-cubic 4 Bi-quartic 5 Bi-quintic
Returns: rescaled_image (
type(self)
) – A copy of this image, rescaled.- diagonal_range (
-
rescale_to_diagonal
(diagonal, round='ceil')¶ 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.
Returns: rescaled_image (type(self)) – A copy of this image, rescaled.
-
rescale_to_reference_shape
(reference_shape, group=None, label=None, round='ceil', order=1)¶ 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 (
PointCloud
) – The reference shape to which the landmarks scale will be matched against. - 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. - label (str, optional) – The label of of the landmark manager that you wish to use. If
None
all landmarks in the group are 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 Bi-quadratic 3 Bi-cubic 4 Bi-quartic 5 Bi-quintic
Returns: rescaled_image (
type(self)
) – A copy of this image, rescaled.- reference_shape (
-
resize
(shape, order=1)¶ 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 Bi-quadratic 3 Bi-cubic 4 Bi-quartic 5 Bi-quintic
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.
-
rotate_ccw_about_centre
(theta, degrees=True, cval=0)¶ Return a rotation of this image clockwise about its centre.
Parameters: - theta (float) – The angle of rotation about the origin.
- degrees (bool, optional) – If
True
, theta is interpreted as a degree. IfFalse
,theta
is interpreted as radians. - cval (
float
, optional) – The value to be set outside the rotated image boundaries.
Returns: rotated_image (
type(self)
) – The rotated image.
-
set_masked_pixels
(pixels, copy=True)[source]¶ 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 allTrue
- in all other cases it will raise a warning.
Raises: Warning
– If thecopy=False
flag cannot be honored.
-
view_widget
(popup=False, browser_style='buttons', figure_size=(10, 8))¶ Visualizes the image object using the
visualize_images
widget. Currently only supports the rendering of 2D images.Parameters: - popup (bool, optional) – If
True
, the widget will appear as a popup window. - browser_style (
{buttons, slider}
, optional) – It defines whether the selector of the images will have the form of plus/minus buttons or a slider. - figure_size ((int, int) tuple, optional) – The initial size of the rendered figure.
- popup (bool, optional) – If
-
warp_to_mask
(template_mask, transform, warp_landmarks=False, order=1, mode='constant', cval=0.0)[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 asself
, 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 Bi-quadratic 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.
Returns: warped_image (
type(self)
) – A copy of this image, warped.- template_mask (
-
warp_to_shape
(template_shape, transform, warp_landmarks=False, order=1, mode='constant', cval=0.0)[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 Bi-quadratic 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.
Returns: warped_image (
MaskedImage
) – 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
-
diagonal
¶ The diagonal size of this image
Type: float
-
has_landmarks
¶ Whether the object has landmarks.
Type: bool
-
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
-
landmarks
¶ The landmarks object.
Type: LandmarkManager
-
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), 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
- image_data (