Image¶
- class menpo.image.base.Image(image_data, copy=True)[source]¶
Bases: Vectorizable, Landmarkable, Viewable
An n-dimensional image.
Images are n-dimensional homogeneous regular arrays of data. Each spatially distinct location in the array is referred to as a pixel. At a pixel, k distinct pieces of information can be stored. Each datum at a pixel is refereed to as being in a channel. All pixels in the image have the same number of channels, and all channels have the same data-type (float).
Parameters: image_data : (M, N ..., Q, C) ndarray
Array representing the image pixels, with the last axis being channels.
copy : bool, optional
If False, the image_data will not be copied on assignment. Note that this will miss out on additional checks. Further note that we still demand that the array is C-contiguous - if it isn’t, a copy will be generated anyway. In general, this should only be used if you know what you are doing.
Raises: Warning :
If copy=False cannot be honoured
ValueError :
If the pixel array is malformed
Attributes
features ImageFeatures Gives access to all the feature types that we support. - as_PILImage()[source]¶
Return a PIL copy of the image. Scales the image by 255 and converts to np.uint8. Image must only have 1 or 3 channels and be two dimensional.
Returns: pil_image : PILImage
PIL copy of image as np.uint8
Raises: ValueError if image is not 2D and 1 channel or 3 channels. :
- as_greyscale(mode='luminosity', channel=None)[source]¶
Returns a greyscale version of the image. If the image does not represent a 2D RGB image, then the ‘luminosity’ mode will fail.
Parameters: mode : {‘average’, ‘luminosity’, ‘channel’}
‘luminosity’ - Calculates the luminance using the CCIR 601 formula
Y’ = 0.2989 R’ + 0.5870 G’ + 0.1140 B’
‘average’ - intensity is an equal average of all three channels ‘channel’ - a specific channel is used
Default ‘luminosity’
channel: int, optional :
The channel to be taken. Only used if mode is ‘channel’.
Default: None
Returns: greyscale_image: :class:`MaskedImage` :
A copy of this image in greyscale.
- as_histogram(keep_channels=True, bins='unique')[source]¶
Histogram binning of the values of this image.
Parameters: keep_channels : bool, optional
If set to False, it returns a single histogram for all the channels of the image. If set to True, it returns a list of histograms, one for each channel.
Default: True
bins : ‘unique’, positive int or sequence of scalars, optional
If set equal to ‘unique’, the bins of the histograms are centered on the unique values of each channel. If set equal to a positive integer, then this is the number of bins. If set equal to a sequence of scalars, these will be used as bins centres.
Default: ‘unique’
Returns: hist : array or list with n_channels arrays
The histogram(s). If keep_channels=False, then hist is an array. If keep_channels=True, then hist is a list with len(hist)=n_channels.
bin_edges : array or list with n_channels arrays
An array or a list of arrays corresponding to the above histograms that store the bins’ edges. The result in the case of list of arrays can be visualized as:
- for k in range(len(hist)):
plt.subplot(1,len(hist),k) width = 0.7 * (bin_edges[k][1] - bin_edges[k][0]) center = (bin_edges[k][:-1] + bin_edges[k][1:]) / 2 plt.bar(center, hist[k], align=’center’, width=width)
Raises: ValueError :
Bins can be either ‘unique’, positive int or a sequence of scalars.
- as_vector(**kwargs)¶
Returns a flattened representation of the object as a single vector.
Returns: vector : (N,) ndarray
The core representation of the object, flattened into a single vector. Note that this is always a view back on to the original object, but is not writable.
- classmethod blank(shape, n_channels=1, fill=0, dtype=<Mock object at 0x7f5c2e9d6a10>)[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
Default: 1
fill : int, optional
The value to fill all pixels with
Default: 0
dtype: numpy data type, optional :
The data type of the image.
Default: np.float
Returns: blank_image : Image
A new image of the requested size.
- constrain_landmarks_to_bounds()[source]¶
Move landmarks that are located outside the image bounds on the bounds.
- constrain_points_to_bounds(points)[source]¶
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()[source]¶
Return a new image with copies of the pixels and landmarks of this image.
This is an efficient copy method. If you need to copy all the state on the object, consider deepcopy instead.
Returns: image: :map:`Image` :
A new image with the same pixels and landmarks as this one, just copied.
- crop(min_indices, max_indices, constrain_to_boundary=False)[source]¶
Return a cropped copy of this image using the given minimum and maximum indices. Landmarks are correctly adjusted so they maintain their position relative to the newly cropped image.
Parameters: min_indices : (n_dims, ) ndarray
The minimum index over each dimension
max_indices : (n_dims, ) ndarray
The maximum index over each dimension
constrain_to_boundary : boolean, optional
If True the crop will be snapped to not go beyond this images boundary. If False, an ImageBoundaryError will be raised if an attempt is made to go beyond the edge of the image.
Default: True
Returns: cropped_image : type(self)
A new instance of self, but cropped.
Raises: ValueError :
min_indices and max_indices both have to be of length n_dims. All max_indices must be greater than min_indices.
ImageBoundaryError :
Raised if constrain_to_boundary is False, and an attempt is made to crop the image in a way that violates the image bounds.
- crop_inplace(min_indices, max_indices, constrain_to_boundary=True)[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 : boolean, optional
If True the crop will be snapped to not go beyond this images boundary. If False, an ImageBoundaryError will be raised if an attempt is made to go beyond the edge of the image.
Default: True
Returns: cropped_image : type(self)
This image, cropped.
Raises: `ValueError` :
min_indices and max_indices both have to be of length n_dims. All max_indices must be greater than min_indices.
`ImageBoundaryError` :
Raised if constrain_to_boundary is False, and an attempt is made to crop the image in a way that violates the image bounds.
- crop_to_landmarks_inplace(group=None, label='all', boundary=0, constrain_to_boundary=True)[source]¶
Crop this image to be bounded around a set of landmarks with an optional n_pixel boundary
Parameters: group : string, Optional
The key of the landmark set that should be used. If None, and if there is only one set of landmarks, this set will be used.
Default: None
label : string, Optional
The label of of the landmark manager that you wish to use. If ‘all’ all landmarks in the group are used.
Default: ‘all’
boundary : int, Optional
An extra padding to be added all around the landmarks bounds.
Default: 0
constrain_to_boundary : boolean, optional
If True the crop will be snapped to not go beyond this images boundary. If False, an :map`ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.
Default: True
Returns: image : Image
This image, cropped to it’s landmarks.
Raises: ImageBoundaryError :
Raised if constrain_to_boundary is False, and an attempt is made to crop the image in a way that violates the image bounds.
- crop_to_landmarks_proportion_inplace(boundary_proportion, group=None, label='all', minimum=True, constrain_to_boundary=True)[source]¶
Crop this image to be bounded around a set of landmarks with a border proportional to the landmark spread or range.
Parameters: boundary_proportion : float
Additional padding to be added all around the landmarks bounds defined as a proportion of the landmarks’ range. See the minimum parameter for a definition of how the range is calculated.
group : string, Optional
The key of the landmark set that should be used. If None, and if there is only one set of landmarks, this set will be used.
Default: None
label : string, Optional
The label of of the landmark manager that you wish to use. If ‘all’ all landmarks in the group are used.
Default: ‘all’
minimum : bool, Optional
If True the specified proportion is relative to the minimum value of the landmarks’ per-dimension range; if False w.r.t. the maximum value of the landmarks’ per-dimension range.
Default: True
constrain_to_boundary : boolean, optional
If True, the crop will be snapped to not go beyond this images boundary. If False, an ImageBoundaryError will be raised if an attempt is made to go beyond the edge of the image.
Default: True
Returns: image : Image
This image, cropped to it’s landmarks with a border proportional to the landmark spread or range.
Raises: ImageBoundaryError :
Raised if constrain_to_boundary is False, and an attempt is made to crop the image in a way that violates the image bounds.
- from_vector(vector, n_channels=None, copy=True)[source]¶
Takes a flattened vector and returns a new image formed by reshaping the vector to the correct pixels and channels.
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_parameters,)
A flattened vector of all pixels and channels of an image.
n_channels : int, optional
If given, will assume that vector is the same shape as this image, but with a possibly different number of channels
Default: Use the existing image channels
copy : bool, optional
If False the vector will not be copied in creating the new image.
Default: True
Returns: image : Image
New image of same shape as this image and the number of specified channels.
Raises: Warning : If the copy=False flag cannot be honored
- from_vector_inplace(vector, copy=True)[source]¶
Takes a flattened vector and update this image by reshaping the vector to the correct dimensions.
Parameters: vector : (n_pixels,) np.bool ndarray
A vector vector of all the pixels of a BooleanImage.
copy: bool, optional :
If False, the vector will be set as the pixels. If True a copy of the vector is taken.
Default: True
Raises: Warning : If copy=False flag cannot be honored
Notes
For BooleanImage’s this is rebuilding a boolean image itself from boolean values. The mask is in no way interpreted in performing the operation, in contrast to MaskedImage, where only the masked region is used in from_vector{_inplace}() and as_vector().
- gaussian_pyramid(n_levels=3, downscale=2, sigma=None, order=1, mode='reflect', cval=0)[source]¶
Return the gaussian pyramid of this image. The first image of the pyramid will be the original, unmodified, image.
Parameters: n_levels : int
Number of levels in the pyramid. When set to -1 the maximum number of levels will be build.
Default: 3
downscale : float, optional
Downscale factor.
Default: 2
sigma : float, optional
Sigma for gaussian filter. Default is 2 * downscale / 6.0 which corresponds to a filter mask twice the size of the scale factor that covers more than 99% of the gaussian distribution.
Default: None
order : int, optional
Order of splines used in interpolation of downsampling. See scipy.ndimage.map_coordinates for detail.
Default: 1
mode : {‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’}, optional
The mode parameter determines how the array borders are handled, where cval is the value when mode is equal to ‘constant’.
Default: ‘reflect’
cval : float, optional
Value to fill past edges of input if mode is ‘constant’.
Default: 0
Returns: image_pyramid: :
Generator yielding pyramid layers as menpo image objects.
- glyph(vectors_block_size=10, use_negative=False, channels=None)[source]¶
Create glyph of a feature image. If feature_data has negative values, the use_negative flag controls whether there will be created a glyph of both positive and negative values concatenated the one on top of the other.
Parameters: vectors_block_size: int :
Defines the size of each block with vectors of the glyph image.
use_negative: bool :
Defines whether to take into account possible negative values of feature_data.
- gradient(**kwargs)[source]¶
Returns an Image 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.
Returns: gradient : Image
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.
- rescale(scale, interpolator='scipy', round='ceil', **kwargs)[source]¶
Return a copy of this image, rescaled by a given factor. Landmarks are rescaled appropriately.
Parameters: scale : float or tuple
The scale factor. If a tuple, the scale to apply to each dimension. If a single float, the scale will be applied uniformly across each dimension.
interpolator : ‘scipy’, optional
The interpolator that should be used to perform the warp.
Default: ‘scipy’
round: {‘ceil’, ‘floor’, ‘round’} :
Rounding function to be applied to floating point shapes.
Default: ‘ceil’
kwargs : dict
Passed through to the interpolator. See menpo.interpolation for details. Note that mode is set to nearest to avoid numerical issues, and cannot be changed here by the user.
Returns: rescaled_image : type(self)
A copy of this image, rescaled.
Raises: ValueError: :
If less scales than dimensions are provided. If any scale is less than or equal to 0.
- rescale_landmarks_to_diagonal_range(diagonal_range, group=None, label='all', interpolator='scipy', round='ceil', **kwargs)[source]¶
Return a copy of this image, rescaled so that the diagonal_range of the bounding box containing its landmarks matches the specified diagonal_range range.
Parameters: diagonal_range: :class:`menpo.shape.pointcloud` :
The diagonal_range range that we want the landmarks of the returned image to have.
group : string, Optional
The key of the landmark set that should be used. If None, and if there is only one set of landmarks, this set will be used.
Default: None
label: string, Optional :
The label of of the landmark manager that you wish to use. If ‘all’ all landmarks in the group are used.
Default: ‘all’
interpolator : ‘scipy’, optional
The interpolator that should be used to perform the warp.
round: {‘ceil’, ‘floor’, ‘round’} :
Rounding function to be applied to floating point shapes.
Default: ‘ceil’
kwargs : dict
Passed through to the interpolator. See menpo.interpolation for details.
Returns: rescaled_image : type(self)
A copy of this image, rescaled.
- rescale_to_reference_shape(reference_shape, group=None, label='all', interpolator='scipy', round='ceil', **kwargs)[source]¶
Return a copy of this image, rescaled so that the scale of a particular group of landmarks matches the scale of the passed reference landmarks.
Parameters: reference_shape: :class:`menpo.shape.pointcloud` :
The reference shape to which the landmarks scale will be matched against.
group : string, Optional
The key of the landmark set that should be used. If None, and if there is only one set of landmarks, this set will be used.
Default: None
label: string, Optional :
The label of of the landmark manager that you wish to use. If ‘all’ all landmarks in the group are used.
Default: ‘all’
interpolator : ‘scipy’ or ‘c’, optional
The interpolator that should be used to perform the warp.
round: {‘ceil’, ‘floor’, ‘round’} :
Rounding function to be applied to floating point shapes.
Default: ‘ceil’
kwargs : dict
Passed through to the interpolator. See menpo.interpolation for details.
Returns: rescaled_image : type(self)
A copy of this image, rescaled.
- resize(shape, interpolator='scipy', **kwargs)[source]¶
Return a copy of this image, resized to a particular shape. All image information (landmarks, the mask in the case of MaskedImage) is resized appropriately.
Parameters: shape : tuple
The new shape to resize to.
interpolator : ‘scipy’ or ‘c’, optional
The interpolator that should be used to perform the warp.
Default: ‘scipy’
kwargs : dict
Passed through to the interpolator. See menpo.interpolation for details.
Returns: resized_image : type(self)
A copy of this image, resized.
Raises: ValueError: :
If the number of dimensions of the new shape does not match the number of dimensions of the image.
- smoothing_pyramid(n_levels=3, downscale=2, sigma=None, mode='reflect', cval=0)[source]¶
Return the smoothing pyramid of this image. The first image of the pyramid will be the original, unmodified, image.
Parameters: n_levels : int
Number of levels in the pyramid. When set to -1 the maximum number of levels will be build.
Default: 3
downscale : float, optional
Downscale factor.
Default: 2
sigma : float, optional
Sigma for gaussian filter. Default is 2 * downscale / 6.0 which corresponds to a filter mask twice the size of the scale factor that covers more than 99% of the gaussian distribution.
Default: None
mode : {‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’}, optional
The mode parameter determines how the array borders are handled, where cval is the value when mode is equal to ‘constant’.
Default: ‘reflect’
cval : float, optional
Value to fill past edges of input if mode is ‘constant’.
Default: 0
Returns: image_pyramid: :
Generator yielding pyramid layers as menpo image objects.
- view(**kwargs)¶
View the object using the default rendering engine figure handling. For example, the default behaviour for Matplotlib is that all draw commands are applied to the same figure object.
Parameters: kwargs : dict
Passed through to specific rendering engine.
Returns: viewer : Renderer
The renderer instantiated.
- view_new(**kwargs)¶
View the object on a new figure.
Parameters: kwargs : dict
Passed through to specific rendering engine.
Returns: viewer : Renderer
The renderer instantiated.
- view_on(figure_id, **kwargs)¶
View the object on a a specific figure specified by the given id.
Parameters: figure_id : object
A unique identifier for a figure.
kwargs : dict
Passed through to specific rendering engine.
Returns: viewer : Renderer
The renderer instantiated.
- warp_to(template_mask, transform, warp_landmarks=False, interpolator='scipy', **kwargs)[source]¶
Return a copy of this image warped 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 True pixel location on the template, which pixel location should be sampled from on this image.
warp_landmarks : bool, optional
If True, warped_image will have the same landmark dictionary as self, but with each landmark updated to the warped position.
Default: False
interpolator : ‘scipy’, optional
The interpolator that should be used to perform the warp.
Default: ‘scipy’
kwargs : dict
Passed through to the interpolator. See menpo.interpolation for details.
Returns: warped_image : type(self)
A copy of this image, warped.
- centre[source]¶
The geometric centre of the Image - the subpixel that is in the middle.
Useful for aligning shapes and images.
Type: (n_dims,) ndarray
- has_landmarks_outside_bounds[source]¶
Indicates whether there are landmarks located outside the image bounds.
Type: bool
- height[source]¶
The height of the image.
This is the height according to image semantics, and is thus the size of the first dimension.
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