BooleanImage¶

class
menpo.image.
BooleanImage
(mask_data, copy=True)[source]¶ Bases:
Image
A mask image made from binary pixels. The region of the image that is left exposed by the mask is referred to as the ‘masked region’. The set of ‘masked’ pixels is those pixels corresponding to a
True
value in the mask. Parameters
mask_data (
(M, N, ..., L)
ndarray) – The binary mask data. Note that there is no channel axis  a 2D Mask Image is built from just a 2D numpy array of mask_data. Automatically coerced in to boolean values.copy (bool, optional) – If
False
, the image_data will not be copied on assignment. Note that if the array you provide is not boolean, there will still be copy. In general this should only be used if you know what you are doing.

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

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)[source]¶ Impossible for a
BooleanImage
to be transformed to aMaskedImage
.

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
whereeps
is some value arbitrarily close to 0, this value at least allows sampling without worrying about floating point error. Type
tuple

bounds_false
(boundary=0, constrain_to_bounds=True)[source]¶ Returns the minimum to maximum indices along all dimensions that the mask includes which fully surround the False mask values. In the case of a 2D Image for instance, the min and max define two corners of a rectangle bounding the False pixel values.
 Parameters
boundary (int >= 0, optional) – A number of pixels that should be added to the extent. A negative value can be used to shrink the bounds in.
constrain_to_bounds (bool, optional) – If
True
, the bounding extent is snapped to not go beyond the edge of the image. IfFalse
, the bounds are left unchanged.
 Returns
min_b (
(D,)
ndarray) – The minimum extent of theTrue
mask region with the boundary along each dimension. Ifconstrain_to_bounds=True
, is clipped to legal image bounds.max_b (
(D,)
ndarray) – The maximum extent of theTrue
mask region with the boundary along each dimension. Ifconstrain_to_bounds=True
, is clipped to legal image bounds.

bounds_true
(boundary=0, constrain_to_bounds=True)[source]¶ Returns the minimum to maximum indices along all dimensions that the mask includes which fully surround the
True
mask values. In the case of a 2D Image for instance, the min and max define two corners of a rectangle bounding the True pixel values. Parameters
boundary (int, optional) – A number of pixels that should be added to the extent. A negative value can be used to shrink the bounds in.
constrain_to_bounds (bool, optional) – If
True
, the bounding extent is snapped to not go beyond the edge of the image. IfFalse
, the bounds are left unchanged.
 Returns
min_b (
(D,)
ndarray) – The minimum extent of theTrue
mask region with the boundary along each dimension. Ifconstrain_to_bounds=True
, is clipped to legal image bounds.max_b (
(D,)
ndarray) – The maximum extent of theTrue
mask region with the boundary along each dimension. Ifconstrain_to_bounds=True
, is clipped to legal image bounds.

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 Imagebounds()
method. For example:>>> im.constrain_landmarks_to_bounds() # Equivalent to below >>> im.landmarks['test'] = im.landmarks['test'].constrain_to_bounds(im.bounds())

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.

constrain_to_landmarks
(group=None, batch_size=None)[source]¶ Returns a copy of this image whereby the
True
values in the image are restricted to be equal to the convex hull around the landmarks chosen. This is not a perpixel convex hull, but instead relies on a triangulated approximation. If the landmarks in question are an instance ofTriMesh
, the triangulation of the landmarks will be used in the convex hull calculation. If the landmarks are an instance ofPointCloud
, Delaunay triangulation will be used to create a triangulation. 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.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. IfNone
, no batching is used and all points are checked at once.
 Returns
constrained (
BooleanImage
) – The new boolean image, constrained by the given landmark group.

constrain_to_pointcloud
(pointcloud, batch_size=None, point_in_pointcloud='pwa')[source]¶ Returns a copy of this image whereby the
True
values in the image are restricted to be equal to the convex hull around a pointcloud. The choice of whether a pixel is inside or outside of the pointcloud is determined by thepoint_in_pointcloud
parameter. By default a Piecewise Affine transform is used to test for containment, which is useful when aligning images by their landmarks. Triangluation will be decided by Delauny  if you wish to customise it, aTriMesh
instance can be passed for thepointcloud
argument. In this case, the triangulation of the Trimesh will be used to define the retained region.For large images, a faster and pixelaccurate method can be used ( ‘convex_hull’). Here, there is no specialization for
TriMesh
instances. Alternatively, a callable can be provided to override the test. By default, the provided implementations are only valid for 2D images. Parameters
pointcloud (
PointCloud
orTriMesh
) – The pointcloud of points that should be constrained to. See point_in_pointcloud for how in some cases aTriMesh
may be used to control 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. IfNone
, 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. If ‘pwa’, Menpo’sPiecewiseAffine
transform will be used to test for containment. In this casepointcloud
should be aTriMesh
. If it isn’t, Delauny triangulation will be used to first triangulatepointcloud
into aTriMesh
before testing for containment. If a callable is passed, it should take two parameters, thePointCloud
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 thePointCloud
.
 Returns
constrained (
BooleanImage
) – The new boolean image, constrained by the given pointcloud. Raises
ValueError – If the image is not 2D and a default implementation is chosen.
ValueError – If the chosen
point_in_pointcloud
is unknown.

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_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. IfFalse
, anImageBoundaryError
will be raised if an attempt is made to go beyond the edge of the image.return_transform (bool, optional) – If
True
, then theTransform
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 isTrue
.
 Raises
ValueError –
min_indices
andmax_indices
both have to be of lengthn_dims
. Allmax_indices
must be greater thanmin_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. IfFalse
, an :map`ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.return_transform (bool, optional) – If
True
, then theTransform
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’ perdimension range; ifFalse
w.r.t. the maximum value of the landmarks’ perdimension 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.return_transform (bool, optional) – If
True
, then theTransform
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_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. IfFalse
, an :map`ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.return_transform (bool, optional) – If
True
, then theTransform
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_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’ perdimension range; ifFalse
w.r.t. the maximum value of the pointclouds’ perdimension 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.return_transform (bool, optional) – If
True
, then theTransform
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.

diagonal
()¶ The diagonal size of this image
 Type
float

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
ormode
parameters are modified fromorder = 0
andmode = '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 extractsample_offsets (
(n_offsets, n_dims)
ndarray orNone
, 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. IfNone
, 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. IfFalse
, a list ofn_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 ifas_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.
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.patch_shape (tuple or ndarray, optional) – The size of the patch to extract
sample_offsets (
(n_offsets, n_dims)
ndarray orNone
, 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. IfNone
, 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. IfFalse
, a list ofn_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 ifas_single_array=False
. Raises
ValueError – If image is not 2D

from_vector
(vector, copy=True)[source]¶ Takes a flattened vector and returns a new
BooleanImage
formed by reshaping the vector to the correct dimensions. Note that this is rebuilding a boolean image itself from boolean values. The mask is in no way interpreted in performing the operation, in contrast toMaskedImage
, where only the masked region is used infrom_vector()
and :meth`as_vector`. Any image landmarks are transferred in the process. Parameters
vector (
(n_pixels,)
bool ndarray) – A flattened vector of all the pixels of aBooleanImage
.copy (bool, optional) – If
False
, no copy of the vector will be taken.
 Returns
image (
BooleanImage
) – New BooleanImage of same shape as this image Raises
Warning – If
copy=False
cannot be honored.

from_vector_inplace
(vector)¶ Deprecated. Use the nonmutating API,
from_vector
.For internal usage in performancesensitive 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 tonan
values. Returns
has_nan_values (bool) – If the vectorized object contains
nan
values.

indices
()¶ Return the indices of all pixels in this image.
 Type
(
n_dims
,n_pixels
) ndarray

classmethod
init_blank
(shape, fill=True, round='ceil', **kwargs)[source]¶ Returns a blank
BooleanImage
of the requested shape Parameters
shape (tuple or list) – The shape of the image. Any floating point values are rounded according to the
round
kwarg.fill (bool, optional) – The mask value to be set everywhere.
round (
{ceil, floor, round}
, optional) – Rounding function to be applied to floating point shapes.
 Returns
blank_image (
BooleanImage
) – A blank mask of the requested size

classmethod
init_from_channels_at_back
(pixels)[source]¶ This method is not required for
BooleanImage
types as boolean images do not expect a channel axis for construction. Parameters
pixels (
(M, N ..., Q)
ndarray) – Array representing the image pixels, with NO channel axis. Returns
image (
BooleanImage
) – A new image from the given boolean pixels.

classmethod
init_from_pointcloud
(pointcloud, group=None, boundary=0, constrain=True, fill=True)[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.fill (int, optional) – The value to fill all pixels with.
constrain (bool, optional) – If
True
, theTrue
values will be image will be constrained to the convex hull of the provided pointcloud. IfFalse
, the mask will be the value offill
.
 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.

invert
()[source]¶ Returns a copy of this boolean image, which is inverted.
 Returns
inverted (
BooleanImage
) – A copy of this boolean mask, where allTrue
values areFalse
and allFalse
values areTrue
.

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
Nearestneighbor
1
Bilinear (default)
2
Biquadratic
3
Bicubic
4
Biquartic
5
Biquintic
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 theTransform
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 isTrue
.
 Raises
ValueError – axis cannot be negative
ValueError – axis={} but the image has {} dimensions

normalize_norm
(mode='all', **kwargs)¶ Returns a copy of this image normalized such that its 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 unit norm. Returns
image (
type(self)
) – A copy of this image, normalized.

normalize_std
(mode='all', **kwargs)¶ Returns a copy of this image normalized such that its 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. 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')¶ 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.
 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 aPointDirectedGraph
, 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 (3channel) or Greyscale (1channel) 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
Nearestneighbor
1
Bilinear (default)
2
Biquadratic
3
Bicubic
4
Biquartic
5
Biquintic
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 theTransform
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 isTrue
.
 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 specifieddiagonal_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
Nearestneighbor
1
Bilinear (default)
2
Biquadratic
3
Bicubic
4
Biquartic
5
Biquintic
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 theTransform
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 isTrue
.

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. IfFalse
, 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 theTransform
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 isTrue
.

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 bygroup
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
Nearestneighbor
1
Bilinear (default)
2
Biquadratic
3
Bicubic
4
Biquartic
5
Biquintic
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 theTransform
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 isTrue
.

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
Nearestneighbor
1
Bilinear (default)
2
Biquadratic
3
Bicubic
4
Biquartic
5
Biquintic
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 theTransform
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 isTrue
.
 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 counterclockwise 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. Ifretain_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. IfFalse
,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. IfFalse
, 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 caseretain_shape=True
.order (int, optional) –
The order of interpolation. The order has to be in the range
[0,5]
. This is only used in caseretain_shape=True
.Order
Interpolation
0
Nearestneighbor
1
Bilinear (default)
2
Biquadratic
3
Bicubic
4
Biquartic
5
Biquintic
warp_landmarks (bool, optional) – If
True
, result will have the same landmark dictionary asself
, but with each landmark updated to the warped position.return_transform (bool, optional) – If
True
, then theTransform
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 isTrue
.
 Raises
ValueError – Image rotation is presently only supported on 2D images

sample
(points_to_sample, mode='constant', cval=False, **kwargs)[source]¶ Sample this image at the given subpixel accurate points. The input PointCloud should have the same number of dimensions as the image e.g. a 2D PointCloud for a 2D multichannel image. A numpy array will be returned the has the values for every given point across each channel of the image.
 Parameters
points_to_sample (
PointCloud
) – Array of points to sample from the image. Should be (n_points, n_dims)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
sampled_pixels ((n_points, n_channels) bool ndarray) – The interpolated values taken across every channel of the image.

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:
(n_center, n_offset, self.n_channels, patch_shape)
ndarraylist 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 ofn_center * n_offset
Image
objects.patch_centers (
PointCloud
) – The centers to set the patches around.offset (list or tuple or
(1, 2)
ndarray orNone
, optional) – The offset to apply on the patch centers within the image. IfNone
, 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. IfNone
, then0
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:
(n_center, n_offset, self.n_channels, patch_shape)
ndarraylist 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 ofn_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 orNone
, optional) – The offset to apply on the patch centers within the image. IfNone
, 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. IfNone
, then0
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. Ifretain_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
andVInvertible
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. IfFalse
, 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 caseretain_shape=True
.order (int, optional) –
The order of interpolation. The order has to be in the range
[0,5]
. This is only used in caseretain_shape=True
.Order
Interpolation
0
Nearestneighbor
1
Bilinear (default)
2
Biquadratic
3
Bicubic
4
Biquartic
5
Biquintic
warp_landmarks (bool, optional) – If
True
, result will have the same landmark dictionary asself
, but with each landmark updated to the warped position.return_transform (bool, optional) – If
True
, then theTransform
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 isTrue
.
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 # Load image 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) im.transform_about_centre(rot_tr).view_landmarks() plt.title('Rotated') # Render rotated image that has shape equal as original image plt.subplot(133) im.transform_about_centre(rot_tr, retain_shape=True).view_landmarks() 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 # Load image 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) im.transform_about_centre(shear_tr).view_landmarks() plt.title('Sheared') # Render sheared image that has shape equal as original image plt.subplot(133) im.transform_about_centre(shear_tr, retain_shape=True).view_landmarks() plt.title('Sheared (Retain original shape)')

warp_to_mask
(template_mask, transform, warp_landmarks=True, mode='constant', cval=False, batch_size=None, return_transform=False)[source]¶ Return a copy of this
BooleanImage
warped into a different reference space.Note that warping into a mask is slower than warping into a full image. If you don’t need a nonlinear mask, consider warp_to_shape instead.
 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.mode (
{constant, nearest, reflect or 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. IfNone
, 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 theTransform
object is also returned.
 Returns
warped_image (
BooleanImage
) – A copy of this image, warped.transform (
Transform
) – The transform that was used. It only applies if return_transform isTrue
.

warp_to_shape
(template_shape, transform, warp_landmarks=True, mode='constant', cval=False, order=None, batch_size=None, return_transform=False)[source]¶ Return a copy of this
BooleanImage
warped into a different reference space.Note that the order keyword argument is in fact ignored, as any order other than 0 makes no sense on a binary image. The keyword argument is present only for compatibility with the
Image
warp_to_shape API. Parameters
template_shape (
(n_dims, )
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.mode (
{constant, nearest, reflect or 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. IfNone
, 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 theTransform
object is also returned.
 Returns
warped_image (
BooleanImage
) – A copy of this image, warped.transform (
Transform
) – The transform that was used. It only applies if return_transform isTrue
.

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 seerescale()
. 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 ofcval
.order (int, optional) –
The order of interpolation. The order has to be in the range [0,5]
Order
Interpolation
0
Nearestneighbor
1
Bilinear (default)
2
Biquadratic
3
Bicubic
4
Biquartic
5
Biquintic
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 theTransform
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 isTrue
.

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

property
mask
¶ Returns the pixels of the mask with no channel axis. This is what should be used to mask any kdimensional image.
 Type
(M, N, ..., L)
, bool ndarray

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