Welcome¶

Welcome to the Menpo documentation!

Menpo is a Python package designed to make manipulating annotated data more simple. In particular, sparse locations on either images or meshes, referred to as landmarks within Menpo, are tightly coupled with their reference objects. For areas such as Computer Vision that involve learning models based on prior knowledge of object location (such as object detection and landmark localisation), Menpo is a very powerful toolkit.

A short example is often more illustrative than a verbose explanation. Let’s assume that you want to load a set of images that have been annotated with bounding boxes, and that these bounding box locations live in text files next to the images. Here’s how we would load the images and extract the areas within the bounding boxes using Menpo:

import menpo.io as mio

images = []
for image in mio.import_images('./images_folder'):
    image.crop_to_landmarks_inplace()
    images.append(image)

Where import_images yields a generator to keep memory usage low.

Although the above is a very simple example, we believe that being able to easily manipulate and couple landmarks with images and meshes, is an important problem for building powerful models in areas such as facial point localisation.

To get started, check out the User Guide for instructions on installation and some of the core concepts within Menpo.

User Guide¶

The User Guide is designed to give you an overview of the key concepts within Menpo. In particular, we want to try and explain some of the design decisions that we made and demonstrate why we think they are powerful concepts for exploring visual data.

Quick Start¶

Here we give a very quick rundown of the basic links and information sources for the project.

Basic Installation¶

Menpo should be installable via pip on all major platforms:

$ pip install menpo

However, in the menpo team, we strongly advocate the usage of conda for scientific Python, as it makes installation of compiled binaries much more simple. In particular, if you wish to use any of the related Menpo projects such as menpofit, menpo3d or menpodetect, you will not be able to easily do so without using conda.

$ conda install -c menpo menpo

To install using conda, please see the thorough instructions for each platform on the Menpo website.

API Documentation¶

Visit API Documentation

Menpo is extensively documented on a per-method/class level and much of this documentation is reflected in the API Documentation. If any functions or classes are missing, please bring it to the attention of the developers on Github.

Notebooks¶

Explore the Menpo Notebooks

For a more thorough set of examples, we provide a set of IPython notebooks that demonstrate common use cases of Menpo. This concentrates on an overview of the functionality of the major classes and ideas behind Menpo.

User Group and Issues¶

If you wish to get in contact with the Menpo developers, you can do so via various channels. If you have found a bug, or if any part of Menpo behaves in a way you do not expect, please raise an issue on Github.

If you want to ask a theoretical question, or are having problems installing or setting up Menpo, please visit the user group.

Introduction¶

This user guide is a general introduction to Menpo, aiming to provide a bird’s eye of Menpo’s design. After reading this guide you should be able to go explore Menpo’s extensive Notebooks and not be too suprised by what you see.

Core Interfaces¶

Menpo is an object oriented framework built around a set of core abstract interfaces, each one governing a single facet of Menpo’s design. Menpo’s key interfaces are:

Shape - spatial data containers
Vectorizable - efficient bi-directional conversion of types to a vector representation
Targetable - objects that generate some spatial data
Transform - flexible spatial transformations
Landmarkable - objects that can be annotated with spatial labelled landmarks

Data containers¶

Most numerical data in Menpo is passed around in one of our core data containers. The features of each of the data containers is explained in great detail in the notebooks - here we just list them to give you a feel for what to expect:

Image - n-dimensional image with k-channels of data
MaskedImage - As Image, but with a boolean mask
BooleanImage - As boolean image that is used for masking images.
PointCloud - n-dimensional ordered point collection
PointUndirectedGraph - n-dimensional ordered point collection with directed connectivity
PointDirectedGraph - n-dimensional ordered point collection with undirected connectivity
TriMesh - As PointCloud, but with a triangulation

Menpo’s Data Types¶

Menpo is a high level software package. It is not a replacement for scikit-image, scikit-learn, or opencv - it ties all these types of packages together in to a unified framework for building and fitting deformable models. As a result, most of our algorithms take as input a higher level representation of data than simple numpy arrays.

Why have data types - what’s wrong with numpy arrays?¶

Menpo’s data types are thin wrappers around numpy arrays. They give semantic meaning to the underlying array through providing clearly named and consistent properties. As an example let’s take a look at PointCloud, Menpo’s workhorse for spatial data. Construction requires a numpy array:

x = np.random.rand(3, 2)
pc = PointCloud(x)

It’s natural to ask the question:

Is this a collection of three 2D points, or two 3D points?

In Menpo, you never do this - just look at the properties on the pointcloud:

pc.n_points  # 3
pc.n_dims    # 2

If we take a look at the properties we can see they are trivial:

@property
def n_points(self):
    return self.points.shape[0]

@property
def n_dims(self):
    return self.points.shape[1]

Using these properties makes code much more readable in algorithms accepting Menpo’s types. Let’s imagine a routine that does some operation on an image and a related point cloud. If it accepted numpy arrays, we might see something like this on the top line:

def foo_arrays(x, img):
    # preallocate the result
    y = np.zeros(x.shape[1],
                 x.shape[2],
                 img.shape[-1])
    ...

On first glance it is not at all apparent what y‘s shape is semantically. Now let’s take a look at the equivalent code using Menpo’s types:

def foo_menpo(pc, img):
    # preallocate the result
    y = np.zeros(pc.n_dims,
                 pc.n_points,
                 img.n_channels)
    ...

This time it’s immediately apparent what y‘s shape is. Although this is a somewhat contrived example, you will find this pattern applied consistently across Menpo, and it aids greatly in keeping the code readable.

Key points¶

1. Containers store the underlying numpy array in an easy to access attribute. For the PointCloud family see the .points attribute. On Image and subclasses, the actual data array is stored at .pixels.

2. Importing assets though menpo.io will result in our data containers, not numpy arrays. This means in a lot of situations you never need to remember the Menpo conventions for ordering of array data - just ask for an image and you will get an Image object.

3. All containers copy data by default. Look for the copy=False keyword argument if you want to avoid copying a large numpy array for performance.

4. Containers perform sanity checks. This helps catch obvious bugs like misshaping an array. You can sometimes suppress them for extra performance with the skip_checks=True keyword argument.

Working with Images and PointClouds¶

Menpo takes an opinionated stance on certain issues - one of which is establishing sensible rules for how to work with spatial data and image data in the same framework.

Let’s start with a quiz - which of the following is correct?

Most would answer b - images are indexed from the top left, with x going across and y going down.

Now another question - how do I access that pixel in the pixels array?

a: lenna[30, 50]
b: lenna[50, 30]

The correct answer is b - pixels get stored in a y, x order so we have to flip the points to access the array.

As Menpo blends together use of PointClouds and Images frequently this can cause a lot of confusion. You might create a Translation of 5 in the y direction as the following:

t = menpo.transform.Translation([0, 5])

And then expect to use it to warp an image:

img.warp_to(reference_shape, t)

and then some spatial data related to the image:

t.apply(some_data)

Unfortunately the meaning of y in these two domains is different - some code would have to flip the order of applying the translation of the transform to an image, a potential cause of confusion.

The worst part about this is that once we go to voxel data (which Image largely supports, and will fully support in the future), a z-axis is added. Now we drop all the swapping business - and the third axis of the spatial data once more corresponds with the third axis of the image data. Trying to keep track of these rules muddies an otherwise very simple concept.

Menpo’s approach¶

Menpo’s solution to this problem is simple - drop the insistence of calling axes x, y, and z. The zeroth axis of the pixel data is simply that - the zeroth axis. It corresponds exactly with the zeroth axis on the point cloud. If you have an image with annotations provided the zeroth axis of the PointCloud representing the annotations will correspond with the zeroth axis of the image. This rule makes working with images and spatial data simple - short you should never have to think about flipping axes in Menpo.

It’s natural to be concerned at this point that establishing such rules must make it really difficult ingest data which follows different conventions. This is incorrect - one of the biggest strengths of the menpo.io module is that each asset importer normalizes the format of the data to format Menpo’s rules.

Key Points¶

Menpo is n-dimensional. We try and avoid speaking of x and y, because there are many different conventions in use.
The IO module ensures that different data formats are normalized upon loading into Menpo. For example, Image types are imported as 64-bit floating point numbers normalised between [0, 1], by default.
axis 0 of landmarks corresponds to axis 0 of the container it is an annotation of.

Vectorizing Objects¶

Figure 1: Vectorizing allows Menpo to have rich data types whilst simultaneously providing efficient linear algebra routines. Here an image is vectorized, and an arbitrary process f() is performed on it’s vector representation. Afterwards the vector is converted the back into an image. The vector operation is completely general, and could have equally been performed on some spatial data.¶

Computer Vision algorithms are frequently formulated as linear algebra problems in a high dimensional space, where each asset is stripped into a vector. In this high dimensional space we may perform any number of operations, but normally we can’t stay in this space for the whole algorithm - we normally have to recast the vector back into it’s original domain in order to perform other operations.

An example of this might be seen with images, where the gradient of the intensity values of an image needs to be taken. This is a complex problem to solve in a vector space representation of the image, but trivial to solve in the image domain.

Menpo bridges the gap by naively supporting bi-directional vectorisation of it’s types through the Vectorizable interface. Through this, any type can be safely and efficiently converted to a vector form and back again. You’ll find the key methods of Vectorizable are extensively used in Menpo. They are

as_vector - generate a vector from one of our types.
from_vector - rebuild one of our types from a vector
from_vector_inplace - alter an object inplace to take on the new state

Key points¶

1. Each type defines it’s own form of vectorization. Calling as_vector on a Image returns all of the pixels in a single strip, whilst on a MaskedImage only the true pixels are returned. This distinction means that much of Menpo’s image algorithms work equally well with masked or unmasked data - it’s the Vectorizable interface that abstracts away the difference between the two.

2. Lots of things are vectorizable, not just images. Pointclouds and lots of transforms are too.

3. The length of the resulting vector of a type can be found by querying the ``n_parameters`` property.

4. The vectorized form of an object does not have to be ‘complete’. from_vector and from_vector_inplace can use the object they are called on to rebuild a complete state. Think of vectorization more as a parametrization of the object, not a complete serialization.

Visualizing Objects¶

In Menpo, we take an opinionated stance that data exploration is a key part of working with visual data. Therefore, we tried to make the mental overhead of visualizing objects as low as possible. Therefore, we made visualization a key concept directly on our data containers, rather than requiring extra imports in order to view your data.

We also took a strong step towards simple visualization of data collections by integrating some of our core types such as Image with visualization widgets for the IPython notebook.

Visualizing 2D Images¶

Without further ado, a quick example of viewing a 2D image:

%matplotlib inline  # This is only needed if viewing in an IPython notebook
import menpo.io as mio

bb = mio.import_builtin_asset.breakingbad_jpg()
bb.view()

Viewing the image landmarks:

%matplotlib inline  # This is only needed if viewing in an IPython notebook
import menpo.io as mio

bb = mio.import_builtin_asset.breakingbad_jpg()
bb.view_landmarks()

Viewing the image with a native IPython widget:

%matplotlib inline  # This is only needed if viewing in an IPython notebook
import menpo.io as mio

bb = mio.import_builtin_asset.breakingbad_jpg()
bb.view_widget()

Visualizing A List Of 2D Images¶

Visualizing lists of images is also incredibly simple if you are using the IPython notebook:

%matplotlib inline
import menpo.io as mio
from menpo.visualize import visualize_images

# import_images is a generator, so we must exhaust the generator before
# we can visualize the list. This is because the widget allows you to
# jump arbitrarily around the list, which cannot be done with generators.
images = list(mio.import_images('./path/to/images/*.jpg'))
visualize_images(images)

Visualizing A 2D PointCloud¶

Visualizing PointCloud objects and subclasses is a very familiar experience:

%matplotlib inline
from menpo.shape import PointCloud
import numpy as np

pcloud = PointCloud(np.array([[0, 0], [1, 0], [1, 1], [0, 1]]))
pcloud.view()

Visualizing In 3D¶

Menpo natively supports 3D objects, such as triangulated meshes, as our base classes are n-dimensional. However, as viewing in 3D is a much more complicated experience, we have segregated the 3D viewing package into one of our sub-packages: Menpo3D.

If you try to view a 3D PointCloud without having Menpo3D installed, you will receive an exception asking you to install it.

Menpo3D also comes with many other complicated pieces of functionality for 3D meshes such as a rasterizer. We recommend you look at Menpo3D if you want to use Menpo for 3D mesh manipulation.

Changelog¶

0.4.0 (2015/02/04)¶

The 0.4.0 release (pending any currently unknown bugs), represents a very significant overhaul of Menpo from v0.3.0. In particular, Menpo has been broken into four distinct packages: Menpo, MenpoFit, Menpo3D and MenpotDetect.

Visualization has had major improvements for 2D viewing, in particular through the use of IPython widgets and explicit options on the viewing methods for common tasks (like changing the landmark marker color). This final release is a much smaller set of changes over the alpha releases, so please check the full changelog for the alphas to see all changes from v0.3.0 to v0.4.0.

Summary of changes since v0.4.0a2:

Lots of documentation rendering fixes and style fixes including this changelog.

Move the LJSON format to V2. V1 is now being deprecated over the next version.

More visualization customization fixes including multiple marker colors for landmark groups.

Github Pull Requests¶

#546 IO doc fixes (@jabooth)
#545 Different marker colour per label (@nontas)
#543 Bug fix for importing an image, case of a dot in image name. (@grigorisg9gr)
#544 Move docs to Sphinx 1.3b2 (@patricksnape)
#536 Docs fixes (@patricksnape)
#530 Visualization and Widgets upgrade (@patricksnape, @nontas)
#540 LJSON v2 (@jabooth)
#537 fix BU3DFE connectivity, pretty JSON files (@jabooth)
#529 BU3D-FE labeller added (@jabooth)
#527 fixes paths for pickle importing (@jabooth)
#525 Fix .rst doc files, auto-generation script (@jabooth)

v0.4.0a2 (2014/12/03)¶

Alpha 2 moves towards extending the graphing API so that visualization is more dependable.

Summary:

Add graph classes, PointGraph, PointDirectedGraph, PointTree, PointUndirectedGraph. This makes visualization of landmarks much nicer looking.

Better support of pickling menpo objects

Add a bounding box method to PointCloud for calculating the correctly oriented bounding box of point clouds.

Allow PCA to operate in place for large data matrices.

Github Pull Requests¶

#522 Add bounding box method to pointclouds (@patricksnape)
#523 HOTFIX: fix export_pickle bug, add path support (@jabooth)
#521 menpo.io add pickle support, move to pathlib (@jabooth)
#520 Documentation fixes (@patricksnape, @jabooth)
#518 PCA memory improvements, inplace dot product (@jabooth)
#519 replace wrapt with functools.wraps - we can pickle (@jabooth)
#517 (@jabooth)
#514 Remove the use of triplot (@patricksnape)
#516 Fix how images are converted to PIL (@patricksnape)
#515 Show the path in the image widgets (@patricksnape)
#511 2D Rotation convenience constructor, Image.rotate_ccw_about_centre (@jabooth)
#510 all menpo io glob operations are now always sorted (@jabooth)
#508 visualize image on MaskedImage reports Mask proportion (@jabooth)
#509 path is now preserved on image warping (@jabooth)
#507 fix rounding issue in n_components (@jabooth)
#506 is_tree update in Graph (@nontas)
#505 (@nontas)
#504 explicitly have kwarg in IO for landmark extensions (@jabooth)
#503 Update the README (@patricksnape)

v0.4.0a1 (2014/10/31)¶

This first alpha release makes a number of large, breaking changes to Menpo from v0.3.0. The biggest change is that Menpo3D and MenpoFit were created and thus all AAM and 3D visualization/rasterization code has been moved out of the main Menpo repository. This is working towards Menpo being pip installable.

Summary:

Fixes memory leak whereby weak references were being kept between landmarks and their host objects. The Landmark manager now no longer keeps references to its host object. This also helps with serialization.

Use pathlib instead of strings for paths in the io module.

Importing of builtin assets from a simple function

Improve support for image importing (including ability to import without normalising)

Add fast methods for image warping, warp_to_mask and warp_to_shape instead of warp_to

Allow masking of triangle meshes

Add IPython visualization widgets for our core types

All expensive properties (properties that would be worth caching in a variable and are not merely a lookup) are changed to methods.

Github Pull Requests¶

#502 Fixes pseudoinverse for Alignment Transforms (@jalabort, @patricksnape)
#501 Remove menpofit widgets (@nontas)
#500 Shapes widget (@nontas)
#499 spin out AAM, CLM, SDM, ATM and related code to menpofit (@jabooth)
#498 Minimum spanning tree bug fix (@nontas)
#492 Some fixes for PIL image importing (@patricksnape)
#494 Widgets bug fix and Active Template Model widget (@nontas)
#491 Widgets fixes (@nontas)
#489 remove _view, fix up color_list -> colour_list (@jabooth)
#486 Image visualisation improvements (@patricksnape)
#488 Move expensive image properties to methods (@jabooth)
#487 Change expensive PCA properties to methods (@jabooth)
#485 MeanInstanceLinearModel.mean is now a method (@jabooth)
#452 Advanced widgets (@patricksnape, @nontas)
#481 Remove 3D (@patricksnape)
#480 Graphs functionality (@nontas)
#479 Extract patches on image (@patricksnape)
#469 Active Template Models (@nontas)
#478 Fix residuals for AAMs (@patricksnape, @jabooth)
#474 remove HDF5able making room for h5it (@jabooth)
#475 Normalize norm and std of Image object (@nontas)
#472 Daisy features (@nontas)
#473 Fix from_mask for Trimesh subclasses (@patricksnape)
#470 expensive properties should really be methods (@jabooth)
#467 get a progress bar on top level feature computation (@jabooth)
#466 Spin out rasterization and related methods to menpo3d (@jabooth)
#465 ‘me_norm’ error type in tests (@nontas)
#463 goodbye ioinfo, hello path (@jabooth)
#464 make mayavi an optional dependency (@jabooth)
#447 Displacements in fitting result (@nontas)
#451 AppVeyor Windows continuous builds from condaci (@jabooth)
#445 Serialize fit results (@patricksnape)
#444 remove pyramid_on_features from Menpo (@jabooth)
#443 create_pyramid now applies features even if pyramid_on_features=False, SDM uses it too (@jabooth)
#369 warp_to_mask, warp_to_shape, fast resizing of images (@nontas, @patricksnape, @jabooth)
#442 add rescale_to_diagonal, diagonal property to Image (@jabooth)
#441 adds constrain_to_landmarks on BooleanImage (@jabooth)
#440 pathlib.Path can no be used in menpo.io (@jabooth)
#439 Labelling fixes (@jabooth, @patricksnape)
#438 extract_channels (@jabooth)
#437 GLRasterizer becomes HDF5able (@jabooth)
#435 import_builtin_asset.ASSET_NAME (@jabooth)
#434 check_regression_features unified with check_features, classmethods removed from SDM (@jabooth)
#433 tidy classifiers (@jabooth)
#432 aam.fitter, clm.fitter, sdm.trainer packages (@jabooth)
#431 More fitmultilevel tidying (@jabooth)
#430 Remove classmethods from DeformableModelBuilder (@jabooth)
#412 First visualization widgets (@jalabort, @nontas)
#429 Masked image fixes (@patricksnape)
#426 rename ‘feature_type’ to ‘features throughout Menpo (@jabooth)
#427 Adds HDF5able serialization support to Menpo (@jabooth)
#425 Faster cached piecewise affine, Cython varient demoted (@jabooth)
#424 (@nontas)
#378 Fitting result fixes (@jabooth, @nontas, @jalabort)
#423 name now displays on constrained features (@jabooth)
#421 Travis CI now makes builds, Linux/OS X Python 2.7/3.4 (@jabooth, @patricksnape)
#400 Features as functions (@nontas, @patricksnape, @jabooth)
#420 move IOInfo to use pathlib (@jabooth)
#405 import menpo is now twice as fast (@jabooth)
#416 waffle.io Badge (@waffle-iron)
#415 export_mesh with .OBJ exporter (@jabooth, @patricksnape)
#410 Fix the render_labels logic (@patricksnape)
#407 Exporters (@patricksnape)
#406 Fix greyscale PIL images (@patricksnape)
#404 LandmarkGroup tojson method and PointGraph (@patricksnape)
#403 Fixes a couple of viewing problems in fitting results (@patricksnape)
#402 Landmarks fixes (@jabooth, @patricksnape)
#401 Dogfood landmark_resolver in menpo.io (@jabooth)
#399 bunch of Python 3 compatibility fixes (@jabooth)
#398 throughout Menpo. (@jabooth)
#397 Performance improvements for Similarity family (@jabooth)
#396 More efficient initialisations of Menpo types (@jabooth)
#395 remove cyclic target reference from landmarks (@jabooth)
#393 Groundwork for dense correspondence pipeline (@jabooth)
#394 weakref to break cyclic references (@jabooth)
#389 assorted fixes (@jabooth)
#390 (@jabooth)
#387 Adds landmark label for tongues (@nontas)
#386 Adds labels for the ibug eye annotation scheme (@jalabort)
#382 BUG fixed: block element not reset if norm=0 (@dubzzz)
#381 Recursive globbing (@jabooth)
#384 Adds support for odd patch shapes in function extract_local_patches_fast (@jalabort)
#379 imported textures have ioinfo, docs improvements (@jabooth)

v0.3.0 (2014/05/27)¶

First public release of Menpo, this release coincided with submission to the ACM Multimedia Open Source Software Competition 2014. This provides the basic scaffolding for Menpo, but it is not advised to use this version over the improvements in 0.4.0.

Github Pull Requests¶

#377 Simple fixes (@patricksnape)
#375 improvements to importing multiple assets (@jabooth)
#374 Menpo’s User guide (@jabooth)

The Menpo API¶

This section attempts to provide a simple browsing experience for the Menpo documentation. In Menpo, we use legible docstrings, and therefore, all documentation should be easily accessible in any sensible IDE (or IPython) via tab completion. However, this section should make most of the core classes available for viewing online.

`menpo.base`¶

Core¶

Core interfaces of Menpo.

Copyable¶

class menpo.base.Copyable[source]¶

Bases: object

Efficient copying of classes containing numpy arrays.

Interface that provides a single method for copying classes very efficiently.

copy()[source]¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

Vectorizable¶

class menpo.base.Vectorizable[source]¶

Bases: Copyable

Flattening of rich objects to vectors and rebuilding them back.

Interface that provides methods for ‘flattening’ an object into a vector, and restoring from the same vectorized form. Useful for statistical analysis of objects, which commonly requires the data to be provided as a single vector.

as_vector(**kwargs)[source]¶

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.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

from_vector(vector)[source]¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	object (`type(self)`) – An new instance of this class.

from_vector_inplace(vector)[source]¶

Update the state of this object from a vector form.

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

n_parameters¶

The length of the vector that this object produces.

Type:	int

Targetable¶

class menpo.base.Targetable[source]¶

Bases: Copyable

Interface for objects that can produce a target PointCloud.

This could for instance be the result of an alignment or a generation of a PointCloud instance from a shape model.

Implementations must define sensible behavior for:

what a target is: see target

how to set a target: see set_target()

how to update the object after a target is set: see _sync_state_from_target()

how to produce a new target after the changes: see _new_target_from_state()

Note that _sync_target_from_state() needs to be triggered as appropriate by subclasses e.g. when from_vector_inplace is called. This will in turn trigger _new_target_from_state(), which each subclass must implement.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

set_target(new_target)[source]¶

Update this object so that it attempts to recreate the new_target.

Parameters:	new_target (`PointCloud`) – The new target that this object should try and regenerate.

n_dims¶

The number of dimensions of the target.

Type:	int

n_points¶

The number of points on the target.

Type:	int

target¶

The current PointCloud that this object produces.

Type:	`PointCloud`

Convenience¶

menpo_src_dir_path¶

menpo.base.menpo_src_dir_path()[source]¶

The path to the top of the menpo Python package.

Useful for locating where the data folder is stored.

Returns:	path (`pathlib.Path`) – The full path to the top of the Menpo package

`menpo.io`¶

Input¶

import_image¶

menpo.io.import_image(filepath, landmark_resolver=<function same_name at 0x7f9bca9b25f0>, normalise=True)[source]¶

Single image (and associated landmarks) importer.

If an image file is found at filepath, returns an Image or subclass representing it. By default, landmark files sharing the same filename stem will be imported and attached with a group name based on the extension of the landmark file, although this behavior can be customised (see landmark_resolver). If the image defines a mask, this mask will be imported.

Parameters:

filepath (pathlib.Path or str) – A relative or absolute filepath to an image file.
landmark_resolver (function, optional) – This function will be used to find landmarks for the image. The function should take one argument (the image itself) and return a dictionary of the form {'group_name': 'landmark_filepath'} Default finds landmarks with the same name as the image file.
normalise (bool, optional) – If True, normalise the image pixels between 0 and 1 and convert to floating point. If false, the native datatype of the image will be maintained (commonly uint8). Note that in general Menpo assumes Image instances contain floating point data - if you disable this flag you will have to manually convert the images you import to floating point before doing most Menpo operations. This however can be useful to save on memory usage if you only wish to view or crop images.

Returns:

images (Image or list of) – An instantiated Image or subclass thereof or a list of images.

import_images¶

menpo.io.import_images(pattern, max_images=None, landmark_resolver=<function same_name at 0x7f9bca9b25f0>, normalise=True, verbose=False)[source]¶

Multiple image (and associated landmarks) importer.

For each image found yields an Image or subclass representing it. By default, landmark files sharing the same filename stem will be imported and attached with a group name based on the extension of the landmark file, although this behavior can be customised (see landmark_resolver). If the image defines a mask, this mask will be imported.

Note that this is a generator function. This allows for pre-processing of data to take place as data is imported (e.g. cropping images to landmarks as they are imported for memory efficiency).

Parameters:	pattern (str) – A glob path pattern to search for images. Every image found to match the glob will be imported one by one. See `image_paths` for more details of what images will be found. max_images (positive int, optional) – If not `None`, only import the first `max_images` found. Else, import all. landmark_resolver (function, optional) – This function will be used to find landmarks for the image. The function should take one argument (the image itself) and return a dictionary of the form `{'group_name': 'landmark_filepath'}` Default finds landmarks with the same name as the image file. normalise (bool, optional) – If `True`, normalise the image pixels between 0 and 1 and convert to floating point. If false, the native datatype of the image will be maintained (commonly uint8). Note that in general Menpo assumes `Image` instances contain floating point data - if you disable this flag you will have to manually convert the images you import to floating point before doing most Menpo operations. This however can be useful to save on memory usage if you only wish to view or crop images. verbose (bool, optional) – If `True` progress of the importing will be dynamically reported with a progress bar.
Returns:	generator (generator yielding `Image` or list of) – Generator yielding `Image` instances found to match the glob pattern provided.
Raises:	`ValueError` – If no images are found at the provided glob.

Examples

Import images at 20% scale from a huge collection:

>>> images = []
>>> for img in menpo.io.import_images('./massive_image_db/*'):
>>>    # rescale to a sensible size as we go
>>>    images.append(img.rescale(0.2))

import_landmark_file¶

menpo.io.import_landmark_file(filepath, asset=None)[source]¶

Single landmark group importer.

If a landmark file is found at filepath, returns a LandmarkGroup representing it.

Parameters:	filepath (pathlib.Path or str) – A relative or absolute filepath to an landmark file.
Returns:	landmark_group (`LandmarkGroup`) – The `LandmarkGroup` that the file format represents.

import_landmark_files¶

menpo.io.import_landmark_files(pattern, max_landmarks=None, verbose=False)[source]¶

Multiple landmark file import generator.

Note that this is a generator function.

Parameters:	pattern (str) – A glob path pattern to search for landmark files. Every landmark file found to match the glob will be imported one by one. See `landmark_file_paths` for more details of what landmark files will be found. max_landmark_files (positive int, optional) – If not `None`, only import the first `max_landmark_files` found. Else, import all. verbose (bool, optional) – If `True` progress of the importing will be dynamically reported.
Returns:	generator (generator yielding `LandmarkGroup`) – Generator yielding `LandmarkGroup` instances found to match the glob pattern provided.
Raises:	`ValueError` – If no landmarks are found at the provided glob.

import_pickle¶

menpo.io.import_pickle(filepath)[source]¶

Import a pickle file of arbitrary Python objects.

Menpo unambiguously uses .pkl as it’s choice of extension for Pickle files. Menpo also supports automatic importing and exporting of gzip compressed pickle files - just choose a filepath ending pkl.gz and gzip compression will automatically be applied. Compression can massively reduce the filesize of a pickle file at the cost of longer import and export times.

Parameters:	filepath (pathlib.Path or str) – A relative or absolute filepath to a `.pkl` or `.pkl.gz` file.
Returns:	object (object) – Whatever Python objects are present in the Pickle file

import_pickles¶

menpo.io.import_pickles(pattern, max_pickles=None, verbose=False)[source]¶

Multiple pickle file import generator.

Note that this is a generator function.

Menpo unambiguously uses .pkl as it’s choice of extension for pickle files. Menpo also supports automatic importing of gzip compressed pickle files - matching files with extension pkl.gz will be automatically un-gzipped and imported.

Parameters:	pattern (str) – The glob path pattern to search for pickles. Every pickle file found to match the glob will be imported one by one. max_pickles (positive int, optional) – If not `None`, only import the first `max_pickles` found. Else, import all. verbose (bool, optional) – If `True` progress of the importing will be dynamically reported.
Returns:	generator (generator yielding object) – Generator yielding whatever Python object is present in the pickle files that match the glob pattern provided.
Raises:	`ValueError` – If no pickles are found at the provided glob.

import_builtin_asset¶

menpo.io.import_builtin_asset()¶

This is a dynamically generated method. This method is designed to automatically generate import methods for each data file in the data folder. This method it designed to be tab completed, so you do not need to call this method explicitly. It should be treated more like a property that will dynamically generate functions that will import the shipped data. For example:

>>> import menpo
>>> bb_image = menpo.io.import_builtin_asset.breakingbad_jpg()

Output¶

export_image¶

menpo.io.export_image(image, fp, extension=None, overwrite=False)[source]¶

Exports a given image. The fp argument can be either a str or any Python type that acts like a file. If a file is provided, the extension kwarg must be provided. If no extension is provided and a str filepath is provided, then the export type is calculated based on the filepath extension.

Due to the mix of string and file types, an explicit overwrite argument is used which is False by default.

Parameters:

image (Image) – The image to export.
fp (str or file-like object) – The string path or file-like object to save the object at/into.
extension (str or None, optional) – The extension to use, this must match the file path if the file path is a string. Determines the type of exporter that is used.
overwrite (bool, optional) – Whether or not to overwrite a file if it already exists.

Raises:

ValueError – File already exists and overwrite != True
ValueError – fp is a str and the extension is not None and the two extensions do not match
ValueError – fp is a file-like object and extension is None
ValueError – The provided extension does not match to an existing exporter type (the output type is not supported).

export_landmark_file¶

menpo.io.export_landmark_file(landmark_group, fp, extension=None, overwrite=False)[source]¶

Exports a given landmark group. The fp argument can be either or a str or any Python type that acts like a file. If a file is provided, the extension kwarg must be provided. If no extension is provided and a str filepath is provided, then the export type is calculated based on the filepath extension.

Due to the mix in string and file types, an explicit overwrite argument is used which is False by default.

Parameters:

landmark_group (LandmarkGroup) – The landmark group to export.
fp (str or file-like object) – The string path or file-like object to save the object at/into.
extension (str or None, optional) – The extension to use, this must match the file path if the file path is a string. Determines the type of exporter that is used.
overwrite (bool, optional) – Whether or not to overwrite a file if it already exists.

Raises:

ValueError – File already exists and overwrite != True
ValueError – fp is a str and the extension is not None and the two extensions do not match
ValueError – fp is a file-like object and extension is None
ValueError – The provided extension does not match to an existing exporter type (the output type is not supported).

export_pickle¶

menpo.io.export_pickle(obj, fp, overwrite=False)[source]¶

Exports a given collection of Python objects with Pickle.

The fp argument can be either a str or any Python type that acts like a file. If fp is a path, it must have the suffix .pkl or .pkl.gz. If .pkl, the object will be pickled using Pickle protocol 2 without compression. If .pkl.gz the object will be pickled using Pickle protocol 2 with gzip compression (at a fixed compression level of 3).

Parameters:	obj (`object`) – The object to export. fp (str or file-like object) – The string path or file-like object to save the object at/into. overwrite (bool, optional) – Whether or not to overwrite a file if it already exists.
Raises:	`ValueError` – File already exists and `overwrite` != `True` `ValueError` – `fp` is a file-like object and `extension` is `None` `ValueError` – The provided extension does not match to an existing exporter type (the output type is not supported).

Path Operations¶

image_paths¶

menpo.io.image_paths(pattern)[source]¶: Return image filepaths that Menpo can import that match the glob pattern.

landmark_file_paths¶

menpo.io.landmark_file_paths(pattern)[source]¶: Return landmark file filepaths that Menpo can import that match the glob pattern.

data_path_to¶

menpo.io.data_path_to(asset_filename)[source]¶

The path to a builtin asset in the ./data folder on this machine.

Parameters:	asset_filename (str) – The filename (with extension) of a file builtin to Menpo. The full set of allowed names is given by `ls_builtin_assets()`
Returns:	data_path (pathlib.Path) – The path to a given asset in the ./data folder
Raises:	`ValueError` – If the asset_filename doesn’t exist in the data folder.

data_dir_path¶

menpo.io.data_dir_path()[source]¶

A path to the Menpo built in ./data folder on this machine.

Returns:	`pathlib.Path` – The path to the local Menpo ./data folder

ls_builtin_assets¶

menpo.io.ls_builtin_assets()[source]¶

List all the builtin asset examples provided in Menpo.

Returns:	list of strings – Filenames of all assets in the data directory shipped with Menpo

`menpo.image`¶

Image Types¶

Image¶

class menpo.image.Image(image_data, copy=True)[source]¶

Bases: Vectorizable, Landmarkable, Viewable, LandmarkableViewable

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

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

_view_2d(figure_id=None, new_figure=False, channels=None, 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 or None) – If int or list of int, the specified channel(s) will be rendered. If all, all the channels will be rendered in subplots. If None and the image is RGB, it will be rendered in RGB mode. If None and the image is not RGB, it is equivalent to all.
interpolation (See Below, optional) – The interpolation used to render the image. For example, if bilinear, the image will be smooth and if nearest, the image will be pixelated. Example options
```
{none, nearest, bilinear, bicubic, spline16, spline36,
hanning, hamming, hermite, kaiser, quadric, catrom, gaussian,
bessel, mitchell, sinc, lanczos}
```
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.

Returns: viewer (ImageViewer) – The image viewing object.

_view_landmarks_2d(channels=None, 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 or None) – If int or list of int, the specified channel(s) will be rendered. If all, all the channels will be rendered in subplots. If None and the image is RGB, it will be rendered in RGB mode. If None and the image is not RGB, it is equivalent to all.
group (str or``None`` optional) – The landmark group to be visualized. If None and there are more than one landmark groups, an error is raised.
with_labels (None or str or list of str, optional) – If not None, only show the given label(s). Should not be used with the without_labels kwarg.
without_labels (None or str or list of str, optional) – If not None, show all except the given label(s). Should not be used with the with_labels kwarg.
figure_id (object, optional) – The id of the figure to be used.
new_figure (bool, optional) – If True, a new figure is created.
interpolation (See Below, optional) –
The interpolation used to render the image. For example, if bilinear, the image will be smooth and if nearest, the image will be pixelated. Example options
```
{none, nearest, bilinear, bicubic, spline16, spline36, hanning,
hamming, hermite, kaiser, quadric, catrom, gaussian, bessel,
mitchell, sinc, lanczos}
```
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 both with_labels and without_labels are passed.
ValueError – If the landmark manager doesn’t contain the provided group label.

as_PILImage()[source]¶

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 uint8 `ValueError` – If pixels data type is float32 or float64 and the pixel range is outside of `[0, 1]`

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

Returns:

hist (ndarray or list with n_channels ndarrays inside) – The histogram(s). If keep_channels=False, then hist is an ndarray. If keep_channels=True, then hist is a list with len(hist)=n_channels.
bin_edges (ndarray or list with n_channels ndarrays inside) – An array or a list of arrays corresponding to the above histograms that store the bins’ edges.

Raises:

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

Examples

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

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

as_masked(mask=None, copy=True)[source]¶

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

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

Parameters:	mask (`(self.shape)` ndarray or `BooleanImage`) – A mask to attach to the newly generated masked image. copy (bool, optional) – If `False`, the produced `MaskedImage` will share pixels with `self`. Only suggested to be used for performance.
Returns:	masked_image (`MaskedImage`) – An image with the same pixels and landmarks as this one, but with a mask.

as_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 0x7f9bca9ea290>)[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 data type, optional) – The data type of the image.
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()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

crop(min_indices, max_indices, constrain_to_boundary=False)[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 (bool, optional) – If `True` the crop will be snapped to not go beyond this images boundary. If `False`, an `ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.
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=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 (bool, optional) – If `True` the crop will be snapped to not go beyond this images boundary. If `False`, an `ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.
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`. 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.

crop_to_landmarks_inplace(group=None, label=None, 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 (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. If `False`, 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 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_inplace(boundary_proportion, group=None, label=None, 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 (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; if `False` w.r.t. the maximum value of the landmarks’ per-dimension range. constrain_to_boundary (bool, optional) – If `True`, the crop will be snapped to not go beyond this images boundary. If `False`, an `ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.
Returns:	image (`Image`) – This image, cropped to its landmarks with a border proportional to the landmark spread or range.
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.

extract_channels(channels)[source]¶

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)[source]¶

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. If `False`, a list of `Image` objects is returned representing each patch.
Returns:	patches (list or ndarray) – Returns the extracted patches. Returns a list if `as_single_array=True` and an ndarray if `as_single_array=False`.
Raises:	`ValueError` – If image is not 2D

extract_patches_around_landmarks(group=None, label=None, patch_size=(16, 16), sample_offsets=None, as_single_array=False)[source]¶

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. If `False`, a list of `Image` objects is returned representing each patch.
Returns:	patches (list or ndarray) – Returns the extracted patches. Returns a list if `as_single_array=True` and an ndarray if `as_single_array=False`.
Raises:	`ValueError` – If image is not 2D

from_vector(vector, n_channels=None, 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,)` ndarray) – 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. copy (bool, optional) – If `False`, the vector will not be copied in creating the new image.
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,)` 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.
Raises:	`Warning` – If `copy=False` flag cannot be honored

Note

For BooleanImage 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)[source]¶

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

indices()[source]¶

Return the indices of all pixels in this image.

Type:	(`n_dims`, `n_pixels`) ndarray

normalize_norm_inplace(mode='all', **kwargs)[source]¶

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

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

normalize_std_inplace(mode='all', **kwargs)[source]¶

Normalizes this image such that its pixel values have zero mean and unit variance.

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

pyramid(n_levels=3, downscale=2)[source]¶

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)[source]¶

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

rescale_to_diagonal(diagonal, round='ceil')[source]¶

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

resize(shape, order=1)[source]¶

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)[source]¶

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. If `False`, `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.

view_widget(popup=False, browser_style='buttons', figure_size=(10, 8))[source]¶

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.

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

Return a copy of this image 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 non-linear mask, consider :meth: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.
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.

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

Return a copy of this image 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 (type(self)) – A copy of this image, warped.

centre¶

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

Useful for aligning shapes and images.

Type:	(`n_dims`,) ndarray

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

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.

all_true()[source]¶

True iff every element of the mask is True.

Type:	bool

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 uint8 `ValueError` – 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.

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

Histogram binning of the values of this image.

Parameters:

keep_channels (bool, optional) – If set to False, it returns a single histogram for all the channels of the image. If set to True, it returns a list of histograms, one for each channel.
bins ({unique}, positive int or sequence of scalars, optional) – If set equal to 'unique', the bins of the histograms are centred on the unique values of each channel. If set equal to a positive int, then this is the number of bins. If set equal to a sequence of scalars, these will be used as bins centres.

Returns:

hist (ndarray or list with n_channels ndarrays inside) – The histogram(s). If keep_channels=False, then hist is an ndarray. If keep_channels=True, then hist is a list with len(hist)=n_channels.
bin_edges (ndarray or list with n_channels ndarrays inside) – An array or a list of arrays corresponding to the above histograms that store the bins’ edges.

Raises:

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

Examples

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

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

as_masked(mask=None, copy=True)[source]¶: Impossible for a BooleanImage to be transformed to a MaskedImage.

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

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. If False, the bounds are left unchanged.

Returns:

min_b ((D,) ndarray) – The minimum extent of the True mask region with the boundary along each dimension. If constrain_to_bounds=True, is clipped to legal image bounds.
max_b ((D,) ndarray) – The maximum extent of the True mask region with the boundary along each dimension. If constrain_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. If False, the bounds are left unchanged.
Returns –
-------- –
min_b ((D,) ndarray) – The minimum extent of the True mask region with the boundary along each dimension. If constrain_to_bounds=True, is clipped to legal image bounds.
max_b ((D,) ndarray) – The maximum extent of the True mask region with the boundary along each dimension. If constrain_to_bounds=True, is clipped to legal image bounds.

constrain_landmarks_to_bounds()¶: Move landmarks that are located outside the image bounds on the 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, label=None, trilist=None)[source]¶

Restricts this mask to be equal to the convex hull around the landmarks chosen. This is not a per-pixel convex hull, but instead relies on a triangulated approximation.

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.

constrain_to_pointcloud(pointcloud, trilist=None)[source]¶

Restricts this mask to be equal to the convex hull around a point cloud. This is not a per-pixel convex hull, but instead relies on a triangulated approximation.

Parameters:	pointcloud (`PointCloud`) – The pointcloud of points that should be constrained to. 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.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

crop(min_indices, max_indices, constrain_to_boundary=False)¶

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

Parameters:	min_indices (`(n_dims,)` ndarray) – The minimum index over each dimension. max_indices (`(n_dims,)` ndarray) – The maximum index over each dimension. constrain_to_boundary (bool, optional) – If `True` the crop will be snapped to not go beyond this images boundary. If `False`, an `ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.
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=False`, and an attempt is made to crop the image in a way that violates the image bounds.

crop_inplace(min_indices, max_indices, constrain_to_boundary=True)¶

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

Parameters:	min_indices (`(n_dims,)` ndarray) – The minimum index over each dimension. max_indices (`(n_dims,)` ndarray) – The maximum index over each dimension. constrain_to_boundary (bool, optional) – If `True` the crop will be snapped to not go beyond this images boundary. If `False`, an `ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.
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`. 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.

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 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. 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. If `False`, 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 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_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; if `False` w.r.t. the maximum value of the landmarks’ per-dimension range. constrain_to_boundary (bool, optional) – If `True`, the crop will be snapped to not go beyond this images boundary. If `False`, an `ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.
Returns:	image (`Image`) – This image, cropped to its landmarks with a border proportional to the landmark spread or range.
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.

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. If `False`, a list of `Image` objects is returned representing each patch.
Returns:	patches (list or ndarray) – Returns the extracted patches. Returns a list if `as_single_array=True` and an ndarray if `as_single_array=False`.
Raises:	`ValueError` – If image is not 2D

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. If `False`, a list of `Image` objects is returned representing each patch.
Returns:	patches (list or ndarray) – Returns the extracted patches. Returns a list if `as_single_array=True` and an ndarray if `as_single_array=False`.
Raises:	`ValueError` – If image is not 2D

false_indices()[source]¶

The indices of pixels that are Flase.

Type:	`(n_dims, n_false)` ndarray

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 to MaskedImage, where only the masked region is used in from_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 a `BooleanImage`. 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, copy=True)¶

Takes a flattened vector and update this image by reshaping the vector to the correct dimensions.

Parameters:	vector (`(n_pixels,)` 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.
Raises:	`Warning` – If `copy=False` flag cannot be honored

Note

For BooleanImage 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)¶

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(**kwargs)¶

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.

indices()¶

Return the indices of all pixels in this image.

Type:	(`n_dims`, `n_pixels`) ndarray

invert()[source]¶

Returns a copy of this boolean image, which is inverted.

Returns:	inverted (`BooleanImage`) – A copy of this boolean mask, where all `True` values are `False` and all `False` values are `True`.

invert_inplace()[source]¶: Inverts this Boolean Image inplace.

n_false()[source]¶

The number of False values in the mask.

Type:	int

n_true()[source]¶

The number of True values in the mask.

Type:	int

normalize_norm_inplace(mode='all', **kwargs)¶

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

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

normalize_std_inplace(mode='all', **kwargs)¶

Normalizes this image such that its pixel values have zero mean and unit variance.

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

proportion_false()[source]¶

The proportion of the mask which is False

Type:	float

proportion_true()[source]¶

The proportion of the mask which is True.

Type:	float

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.

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.

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. If `False`, `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.

true_indices()[source]¶

The indices of pixels that are True.

Type:	`(n_dims, n_true)` ndarray

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.

warp_to_mask(template_mask, transform, warp_landmarks=True, mode='constant', cval=0.0)[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 non-linear 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.

Returns:

warped_image (BooleanImage) – A copy of this image, warped.

warp_to_shape(template_shape, transform, warp_landmarks=True, mode='constant', cval=0.0, order=None)[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.

Returns:

warped_image (BooleanImage) – 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`

mask¶

Returns the pixels of the mask with no channel axis. This is what should be used to mask any k-dimensional image.

Type:	`(M, N, ..., L)`, bool ndarray

n_channels¶

The number of channels on each pixel in the image.

Type:	int

n_dims¶

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

Type:	int

n_elements¶

Total number of data points in the image (prod(shape), 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

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 or BooleanImage, optional) – A binary array representing the mask. Must be the same shape as the image. Only one mask is supported for an image (so the mask is applied to every channel equally).
copy (bool, optional) – If False, the image_data will not be copied on assignment. If a mask is provided, this also won’t be copied. In general this should only be used if you know what you are doing.

Raises:

ValueError – Mask is not the same shape as the image

_view_2d(figure_id=None, new_figure=False, channels=None, masked=True, interpolation='bilinear', 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 or None) – If int or list of int, the specified channel(s) will be rendered. If all, all the channels will be rendered in subplots. If None and the image is RGB, it will be rendered in RGB mode. If None and the image is not RGB, it is equivalent to all.
masked (bool, optional) – If True, only the masked pixels will be rendered.
interpolation (See Below, optional) – The interpolation used to render the image. For example, if bilinear, the image will be smooth and if nearest, the image will be pixelated. Example options
```
{none, nearest, bilinear, bicubic, spline16, spline36,
hanning, hamming, hermite, kaiser, quadric, catrom, gaussian,
bessel, mitchell, sinc, lanczos}
```
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 or None) – If int or list of int, the specified channel(s) will be rendered. If all, all the channels will be rendered in subplots. If None and the image is RGB, it will be rendered in RGB mode. If None and the image is not RGB, it is equivalent to all.
masked (bool, optional) – If True, only the masked pixels will be rendered.
group (str 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 not None, only show the given label(s). Should not be used with the without_labels kwarg.
without_labels (None or str or list of str, optional) – If not None, show all except the given label(s). Should not be used with the with_labels kwarg.
figure_id (object, optional) – The id of the figure to be used.
new_figure (bool, optional) – If True, a new figure is created.
interpolation (See Below, optional) –
The interpolation used to render the image. For example, if bilinear, the image will be smooth and if nearest, the image will be pixelated. Example options
```
{none, nearest, bilinear, bicubic, spline16, spline36, hanning,
hamming, hermite, kaiser, quadric, catrom, gaussian, bessel,
mitchell, sinc, lanczos}
```
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 both with_labels and without_labels are passed.
ValueError – If the landmark manager doesn’t contain the provided group label.

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 uint8 `ValueError` – 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.

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

Histogram binning of the values of this image.

Parameters:

keep_channels (bool, optional) – If set to False, it returns a single histogram for all the channels of the image. If set to True, it returns a list of histograms, one for each channel.
bins ({unique}, positive int or sequence of scalars, optional) – If set equal to 'unique', the bins of the histograms are centred on the unique values of each channel. If set equal to a positive int, then this is the number of bins. If set equal to a sequence of scalars, these will be used as bins centres.

Returns:

hist (ndarray or list with n_channels ndarrays inside) – The histogram(s). If keep_channels=False, then hist is an ndarray. If keep_channels=True, then hist is a list with len(hist)=n_channels.
bin_edges (ndarray or list with n_channels ndarrays inside) – An array or a list of arrays corresponding to the above histograms that store the bins’ edges.

Raises:

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

Examples

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

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

as_masked(mask=None, copy=True)¶

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

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

Parameters:	mask (`(self.shape)` ndarray or `BooleanImage`) – A mask to attach to the newly generated masked image. copy (bool, optional) – If `False`, the produced `MaskedImage` will share pixels with `self`. Only suggested to be used for performance.
Returns:	masked_image (`MaskedImage`) – An image with the same pixels and landmarks as this one, but with a mask.

as_unmasked(copy=True)[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 produced `Image` will share pixels with `self`. 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 0x7f9bca9f7690>, 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 or BooleanImage) – An optional mask that can be applied to the image. Has to have a shape equal to that of the image.

Notes

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

super(SubClass, cls).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.

constrain_points_to_bounds(points)¶

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

Parameters:	points (`(d,)` ndarray) – Points to be snapped to the image boundaries.
Returns:	bounded_points (`(d,)` ndarray) – Points snapped to not stray outside the image edges.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

crop(min_indices, max_indices, constrain_to_boundary=False)¶

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

Parameters:	min_indices (`(n_dims,)` ndarray) – The minimum index over each dimension. max_indices (`(n_dims,)` ndarray) – The maximum index over each dimension. constrain_to_boundary (bool, optional) – If `True` the crop will be snapped to not go beyond this images boundary. If `False`, an `ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.
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=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 (bool, optional) – If `True` the crop will be snapped to not go beyond this images boundary. If `False`, an `ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.
Returns:	cropped_image (type(self)) – This image, but cropped.
Raises:	`ValueError` – `min_indices` and `max_indices` both have to be of length `n_dims`. All `max_indices` must be greater than `min_indices`. 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.

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 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. 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. If `False`, 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 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_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; if `False` w.r.t. the maximum value of the landmarks’ per-dimension range. constrain_to_boundary (bool, optional) – If `True`, the crop will be snapped to not go beyond this images boundary. If `False`, an `ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image.
Returns:	image (`Image`) – This image, cropped to its landmarks with a border proportional to the landmark spread or range.
Raises:	`ImageBoundaryError` – Raised if `constrain_to_boundary=False`, and an attempt is made to crop the image in a way that violates the image bounds.

crop_to_true_mask(boundary=0, constrain_to_boundary=True)[source]¶

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

Parameters:	boundary (int, optional) – An extra padding to be added all around the true mask region. constrain_to_boundary (bool, optional) – If `True` the crop will be snapped to not go beyond this images boundary. If `False`, an `ImageBoundaryError` will be raised if an attempt is made to go beyond the edge of the image. Note that is only possible if `boundary != 0`.
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. If `False`, a list of `Image` objects is returned representing each patch.
Returns:	patches (list or ndarray) – Returns the extracted patches. Returns a list if `as_single_array=True` and an ndarray if `as_single_array=False`.
Raises:	`ValueError` – If image is not 2D

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. If `False`, a list of `Image` objects is returned representing each patch.
Returns:	patches (list or ndarray) – Returns the extracted patches. Returns a list if `as_single_array=True` and an ndarray if `as_single_array=False`.
Raises:	`ValueError` – If image is not 2D

from_vector(vector, n_channels=None)[source]¶

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

On masked images, the vector is always copied.

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

Note that landmarks are transferred in the process.

Parameters:	vector (`(n_pixels,)`) – A flattened vector of all pixels and channels of an image. n_channels (int, optional) – If given, will assume that vector is the same shape as this image, but with a possibly different number of channels.
Returns:	image (`MaskedImage`) – New image of same shape as this image and the number of specified channels.

from_vector_inplace(vector, 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. If `True` a copy of the vector is taken.
Raises:	`Warning` – If `copy=False` cannot be honored.

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 the `True` 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

n_false_pixels()[source]¶

The number of False values in the mask.

Type:	int

n_true_elements()[source]¶

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

Type:	int

n_true_pixels()[source]¶

The number of True values in the mask.

Type:	int

normalize_norm_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) – If `all`, the normalization is over all channels. If `per_channel`, each channel individually is mean centred and normalized in variance. limit_to_mask (bool, optional) – If `True`, the normalization is only performed wrt the masked pixels. If `False`, the normalization is wrt all pixels, regardless of their masking value.

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) – If `all`, the normalization is over all channels. If `per_channel`, each channel individually is mean centred and normalized in variance. limit_to_mask (bool, optional) – If `True`, the normalization is only performed wrt the masked pixels. If `False`, the normalization is wrt all pixels, regardless of their masking value.

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.

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.

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. If `False`, `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 all `True` - in all other cases it will raise a warning.
Raises:	`Warning` – If the `copy=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.

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 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 (type(self)) – A copy of this image, warped.

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

Exceptions¶

ImageBoundaryError¶

class menpo.image.ImageBoundaryError(requested_min, requested_max, snapped_min, snapped_max)[source]¶

Bases: ValueError

Exception that is thrown when an attempt is made to crop an image beyond the edge of it’s boundary.

Parameters:

requested_min ((d,) ndarray) – The per-dimension minimum index requested for the crop
requested_max ((d,) ndarray) – The per-dimension maximum index requested for the crop
snapped_min ((d,) ndarray) – The per-dimension minimum index that could be used if the crop was constrained to the image boundaries.
requested_max – The per-dimension maximum index that could be used if the crop was constrained to the image boundaries.

`menpo.feature`¶

Features¶

no_op¶

menpo.feature.no_op(image, *args, **kwargs)[source]¶

A no operation feature - does nothing but return a copy of the pixels passed in.

Parameters:	pixels (`Image` or subclass or `(X, Y, ..., Z, C)` ndarray) – Either the image object itself or an array with the pixels. The last dimension is interpreted as channels. This means an N-dimensional image is represented by an N+1 dimensional array.
Returns:	pixels (`Image` or subclass or `(X, Y, ..., Z, C)` ndarray) – A copy of the image that was passed in.

gradient¶

menpo.feature.gradient(image, *args, **kwargs)[source]¶

Calculates the gradient of an input image. The image is assumed to have channel information on the last axis. In the case of multiple channels, it returns the gradient over each axis over each channel as the last axis.

Parameters:	pixels (`Image` or subclass or `(X, Y, ..., Z, C)` ndarray) – Either the image object itself or an array with the pixels. The last dimension is interpreted as channels. This means an N-dimensional image is represented by an N+1 dimensional array.
Returns:	gradient (ndarray, shape (X, Y, ..., Z, C length([X, Y, ..., Z]))*) – The gradient over each axis over each channel. Therefore, the last axis of the gradient of a 2D, single channel image, will have length 2. The last axis of the gradient of a 2D, 3-channel image, will have length 6, he ordering being [Rd_x, Rd_y, Gd_x, Gd_y, Bd_x, Bd_y].

gaussian_filter¶

menpo.feature.gaussian_filter(image, *args, **kwargs)[source]¶

Calculates the convolution of the input image with a multidimensional Gaussian filter.

Parameters:

pixels (Image or subclass or (X, Y, ..., Z, C) ndarray) – Either the image object itself or an array with the pixels. The last dimension is interpreted as channels. This means an N-dimensional image is represented by an N+1 dimensional array.
sigma (float or list of float) – The standard deviation for Gaussian kernel. The standard deviations of the Gaussian filter are given for each axis as a list, or as a single float, in which case it is equal for all axes.

Returns:

output_image (Image or subclass or (X, Y, ..., Z, C) ndarray) – The filtered image has the same type and size as the input pixels.

igo¶

menpo.feature.igo(image, *args, **kwargs)[source]¶

Extracts Image Gradient Orientation (IGO) features from the input image. The output image has N * C number of channels, where N is the number of channels of the original image and C = 2 or C = 4 depending on whether double angles are used.

Parameters:	pixels (`Image` or subclass or `(X, Y, ..., Z, C)` ndarray) – Either the image object itself or an array with the pixels. The last dimension is interpreted as channels. This means an N-dimensional image is represented by an N+1 dimensional array. double_angles (bool, optional) – Assume that `phi` represents the gradient orientations. If this flag is `False`, the features image is the concatenation of `cos(phi)` and `sin(phi)`, thus 2 channels. If `True`, the features image is the concatenation of `cos(phi)`, `sin(phi)`, `cos(2 * phi)`, `sin(2 * phi)`, thus 4 channels. verbose (bool, optional) – Flag to print IGO related information.
Returns:	igo (`Image` or subclass or `(X, Y, ..., Z, C)` ndarray) – The IGO features image. It has the same type and shape as the input `pixels`. The output number of channels depends on the `double_angles` flag.
Raises:	`ValueError` – Image has to be 2D in order to extract IGOs.

References

[1]	G. Tzimiropoulos, S. Zafeiriou and M. Pantic, “Subspace learning from image gradient orientations”, IEEE Transactions on Pattern Analysis and Machine Intelligence, vol. 34, num. 12, p. 2454–2466, 2012.

es¶

menpo.feature.es(image, *args, **kwargs)[source]¶

Extracts Edge Structure (ES) features from the input image. The output image has N * C number of channels, where N is the number of channels of the original image and C = 2.

Parameters:	pixels (`Image` or subclass or `(X, Y, ..., Z, C)` ndarray) – Either the image object itself or an array with the pixels. The last dimension is interpreted as channels. This means an N-dimensional image is represented by an N+1 dimensional array. verbose (bool, optional) – Flag to print ES related information.
Returns:	es (`Image` or subclass or `(X, Y, ..., Z, C)` ndarray) – The ES features image. It has the same type and shape as the input `pixels`. The output number of channels is `C = 2`.
Raises:	`ValueError` – Image has to be 2D in order to extract ES features.

References

[1]	T. Cootes, C. Taylor, “On representing edge structure for model matching”, Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition (CVPR), 2001.

lbp¶

menpo.feature.lbp(image, *args, **kwargs)[source]¶

Extracts Local Binary Pattern (LBP) features from the input image. The output image has N * C number of channels, where N is the number of channels of the original image and C is the number of radius/samples values combinations that are used in the LBP computation.

Parameters:	pixels (`Image` or subclass or `(X, Y, ..., Z, C)` ndarray) – Either the image object itself or an array with the pixels. The last dimension is interpreted as channels. This means an N-dimensional image is represented by an N+1 dimensional array. radius (int or list of int or `None`, optional) – It defines the radius of the circle (or circles) at which the sampling points will be extracted. The radius (or radii) values must be greater than zero. There must be a radius value for each samples value, thus they both need to have the same length. If `None`, then `[1, 2, 3, 4]` is used. samples (int or list of int or `None`, optional) – It defines the number of sampling points that will be extracted at each circle. The samples value (or values) must be greater than zero. There must be a samples value for each radius value, thus they both need to have the same length. If `None`, then `[8, 8, 8, 8]` is used. mapping_type ({`u2`, `ri`, `riu2`, `none`}, optional) – It defines the mapping type of the LBP codes. Select `u2` for uniform-2 mapping, `ri` for rotation-invariant mapping, `riu2` for uniform-2 and rotation-invariant mapping and `none` to use no mapping and only the decimal values instead. window_step_vertical (float, optional) – Defines the vertical step by which the window is moved, thus it controls the features density. The metric unit is defined by window_step_unit. window_step_horizontal (float, optional) – Defines the horizontal step by which the window is moved, thus it controls the features density. The metric unit is defined by window_step_unit. window_step_unit ({`pixels`, `window`}, optional) – Defines the metric unit of the window_step_vertical and window_step_horizontal parameters. padding (bool, optional) – If `True`, the output image is padded with zeros to match the input image’s size. verbose (bool, optional) – Flag to print LBP related information. skip_checks (bool, optional) – If `True`, do not perform any validation of the parameters.
Returns:	lbp (`Image` or subclass or `(X, Y, ..., Z, C)` ndarray) – The ES features image. It has the same type and shape as the input `pixels`. The output number of channels is `C = len(radius) * len(samples)`.
Raises:	`ValueError` – Radius and samples must both be either integers or lists `ValueError` – Radius and samples must have the same length `ValueError` – Radius must be > 0 `ValueError` – Radii must be > 0 `ValueError` – Samples must be > 0 `ValueError` – Mapping type must be u2, ri, riu2 or none `ValueError` – Horizontal window step must be > 0 `ValueError` – Vertical window step must be > 0 `ValueError` – Window step unit must be either pixels or window

References

[1]	T. Ojala, M. Pietikainen, and T. Maenpaa, “Multiresolution gray-scale and rotation invariant texture classification with local binary patterns”, IEEE Transactions on Pattern Analysis and Machine Intelligence, vol. 24, num. 7, p. 971-987, 2002.

hog¶

menpo.feature.hog(image, *args, **kwargs)[source]¶

Extracts Histograms of Oriented Gradients (HOG) features from the input image.

Parameters:	pixels (`Image` or subclass or `(X, Y, ..., Z, C)` ndarray) – Either the image object itself or an array with the pixels. The last dimension is interpreted as channels. This means an N-dimensional image is represented by an N+1 dimensional array. mode ({`dense`, `sparse`}, optional) – The `sparse` case refers to the traditional usage of HOGs, so predefined parameters values are used. The `sparse` case of `dalaltriggs` algorithm sets `window_height = window_width = block_size` and `window_step_horizontal = window_step_vertical = cell_size`. The `sparse` case of `zhuramanan` algorithm sets `window_height = window_width = 3 * cell_size` and `window_step_horizontal = window_step_vertical = cell_size`. In the `dense` case, the user can choose values for window_height, window_width, window_unit, window_step_vertical, window_step_horizontal, window_step_unit and padding to customize the HOG calculation. window_height (float, optional) – Defines the height of the window. The metric unit is defined by window_unit. window_width (float, optional) – Defines the width of the window. The metric unit is defined by window_unit. window_unit ({`blocks`, `pixels`}, optional) – Defines the metric unit of the window_height and window_width parameters. window_step_vertical (float, optional) – Defines the vertical step by which the window is moved, thus it controls the features’ density. The metric unit is defined by window_step_unit. window_step_horizontal (float, optional) – Defines the horizontal step by which the window is moved, thus it controls the features’ density. The metric unit is defined by window_step_unit. window_step_unit ({`pixels`, `cells`}, optional) – Defines the metric unit of the window_step_vertical and window_step_horizontal parameters. padding (bool, optional) – If `True`, the output image is padded with zeros to match the input image’s size. algorithm ({`dalaltriggs`, `zhuramanan`}, optional) – Specifies the algorithm used to compute HOGs. `dalaltriggs` is the implementation of [1] and `zhuramanan` is the implementation of [2]. cell_size (float, optional) – Defines the cell size in pixels. This value is set to both the width and height of the cell. This option is valid for both algorithms. block_size (float, optional) – Defines the block size in cells. This value is set to both the width and height of the block. This option is valid only for the `dalaltriggs` algorithm. num_bins (float, optional) – Defines the number of orientation histogram bins. This option is valid only for the `dalaltriggs` algorithm. signed_gradient (bool, optional) – Flag that defines whether we use signed or unsigned gradient angles. This option is valid only for the `dalaltriggs` algorithm. l2_norm_clip (float, optional) – Defines the clipping value of the gradients’ L2-norm. This option is valid only for the `dalaltriggs` algorithm. verbose (bool, optional) – Flag to print HOG related information.
Returns:	hog (`Image` or subclass or `(X, Y, ..., Z, K)` ndarray) – The HOG features image. It has the same type as the input `pixels`. The output number of channels in the case of `dalaltriggs` is `K = num_bins * block_size *block_size` and `K = 31` in the case of `zhuramanan`.
Raises:	`ValueError` – HOG features mode must be either dense or sparse `ValueError` – Algorithm must be either dalaltriggs or zhuramanan `ValueError` – Number of orientation bins must be > 0 `ValueError` – Cell size (in pixels) must be > 0 `ValueError` – Block size (in cells) must be > 0 `ValueError` – Value for L2-norm clipping must be > 0.0 `ValueError` – Window height must be >= block size and <= image height `ValueError` – Window width must be >= block size and <= image width `ValueError` – Window unit must be either pixels or blocks `ValueError` – Horizontal window step must be > 0 `ValueError` – Vertical window step must be > 0 `ValueError` – Window step unit must be either pixels or cells

References

[1]	N. Dalal and B. Triggs, “Histograms of oriented gradients for human detection”, Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition (CVPR), 2005.

[2]	X. Zhu, D. Ramanan. “Face detection, pose estimation and landmark localization in the wild”, Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition (CVPR), 2012.

daisy¶

menpo.feature.daisy(image, *args, **kwargs)[source]¶

Extracts Daisy features from the input image. The output image has N * C number of channels, where N is the number of channels of the original image and C is the feature channels determined by the input options. Specifically, C = (rings * histograms + 1) * orientations.

Parameters:	pixels (`Image` or subclass or `(X, Y, ..., Z, C)` ndarray) – Either the image object itself or an array with the pixels. The last dimension is interpreted as channels. This means an N-dimensional image is represented by an N+1 dimensional array. step (int, optional) – The sampling step that defines the density of the output image. radius (int, optional) – The radius (in pixels) of the outermost ring. rings (int, optional) – The number of rings to be used. histograms (int, optional) – The number of histograms sampled per ring. orientations (int, optional) – The number of orientations (bins) per histogram. normalization ([ ‘l1’, ‘l2’, ‘daisy’, None ], optional) – It defines how to normalize the descriptors If ‘l1’ then L1-normalization is applied at each descriptor. If ‘l2’ then L2-normalization is applied at each descriptor. If ‘daisy’ then L2-normalization is applied at individual histograms. If None then no normalization is employed. sigmas (list of float or `None`, optional) – Standard deviation of spatial Gaussian smoothing for the centre histogram and for each ring of histograms. The list of sigmas should be sorted from the centre and out. I.e. the first sigma value defines the spatial smoothing of the centre histogram and the last sigma value defines the spatial smoothing of the outermost ring. Specifying sigmas overrides the rings parameter by setting `rings = len(sigmas) - 1`. ring_radii (list of float or `None`, optional) – Radius (in pixels) for each ring. Specifying ring_radii overrides the rings and radius parameters by setting `rings = len(ring_radii)` and `radius = ring_radii[-1]`. If both sigmas and ring_radii are given, they must satisfy len(ring_radii) == len(sigmas) + 1 since no radius is needed for the centre histogram. verbose (bool) – Flag to print Daisy related information.
Returns:	daisy (`Image` or subclass or `(X, Y, ..., Z, C)` ndarray) – The ES features image. It has the same type and shape as the input `pixels`. The output number of channels is `C = (rings * histograms + 1) * orientations`.
Raises:	`ValueError` – len(sigmas)-1 != len(ring_radii) `ValueError` – Invalid normalization method.

References

[1]	E. Tola, V. Lepetit and P. Fua, “Daisy: An efficient dense descriptor applied to wide-baseline stereo”, IEEE Transactions on Pattern Analysis and Machine Intelligence, vol. 32, num. 5, p. 815-830, 2010.

Widget¶

features_selection_widget¶

menpo.feature.features_selection_widget(popup=True)[source]¶

Widget that allows for easy selection of a features function and its options. It also has a ‘preview’ tab for visual inspection. It returns a list of length 1 with the selected features function closure.

Parameters:	popup (bool, optional) – If `True`, the widget will appear as a popup window.
Returns:	features_function (list of length `1`) – The function closure of the features function using functools.partial. So the function can be called as: features_image = features_function[0](image)

Examples

The widget can be invoked as

from menpo.feature import features_selection_widget
features_fun = features_selection_widget()

And the returned function can be used as

import menpo.io as mio
image = mio.import_builtin_asset.lenna_png()
features_image = features_fun[0](image)

`menpo.landmark`¶

Abstract Classes¶

Landmarkable¶

class menpo.landmark.Landmarkable[source]¶

Bases: Copyable

Abstract interface for object that can have landmarks attached to them. Landmarkable objects have a public dictionary of landmarks which are managed by a LandmarkManager. This means that different sets of landmarks can be attached to the same object. Landmarks can be N-dimensional and are expected to be some subclass of PointCloud. These landmarks are wrapped inside a LandmarkGroup object that performs useful tasks like label filtering and viewing.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

has_landmarks¶

Whether the object has landmarks.

Type:	bool

landmarks¶

The landmarks object.

Type:	`LandmarkManager`

n_dims¶

The total number of dimensions.

Type:	int

n_landmark_groups¶

The number of landmark groups on this object.

Type:	int

LabellingError¶

class menpo.landmark.LabellingError[source]¶

Bases: Exception

Raised when labelling a landmark manager and the set of landmarks does not match the expected semantic layout.

Landmarks & Labeller¶

LandmarkManager¶

class menpo.landmark.LandmarkManager[source]¶

Bases: MutableMapping, Transformable

Store for LandmarkGroup instances associated with an object

Every Landmarkable instance has an instance of this class available at the .landmarks property. It is through this class that all access to landmarks attached to instances is handled. In general the LandmarkManager provides a dictionary-like interface for storing landmarks. LandmarkGroup instances are stored under string keys - these keys are refereed to as the group name. A special case is where there is a single unambiguous LandmarkGroup attached to a LandmarkManager - in this case None can be used as a key to access the sole group.

Note that all landmarks stored on a Landmarkable in it’s attached LandmarkManager are automatically transformed and copied with their parent object.

clear() → None. Remove all items from D.¶

copy()[source]¶

Generate an efficient copy of this LandmarkManager.

Returns:	`type(self)` – A copy of this object

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

items() → list of D's (key, value) pairs, as 2-tuples¶

iteritems() → an iterator over the (key, value) items of D¶

iterkeys() → an iterator over the keys of D¶

itervalues() → an iterator over the values of D¶

keys() → list of D's keys¶

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair¶: as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D¶

update([E, ]**F) → None. Update D from mapping/iterable E and F.¶: If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → list of D's values¶

view_widget(popup=False, browser_style='buttons', figure_size=(10, 8))[source]¶

Visualizes the landmark manager object using the visualize_landmarks widget.

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 landmark managers will have the form of plus/minus buttons or a slider. figure_size ((int, int), optional) – The initial size of the rendered figure.

group_labels¶

All the labels for the landmark set.

Type:	list of str

has_landmarks¶

Whether the object has landmarks or not

Type:	int

n_dims¶

The total number of dimensions.

Type:	int

n_groups¶

Total number of labels.

Type:	int

LandmarkGroup¶

class menpo.landmark.LandmarkGroup(pointcloud, labels_to_masks, copy=True)[source]¶

Bases: MutableMapping, Copyable, Viewable

An immutable object that holds a PointCloud (or a subclass) and stores labels for each point. These labels are defined via masks on the PointCloud. For this reason, the PointCloud is considered to be immutable.

The labels to masks must be within an OrderedDict so that semantic ordering can be maintained.

Parameters:	pointcloud (`PointCloud`) – The pointcloud representing the landmarks. labels_to_masks (ordereddict {str -> bool ndarray}) – For each label, the mask that specifies the indices in to the pointcloud that belong to the label. copy (bool, optional) – If `True`, a copy of the `PointCloud` is stored on the group.
Raises:	`ValueError` – If dict passed instead of OrderedDict `ValueError` – If no set of label masks is passed. `ValueError` – If any of the label masks differs in size to the pointcloud. `ValueError` – If there exists any point in the pointcloud that is not covered by a label.

clear() → None. Remove all items from D.¶

copy()[source]¶

Generate an efficient copy of this LandmarkGroup.

Returns:	`type(self)` – A copy of this object

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

items() → list of D's (key, value) pairs, as 2-tuples¶

iteritems() → an iterator over the (key, value) items of D¶

iterkeys() → an iterator over the keys of D¶

itervalues() → an iterator over the values of D¶

keys() → list of D's keys¶

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair¶: as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D¶

tojson()[source]¶

Convert this LandmarkGroup to a dictionary JSON representation.

Returns:	json (`dict`) – Dictionary conforming to the LJSON v2 specification.

update([E, ]**F) → None. Update D from mapping/iterable E and F.¶: If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → list of D's values¶

view_widget(popup=False, browser_style='buttons', figure_size=(10, 8))[source]¶

Visualizes the landmark group object using the visualize_landmarkgroups widget.

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 landmark managers will have the form of plus/minus buttons or a slider. figure_size ((int, int), optional) – The initial size of the rendered figure.

with_labels(labels=None)[source]¶

A new landmark group that contains only the certain labels

Parameters:	labels (str or list of str, optional) – Labels that should be kept in the returned landmark group. If `None` is passed, and if there is only one label on this group, the label will be substituted automatically.
Returns:	landmark_group (`LandmarkGroup`) – A new landmark group with the same group label but containing only the given label.

without_labels(labels)[source]¶

A new landmark group that excludes certain labels label.

Parameters:	labels (str or list of str) – Labels that should be excluded in the returned landmark group.
Returns:	landmark_group (`LandmarkGroup`) – A new landmark group with the same group label but containing all labels except the given label.

labels¶

The list of labels that belong to this group.

Type:	list of str

lms¶

The pointcloud representing all the landmarks in the group.

Type:	`PointCloud`

n_dims¶

The dimensionality of these landmarks.

Type:	int

n_labels¶

Number of labels in the group.

Type:	int

n_landmarks¶

The total number of landmarks in the group.

Type:	int

labeller¶

menpo.landmark.labeller(landmarkable, group, label_func)[source]¶

Re-label an existing landmark group on a Landmarkable object with a new label set.

Parameters:

landmarkable (Landmarkable) – Landmarkable that will have it’s LandmarkManager augmented with a new LandmarkGroup
group (str) – The group label of the existing landmark group that should be re-labelled. A copy of this group will be attached to it’s landmark manager with new labels. The group label of this new group and the labels it will have is determined by label_func
label_func (func -> (str, LandmarkGroup)) – A labelling function taken from this module, Takes as input a LandmarkGroup and returns a tuple of (new group label, new LandmarkGroup with semantic labels applied).

Returns:

landmarkable (Landmarkable) – Augmented landmarkable (this is just for convenience, the object will actually be modified in place)

Face Labels¶

ibug_face_49¶

menpo.landmark.ibug_face_49(landmark_group)[source]¶

Apply the ibug’s “standard” 49 point semantic labels (based on the original semantic labels of multiPIE but removing the annotations corresponding to the jaw region and the 2 describing the inner mouth corners) to the landmark group.

The group label will be ibug_face_49.

The semantic labels applied are as follows:

left_eyebrow

right_eyebrow

nose

left_eye

right_eye

mouth

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `ibug_face_49` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 68 points

References

[1]	http://www.multipie.org/

ibug_face_51¶

menpo.landmark.ibug_face_51(landmark_group)[source]¶

Apply the ibug’s “standard” 51 point semantic labels (based on the original semantic labels of multiPIE but removing the annotations corresponding to the jaw region) to the landmark group.

The group label will be ibug_face_51.

The semantic labels applied are as follows:

left_eyebrow

right_eyebrow

nose

left_eye

right_eye

mouth

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `ibug_face_51` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 68 points

References

[1]	http://www.multipie.org/

ibug_face_66¶

menpo.landmark.ibug_face_66(landmark_group)[source]¶

Apply the ibug’s “standard” 66 point semantic labels (based on the original semantic labels of multiPIE but ignoring the 2 points describing the inner mouth corners) to the landmark group.

The group label will be ibug_face_66.

The semantic labels applied are as follows:

jaw

left_eyebrow

right_eyebrow

nose

left_eye

right_eye

mouth

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `ibug_face_66` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 68 points

References

[1]	http://www.multipie.org/

ibug_face_68¶

menpo.landmark.ibug_face_68(landmark_group)[source]¶

Apply the ibug’s “standard” 68 point semantic labels (based on the original semantic labels of multiPIE) to the landmark group.

The group label will be ibug_face_68.

The semantic labels applied are as follows:

jaw

left_eyebrow

right_eyebrow

nose

left_eye

right_eye

mouth

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `ibug_face_68` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 68 points

References

[1]	http://www.multipie.org/

ibug_face_68_trimesh¶

menpo.landmark.ibug_face_68_trimesh(landmark_group)[source]¶

Apply the ibug’s “standard” 68 point triangulation to the landmarks in the given landmark group.

The group label will be ibug_face_68_trimesh.

The semantic labels applied are as follows:

tri

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `ibug_face_68_trimesh` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 68 points

References

[1]	http://www.multipie.org/

ibug_face_65_closed_mouth¶

menpo.landmark.ibug_face_65_closed_mouth(landmark_group)[source]¶

Apply the ibug’s “standard” 68 point semantic labels (based on the original semantic labels of multiPIE) to the landmarks in the given landmark group - but ignore the 3 points that are coincident for a closed mouth. Therefore, there only 65 points are returned.

The group label will be ibug_face_65_closed_mouth.

The semantic labels applied are as follows:

jaw

left_eyebrow

right_eyebrow

nose

left_eye

right_eye

mouth

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `ibug_face_65_closed_mouth` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 68 points

References

[1]	http://www.multipie.org/

imm_face¶

menpo.landmark.imm_face(landmark_group)[source]¶

Apply the 58 point semantic labels from the IMM dataset to the landmarks in the given landmark group.

The group label will be imm_face.

The semantic labels applied are as follows:

jaw

left_eye

right_eye

left_eyebrow

right_eyebrow

mouth

nose

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `imm_face` landmark_group (`LandmarkGroup`) – New landmark group
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 58 points

References

[1]	http://www2.imm.dtu.dk/~aam/

lfpw_face¶

menpo.landmark.lfpw_face(landmark_group)[source]¶

Apply the 29 point semantic labels from the LFPW dataset to the landmarks in the given landmark group.

The group label will be lfpw_face.

The semantic labels applied are as follows:

chin

left_eye

right_eye

left_eyebrow

right_eyebrow

mouth

nose

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `lfpw_face` landmark_group (`LandmarkGroup`) – New landmark group
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 29 points

References

[1]	http://homes.cs.washington.edu/~neeraj/databases/lfpw/

bu3dfe_83¶

menpo.landmark.bu3dfe_83(landmark_group)[source]¶

Apply the BU-3DFE (Binghamton University 3D Facial Expression) Database 83 point facial annotation markup to this landmark group.

The group label will be bu3dfe_83.

The semantic labels applied are as follows:

right_eye

left_eye

right_eyebrow

left_eyebrow

right_nose

left_nose

nostrils

outer_mouth

inner_mouth

jaw

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `bu3dfe_83` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	class:menpo.landmark.exceptions.LabellingError – If the given landmark group contains less than 83 points

References

[1]	http://www.cs.binghamton.edu/~lijun/Research/3DFE/3DFE_Analysis.html

Eyes Labels¶

ibug_open_eye¶

menpo.landmark.ibug_open_eye(landmark_group)[source]¶

Apply the ibug’s “standard” open eye semantic labels to the landmarks in the given landmark group.

The group label will be ibug_open_eye.

The semantic labels applied are as follows:

upper_eyelid

lower_eyelid

iris

pupil

sclera

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `ibug_open_eye` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 38 points

ibug_open_eye_trimesh¶

menpo.landmark.ibug_open_eye_trimesh(landmark_group)[source]¶

Apply the ibug’s “standard” open eye semantic labels to the landmarks in the given landmark group.

The group label will be ibug_open_eye_trimesh.

The semantic labels applied are as follows:

tri

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `ibug_open_eye_trimesh` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 38 points

ibug_close_eye_trimesh¶

menpo.landmark.ibug_close_eye_trimesh(landmark_group)[source]¶

Apply the ibug’s “standard” close eye semantic labels to the landmarks in the given landmark group.

The group label will be ibug_close_eye_trimesh.

The semantic labels applied are as follows:

tri

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `ibug_close_eye_trimesh` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 38 points

ibug_close_eye_points¶

menpo.landmark.ibug_close_eye_points(landmark_group)[source]¶

Apply the ibug’s “standard” close eye semantic labels to the landmarks in the given landmark group.

The group label will be ibug_close_eye.

The semantic labels applied are as follows:

upper_eyelid

lower_eyelid

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `ibug_close_eye` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 17 points

Hands Labels¶

ibug_hand¶

menpo.landmark.ibug_hand(landmark_group)[source]¶

Apply the ibug’s “standard” 39 point semantic labels to the landmark group.

The group label will be ibug_hand.

The semantic labels applied are as follows:

thumb

index

middle

ring

pinky

palm

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `ibug_hand` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 39 points

Pose Labels¶

stickmen_pose¶

menpo.landmark.stickmen_pose(landmark_group)[source]¶

Apply the stickmen “standard” 12 point semantic labels to the landmark group.

The group label will be stickmen_pose.

The semantic labels applied are as follows:

torso

right_upper_arm

left_upper_arm

right_lower_arm

left_lower_arm

head

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `stickmen_pose` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 12 points

References

[1]	http://www.robots.ox.ac.uk/~vgg/data/stickmen/

flic_pose¶

menpo.landmark.flic_pose(landmark_group)[source]¶

Apply the flic “standard” 11 point semantic labels to the landmark group.

The group label will be flic_pose.

The semantic labels applied are as follows:

left_arm

right_arm

hips

face

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `flic_pose` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 11 points

References

[1]	http://vision.grasp.upenn.edu/cgi-bin/index.php?n=VideoLearning.FLIC

lsp_pose¶

menpo.landmark.lsp_pose(landmark_group)[source]¶

Apply the lsp “standard” 14 point semantic labels to the landmark group.

The group label will be lsp_pose.

The semantic labels applied are as follows:

left_leg

right_leg

left_arm

right_arm

head

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `lsp_pose` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 14 points

References

[1]	http://www.comp.leeds.ac.uk/mat4saj/lsp.html

Car Labels¶

streetscene_car_view_0¶

menpo.landmark.streetscene_car_view_0(landmark_group)[source]¶

Apply the 8 point semantic labels of the view 0 of the MIT Street Scene Car dataset to the landmark group.

The group label will be streetscene_car_view_0.

The semantic labels applied are as follows:

front

bonnet

windshield

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `streetscene_car_view_0` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 20 points

References

[1]	http://www.cs.cmu.edu/~vboddeti/alignment.html

streetscene_car_view_1¶

menpo.landmark.streetscene_car_view_1(landmark_group)[source]¶

Apply the 14 point semantic labels of the view 1 of the MIT Street Scene Car dataset to the landmark group.

The group label will be streetscene_car_view_1.

The semantic labels applied are as follows:

front

bonnet

windshield

left_side

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `streetscene_car_view_1` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 20 points

References

[1]	http://www.cs.cmu.edu/~vboddeti/alignment.html

streetscene_car_view_2¶

menpo.landmark.streetscene_car_view_2(landmark_group)[source]¶

Apply the 10 point semantic labels of the view 2 of the MIT Street Scene Car dataset to the landmark group.

The group label will be streetscene_car_view_2.

The semantic labels applied are as follows:

left_side

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: ‘streetscene_car_view_2’ landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 20 points

References

[1]	http://www.cs.cmu.edu/~vboddeti/alignment.html

streetscene_car_view_3¶

menpo.landmark.streetscene_car_view_3(landmark_group)[source]¶

Apply the 14 point semantic labels of the view 3 of the MIT Street Scene Car dataset to the landmark group.

The group label will be streetscene_car_view_2.

The semantic labels applied are as follows:

left_side

rear windshield

trunk

rear

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `streetscene_car_view_3` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 20 points

References

[1]	http://www.cs.cmu.edu/~vboddeti/alignment.html

streetscene_car_view_4¶

menpo.landmark.streetscene_car_view_4(landmark_group)[source]¶

Apply the 14 point semantic labels of the view 4 of the MIT Street Scene Car dataset to the landmark group.

The group label will be streetscene_car_view_4.

The semantic labels applied are as follows:

front

bonnet

windshield

right_side

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: ‘streetscene_car_view_4’ landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 20 points

References

[1]	http://www.cs.cmu.edu/~vboddeti/alignment.html

streetscene_car_view_5¶

menpo.landmark.streetscene_car_view_5(landmark_group)[source]¶

Apply the 10 point semantic labels of the view 5 of the MIT Street Scene Car dataset to the landmark group.

The group label will be streetscene_car_view_5.

The semantic labels applied are as follows:

right_side

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `streetscene_car_view_5` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 20 points

References

[1]	http://www.cs.cmu.edu/~vboddeti/alignment.html

streetscene_car_view_6¶

menpo.landmark.streetscene_car_view_6(landmark_group)[source]¶

Apply the 14 point semantic labels of the view 6 of the MIT Street Scene Car dataset to the landmark group.

The group label will be streetscene_car_view_6.

The semantic labels applied are as follows:

right_side

rear_windshield

trunk

rear

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `streetscene_car_view_3` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 20 points

References

[1]	http://www.cs.cmu.edu/~vboddeti/alignment.html

streetscene_car_view_7¶

menpo.landmark.streetscene_car_view_7(landmark_group)[source]¶

Apply the 8 point semantic labels of the view 0 of the MIT Street Scene Car dataset to the landmark group.

The group label will be streetscene_car_view_7.

The semantic labels applied are as follows:

rear_windshield

trunk

rear

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `streetscene_car_view_7` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 20 points

References

[1]	http://www.cs.cmu.edu/~vboddeti/alignment.html

Tongue Labels¶

ibug_tongue¶

menpo.landmark.ibug_tongue(landmark_group)[source]¶

Apply the ibug’s “standard” tongue semantic labels to the landmarks in the given landmark group.

The group label will be ibug_tongue.

The semantic labels applied are as follows:

outline

bisector

Parameters:	landmark_group (`LandmarkGroup`) – The landmark group to apply semantic labels to.
Returns:	group (str) – The group label: `ibug_tongue` landmark_group (`LandmarkGroup`) – New landmark group.
Raises:	`error` (`LabellingError`) – If the given landmark group contains less than 19 points

`menpo.math`¶

Decomposition¶

eigenvalue_decomposition¶

menpo.math.eigenvalue_decomposition(S, eps=1e-10)[source]¶

Eigenvalue decomposition of a given covariance (or scatter) matrix.

Parameters:

S ((N, N) ndarray) – Covariance/Scatter matrix
eps (float, optional) –
Small value to be used for the tolerance limit computation. The final limit is computed as
```
limit = np.max(np.abs(eigenvalues)) * eps
```

Returns:

pos_eigenvectors ((N, p) ndarray) – The matrix with the eigenvectors corresponding to positive eigenvalues.
pos_eigenvalues ((p,) ndarray) – The array of positive eigenvalues.

principal_component_decomposition¶

menpo.math.principal_component_decomposition(X, whiten=False, centre=True, bias=False, inplace=False)[source]¶

Apply Principal Component Analysis (PCA) on the data matrix X. In the case where the data matrix is very large, it is advisable to set inplace = True. However, note this destructively edits the data matrix by subtracting the mean inplace.

Parameters:

X ((n_samples, n_features) ndarray) – Training data.
whiten (bool, optional) – Normalise the eigenvectors to have unit magnitude.
centre (bool, optional) – Whether to centre the data matrix. If False, zero will be subtracted.
bias (bool, optional) – Whether to use a biased estimate of the number of samples. If False, subtracts 1 from the number of samples.
inplace (bool, optional) – Whether to do the mean subtracting inplace or not. This is crucial if the data matrix is greater than half the available memory size.

Returns:

eigenvectors ((n_components, n_features) ndarray) – The eigenvectors of the data matrix.
eigenvalues ((n_components,) ndarray) – The positive eigenvalues from the data matrix.
mean_vector ((n_components,) ndarray) – The mean that was subtracted from the dataset.

Linear Algebra¶

dot_inplace_right¶

menpo.math.dot_inplace_right(a, b, block_size=1000)[source]¶

Inplace dot product for memory efficiency. It computes a * b = c where b will be replaced inplace with c.

Parameters:

a ((n_small, k) ndarray, n_small <= k) – The first array to dot - assumed to be small. n_small must be smaller than k so the result can be stored within the memory space of b.
b ((k, n_big) ndarray) – Second array to dot - assumed to be large. Will be damaged by this function call as it is used to store the output inplace.
block_size (int, optional) – The size of the block of b that a will be dotted against in each iteration. larger block sizes increase the time performance of the dot product at the cost of a higher memory overhead for the operation.

Returns:

c ((n_small, n_big) ndarray) – The output of the operation. Exactly the same as a memory view onto b (b[:n_small]) as b is modified inplace to store the result.

dot_inplace_left¶

menpo.math.dot_inplace_left(a, b, block_size=1000)[source]¶

Inplace dot product for memory efficiency. It computes a * b = c, where a will be replaced inplace with c.

Parameters:

a ((n_big, k) ndarray) – First array to dot - assumed to be large. Will be damaged by this function call as it is used to store the output inplace.
b ((k, n_small) ndarray, n_small <= k) – The second array to dot - assumed to be small. n_small must be smaller than k so the result can be stored within the memory space of a.
block_size (int, optional) – The size of the block of a that will be dotted against b in each iteration. larger block sizes increase the time performance of the dot product at the cost of a higher memory overhead for the operation.

Returns:

c ((n_big, n_small) ndarray) – The output of the operation. Exactly the same as a memory view onto a (a[:, :n_small]) as a is modified inplace to store the result.

Convolution¶

log_gabor¶

menpo.math.log_gabor(image, **kwargs)[source]¶

Creates a log-gabor filter bank, including smoothing the images via a low-pass filter at the edges.

To create a 2D filter bank, simply specify the number of phi orientations (orientations in the xy-plane).

To create a 3D filter bank, you must specify both the number of phi (azimuth) and theta (elevation) orientations.

This algorithm is directly derived from work by Peter Kovesi.

Parameters:

image ((M, N, ...) ndarray) – Image to be convolved
num_scales (int, optional) –
Number of wavelet scales.

Default 2D 4

Default 3D 4
num_phi_orientations (int, optional) –
Number of filter orientations in the xy-plane

Default 2D 6

Default 3D 6
num_theta_orientations (int, optional) –
Only required for 3D. Number of filter orientations in the z-plane

Default 2D N/A

Default 3D 4
min_wavelength (int, optional) –
Wavelength of smallest scale filter.

Default 2D 3

Default 3D 3
scaling_constant (int, optional) –
Scaling factor between successive filters.

Default 2D 2

Default 3D 2
center_sigma (float, optional) –
Ratio of the standard deviation of the Gaussian describing the Log Gabor filter’s transfer function in the frequency domain to the filter centre frequency.

Default 2D 0.65

Default 3D 0.65
d_phi_sigma (float, optional) –
Angular bandwidth in xy-plane

Default 2D 1.3

Default 3D 1.5
d_theta_sigma (float, optional) –
Only required for 3D. Angular bandwidth in z-plane

Default 2D N/A

Default 3D 1.5

Returns:

complex_conv ((num_scales, num_orientations, image.shape) ndarray) – Complex valued convolution results. The real part is the result of convolving with the even symmetric filter, the imaginary part is the result from convolution with the odd symmetric filter.
bandpass ((num_scales, image.shape) ndarray) – Bandpass images corresponding to each scale s
S ((image.shape,) ndarray) – Convolved image

Examples

Return the magnitude of the convolution over the image at scale s and orientation o

np.abs(complex_conv[s, o, :, :])

Return the phase angles

np.angle(complex_conv[s, o, :, :])

References

[1]	D. J. Field, “Relations Between the Statistics of Natural Images and the Response Properties of Cortical Cells”, Journal of The Optical Society of America A, Vol 4, No. 12, December 1987. pp 2379-2394

`menpo.model`¶

LinearModel¶

class menpo.model.LinearModel(components)[source]¶

Bases: Copyable

A Linear Model contains a matrix of vector components, each component vector being made up of features.

Parameters:	components (`(n_components, n_features)` ndarray) – The components array.

component_vector(index)[source]¶

A particular component of the model, in vectorized form.

Parameters:	index (int) – The component that is to be returned.
Returns:	component_vector (`(n_features,)` ndarray) – The component vector.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

instance_vector(weights)[source]¶

Creates a new vector instance of the model by weighting together the components.

Parameters:

weights ((n_weights,) ndarray or list) –

The weightings for the first n_weights components that should be used.

weights[j] is the linear contribution of the j’th principal component to the instance vector.

Returns: vector ((n_features,) ndarray) – The instance vector for the weighting provided.

instance_vectors(weights)[source]¶

Creates new vectorized instances of the model using all the components of the linear model.

Parameters:

weights ((n_vectors, n_weights) ndarray or list of lists) –

The weightings for all components of the linear model. All components will be used to produce the instance.

weights[i, j] is the linear contribution of the j’th principal component to the i’th instance vector produced.

Raises: ValueError – If n_weights > n_available_components

Returns: vectors ((n_vectors, n_features) ndarray) – The instance vectors for the weighting provided.

orthonormalize_against_inplace(linear_model)[source]¶

Enforces that the union of this model’s components and another are both mutually orthonormal.

Both models keep its number of components unchanged or else a value error is raised.

Parameters:	linear_model (`LinearModel`) – A second linear model to orthonormalize this against.
Raises:	`ValueError` – The number of features must be greater or equal than the sum of the number of components in both linear models ({} < {})

orthonormalize_inplace()[source]¶: Enforces that this model’s components are orthonormalized, s.t. component_vector(i).dot(component_vector(j) = dirac_delta.

project_out_vector(vector)[source]¶

Returns a version of vector where all the basis of the model have been projected out.

Parameters:	vector (`(n_features,)` ndarray) – A novel vector.
Returns:	projected_out (`(n_features,)` ndarray) – A copy of vector with all basis of the model projected out.

project_out_vectors(vectors)[source]¶

Returns a version of vectors where all the basis of the model have been projected out.

Parameters:	vectors (`(n_vectors, n_features)` ndarray) – A matrix of novel vectors.
Returns:	projected_out (`(n_vectors, n_features)` ndarray) – A copy of vectors with all basis of the model projected out.

project_vector(vector)[source]¶

Projects the vector onto the model, retrieving the optimal linear reconstruction weights.

Parameters:	vector (`(n_features,)` ndarray) – A vectorized novel instance.
Returns:	weights (`(n_components,)` ndarray) – A vector of optimal linear weights.

project_vectors(vectors)[source]¶

Projects each of the vectors onto the model, retrieving the optimal linear reconstruction weights for each instance.

Parameters:	vectors (`(n_samples, n_features)` ndarray) – Array of vectorized novel instances.
Returns:	weights (`(n_samples, n_components)` ndarray) – The matrix of optimal linear weights.

reconstruct_vector(vector)[source]¶

Project a vector onto the linear space and rebuild from the weights found.

Parameters:	vector (`(n_features, )` ndarray) – A vectorized novel instance to project.
Returns:	reconstructed (`(n_features,)` ndarray) – The reconstructed vector.

reconstruct_vectors(vectors)[source]¶

Projects the vectors onto the linear space and rebuilds vectors from the weights found.

Parameters:	vectors (`(n_vectors, n_features)` ndarray) – A set of vectors to project.
Returns:	reconstructed (`(n_vectors, n_features)` ndarray) – The reconstructed vectors.

components¶

The components matrix of the linear model.

Type:	`(n_available_components, n_features)` ndarray

n_components¶

The number of bases of the model.

Type:	int

n_features¶

The number of elements in each linear component.

Type:	int

InstanceLinearModel¶

class menpo.model.InstanceLinearModel(components)[source]¶

Bases: LinearModel, InstanceBackedModel

Mixin of LinearModel and InstanceBackedModel objects.

Parameters:	components (`(n_components, n_features)` ndarray) – The components array. template_instance (`Vectorizable`) – The template instance.

component(index)¶

A particular component of the model, in vectorized form.

Parameters:	index (int) – The component that is to be returned.
Returns:	component_vector (type(self.template_instance)) – The component vector.

component_vector(index)¶

A particular component of the model, in vectorized form.

Parameters:	index (int) – The component that is to be returned.
Returns:	component_vector (`(n_features,)` ndarray) – The component vector.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

instance(weights)¶

Creates a new instance of the model using the first len(weights) components.

Parameters:	weights (`(n_weights,)` ndarray or list) – `weights[i]` is the linear contribution of the i’th component to the instance vector.
Raises:	`ValueError` – If n_weights > n_components
Returns:	instance (type(self.template_instance)) – An instance of the model.

instance_vector(weights)¶

Creates a new vector instance of the model by weighting together the components.

Parameters:

weights ((n_weights,) ndarray or list) –

The weightings for the first n_weights components that should be used.

weights[j] is the linear contribution of the j’th principal component to the instance vector.

Returns: vector ((n_features,) ndarray) – The instance vector for the weighting provided.

instance_vectors(weights)¶

Creates new vectorized instances of the model using all the components of the linear model.

Parameters:

weights ((n_vectors, n_weights) ndarray or list of lists) –

The weightings for all components of the linear model. All components will be used to produce the instance.

weights[i, j] is the linear contribution of the j’th principal component to the i’th instance vector produced.

Raises: ValueError – If n_weights > n_available_components

Returns: vectors ((n_vectors, n_features) ndarray) – The instance vectors for the weighting provided.

orthonormalize_against_inplace(linear_model)¶

Enforces that the union of this model’s components and another are both mutually orthonormal.

Both models keep its number of components unchanged or else a value error is raised.

Parameters:	linear_model (`LinearModel`) – A second linear model to orthonormalize this against.
Raises:	`ValueError` – The number of features must be greater or equal than the sum of the number of components in both linear models ({} < {})

orthonormalize_inplace()¶: Enforces that this model’s components are orthonormalized, s.t. component_vector(i).dot(component_vector(j) = dirac_delta.

project(instance)¶

Projects the instance onto the model, retrieving the optimal linear weightings.

Parameters:	novel_instance (`Vectorizable`) – A novel instance.
Returns:	projected (`(n_components,)` ndarray) – A vector of optimal linear weightings.

project_out(instance)¶

Returns a version of instance where all the basis of the model have been projected out.

Parameters:	instance (`Vectorizable`) – A novel instance of `Vectorizable`.
Returns:	projected_out (self.instance_class) – A copy of instance, with all basis of the model projected out.

project_out_vector(vector)¶

Returns a version of vector where all the basis of the model have been projected out.

Parameters:	vector (`(n_features,)` ndarray) – A novel vector.
Returns:	projected_out (`(n_features,)` ndarray) – A copy of vector with all basis of the model projected out.

project_out_vectors(vectors)¶

Returns a version of vectors where all the basis of the model have been projected out.

Parameters:	vectors (`(n_vectors, n_features)` ndarray) – A matrix of novel vectors.
Returns:	projected_out (`(n_vectors, n_features)` ndarray) – A copy of vectors with all basis of the model projected out.

project_vector(vector)¶

Projects the vector onto the model, retrieving the optimal linear reconstruction weights.

Parameters:	vector (`(n_features,)` ndarray) – A vectorized novel instance.
Returns:	weights (`(n_components,)` ndarray) – A vector of optimal linear weights.

project_vectors(vectors)¶

Projects each of the vectors onto the model, retrieving the optimal linear reconstruction weights for each instance.

Parameters:	vectors (`(n_samples, n_features)` ndarray) – Array of vectorized novel instances.
Returns:	weights (`(n_samples, n_components)` ndarray) – The matrix of optimal linear weights.

reconstruct(instance)¶

Projects a instance onto the linear space and rebuilds from the weights found.

Syntactic sugar for:

instance(project(instance))

but faster, as it avoids the conversion that takes place each time.

Parameters:	instance (`Vectorizable`) – A novel instance of `Vectorizable`.
Returns:	reconstructed (self.instance_class) – The reconstructed object.

reconstruct_vector(vector)¶

Project a vector onto the linear space and rebuild from the weights found.

Parameters:	vector (`(n_features, )` ndarray) – A vectorized novel instance to project.
Returns:	reconstructed (`(n_features,)` ndarray) – The reconstructed vector.

reconstruct_vectors(vectors)¶

Projects the vectors onto the linear space and rebuilds vectors from the weights found.

Parameters:	vectors (`(n_vectors, n_features)` ndarray) – A set of vectors to project.
Returns:	reconstructed (`(n_vectors, n_features)` ndarray) – The reconstructed vectors.

components¶

The components matrix of the linear model.

Type:	`(n_available_components, n_features)` ndarray

n_components¶

The number of bases of the model.

Type:	int

n_features¶

The number of elements in each linear component.

Type:	int

MeanLinearModel¶

class menpo.model.MeanLinearModel(components, mean_vector)[source]¶

Bases: LinearModel

A Linear Model containing a matrix of vector components, each component vector being made up of features. The model additionally has a mean component which is handled accordingly when either:

A component of the model is selected
A projection operation is performed

Parameters:	components (`(n_components, n_features)` ndarray) – The components array. mean_vector (`(n_features,)` ndarray) – The mean vector.

component_vector(index, with_mean=True, scale=1.0)[source]¶

A particular component of the model, in vectorized form.

Parameters:	index (int) – The component that is to be returned with_mean (bool, optional) – If `True`, the component will be blended with the mean vector before being returned. If not, the component is returned on it’s own. scale (float, optional) – A scale factor that should be directly applied to the component. Only valid in the case where `with_mean == True`.
Returns:	component_vector (`(n_features,)` ndarray) – The component vector.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

instance_vector(weights)¶

Creates a new vector instance of the model by weighting together the components.

Parameters:

weights ((n_weights,) ndarray or list) –

The weightings for the first n_weights components that should be used.

weights[j] is the linear contribution of the j’th principal component to the instance vector.

Returns: vector ((n_features,) ndarray) – The instance vector for the weighting provided.

instance_vectors(weights)¶

Creates new vectorized instances of the model using all the components of the linear model.

Parameters:

weights ((n_vectors, n_weights) ndarray or list of lists) –

The weightings for all components of the linear model. All components will be used to produce the instance.

weights[i, j] is the linear contribution of the j’th principal component to the i’th instance vector produced.

Raises: ValueError – If n_weights > n_available_components

Returns: vectors ((n_vectors, n_features) ndarray) – The instance vectors for the weighting provided.

orthonormalize_against_inplace(linear_model)¶

Enforces that the union of this model’s components and another are both mutually orthonormal.

Both models keep its number of components unchanged or else a value error is raised.

Parameters:	linear_model (`LinearModel`) – A second linear model to orthonormalize this against.
Raises:	`ValueError` – The number of features must be greater or equal than the sum of the number of components in both linear models ({} < {})

orthonormalize_inplace()¶: Enforces that this model’s components are orthonormalized, s.t. component_vector(i).dot(component_vector(j) = dirac_delta.

project_out_vector(vector)¶

Returns a version of vector where all the basis of the model have been projected out.

Parameters:	vector (`(n_features,)` ndarray) – A novel vector.
Returns:	projected_out (`(n_features,)` ndarray) – A copy of vector with all basis of the model projected out.

project_out_vectors(vectors)¶

Returns a version of vectors where all the basis of the model have been projected out.

Parameters:	vectors (`(n_vectors, n_features)` ndarray) – A matrix of novel vectors.
Returns:	projected_out (`(n_vectors, n_features)` ndarray) – A copy of vectors with all basis of the model projected out.

project_vector(vector)¶

Projects the vector onto the model, retrieving the optimal linear reconstruction weights.

Parameters:	vector (`(n_features,)` ndarray) – A vectorized novel instance.
Returns:	weights (`(n_components,)` ndarray) – A vector of optimal linear weights.

project_vectors(vectors)[source]¶

Projects each of the vectors onto the model, retrieving the optimal linear reconstruction weights for each instance.

Parameters:	vectors (`(n_samples, n_features)` ndarray) – Array of vectorized novel instances.
Returns:	projected (`(n_samples, n_components)` ndarray) – The matrix of optimal linear weights.

reconstruct_vector(vector)¶

Project a vector onto the linear space and rebuild from the weights found.

Parameters:	vector (`(n_features, )` ndarray) – A vectorized novel instance to project.
Returns:	reconstructed (`(n_features,)` ndarray) – The reconstructed vector.

reconstruct_vectors(vectors)¶

Projects the vectors onto the linear space and rebuilds vectors from the weights found.

Parameters:	vectors (`(n_vectors, n_features)` ndarray) – A set of vectors to project.
Returns:	reconstructed (`(n_vectors, n_features)` ndarray) – The reconstructed vectors.

components¶

The components matrix of the linear model.

Type:	`(n_available_components, n_features)` ndarray

n_components¶

The number of bases of the model.

Type:	int

n_features¶

The number of elements in each linear component.

Type:	int

MeanInstanceLinearModel¶

class menpo.model.MeanInstanceLinearModel(components, mean_vector, template_instance)[source]¶

Bases: MeanLinearModel, InstanceBackedModel

Mixin of MeanLinearModel and InstanceBackedModel objects.

Parameters:	components (`(n_components, n_features)` ndarray) – The components array. mean_vector (`(n_features,)` ndarray) – The mean vector. template_instance (`Vectorizable`) – The template instance.

component(index, with_mean=True, scale=1.0)[source]¶

Return a particular component of the linear model.

Parameters:

index (int) – The component that is to be returned
with_mean (bool, optional) – If True, the component will be blended with the mean vector before being returned. If not, the component is returned on it’s own.
scale (float, optional) – A scale factor that should be applied to the component. Only valid in the case where with_mean == True. See component_vector() for how this scale factor is interpreted.

Returns:

component (type(self.template_instance)) – The requested component.

component_vector(index, with_mean=True, scale=1.0)¶

A particular component of the model, in vectorized form.

Parameters:	index (int) – The component that is to be returned with_mean (bool, optional) – If `True`, the component will be blended with the mean vector before being returned. If not, the component is returned on it’s own. scale (float, optional) – A scale factor that should be directly applied to the component. Only valid in the case where `with_mean == True`.
Returns:	component_vector (`(n_features,)` ndarray) – The component vector.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

instance(weights)¶

Creates a new instance of the model using the first len(weights) components.

Parameters:	weights (`(n_weights,)` ndarray or list) – `weights[i]` is the linear contribution of the i’th component to the instance vector.
Raises:	`ValueError` – If n_weights > n_components
Returns:	instance (type(self.template_instance)) – An instance of the model.

instance_vector(weights)¶

Creates a new vector instance of the model by weighting together the components.

Parameters:

weights ((n_weights,) ndarray or list) –

The weightings for the first n_weights components that should be used.

weights[j] is the linear contribution of the j’th principal component to the instance vector.

Returns: vector ((n_features,) ndarray) – The instance vector for the weighting provided.

instance_vectors(weights)¶

Creates new vectorized instances of the model using all the components of the linear model.

Parameters:

weights ((n_vectors, n_weights) ndarray or list of lists) –

The weightings for all components of the linear model. All components will be used to produce the instance.

weights[i, j] is the linear contribution of the j’th principal component to the i’th instance vector produced.

Raises: ValueError – If n_weights > n_available_components

Returns: vectors ((n_vectors, n_features) ndarray) – The instance vectors for the weighting provided.

mean()[source]¶

Return the mean of the model.

Type:	`Vectorizable`

orthonormalize_against_inplace(linear_model)¶

Enforces that the union of this model’s components and another are both mutually orthonormal.

Both models keep its number of components unchanged or else a value error is raised.

Parameters:	linear_model (`LinearModel`) – A second linear model to orthonormalize this against.
Raises:	`ValueError` – The number of features must be greater or equal than the sum of the number of components in both linear models ({} < {})

orthonormalize_inplace()¶: Enforces that this model’s components are orthonormalized, s.t. component_vector(i).dot(component_vector(j) = dirac_delta.

project(instance)¶

Projects the instance onto the model, retrieving the optimal linear weightings.

Parameters:	novel_instance (`Vectorizable`) – A novel instance.
Returns:	projected (`(n_components,)` ndarray) – A vector of optimal linear weightings.

project_out(instance)¶

Returns a version of instance where all the basis of the model have been projected out.

Parameters:	instance (`Vectorizable`) – A novel instance of `Vectorizable`.
Returns:	projected_out (self.instance_class) – A copy of instance, with all basis of the model projected out.

project_out_vector(vector)¶

Returns a version of vector where all the basis of the model have been projected out.

Parameters:	vector (`(n_features,)` ndarray) – A novel vector.
Returns:	projected_out (`(n_features,)` ndarray) – A copy of vector with all basis of the model projected out.

project_out_vectors(vectors)¶

Returns a version of vectors where all the basis of the model have been projected out.

Parameters:	vectors (`(n_vectors, n_features)` ndarray) – A matrix of novel vectors.
Returns:	projected_out (`(n_vectors, n_features)` ndarray) – A copy of vectors with all basis of the model projected out.

project_vector(vector)¶

Projects the vector onto the model, retrieving the optimal linear reconstruction weights.

Parameters:	vector (`(n_features,)` ndarray) – A vectorized novel instance.
Returns:	weights (`(n_components,)` ndarray) – A vector of optimal linear weights.

project_vectors(vectors)¶

Projects each of the vectors onto the model, retrieving the optimal linear reconstruction weights for each instance.

Parameters:	vectors (`(n_samples, n_features)` ndarray) – Array of vectorized novel instances.
Returns:	projected (`(n_samples, n_components)` ndarray) – The matrix of optimal linear weights.

reconstruct(instance)¶

Projects a instance onto the linear space and rebuilds from the weights found.

Syntactic sugar for:

instance(project(instance))

but faster, as it avoids the conversion that takes place each time.

Parameters:	instance (`Vectorizable`) – A novel instance of `Vectorizable`.
Returns:	reconstructed (self.instance_class) – The reconstructed object.

reconstruct_vector(vector)¶

Project a vector onto the linear space and rebuild from the weights found.

Parameters:	vector (`(n_features, )` ndarray) – A vectorized novel instance to project.
Returns:	reconstructed (`(n_features,)` ndarray) – The reconstructed vector.

reconstruct_vectors(vectors)¶

Projects the vectors onto the linear space and rebuilds vectors from the weights found.

Parameters:	vectors (`(n_vectors, n_features)` ndarray) – A set of vectors to project.
Returns:	reconstructed (`(n_vectors, n_features)` ndarray) – The reconstructed vectors.

components¶

The components matrix of the linear model.

Type:	`(n_available_components, n_features)` ndarray

n_components¶

The number of bases of the model.

Type:	int

n_features¶

The number of elements in each linear component.

Type:	int

PCAModel¶

class menpo.model.PCAModel(samples, centre=True, bias=False, verbose=False, n_samples=None)[source]¶

Bases: MeanInstanceLinearModel

A MeanInstanceLinearModel where components are Principal Components.

Principal Component Analysis (PCA) by eigenvalue decomposition of the data’s scatter matrix. For details of the implementation of PCA, see principal_component_decomposition.

Parameters:

samples (list of Vectorizable) – List of samples to build the model from.
centre (bool, optional) – When True (default) PCA is performed after mean centering the data. If False the data is assumed to be centred, and the mean will be 0.
bias (bool, optional) – When True a biased estimator of the covariance matrix is used. See notes.
n_samples (int, optional) – If provided then samples must be an iterator that yields n_samples. If not provided then samples has to be a list (so we know how large the data matrix needs to be).

Notes

True bias means that we calculate the covariance as \(\frac{1}{N} \sum_{i=1}^N \mathbf{x}_i \mathbf{x}_i^T\) instead of default \(\frac{1}{N-1} \sum_{i=1}^N \mathbf{x}_i \mathbf{x}_i^T\).

component(index, with_mean=True, scale=1.0)¶

Return a particular component of the linear model.

Parameters:

index (int) – The component that is to be returned
with_mean (bool, optional) – If True, the component will be blended with the mean vector before being returned. If not, the component is returned on it’s own.
scale (float, optional) – A scale factor that should be applied to the component. Only valid in the case where with_mean == True. See component_vector() for how this scale factor is interpreted.

Returns:

component (type(self.template_instance)) – The requested component.

component_vector(index, with_mean=True, scale=1.0)[source]¶

A particular component of the model, in vectorized form.

Parameters:

index (int) – The component that is to be returned
with_mean (bool, optional) – If True, the component will be blended with the mean vector before being returned. If not, the component is returned on it’s own.
scale (float, optional) – A scale factor that should be applied to the component. Only valid in the case where with_mean is True. The scale is applied in units of standard deviations (so a scale of 1.0 with_mean visualizes the mean plus 1 std. dev of the component in question).

Returns:

component_vector ((n_features,) ndarray) – The component vector of the given index.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

distance_to_subspace(instance)[source]¶

Returns a version of instance where all the basis of the model have been projected out and which has been scaled by the inverse of the noise_variance

Parameters:	instance (`Vectorizable`) – A novel instance.
Returns:	scaled_projected_out (self.instance_class) – A copy of instance, with all basis of the model projected out and scaled by the inverse of the noise_variance.

distance_to_subspace_vector(vector_instance)[source]¶

Returns a version of instance where all the basis of the model have been projected out and which has been scaled by the inverse of the noise_variance.

Parameters:	vector_instance (`(n_features,)` ndarray) – A novel vector.
Returns:	scaled_projected_out (`(n_features,)` ndarray) – A copy of vector_instance with all basis of the model projected out and scaled by the inverse of the noise_variance.

eigenvalues_cumulative_ratio()[source]¶

Returns the cumulative ratio between the variance captured by the active components and the total amount of variance present on the original samples.

Returns:	eigenvalues_cumulative_ratio (`(n_active_components,)` ndarray) – Array of cumulative eigenvalues.

eigenvalues_ratio()[source]¶

Returns the ratio between the variance captured by each active component and the total amount of variance present on the original samples.

Returns:	eigenvalues_ratio (`(n_active_components,)` ndarray) – The active eigenvalues array scaled by the original variance.

instance(weights)¶

Creates a new instance of the model using the first len(weights) components.

Parameters:	weights (`(n_weights,)` ndarray or list) – `weights[i]` is the linear contribution of the i’th component to the instance vector.
Raises:	`ValueError` – If n_weights > n_components
Returns:	instance (type(self.template_instance)) – An instance of the model.

instance_vector(weights)¶

Creates a new vector instance of the model by weighting together the components.

Parameters:

weights ((n_weights,) ndarray or list) –

The weightings for the first n_weights components that should be used.

weights[j] is the linear contribution of the j’th principal component to the instance vector.

Returns: vector ((n_features,) ndarray) – The instance vector for the weighting provided.

instance_vectors(weights)[source]¶

Creates new vectorized instances of the model using the first components in a particular weighting.

Parameters:

weights ((n_vectors, n_weights) ndarray or list of lists) –

The weightings for the first n_weights components that should be used per instance that is to be produced

weights[i, j] is the linear contribution of the j’th principal component to the i’th instance vector produced. Note that if n_weights < n_components, only the first n_weight components are used in the reconstruction (i.e. unspecified weights are implicitly 0).

Returns: vectors ((n_vectors, n_features) ndarray) – The instance vectors for the weighting provided.

Raises: ValueError – If n_weights > n_components

inverse_noise_variance()[source]¶

Returns the inverse of the noise variance.

Returns:	inverse_noise_variance (float) – Inverse of the noise variance.
Raises:	`ValueError` – If `noise_variance() == 0`

mean()¶

Return the mean of the model.

Type:	`Vectorizable`

noise_variance()[source]¶

Returns the average variance captured by the inactive components, i.e. the sample noise assumed in a Probabilistic PCA formulation.

If all components are active, then noise_variance == 0.0.

Returns:	noise_variance (float) – The mean variance of the inactive components.

noise_variance_ratio()[source]¶

Returns the ratio between the noise variance and the total amount of variance present on the original samples.

Returns:	noise_variance_ratio (float) – The ratio between the noise variance and the variance present in the original samples.

original_variance()[source]¶

Returns the total amount of variance captured by the original model, i.e. the amount of variance present on the original samples.

Returns:	optional_variance (float) – The variance captured by the model.

orthonormalize_against_inplace(linear_model)[source]¶

Enforces that the union of this model’s components and another are both mutually orthonormal.

Note that the model passed in is guaranteed to not have it’s number of available components changed. This model, however, may loose some dimensionality due to reaching a degenerate state.

The removed components will always be trimmed from the end of components (i.e. the components which capture the least variance). If trimming is performed, n_components and n_available_components would be altered - see trim_components() for details.

Parameters:	linear_model (`LinearModel`) – A second linear model to orthonormalize this against.

orthonormalize_inplace()¶: Enforces that this model’s components are orthonormalized, s.t. component_vector(i).dot(component_vector(j) = dirac_delta.

plot_eigenvalues(figure_id=None, new_figure=False, render_lines=True, line_colour='b', line_style='-', line_width=2, render_markers=True, marker_style='o', marker_size=6, marker_face_colour='b', marker_edge_colour='k', marker_edge_width=1.0, render_axes=True, axes_font_name='sans-serif', axes_font_size=10, axes_font_style='normal', axes_font_weight='normal', figure_size=(10, 6), render_grid=True, grid_line_style='--', grid_line_width=0.5)[source]¶

Plot of the eigenvalues.

Parameters:

figure_id (object, optional) – The id of the figure to be used.
new_figure (bool, optional) – If True, a new figure is created.
render_lines (bool, optional) – If True, the line 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`
or
`list` of length ``3``

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`
or
`list` of length ``3``

marker_edge_colour (See Below, optional) –

The edge colour of the markers. Example options

{``r``, ``g``, ``b``, ``c``, ``m``, ``k``, ``w``}
or
``(3, )`` `ndarray`
or
`list` of length ``3``

marker_edge_width (float, optional) – The width of the markers’ edge.
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``}

figure_size ((float, float) or None, optional) – The size of the figure in inches.
render_grid (bool, optional) – If True, the grid will be rendered.
grid_line_style ({-, --, -., :}, optional) – The style of the grid lines.
grid_line_width (float, optional) – The width of the grid lines.

Returns:

viewer (MatplotlibRenderer) – The viewer object.

plot_eigenvalues_cumulative_ratio(figure_id=None, new_figure=False, render_lines=True, line_colour='b', line_style='-', line_width=2, render_markers=True, marker_style='o', marker_size=6, marker_face_colour='b', marker_edge_colour='k', marker_edge_width=1.0, render_axes=True, axes_font_name='sans-serif', axes_font_size=10, axes_font_style='normal', axes_font_weight='normal', figure_size=(10, 6), render_grid=True, grid_line_style='--', grid_line_width=0.5)[source]¶

Plot of the variance ratio captured by the eigenvalues.

Parameters:

figure_id (object, optional) – The id of the figure to be used.
new_figure (bool, optional) – If True, a new figure is created.
render_lines (bool, optional) – If True, the line 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`
or
`list` of length ``3``

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`
or
`list` of length ``3``

marker_edge_colour (See Below, optional) –

The edge colour of the markers. Example options

{``r``, ``g``, ``b``, ``c``, ``m``, ``k``, ``w``}
or
``(3, )`` `ndarray`
or
`list` of length ``3``

marker_edge_width (float, optional) – The width of the markers’ edge.
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``}

figure_size ((float, float) or None, optional) – The size of the figure in inches.
render_grid (bool, optional) – If True, the grid will be rendered.
grid_line_style ({-, --, -., :}, optional) – The style of the grid lines.
grid_line_width (float, optional) – The width of the grid lines.

Returns:

viewer (MatplotlibRenderer) – The viewer object.

plot_eigenvalues_ratio(figure_id=None, new_figure=False, render_lines=True, line_colour='b', line_style='-', line_width=2, render_markers=True, marker_style='o', marker_size=6, marker_face_colour='b', marker_edge_colour='k', marker_edge_width=1.0, render_axes=True, axes_font_name='sans-serif', axes_font_size=10, axes_font_style='normal', axes_font_weight='normal', figure_size=(10, 6), render_grid=True, grid_line_style='--', grid_line_width=0.5)[source]¶

Plot of the variance ratio captured by the eigenvalues.

Parameters:

figure_id (object, optional) – The id of the figure to be used.
new_figure (bool, optional) – If True, a new figure is created.
render_lines (bool, optional) – If True, the line 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`
or
`list` of length ``3``

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`
or
`list` of length ``3``

marker_edge_colour (See Below, optional) –

The edge colour of the markers. Example options

{``r``, ``g``, ``b``, ``c``, ``m``, ``k``, ``w``}
or
``(3, )`` `ndarray`
or
`list` of length ``3``

marker_edge_width (float, optional) – The width of the markers’ edge.
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``}

figure_size ((float, float) or None, optional) – The size of the figure in inches.
render_grid (bool, optional) – If True, the grid will be rendered.
grid_line_style ({-, --, -., :}, optional) – The style of the grid lines.
grid_line_width (float, optional) – The width of the grid lines.

Returns:

viewer (MatplotlibRenderer) – The viewer object.

project(instance)¶

Projects the instance onto the model, retrieving the optimal linear weightings.

Parameters:	novel_instance (`Vectorizable`) – A novel instance.
Returns:	projected (`(n_components,)` ndarray) – A vector of optimal linear weightings.

project_out(instance)¶

Returns a version of instance where all the basis of the model have been projected out.

Parameters:	instance (`Vectorizable`) – A novel instance of `Vectorizable`.
Returns:	projected_out (self.instance_class) – A copy of instance, with all basis of the model projected out.

project_out_vector(vector)¶

Returns a version of vector where all the basis of the model have been projected out.

Parameters:	vector (`(n_features,)` ndarray) – A novel vector.
Returns:	projected_out (`(n_features,)` ndarray) – A copy of vector with all basis of the model projected out.

project_out_vectors(vectors)¶

Returns a version of vectors where all the basis of the model have been projected out.

Parameters:	vectors (`(n_vectors, n_features)` ndarray) – A matrix of novel vectors.
Returns:	projected_out (`(n_vectors, n_features)` ndarray) – A copy of vectors with all basis of the model projected out.

project_vector(vector)¶

Projects the vector onto the model, retrieving the optimal linear reconstruction weights.

Parameters:	vector (`(n_features,)` ndarray) – A vectorized novel instance.
Returns:	weights (`(n_components,)` ndarray) – A vector of optimal linear weights.

project_vectors(vectors)¶

Projects each of the vectors onto the model, retrieving the optimal linear reconstruction weights for each instance.

Parameters:	vectors (`(n_samples, n_features)` ndarray) – Array of vectorized novel instances.
Returns:	projected (`(n_samples, n_components)` ndarray) – The matrix of optimal linear weights.

project_whitened(instance)[source]¶

Returns a sheared (non-orthogonal) reconstruction of instance.

Parameters:	instance (`Vectorizable`) – A novel instance.
Returns:	sheared_reconstruction (self.instance_class) – A sheared (non-orthogonal) reconstruction of instance.

project_whitened_vector(vector_instance)[source]¶

Returns a sheared (non-orthogonal) reconstruction of vector_instance.

Parameters:	vector_instance (`(n_features,)` ndarray) – A novel vector.
Returns:	sheared_reconstruction (`(n_features,)` ndarray) – A sheared (non-orthogonal) reconstruction of vector_instance

reconstruct(instance)¶

Projects a instance onto the linear space and rebuilds from the weights found.

Syntactic sugar for:

instance(project(instance))

but faster, as it avoids the conversion that takes place each time.

Parameters:	instance (`Vectorizable`) – A novel instance of `Vectorizable`.
Returns:	reconstructed (self.instance_class) – The reconstructed object.

reconstruct_vector(vector)¶

Project a vector onto the linear space and rebuild from the weights found.

Parameters:	vector (`(n_features, )` ndarray) – A vectorized novel instance to project.
Returns:	reconstructed (`(n_features,)` ndarray) – The reconstructed vector.

reconstruct_vectors(vectors)¶

Projects the vectors onto the linear space and rebuilds vectors from the weights found.

Parameters:	vectors (`(n_vectors, n_features)` ndarray) – A set of vectors to project.
Returns:	reconstructed (`(n_vectors, n_features)` ndarray) – The reconstructed vectors.

trim_components(n_components=None)[source]¶

Permanently trims the components down to a certain amount. The number of active components will be automatically reset to this particular value.

This will reduce self.n_components down to n_components (if None, self.n_active_components will be used), freeing up memory in the process.

Once the model is trimmed, the trimmed components cannot be recovered.

Parameters:	n_components (int >= `1` or float > `0.0` or `None`, optional) – The number of components that are kept or else the amount (ratio) of variance that is kept. If `None`, self.n_active_components is used.

Notes

In case n_components is greater than the total number of components or greater than the amount of variance currently kept, this method does not perform any action.

variance()[source]¶

Returns the total amount of variance retained by the active components.

Returns:	variance (float) – Total variance captured by the active components.

variance_ratio()[source]¶

Returns the ratio between the amount of variance retained by the active components and the total amount of variance present on the original samples.

Returns:	variance_ratio (float) – Ratio of active components variance and total variance present in original samples.

whitened_components()[source]¶

Returns the active components of the model whitened.

Returns:	whitened_components (`(n_active_components, n_features)` ndarray) – The whitened components.

components¶

Returns the active components of the model.

Type:	`(n_active_components, n_features)` ndarray

eigenvalues¶

Returns the eigenvalues associated to the active components of the model, i.e. the amount of variance captured by each active component.

Type:	`(n_active_components,)` ndarray

n_active_components¶

The number of components currently in use on this model.

Type:	int

n_components¶

The number of bases of the model.

Type:	int

n_features¶

The number of elements in each linear component.

Type:	int

`menpo.shape`¶

Base Classes¶

Shape¶

class menpo.shape.base.Shape[source]¶

Bases: Vectorizable, Transformable, Landmarkable, LandmarkableViewable, Viewable

Abstract representation of shape. Shapes are Transformable, Vectorizable, Landmarkable, LandmarkableViewable and Viewable. This base class handles transforming landmarks when the shape is transformed. Therefore, implementations of Shape have to implement the abstract _transform_self_inplace() method that handles transforming the Shape itself.

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.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	object (`type(self)`) – An new instance of this class.

from_vector_inplace(vector)¶

Update the state of this object from a vector form.

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

has_landmarks¶

Whether the object has landmarks.

Type:	bool

landmarks¶

The landmarks object.

Type:	`LandmarkManager`

n_dims¶

The total number of dimensions.

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

PointCloud¶

class menpo.shape.PointCloud(points, copy=True)[source]¶

Bases: Shape

An N-dimensional point cloud. This is internally represented as an ndarray of shape (n_points, n_dims). This class is important for dealing with complex functionality such as viewing and representing metadata such as landmarks.

Currently only 2D and 3D pointclouds are viewable.

Parameters:

points ((n_points, n_dims) ndarray) – The array representing the points.
copy (bool, optional) – If False, the points 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.

_view_2d(figure_id=None, new_figure=False, image_view=True, render_markers=True, marker_style='o', marker_size=20, marker_face_colour='r', marker_edge_colour='k', marker_edge_width=1.0, render_axes=True, 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), label=None, **kwargs)[source]¶

Visualization of the PointCloud in 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.
image_view (bool, optional) – If True the PointCloud will be viewed as if it is in the image coordinate system.
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_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.
label (str, optional) – The name entry in case of a legend.

Returns: viewer (PointGraphViewer2d) – The viewer object.

_view_landmarks_2d(group=None, with_labels=None, without_labels=None, figure_id=None, new_figure=False, image_view=True, 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:

group (str or``None`` optional) – The landmark group to be visualized. If None and there are more than one landmark groups, an error is raised.
with_labels (None or str or list of str, optional) – If not None, only show the given label(s). Should not be used with the without_labels kwarg.
without_labels (None or str or list of str, optional) – If not None, show all except the given label(s). Should not be used with the with_labels kwarg.
figure_id (object, optional) – The id of the figure to be used.
new_figure (bool, optional) – If True, a new figure is created.
image_view (bool, optional) – If True the PointCloud will be viewed as if it is in the image coordinate system.
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 both with_labels and without_labels are passed.
ValueError – If the landmark manager doesn’t contain the provided group label.

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.

bounding_box()[source]¶

Return the bounding box of this PointCloud as a directed graph. The the first point (0) will be nearest the origin for an axis aligned Pointcloud. In the case of an image, this ordering would appear as:

0<--3
|   ^
|   |
v   |
1-->2

Returns:	bounding_box (`PointDirectedGraph`) – The axis aligned bounding box of the PointCloud.

bounds(boundary=0)[source]¶

The minimum to maximum extent of the PointCloud. An optional boundary argument can be provided to expand the bounds by a constant margin.

Parameters:	boundary (float) – A optional padding distance that is added to the bounds. Default is `0`, meaning the max/min of tightest possible containing square/cube/hypercube is returned.
Returns:	min_b (`(n_dims,)` ndarray) – The minimum extent of the `PointCloud` and boundary along each dimension max_b (`(n_dims,)` ndarray) – The maximum extent of the `PointCloud` and boundary along each dimension

centre()[source]¶

The mean of all the points in this PointCloud (centre of mass).

Returns:	centre (`(n_dims)` ndarray) – The mean of this PointCloud’s points.

centre_of_bounds()[source]¶

The centre of the absolute bounds of this PointCloud. Contrast with centre(), which is the mean point position.

Returns:	centre (`n_dims` ndarray) – The centre of the bounds of this PointCloud.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

distance_to(pointcloud, **kwargs)[source]¶

Returns a distance matrix between this PointCloud and another. By default the Euclidean distance is calculated - see scipy.spatial.distance.cdist for valid kwargs to change the metric and other properties.

Parameters:	pointcloud (`PointCloud`) – The second pointcloud to compute distances between. This must be of the same dimension as this PointCloud.
Returns:	distance_matrix (`(n_points, n_points)` ndarray) – The symmetric pairwise distance matrix between the two PointClouds s.t. `distance_matrix[i, j]` is the distance between the i’th point of this PointCloud and the j’th point of the input PointCloud.

from_mask(mask)[source]¶

A 1D boolean array with the same number of elements as the number of points in the PointCloud. This is then broadcast across the dimensions of the PointCloud and returns a new PointCloud containing only those points that were True in the mask.

Parameters:	mask (`(n_points,)` ndarray) – 1D array of booleans
Returns:	pointcloud (`PointCloud`) – A new pointcloud that has been masked.
Raises:	`ValueError` – Mask must have same number of points as pointcloud.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	object (`type(self)`) – An new instance of this class.

from_vector_inplace(vector)[source]¶

Updates the points of this PointCloud in-place with the reshaped points from the provided vector. Note that the vector should have the form [x0, y0, x1, y1, ....., xn, yn] for 2D.

Parameters:	vector (`(n_points,)` ndarray) – The vector from which to create the points’ array.

h_points()[source]¶

Convert poincloud to a homogeneous array: (n_dims + 1, n_points)

Type:	`type(self)`

norm(**kwargs)[source]¶

Returns the norm of this PointCloud. This is a translation and rotation invariant measure of the point cloud’s intrinsic size - in other words, it is always taken around the point cloud’s centre.

By default, the Frobenius norm is taken, but this can be changed by setting kwargs - see numpy.linalg.norm for valid options.

Returns:	norm (float) – The norm of this `PointCloud`

range(boundary=0)[source]¶

The range of the extent of the PointCloud.

Parameters:	boundary (float) – A optional padding distance that is used to extend the bounds from which the range is computed. Default is `0`, no extension is performed.
Returns:	range (`(n_dims,)` ndarray) – The range of the `PointCloud` extent in each dimension.

tojson()[source]¶

Convert this PointCloud to a dictionary representation suitable for inclusion in the LJSON landmark format.

Returns:	json (dict) – Dictionary with `points` keys.

view_widget(popup=False, browser_style='buttons', figure_size=(10, 8))[source]¶

Visualization of the PointCloud using the visualize_pointclouds widget.

Parameters:	popup (bool, optional) – If `True`, the widget will be rendered in a popup window. browser_style (`{buttons, slider}`, optional) – It defines whether the selector of the PointCloud objects will have the form of plus/minus buttons or a slider. figure_size ((int, int), optional) – The initial size of the rendered figure.

has_landmarks¶

Whether the object has landmarks.

Type:	bool

landmarks¶

The landmarks object.

Type:	`LandmarkManager`

n_dims¶

The number of dimensions in the pointcloud.

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_points¶

The number of points in the pointcloud.

Type:	int

Graphs & PointGraphs¶

UndirectedGraph¶

class menpo.shape.UndirectedGraph(adjacency_array, copy=True)[source]¶

Bases: Graph

Class for Undirected Graph definition and manipulation.

Parameters:

adjacency_array ((n_edges, 2, ) ndarray) –

The Adjacency Array of the graph, i.e. an array containing the sets of the graph’s edges. The numbering of vertices is assumed to start from 0. For example:

|---0---|        adjacency_array = ndarray([[0, 1],
|       |                                   [0, 2],
|       |                                   [1, 2],
1-------2                                   [1, 3],
|       |                                   [2, 4],
|       |                                   [3, 4],
3-------4                                   [3, 5]])
|
5

copy (bool, optional) – If False, the adjacency_list will not be copied on assignment.

Raises:

ValueError – You must provide at least one edge.
ValueError – Adjacency list must contain the sets of connected edges and thus must have shape (n_edges, 2).
ValueError – The vertices must be numbered starting from 0.

find_all_paths(start, end, path=[])¶

Returns a list of lists with all the paths (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end. path (list, optional) – An existing path to append to.
Returns:	paths (list of list) – The list containing all the paths from start to end.

find_path(start, end, path=None)¶

Returns a list with the first path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The path’s vertices.

find_shortest_path(start, end, path=None)¶

Returns a list with the shortest path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The shortest path’s vertices.

get_adjacency_matrix()[source]¶

Returns the adjacency matrix of the graph, i.e. the boolean ndarray that is True and False if there is an edge connecting the two vertices or not respectively.

Type:	`(n_vertices, n_vertices, )` ndarray

has_cycles()[source]¶

Whether the graph has at least on cycle.

Returns:	has_cycles (bool) – True if it has at least one cycle.

is_edge(vertex_1, vertex_2)[source]¶

Returns whether there is an edge between the provided vertices.

Parameters:	vertex_1 (int) – The first selected vertex. vertex_2 (int) – The second selected vertex.
Returns:	is_edge (bool) – True if there is an edge.
Raises:	`ValueError` – The vertex must be between 0 and {n_vertices-1}.

is_tree()¶

Checks if the graph is tree.

Returns:	is_true (bool) – If the graph is a tree.

minimum_spanning_tree(weights, root_vertex)[source]¶

Returns the minimum spanning tree given weights to the graph’s edges using Kruskal’s algorithm.

Parameters:	weights (`(n_vertices, n_vertices, )` ndarray) – A matrix of the same size as the adjacency matrix that attaches a weight to each edge of the undirected graph. root_vertex (int) – The vertex that will be set as root in the output MST.
Returns:	mst (`Tree`) – The computed minimum spanning tree.
Raises:	`ValueError` – Provided graph is not an UndirectedGraph. `ValueError` – Asymmetric weights provided.

n_neighbours(vertex)[source]¶

Returns the number of neighbours of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	n_neighbours (int) – The number of neighbours.
Raises:	`ValueError` – The vertex must be between 0 and {n_vertices-1}.

n_paths(start, end)¶

Returns the number of all the paths (without cycles) existing from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end.
Returns:	paths (int) – The paths’ numbers.

neighbours(vertex)[source]¶

Returns the neighbours of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	neighbours (list) – The list of neighbours.
Raises:	`ValueError` – The vertex must be between 0 and {n_vertices-1}.

n_edges¶

Returns the number of the graph edges.

Type:	int

n_vertices¶

Returns the number of the graph vertices.

Type:	int

DirectedGraph¶

class menpo.shape.DirectedGraph(adjacency_array, copy=True)[source]¶

Bases: Graph

Class for Directed Graph definition and manipulation.

Parameters:

adjacency_array ((n_edges, 2, ) ndarray) –

The Adjacency Array of the graph, i.e. an array containing the sets of the graph’s edges. The numbering of vertices is assumed to start from 0.

We assume that the vertices in the first column of the adjacency_array are the parents and the vertices in the second column of the adjacency_array are the children, for example:

|-->0<--|        adjacency_array = ndarray([[1, 0],
|       |                                   [2, 0],
|       |                                   [1, 2],
1<----->2                                   [2, 1],
|       |                                   [1, 3],
v       v                                   [2, 4],
3------>4                                   [3, 4],
|                                           [3, 5]])
v
5

copy (bool, optional) – If False, the adjacency_list will not be copied on assignment.

Raises:

ValueError – You must provide at least one edge.
ValueError – Adjacency list must contain the sets of connected edges and thus must have shape (n_edges, 2).
ValueError – The vertices must be numbered starting from 0.

children(vertex)[source]¶

Returns the children of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	children (list) – The list of children.
Raises:	`ValueError` – The vertex must be between 0 and {n_vertices-1}.

find_all_paths(start, end, path=[])¶

Returns a list of lists with all the paths (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end. path (list, optional) – An existing path to append to.
Returns:	paths (list of list) – The list containing all the paths from start to end.

find_path(start, end, path=None)¶

Returns a list with the first path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The path’s vertices.

find_shortest_path(start, end, path=None)¶

Returns a list with the shortest path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The shortest path’s vertices.

get_adjacency_matrix()[source]¶

Returns the Adjacency Matrix of the graph, i.e. the boolean ndarray that is True and False if there is an edge connecting the two vertices or not respectively.

Type:	`(n_vertices, n_vertices, )` ndarray

has_cycles()[source]¶

Whether the graph has at least on cycle.

Returns:	has_cycles (bool) – `True` if it has at least one cycle.

is_edge(parent, child)[source]¶

Returns whether there is an edge between the provided vertices.

Parameters:	parent (int) – The first selected vertex which is considered as the parent. child (int) – The second selected vertex which is considered as the child.
Returns:	is_edge (bool) – True if there is an edge.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

is_tree()¶

Checks if the graph is tree.

Returns:	is_true (bool) – If the graph is a tree.

n_children(vertex)[source]¶

Returns the number of children of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	n_children (int) – The number of children.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

n_parent(vertex)[source]¶

Returns the number of parents of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	n_parent (int) – The number of parents.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

n_paths(start, end)¶

Returns the number of all the paths (without cycles) existing from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end.
Returns:	paths (int) – The paths’ numbers.

parent(vertex)[source]¶

Returns the parents of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	parent (list) – The list of parents.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

n_edges¶

Returns the number of the graph edges.

Type:	int

n_vertices¶

Returns the number of the graph vertices.

Type:	int

PointGraph¶

class menpo.shape.PointGraph(points, adjacency_array, copy=True)[source]¶

Bases: Graph, PointCloud

Class for defining a graph with geometry.

Parameters:

points (ndarray) – The array of point locations.

adjacency_array ((n_edges, 2, ) ndarray) –

The adjacency array of the graph, i.e. an array containing the sets of the graph’s edges. The numbering of vertices is assumed to start from 0.

For an undirected graph, the order of an edge’s vertices doesn’t matter, for example

|---0---|        adjacency_array = ndarray([[0, 1],
|       |                                   [0, 2],
|       |                                   [1, 2],
1-------2                                   [1, 3],
|       |                                   [2, 4],
|       |                                   [3, 4],
3-------4                                   [3, 5]])
|
5

For a directed graph, we assume that the vertices in the first column of the adjacency_array are the fathers and the vertices in the second column of the adjacency_array are the children, for example

|-->0<--|        adjacency_array = ndarray([[1, 0],
|       |                                   [2, 0],
|       |                                   [1, 2],
1<----->2                                   [2, 1],
|       |                                   [1, 3],
v       v                                   [2, 4],
3------>4                                   [3, 4],
|                                           [3, 5]])
v
5

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.

bounding_box()¶

Return the bounding box of this PointCloud as a directed graph. The the first point (0) will be nearest the origin for an axis aligned Pointcloud. In the case of an image, this ordering would appear as:

0<--3
|   ^
|   |
v   |
1-->2

Returns:	bounding_box (`PointDirectedGraph`) – The axis aligned bounding box of the PointCloud.

bounds(boundary=0)¶

The minimum to maximum extent of the PointCloud. An optional boundary argument can be provided to expand the bounds by a constant margin.

Parameters:	boundary (float) – A optional padding distance that is added to the bounds. Default is `0`, meaning the max/min of tightest possible containing square/cube/hypercube is returned.
Returns:	min_b (`(n_dims,)` ndarray) – The minimum extent of the `PointCloud` and boundary along each dimension max_b (`(n_dims,)` ndarray) – The maximum extent of the `PointCloud` and boundary along each dimension

centre()¶

The mean of all the points in this PointCloud (centre of mass).

Returns:	centre (`(n_dims)` ndarray) – The mean of this PointCloud’s points.

centre_of_bounds()¶

The centre of the absolute bounds of this PointCloud. Contrast with centre(), which is the mean point position.

Returns:	centre (`n_dims` ndarray) – The centre of the bounds of this PointCloud.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

distance_to(pointcloud, **kwargs)¶

Returns a distance matrix between this PointCloud and another. By default the Euclidean distance is calculated - see scipy.spatial.distance.cdist for valid kwargs to change the metric and other properties.

Parameters:	pointcloud (`PointCloud`) – The second pointcloud to compute distances between. This must be of the same dimension as this PointCloud.
Returns:	distance_matrix (`(n_points, n_points)` ndarray) – The symmetric pairwise distance matrix between the two PointClouds s.t. `distance_matrix[i, j]` is the distance between the i’th point of this PointCloud and the j’th point of the input PointCloud.

find_all_paths(start, end, path=[])¶

Returns a list of lists with all the paths (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end. path (list, optional) – An existing path to append to.
Returns:	paths (list of list) – The list containing all the paths from start to end.

find_path(start, end, path=None)¶

Returns a list with the first path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The path’s vertices.

find_shortest_path(start, end, path=None)¶

Returns a list with the shortest path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The shortest path’s vertices.

from_mask(mask)¶

A 1D boolean array with the same number of elements as the number of points in the PointCloud. This is then broadcast across the dimensions of the PointCloud and returns a new PointCloud containing only those points that were True in the mask.

Parameters:	mask (`(n_points,)` ndarray) – 1D array of booleans
Returns:	pointcloud (`PointCloud`) – A new pointcloud that has been masked.
Raises:	`ValueError` – Mask must have same number of points as pointcloud.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	object (`type(self)`) – An new instance of this class.

from_vector_inplace(vector)¶

Updates the points of this PointCloud in-place with the reshaped points from the provided vector. Note that the vector should have the form [x0, y0, x1, y1, ....., xn, yn] for 2D.

Parameters:	vector (`(n_points,)` ndarray) – The vector from which to create the points’ array.

get_adjacency_matrix()¶

Returns the adjacency matrix of the graph, i.e. the boolean ndarray that is True and False if there is an edge connecting the two vertices or not respectively.

Type:	`(n_vertices, n_vertices, )` ndarray

h_points()¶

Convert poincloud to a homogeneous array: (n_dims + 1, n_points)

Type:	`type(self)`

has_cycles()¶

Checks if the graph has at least one cycle.

Returns:	has_cycles (bool) – If the graph has cycles.

is_tree()¶

Checks if the graph is tree.

Returns:	is_true (bool) – If the graph is a tree.

n_paths(start, end)¶

Returns the number of all the paths (without cycles) existing from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end.
Returns:	paths (int) – The paths’ numbers.

norm(**kwargs)¶

Returns the norm of this PointCloud. This is a translation and rotation invariant measure of the point cloud’s intrinsic size - in other words, it is always taken around the point cloud’s centre.

By default, the Frobenius norm is taken, but this can be changed by setting kwargs - see numpy.linalg.norm for valid options.

Returns:	norm (float) – The norm of this `PointCloud`

range(boundary=0)¶

The range of the extent of the PointCloud.

Parameters:	boundary (float) – A optional padding distance that is used to extend the bounds from which the range is computed. Default is `0`, no extension is performed.
Returns:	range (`(n_dims,)` ndarray) – The range of the `PointCloud` extent in each dimension.

tojson()[source]¶

Convert this PointGraph to a dictionary representation suitable for inclusion in the LJSON landmark format.

Returns:	json (dict) – Dictionary with `points` and `connectivity` keys.

view_widget(popup=False, browser_style='buttons', figure_size=(10, 8))[source]¶

Visualization of the PointGraph using the visualize_pointclouds widget.

Parameters:	popup (bool, optional) – If `True`, the widget will be rendered in a popup window. browser_style (`{buttons, slider}`, optional) – It defines whether the selector of the PointGraph objects will have the form of plus/minus buttons or a slider. figure_size ((int, int) tuple, optional) – The initial size of the rendered figure.

has_landmarks¶

Whether the object has landmarks.

Type:	bool

landmarks¶

The landmarks object.

Type:	`LandmarkManager`

n_dims¶

The number of dimensions in the pointcloud.

Type:	int

n_edges¶

Returns the number of the graph edges.

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_points¶

The number of points in the pointcloud.

Type:	int

n_vertices¶

Returns the number of the graph vertices.

Type:	int

PointUndirectedGraph¶

class menpo.shape.PointUndirectedGraph(points, adjacency_array, copy=True)[source]¶

Bases: PointGraph, UndirectedGraph

Class for defining an Undirected Graph with geometry.

Parameters:

points (ndarray) – The array of point locations.

adjacency_array ((n_edges, 2, ) ndarray) –

The adjacency array of the graph, i.e. an array containing the sets of the graph’s edges. The numbering of vertices is assumed to start from 0. For example

|---0---|        adjacency_array = ndarray([[0, 1],
|       |                                   [0, 2],
|       |                                   [1, 2],
1-------2                                   [1, 3],
|       |                                   [2, 4],
|       |                                   [3, 4],
3-------4                                   [3, 5]])
|
5

copy (bool, optional) – If False, the adjacency_list will not be copied on assignment.

Raises:

ValueError – A point for each graph vertex needs to be passed. Got n_points points instead of n_vertices.

_view_2d(figure_id=None, new_figure=False, image_view=True, render_lines=True, line_colour='r', line_style='-', line_width=1.0, render_markers=True, marker_style='o', marker_size=20, marker_face_colour='k', marker_edge_colour='k', marker_edge_width=1.0, render_axes=True, 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), label=None)¶

Visualization of the pointgraph in 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.
image_view (bool, optional) – If True the PointGraph will be viewed as if it is in the image coordinate system.
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_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.
label (str, optional) – The name entry in case of a legend.

Returns: viewer (PointGraphViewer2d) – The viewer object.

_view_landmarks_2d(group=None, with_labels=None, without_labels=None, figure_id=None, new_figure=False, image_view=True, 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))¶

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

Parameters:

group (str or``None`` optional) – The landmark group to be visualized. If None and there are more than one landmark groups, an error is raised.
with_labels (None or str or list of str, optional) – If not None, only show the given label(s). Should not be used with the without_labels kwarg.
without_labels (None or str or list of str, optional) – If not None, show all except the given label(s). Should not be used with the with_labels kwarg.
figure_id (object, optional) – The id of the figure to be used.
new_figure (bool, optional) – If True, a new figure is created.
image_view (bool, optional) – If True the PointCloud will be viewed as if it is in the image coordinate system.
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 both with_labels and without_labels are passed.
ValueError – If the landmark manager doesn’t contain the provided group label.

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.

bounding_box()¶

Return the bounding box of this PointCloud as a directed graph. The the first point (0) will be nearest the origin for an axis aligned Pointcloud. In the case of an image, this ordering would appear as:

0<--3
|   ^
|   |
v   |
1-->2

Returns:	bounding_box (`PointDirectedGraph`) – The axis aligned bounding box of the PointCloud.

bounds(boundary=0)¶

The minimum to maximum extent of the PointCloud. An optional boundary argument can be provided to expand the bounds by a constant margin.

Parameters:	boundary (float) – A optional padding distance that is added to the bounds. Default is `0`, meaning the max/min of tightest possible containing square/cube/hypercube is returned.
Returns:	min_b (`(n_dims,)` ndarray) – The minimum extent of the `PointCloud` and boundary along each dimension max_b (`(n_dims,)` ndarray) – The maximum extent of the `PointCloud` and boundary along each dimension

centre()¶

The mean of all the points in this PointCloud (centre of mass).

Returns:	centre (`(n_dims)` ndarray) – The mean of this PointCloud’s points.

centre_of_bounds()¶

The centre of the absolute bounds of this PointCloud. Contrast with centre(), which is the mean point position.

Returns:	centre (`n_dims` ndarray) – The centre of the bounds of this PointCloud.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

distance_to(pointcloud, **kwargs)¶

Returns a distance matrix between this PointCloud and another. By default the Euclidean distance is calculated - see scipy.spatial.distance.cdist for valid kwargs to change the metric and other properties.

Parameters:	pointcloud (`PointCloud`) – The second pointcloud to compute distances between. This must be of the same dimension as this PointCloud.
Returns:	distance_matrix (`(n_points, n_points)` ndarray) – The symmetric pairwise distance matrix between the two PointClouds s.t. `distance_matrix[i, j]` is the distance between the i’th point of this PointCloud and the j’th point of the input PointCloud.

find_all_paths(start, end, path=[])¶

Returns a list of lists with all the paths (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end. path (list, optional) – An existing path to append to.
Returns:	paths (list of list) – The list containing all the paths from start to end.

find_path(start, end, path=None)¶

Returns a list with the first path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The path’s vertices.

find_shortest_path(start, end, path=None)¶

Returns a list with the shortest path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The shortest path’s vertices.

from_mask(mask)[source]¶

A 1D boolean array with the same number of elements as the number of points in the PointUndirectedGraph. This is then broadcast across the dimensions of the PointUndirectedGraph and returns a new PointUndirectedGraph containing only those points that were True in the mask.

Parameters:	mask (`(n_points,)` ndarray) – 1D array of booleans
Returns:	pointgraph (`PointUndirectedGraph`) – A new pointgraph that has been masked.
Raises:	`ValueError` – Mask must have same number of points as pointgraph.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	object (`type(self)`) – An new instance of this class.

from_vector_inplace(vector)¶

Updates the points of this PointCloud in-place with the reshaped points from the provided vector. Note that the vector should have the form [x0, y0, x1, y1, ....., xn, yn] for 2D.

Parameters:	vector (`(n_points,)` ndarray) – The vector from which to create the points’ array.

get_adjacency_matrix()¶

Returns the adjacency matrix of the graph, i.e. the boolean ndarray that is True and False if there is an edge connecting the two vertices or not respectively.

Type:	`(n_vertices, n_vertices, )` ndarray

h_points()¶

Convert poincloud to a homogeneous array: (n_dims + 1, n_points)

Type:	`type(self)`

has_cycles()¶

Whether the graph has at least on cycle.

Returns:	has_cycles (bool) – True if it has at least one cycle.

is_edge(vertex_1, vertex_2)¶

Returns whether there is an edge between the provided vertices.

Parameters:	vertex_1 (int) – The first selected vertex. vertex_2 (int) – The second selected vertex.
Returns:	is_edge (bool) – True if there is an edge.
Raises:	`ValueError` – The vertex must be between 0 and {n_vertices-1}.

is_tree()¶

Checks if the graph is tree.

Returns:	is_true (bool) – If the graph is a tree.

minimum_spanning_tree(weights, root_vertex)¶

Returns the minimum spanning tree given weights to the graph’s edges using Kruskal’s algorithm.

Parameters:	weights (`(n_vertices, n_vertices, )` ndarray) – A matrix of the same size as the adjacency matrix that attaches a weight to each edge of the undirected graph. root_vertex (int) – The vertex that will be set as root in the output MST.
Returns:	mst (`Tree`) – The computed minimum spanning tree.
Raises:	`ValueError` – Provided graph is not an UndirectedGraph. `ValueError` – Asymmetric weights provided.

n_neighbours(vertex)¶

Returns the number of neighbours of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	n_neighbours (int) – The number of neighbours.
Raises:	`ValueError` – The vertex must be between 0 and {n_vertices-1}.

n_paths(start, end)¶

Returns the number of all the paths (without cycles) existing from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end.
Returns:	paths (int) – The paths’ numbers.

neighbours(vertex)¶

Returns the neighbours of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	neighbours (list) – The list of neighbours.
Raises:	`ValueError` – The vertex must be between 0 and {n_vertices-1}.

norm(**kwargs)¶

Returns the norm of this PointCloud. This is a translation and rotation invariant measure of the point cloud’s intrinsic size - in other words, it is always taken around the point cloud’s centre.

By default, the Frobenius norm is taken, but this can be changed by setting kwargs - see numpy.linalg.norm for valid options.

Returns:	norm (float) – The norm of this `PointCloud`

range(boundary=0)¶

The range of the extent of the PointCloud.

Parameters:	boundary (float) – A optional padding distance that is used to extend the bounds from which the range is computed. Default is `0`, no extension is performed.
Returns:	range (`(n_dims,)` ndarray) – The range of the `PointCloud` extent in each dimension.

tojson()¶

Convert this PointGraph to a dictionary representation suitable for inclusion in the LJSON landmark format.

Returns:	json (dict) – Dictionary with `points` and `connectivity` keys.

view_widget(popup=False, browser_style='buttons', figure_size=(10, 8))¶

Visualization of the PointGraph using the visualize_pointclouds widget.

Parameters:	popup (bool, optional) – If `True`, the widget will be rendered in a popup window. browser_style (`{buttons, slider}`, optional) – It defines whether the selector of the PointGraph objects will have the form of plus/minus buttons or a slider. figure_size ((int, int) tuple, optional) – The initial size of the rendered figure.

has_landmarks¶

Whether the object has landmarks.

Type:	bool

landmarks¶

The landmarks object.

Type:	`LandmarkManager`

n_dims¶

The number of dimensions in the pointcloud.

Type:	int

n_edges¶

Returns the number of the graph edges.

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_points¶

The number of points in the pointcloud.

Type:	int

n_vertices¶

Returns the number of the graph vertices.

Type:	int

PointDirectedGraph¶

class menpo.shape.PointDirectedGraph(points, adjacency_array, copy=True)[source]¶

Bases: PointGraph, DirectedGraph

Class for defining a directed graph with geometry.

Parameters:

points ((n_points, n_dims) ndarray) – The array representing the points.

adjacency_array ((n_edges, 2, ) ndarray) –

The adjacency array of the graph, i.e. an array containing the sets of the graph’s edges. The numbering of vertices is assumed to start from 0. For example

|-->0<--|        adjacency_array = ndarray([[1, 0],
|       |                                   [2, 0],
|       |                                   [1, 2],
1<----->2                                   [2, 1],
|       |                                   [1, 3],
v       v                                   [2, 4],
3------>4                                   [3, 4],
|                                           [3, 5]])
v
5

copy (bool, optional) – If False, the adjacency_list will not be copied on assignment.

Raises:

ValueError – A point for each graph vertex needs to be passed. Got {n_points} points instead of {n_vertices}.

_view_2d(figure_id=None, new_figure=False, image_view=True, render_lines=True, line_colour='r', line_style='-', line_width=1.0, render_markers=True, marker_style='o', marker_size=20, marker_face_colour='k', marker_edge_colour='k', marker_edge_width=1.0, render_axes=True, 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), label=None)¶

Visualization of the pointgraph in 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.
image_view (bool, optional) – If True the PointGraph will be viewed as if it is in the image coordinate system.
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_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.
label (str, optional) – The name entry in case of a legend.

Returns: viewer (PointGraphViewer2d) – The viewer object.

_view_landmarks_2d(group=None, with_labels=None, without_labels=None, figure_id=None, new_figure=False, image_view=True, 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))¶

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

Parameters:

group (str or``None`` optional) – The landmark group to be visualized. If None and there are more than one landmark groups, an error is raised.
with_labels (None or str or list of str, optional) – If not None, only show the given label(s). Should not be used with the without_labels kwarg.
without_labels (None or str or list of str, optional) – If not None, show all except the given label(s). Should not be used with the with_labels kwarg.
figure_id (object, optional) – The id of the figure to be used.
new_figure (bool, optional) – If True, a new figure is created.
image_view (bool, optional) – If True the PointCloud will be viewed as if it is in the image coordinate system.
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 both with_labels and without_labels are passed.
ValueError – If the landmark manager doesn’t contain the provided group label.

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.

bounding_box()¶

Return the bounding box of this PointCloud as a directed graph. The the first point (0) will be nearest the origin for an axis aligned Pointcloud. In the case of an image, this ordering would appear as:

0<--3
|   ^
|   |
v   |
1-->2

Returns:	bounding_box (`PointDirectedGraph`) – The axis aligned bounding box of the PointCloud.

bounds(boundary=0)¶

The minimum to maximum extent of the PointCloud. An optional boundary argument can be provided to expand the bounds by a constant margin.

Parameters:	boundary (float) – A optional padding distance that is added to the bounds. Default is `0`, meaning the max/min of tightest possible containing square/cube/hypercube is returned.
Returns:	min_b (`(n_dims,)` ndarray) – The minimum extent of the `PointCloud` and boundary along each dimension max_b (`(n_dims,)` ndarray) – The maximum extent of the `PointCloud` and boundary along each dimension

centre()¶

The mean of all the points in this PointCloud (centre of mass).

Returns:	centre (`(n_dims)` ndarray) – The mean of this PointCloud’s points.

centre_of_bounds()¶

The centre of the absolute bounds of this PointCloud. Contrast with centre(), which is the mean point position.

Returns:	centre (`n_dims` ndarray) – The centre of the bounds of this PointCloud.

children(vertex)¶

Returns the children of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	children (list) – The list of children.
Raises:	`ValueError` – The vertex must be between 0 and {n_vertices-1}.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

distance_to(pointcloud, **kwargs)¶

Returns a distance matrix between this PointCloud and another. By default the Euclidean distance is calculated - see scipy.spatial.distance.cdist for valid kwargs to change the metric and other properties.

Parameters:	pointcloud (`PointCloud`) – The second pointcloud to compute distances between. This must be of the same dimension as this PointCloud.
Returns:	distance_matrix (`(n_points, n_points)` ndarray) – The symmetric pairwise distance matrix between the two PointClouds s.t. `distance_matrix[i, j]` is the distance between the i’th point of this PointCloud and the j’th point of the input PointCloud.

find_all_paths(start, end, path=[])¶

Returns a list of lists with all the paths (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end. path (list, optional) – An existing path to append to.
Returns:	paths (list of list) – The list containing all the paths from start to end.

find_path(start, end, path=None)¶

Returns a list with the first path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The path’s vertices.

find_shortest_path(start, end, path=None)¶

Returns a list with the shortest path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The shortest path’s vertices.

from_mask(mask)[source]¶

A 1D boolean array with the same number of elements as the number of points in the PointDirectedGraph. This is then broadcast across the dimensions of the PointDirectedGraph and returns a new PointDirectedGraph containing only those points that were True in the mask.

Parameters:	mask (`(n_points,)` ndarray) – 1D array of booleans
Returns:	pointgraph (`PointDirectedGraph`) – A new pointgraph that has been masked.
Raises:	`ValueError` – Mask must have same number of points as pointgraph.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	object (`type(self)`) – An new instance of this class.

from_vector_inplace(vector)¶

Updates the points of this PointCloud in-place with the reshaped points from the provided vector. Note that the vector should have the form [x0, y0, x1, y1, ....., xn, yn] for 2D.

Parameters:	vector (`(n_points,)` ndarray) – The vector from which to create the points’ array.

get_adjacency_matrix()¶

Returns the Adjacency Matrix of the graph, i.e. the boolean ndarray that is True and False if there is an edge connecting the two vertices or not respectively.

Type:	`(n_vertices, n_vertices, )` ndarray

h_points()¶

Convert poincloud to a homogeneous array: (n_dims + 1, n_points)

Type:	`type(self)`

has_cycles()¶

Whether the graph has at least on cycle.

Returns:	has_cycles (bool) – `True` if it has at least one cycle.

is_edge(parent, child)¶

Returns whether there is an edge between the provided vertices.

Parameters:	parent (int) – The first selected vertex which is considered as the parent. child (int) – The second selected vertex which is considered as the child.
Returns:	is_edge (bool) – True if there is an edge.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

is_tree()¶

Checks if the graph is tree.

Returns:	is_true (bool) – If the graph is a tree.

n_children(vertex)¶

Returns the number of children of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	n_children (int) – The number of children.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

n_parent(vertex)¶

Returns the number of parents of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	n_parent (int) – The number of parents.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

n_paths(start, end)¶

Returns the number of all the paths (without cycles) existing from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end.
Returns:	paths (int) – The paths’ numbers.

norm(**kwargs)¶

Returns the norm of this PointCloud. This is a translation and rotation invariant measure of the point cloud’s intrinsic size - in other words, it is always taken around the point cloud’s centre.

By default, the Frobenius norm is taken, but this can be changed by setting kwargs - see numpy.linalg.norm for valid options.

Returns:	norm (float) – The norm of this `PointCloud`

parent(vertex)¶

Returns the parents of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	parent (list) – The list of parents.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

range(boundary=0)¶

The range of the extent of the PointCloud.

Parameters:	boundary (float) – A optional padding distance that is used to extend the bounds from which the range is computed. Default is `0`, no extension is performed.
Returns:	range (`(n_dims,)` ndarray) – The range of the `PointCloud` extent in each dimension.

relative_location_edge(parent, child)[source]¶

Returns the relative location between the provided vertices. That is if vertex j is the parent and vertex i is its child and vector l denotes the coordinates of a vertex, then

l_i - l_j = [[x_i], [y_i]] - [[x_j], [y_j]] =
          = [[x_i - x_j], [y_i - y_j]]

Parameters:	parent (int) – The first selected vertex which is considered as the parent. child (int) – The second selected vertex which is considered as the child.
Returns:	relative_location (`(2,)` ndarray) – The relative location vector.
Raises:	`ValueError` – Vertices `parent` and `child` are not connected with an edge.

relative_locations()[source]¶

Returns the relative location between the vertices of each edge. If vertex j is the parent and vertex i is its child and vector l denotes the coordinates of a vertex, then:

l_i - l_j = [[x_i], [y_i]] - [[x_j], [y_j]] =
          = [[x_i - x_j], [y_i - y_j]]

Returns:	relative_locations (`(n_vertexes, 2)` ndarray) – The relative locations vector.

tojson()¶

Convert this PointGraph to a dictionary representation suitable for inclusion in the LJSON landmark format.

Returns:	json (dict) – Dictionary with `points` and `connectivity` keys.

view_widget(popup=False, browser_style='buttons', figure_size=(10, 8))¶

Visualization of the PointGraph using the visualize_pointclouds widget.

Parameters:	popup (bool, optional) – If `True`, the widget will be rendered in a popup window. browser_style (`{buttons, slider}`, optional) – It defines whether the selector of the PointGraph objects will have the form of plus/minus buttons or a slider. figure_size ((int, int) tuple, optional) – The initial size of the rendered figure.

has_landmarks¶

Whether the object has landmarks.

Type:	bool

landmarks¶

The landmarks object.

Type:	`LandmarkManager`

n_dims¶

The number of dimensions in the pointcloud.

Type:	int

n_edges¶

Returns the number of the graph edges.

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_points¶

The number of points in the pointcloud.

Type:	int

n_vertices¶

Returns the number of the graph vertices.

Type:	int

Trees & PointTrees¶

Tree¶

class menpo.shape.Tree(adjacency_array, root_vertex, copy=True)[source]¶

Bases: DirectedGraph

Class for Tree definitions and manipulation.

Parameters:

adjacency_array ((n_edges, 2, ) ndarray) –

The Adjacency Array of the tree, i.e. an array containing the sets of the tree’s edges. The numbering of vertices is assumed to start from 0.

We assume that the vertices in the first column of the adjacency_array are the parents and the vertices in the second column of the adjacency_array are the children, for example:

      0            adjacency_array = ndarray([[0, 1],
      |                                       [0, 2],
   ___|___                                    [1, 3],
  1       2                                   [1, 4],
  |       |                                   [2, 5],
 _|_      |                                   [3, 6],
3   4     5                                   [4, 7],
|   |     |                                   [5, 8]])
|   |     |
6   7     8

root_vertex (int) – The vertex that will be considered as root.
copy (bool, optional) – If False, the adjacency_list will not be copied on assignment.

Raises:

ValueError – The provided edges do not represent a tree.
ValueError – The root_vertex must be in the range [0, n_vertices - 1].

children(vertex)¶

Returns the children of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	children (list) – The list of children.
Raises:	`ValueError` – The vertex must be between 0 and {n_vertices-1}.

depth_of_vertex(vertex)[source]¶

Returns the depth of the specified vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	depth (int) – The depth of the selected vertex.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

find_all_paths(start, end, path=[])¶

Returns a list of lists with all the paths (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end. path (list, optional) – An existing path to append to.
Returns:	paths (list of list) – The list containing all the paths from start to end.

find_path(start, end, path=None)¶

Returns a list with the first path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The path’s vertices.

find_shortest_path(start, end, path=None)¶

Returns a list with the shortest path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The shortest path’s vertices.

get_adjacency_matrix()¶

Returns the Adjacency Matrix of the graph, i.e. the boolean ndarray that is True and False if there is an edge connecting the two vertices or not respectively.

Type:	`(n_vertices, n_vertices, )` ndarray

has_cycles()¶

Whether the graph has at least on cycle.

Returns:	has_cycles (bool) – `True` if it has at least one cycle.

is_edge(parent, child)¶

Returns whether there is an edge between the provided vertices.

Parameters:	parent (int) – The first selected vertex which is considered as the parent. child (int) – The second selected vertex which is considered as the child.
Returns:	is_edge (bool) – True if there is an edge.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

is_leaf(vertex)[source]¶

Returns whether the vertex is a leaf.

Parameters:	vertex (int) – The selected vertex.
Returns:	is_leaf (bool) – If True, then selected vertex is a leaf.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

is_tree()¶

Checks if the graph is tree.

Returns:	is_true (bool) – If the graph is a tree.

n_children(vertex)¶

Returns the number of children of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	n_children (int) – The number of children.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

n_parent(vertex)¶

Returns the number of parents of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	n_parent (int) – The number of parents.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

n_paths(start, end)¶

Returns the number of all the paths (without cycles) existing from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end.
Returns:	paths (int) – The paths’ numbers.

n_vertices_at_depth(depth)[source]¶

Returns the number of vertices at the specified depth.

Parameters:	depth (int) – The selected depth.
Returns:	n_vertices (int) – The number of vertices that lie in the specified depth.

parent(vertex)[source]¶

Returns the parent of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	parent (int) – The parent vertex.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

vertices_at_depth(depth)[source]¶

Returns a list of vertices at the specified depth.

Parameters:	depth (int) – The selected depth.
Returns:	vertices (list) – The vertices that lie in the specified depth.

leaves¶

Returns a list with the all leaves of the tree.

Type:	list

maximum_depth¶

Returns the maximum depth of the tree.

Type:	int

n_edges¶

Returns the number of the graph edges.

Type:	int

n_leaves¶

Returns the number of leaves of the tree.

Type:	int

n_vertices¶

Returns the number of the graph vertices.

Type:	int

PointTree¶

class menpo.shape.PointTree(points, adjacency_array, root_vertex, copy=True)[source]¶

Bases: PointDirectedGraph, Tree

Class for defining a Tree with geometry.

Parameters:

points ((n_points, n_dims) ndarray) – The array representing the points.

adjacency_array ((n_edges, 2, ) ndarray) –

The Adjacency Array of the tree, i.e. an array containing the sets of the tree’s edges. The numbering of vertices is assumed to start from 0.

We assume that the vertices in the first column of the adjacency_array are the fathers and the vertices in the second column of the adjacency_array are the children, for example:

      0            adjacency_array = ndarray([[0, 1],
      |                                       [0, 2],
   ___|___                                    [1, 3],
  1       2                                   [1, 4],
  |       |                                   [2, 5],
 _|_      |                                   [3, 6],
3   4     5                                   [4, 7],
|   |     |                                   [5, 8]])
|   |     |
6   7     8

root_vertex (int) – The root vertex of the tree.
copy (bool, optional) – If False, the adjacency_list will not be copied on assignment.

_view_2d(figure_id=None, new_figure=False, image_view=True, render_lines=True, line_colour='r', line_style='-', line_width=1.0, render_markers=True, marker_style='o', marker_size=20, marker_face_colour='k', marker_edge_colour='k', marker_edge_width=1.0, render_axes=True, 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), label=None)¶

Visualization of the pointgraph in 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.
image_view (bool, optional) – If True the PointGraph will be viewed as if it is in the image coordinate system.
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_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.
label (str, optional) – The name entry in case of a legend.

Returns: viewer (PointGraphViewer2d) – The viewer object.

_view_landmarks_2d(group=None, with_labels=None, without_labels=None, figure_id=None, new_figure=False, image_view=True, 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))¶

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

Parameters:

group (str or``None`` optional) – The landmark group to be visualized. If None and there are more than one landmark groups, an error is raised.
with_labels (None or str or list of str, optional) – If not None, only show the given label(s). Should not be used with the without_labels kwarg.
without_labels (None or str or list of str, optional) – If not None, show all except the given label(s). Should not be used with the with_labels kwarg.
figure_id (object, optional) – The id of the figure to be used.
new_figure (bool, optional) – If True, a new figure is created.
image_view (bool, optional) – If True the PointCloud will be viewed as if it is in the image coordinate system.
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 both with_labels and without_labels are passed.
ValueError – If the landmark manager doesn’t contain the provided group label.

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.

bounding_box()¶

Return the bounding box of this PointCloud as a directed graph. The the first point (0) will be nearest the origin for an axis aligned Pointcloud. In the case of an image, this ordering would appear as:

0<--3
|   ^
|   |
v   |
1-->2

Returns:	bounding_box (`PointDirectedGraph`) – The axis aligned bounding box of the PointCloud.

bounds(boundary=0)¶

The minimum to maximum extent of the PointCloud. An optional boundary argument can be provided to expand the bounds by a constant margin.

Parameters:	boundary (float) – A optional padding distance that is added to the bounds. Default is `0`, meaning the max/min of tightest possible containing square/cube/hypercube is returned.
Returns:	min_b (`(n_dims,)` ndarray) – The minimum extent of the `PointCloud` and boundary along each dimension max_b (`(n_dims,)` ndarray) – The maximum extent of the `PointCloud` and boundary along each dimension

centre()¶

The mean of all the points in this PointCloud (centre of mass).

Returns:	centre (`(n_dims)` ndarray) – The mean of this PointCloud’s points.

centre_of_bounds()¶

The centre of the absolute bounds of this PointCloud. Contrast with centre(), which is the mean point position.

Returns:	centre (`n_dims` ndarray) – The centre of the bounds of this PointCloud.

children(vertex)¶

Returns the children of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	children (list) – The list of children.
Raises:	`ValueError` – The vertex must be between 0 and {n_vertices-1}.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

depth_of_vertex(vertex)¶

Returns the depth of the specified vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	depth (int) – The depth of the selected vertex.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

distance_to(pointcloud, **kwargs)¶

Returns a distance matrix between this PointCloud and another. By default the Euclidean distance is calculated - see scipy.spatial.distance.cdist for valid kwargs to change the metric and other properties.

Parameters:	pointcloud (`PointCloud`) – The second pointcloud to compute distances between. This must be of the same dimension as this PointCloud.
Returns:	distance_matrix (`(n_points, n_points)` ndarray) – The symmetric pairwise distance matrix between the two PointClouds s.t. `distance_matrix[i, j]` is the distance between the i’th point of this PointCloud and the j’th point of the input PointCloud.

find_all_paths(start, end, path=[])¶

Returns a list of lists with all the paths (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end. path (list, optional) – An existing path to append to.
Returns:	paths (list of list) – The list containing all the paths from start to end.

find_path(start, end, path=None)¶

Returns a list with the first path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The path’s vertices.

find_shortest_path(start, end, path=None)¶

Returns a list with the shortest path (without cycles) found from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the path starts. end (int) – The vertex from which the path ends. path (list, optional) – An existing path to append to.
Returns:	path (list) – The shortest path’s vertices.

from_mask(mask)[source]¶

A 1D boolean array with the same number of elements as the number of points in the PointTree. This is then broadcast across the dimensions of the PointTree and returns a new PointTree containing only those points that were True in the mask.

Parameters:	mask (`(n_points,)` ndarray) – 1D array of booleans
Returns:	pointtree (`PointTree`) – A new pointtree that has been masked.
Raises:	`ValueError` – Mask must have same number of points as pointtree.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	object (`type(self)`) – An new instance of this class.

from_vector_inplace(vector)¶

Updates the points of this PointCloud in-place with the reshaped points from the provided vector. Note that the vector should have the form [x0, y0, x1, y1, ....., xn, yn] for 2D.

Parameters:	vector (`(n_points,)` ndarray) – The vector from which to create the points’ array.

get_adjacency_matrix()¶

Returns the Adjacency Matrix of the graph, i.e. the boolean ndarray that is True and False if there is an edge connecting the two vertices or not respectively.

Type:	`(n_vertices, n_vertices, )` ndarray

h_points()¶

Convert poincloud to a homogeneous array: (n_dims + 1, n_points)

Type:	`type(self)`

has_cycles()¶

Whether the graph has at least on cycle.

Returns:	has_cycles (bool) – `True` if it has at least one cycle.

is_edge(parent, child)¶

Returns whether there is an edge between the provided vertices.

Parameters:	parent (int) – The first selected vertex which is considered as the parent. child (int) – The second selected vertex which is considered as the child.
Returns:	is_edge (bool) – True if there is an edge.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

is_leaf(vertex)¶

Returns whether the vertex is a leaf.

Parameters:	vertex (int) – The selected vertex.
Returns:	is_leaf (bool) – If True, then selected vertex is a leaf.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

is_tree()¶

Checks if the graph is tree.

Returns:	is_true (bool) – If the graph is a tree.

n_children(vertex)¶

Returns the number of children of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	n_children (int) – The number of children.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

n_parent(vertex)¶

Returns the number of parents of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	n_parent (int) – The number of parents.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

n_paths(start, end)¶

Returns the number of all the paths (without cycles) existing from start vertex to end vertex.

Parameters:	start (int) – The vertex from which the paths start. end (int) – The vertex from which the paths end.
Returns:	paths (int) – The paths’ numbers.

n_vertices_at_depth(depth)¶

Returns the number of vertices at the specified depth.

Parameters:	depth (int) – The selected depth.
Returns:	n_vertices (int) – The number of vertices that lie in the specified depth.

norm(**kwargs)¶

Returns the norm of this PointCloud. This is a translation and rotation invariant measure of the point cloud’s intrinsic size - in other words, it is always taken around the point cloud’s centre.

By default, the Frobenius norm is taken, but this can be changed by setting kwargs - see numpy.linalg.norm for valid options.

Returns:	norm (float) – The norm of this `PointCloud`

parent(vertex)¶

Returns the parent of the selected vertex.

Parameters:	vertex (int) – The selected vertex.
Returns:	parent (int) – The parent vertex.
Raises:	`ValueError` – The vertex must be in the range `[0, n_vertices - 1]`.

range(boundary=0)¶

The range of the extent of the PointCloud.

Parameters:	boundary (float) – A optional padding distance that is used to extend the bounds from which the range is computed. Default is `0`, no extension is performed.
Returns:	range (`(n_dims,)` ndarray) – The range of the `PointCloud` extent in each dimension.

relative_location_edge(parent, child)¶

Returns the relative location between the provided vertices. That is if vertex j is the parent and vertex i is its child and vector l denotes the coordinates of a vertex, then

l_i - l_j = [[x_i], [y_i]] - [[x_j], [y_j]] =
          = [[x_i - x_j], [y_i - y_j]]

Parameters:	parent (int) – The first selected vertex which is considered as the parent. child (int) – The second selected vertex which is considered as the child.
Returns:	relative_location (`(2,)` ndarray) – The relative location vector.
Raises:	`ValueError` – Vertices `parent` and `child` are not connected with an edge.

relative_locations()¶

Returns the relative location between the vertices of each edge. If vertex j is the parent and vertex i is its child and vector l denotes the coordinates of a vertex, then:

l_i - l_j = [[x_i], [y_i]] - [[x_j], [y_j]] =
          = [[x_i - x_j], [y_i - y_j]]

Returns:	relative_locations (`(n_vertexes, 2)` ndarray) – The relative locations vector.

tojson()¶

Convert this PointGraph to a dictionary representation suitable for inclusion in the LJSON landmark format.

Returns:	json (dict) – Dictionary with `points` and `connectivity` keys.

vertices_at_depth(depth)¶

Returns a list of vertices at the specified depth.

Parameters:	depth (int) – The selected depth.
Returns:	vertices (list) – The vertices that lie in the specified depth.

view_widget(popup=False, browser_style='buttons', figure_size=(10, 8))¶

Visualization of the PointGraph using the visualize_pointclouds widget.

Parameters:	popup (bool, optional) – If `True`, the widget will be rendered in a popup window. browser_style (`{buttons, slider}`, optional) – It defines whether the selector of the PointGraph objects will have the form of plus/minus buttons or a slider. figure_size ((int, int) tuple, optional) – The initial size of the rendered figure.

has_landmarks¶

Whether the object has landmarks.

Type:	bool

landmarks¶

The landmarks object.

Type:	`LandmarkManager`

leaves¶

Returns a list with the all leaves of the tree.

Type:	list

maximum_depth¶

Returns the maximum depth of the tree.

Type:	int

n_dims¶

The number of dimensions in the pointcloud.

Type:	int

n_edges¶

Returns the number of the graph edges.

Type:	int

n_landmark_groups¶

The number of landmark groups on this object.

Type:	int

n_leaves¶

Returns the number of leaves of the tree.

Type:	int

n_parameters¶

The length of the vector that this object produces.

Type:	int

n_points¶

The number of points in the pointcloud.

Type:	int

n_vertices¶

Returns the number of the graph vertices.

Type:	int

Triangular Meshes¶

TriMesh¶

class menpo.shape.TriMesh(points, trilist=None, copy=True)[source]¶

Bases: PointCloud

A pointcloud with a connectivity defined by a triangle list. These are designed to be explicitly 2D or 3D.

Parameters:

points ((n_points, n_dims) ndarray) – The array representing the points.
trilist ((M, 3) ndarray or None, optional) – The triangle list. If None, a Delaunay triangulation of the points will be used instead.
copy (bool, optional) – If False, the points will not be copied on assignment. Any trilist will also not be copied. In general this should only be used if you know what you are doing.

_view_2d(figure_id=None, new_figure=False, image_view=True, render_lines=True, line_colour='r', line_style='-', line_width=1.0, render_markers=True, marker_style='o', marker_size=20, marker_face_colour='k', marker_edge_colour='k', marker_edge_width=1.0, render_axes=True, 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), label=None)[source]¶

Visualization of the TriMesh in 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.
image_view (bool, optional) – If True the TriMesh will be viewed as if it is in the image coordinate system.
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_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.
label (str, optional) – The name entry in case of a legend.

Returns: viewer (PointGraphViewer2d) – The viewer object.

_view_landmarks_2d(group=None, with_labels=None, without_labels=None, figure_id=None, new_figure=False, image_view=True, 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))¶

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

Parameters:

group (str or``None`` optional) – The landmark group to be visualized. If None and there are more than one landmark groups, an error is raised.
with_labels (None or str or list of str, optional) – If not None, only show the given label(s). Should not be used with the without_labels kwarg.
without_labels (None or str or list of str, optional) – If not None, show all except the given label(s). Should not be used with the with_labels kwarg.
figure_id (object, optional) – The id of the figure to be used.
new_figure (bool, optional) – If True, a new figure is created.
image_view (bool, optional) – If True the PointCloud will be viewed as if it is in the image coordinate system.
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 both with_labels and without_labels are passed.
ValueError – If the landmark manager doesn’t contain the provided group label.

as_pointgraph(copy=True)[source]¶

Converts the TriMesh to a PointUndirectedGraph.

Parameters:	copy (bool, optional) – If `True`, the graph will be a copy.
Returns:	pointgraph (`PointUndirectedGraph`) – The point graph.

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.

bounding_box()¶

Return the bounding box of this PointCloud as a directed graph. The the first point (0) will be nearest the origin for an axis aligned Pointcloud. In the case of an image, this ordering would appear as:

0<--3
|   ^
|   |
v   |
1-->2

Returns:	bounding_box (`PointDirectedGraph`) – The axis aligned bounding box of the PointCloud.

bounds(boundary=0)¶

The minimum to maximum extent of the PointCloud. An optional boundary argument can be provided to expand the bounds by a constant margin.

Parameters:	boundary (float) – A optional padding distance that is added to the bounds. Default is `0`, meaning the max/min of tightest possible containing square/cube/hypercube is returned.
Returns:	min_b (`(n_dims,)` ndarray) – The minimum extent of the `PointCloud` and boundary along each dimension max_b (`(n_dims,)` ndarray) – The maximum extent of the `PointCloud` and boundary along each dimension

centre()¶

The mean of all the points in this PointCloud (centre of mass).

Returns:	centre (`(n_dims)` ndarray) – The mean of this PointCloud’s points.

centre_of_bounds()¶

The centre of the absolute bounds of this PointCloud. Contrast with centre(), which is the mean point position.

Returns:	centre (`n_dims` ndarray) – The centre of the bounds of this PointCloud.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

distance_to(pointcloud, **kwargs)¶

Returns a distance matrix between this PointCloud and another. By default the Euclidean distance is calculated - see scipy.spatial.distance.cdist for valid kwargs to change the metric and other properties.

Parameters:	pointcloud (`PointCloud`) – The second pointcloud to compute distances between. This must be of the same dimension as this PointCloud.
Returns:	distance_matrix (`(n_points, n_points)` ndarray) – The symmetric pairwise distance matrix between the two PointClouds s.t. `distance_matrix[i, j]` is the distance between the i’th point of this PointCloud and the j’th point of the input PointCloud.

face_normals()[source]¶

Compute the face normals from the current set of points and triangle list. Only valid for 3D dimensional meshes.

Returns:	normals (`(n_tris, 3)` ndarray) – Normal at each face.
Raises:	`ValueError` – If mesh is not 3D

from_mask(mask)[source]¶

A 1D boolean array with the same number of elements as the number of points in the TriMesh. This is then broadcast across the dimensions of the mesh and returns a new mesh containing only those points that were True in the mask.

Parameters:	mask (`(n_points,)` ndarray) – 1D array of booleans
Returns:	mesh (`TriMesh`) – A new mesh that has been masked.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	object (`type(self)`) – An new instance of this class.

from_vector_inplace(vector)¶

Updates the points of this PointCloud in-place with the reshaped points from the provided vector. Note that the vector should have the form [x0, y0, x1, y1, ....., xn, yn] for 2D.

Parameters:	vector (`(n_points,)` ndarray) – The vector from which to create the points’ array.

h_points()¶

Convert poincloud to a homogeneous array: (n_dims + 1, n_points)

Type:	`type(self)`

norm(**kwargs)¶

Returns the norm of this PointCloud. This is a translation and rotation invariant measure of the point cloud’s intrinsic size - in other words, it is always taken around the point cloud’s centre.

By default, the Frobenius norm is taken, but this can be changed by setting kwargs - see numpy.linalg.norm for valid options.

Returns:	norm (float) – The norm of this `PointCloud`

range(boundary=0)¶

The range of the extent of the PointCloud.

Parameters:	boundary (float) – A optional padding distance that is used to extend the bounds from which the range is computed. Default is `0`, no extension is performed.
Returns:	range (`(n_dims,)` ndarray) – The range of the `PointCloud` extent in each dimension.

tojson()[source]¶

Convert this TriMesh to a dictionary representation suitable for inclusion in the LJSON landmark format. Note that this enforces a simpler representation, and as such is not suitable for a permanent serialization of a TriMesh (to be clear, TriMesh‘s serialized as part of a landmark set will be rebuilt as a PointUndirectedGraph).

Returns:	json (dict) – Dictionary with `points` and `connectivity` keys.

vertex_normals()[source]¶

Compute the per-vertex normals from the current set of points and triangle list. Only valid for 3D dimensional meshes.

Returns:	normals (`(n_points, 3)` ndarray) – Normal at each point.
Raises:	`ValueError` – If mesh is not 3D

view_widget(popup=False, browser_style='buttons', figure_size=(10, 8))[source]¶

Visualization of the TriMesh using the visualize_pointclouds widget.

Parameters:	popup (bool, optional) – If `True`, the widget will be rendered in a popup window. browser_style (`{buttons, slider}`, optional) – It defines whether the selector of the TriMesh objects will have the form of plus/minus buttons or a slider. figure_size ((int, int) tuple, optional) – The initial size of the rendered figure.

has_landmarks¶

Whether the object has landmarks.

Type:	bool

landmarks¶

The landmarks object.

Type:	`LandmarkManager`

n_dims¶

The number of dimensions in the pointcloud.

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_points¶

The number of points in the pointcloud.

Type:	int

n_tris¶

The number of triangles in the triangle list.

Type:	int

ColouredTriMesh¶

class menpo.shape.ColouredTriMesh(points, trilist=None, colours=None, copy=True)[source]¶

Bases: TriMesh

Combines a TriMesh with a colour per vertex.

Parameters:

points ((n_points, n_dims) ndarray) – The array representing the points.
trilist ((M, 3) ndarray or None, optional) – The triangle list. If None, a Delaunay triangulation of the points will be used instead.
colours ((N, 3) ndarray, optional) – The floating point RGB colour per vertex. If not given, grey will be assigned to each vertex.
copy (bool, optional) – If False, the points, trilist and colours will not be copied on assignment. In general this should only be used if you know what you are doing.

Raises:

ValueError – If the number of colour values does not match the number of vertices.

_view_2d(figure_id=None, new_figure=False, image_view=True, render_lines=True, line_colour='r', line_style='-', line_width=1.0, render_markers=True, marker_style='o', marker_size=20, marker_face_colour='k', marker_edge_colour='k', marker_edge_width=1.0, render_axes=True, 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), label=None)[source]¶

Visualization of the TriMesh in 2D. Currently, explicit coloured TriMesh viewing is not supported, and therefore viewing falls back to uncoloured 2D TriMesh viewing.

Returns:	figure_id (object, optional) – The id of the figure to be used. new_figure (bool, optional) – If `True`, a new figure is created. image_view (bool, optional) – If `True` the ColouredTriMesh will be viewed as if it is in the image coordinate system. 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_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. label (str, optional) – The name entry in case of a legend.
Returns:	viewer (`PointGraphViewer2d`) – The viewer object.
Raises:	`warning` – 2D Viewing of Coloured TriMeshes is not supported, automatically falls back to 2D `TriMesh` viewing.

_view_landmarks_2d(group=None, with_labels=None, without_labels=None, figure_id=None, new_figure=False, image_view=True, 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))¶

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

Parameters:

group (str or``None`` optional) – The landmark group to be visualized. If None and there are more than one landmark groups, an error is raised.
with_labels (None or str or list of str, optional) – If not None, only show the given label(s). Should not be used with the without_labels kwarg.
without_labels (None or str or list of str, optional) – If not None, show all except the given label(s). Should not be used with the with_labels kwarg.
figure_id (object, optional) – The id of the figure to be used.
new_figure (bool, optional) – If True, a new figure is created.
image_view (bool, optional) – If True the PointCloud will be viewed as if it is in the image coordinate system.
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 both with_labels and without_labels are passed.
ValueError – If the landmark manager doesn’t contain the provided group label.

as_pointgraph(copy=True)¶

Converts the TriMesh to a PointUndirectedGraph.

Parameters:	copy (bool, optional) – If `True`, the graph will be a copy.
Returns:	pointgraph (`PointUndirectedGraph`) – The point graph.

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.

bounding_box()¶

Return the bounding box of this PointCloud as a directed graph. The the first point (0) will be nearest the origin for an axis aligned Pointcloud. In the case of an image, this ordering would appear as:

0<--3
|   ^
|   |
v   |
1-->2

Returns:	bounding_box (`PointDirectedGraph`) – The axis aligned bounding box of the PointCloud.

bounds(boundary=0)¶

The minimum to maximum extent of the PointCloud. An optional boundary argument can be provided to expand the bounds by a constant margin.

Parameters:	boundary (float) – A optional padding distance that is added to the bounds. Default is `0`, meaning the max/min of tightest possible containing square/cube/hypercube is returned.
Returns:	min_b (`(n_dims,)` ndarray) – The minimum extent of the `PointCloud` and boundary along each dimension max_b (`(n_dims,)` ndarray) – The maximum extent of the `PointCloud` and boundary along each dimension

centre()¶

The mean of all the points in this PointCloud (centre of mass).

Returns:	centre (`(n_dims)` ndarray) – The mean of this PointCloud’s points.

centre_of_bounds()¶

The centre of the absolute bounds of this PointCloud. Contrast with centre(), which is the mean point position.

Returns:	centre (`n_dims` ndarray) – The centre of the bounds of this PointCloud.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

distance_to(pointcloud, **kwargs)¶

Returns a distance matrix between this PointCloud and another. By default the Euclidean distance is calculated - see scipy.spatial.distance.cdist for valid kwargs to change the metric and other properties.

Parameters:	pointcloud (`PointCloud`) – The second pointcloud to compute distances between. This must be of the same dimension as this PointCloud.
Returns:	distance_matrix (`(n_points, n_points)` ndarray) – The symmetric pairwise distance matrix between the two PointClouds s.t. `distance_matrix[i, j]` is the distance between the i’th point of this PointCloud and the j’th point of the input PointCloud.

face_normals()¶

Compute the face normals from the current set of points and triangle list. Only valid for 3D dimensional meshes.

Returns:	normals (`(n_tris, 3)` ndarray) – Normal at each face.
Raises:	`ValueError` – If mesh is not 3D

from_mask(mask)[source]¶

A 1D boolean array with the same number of elements as the number of points in the ColouredTriMesh. This is then broadcast across the dimensions of the mesh and returns a new mesh containing only those points that were True in the mask.

Parameters:	mask (`(n_points,)` ndarray) – 1D array of booleans
Returns:	mesh (`ColouredTriMesh`) – A new mesh that has been masked.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	object (`type(self)`) – An new instance of this class.

from_vector_inplace(vector)¶

Updates the points of this PointCloud in-place with the reshaped points from the provided vector. Note that the vector should have the form [x0, y0, x1, y1, ....., xn, yn] for 2D.

Parameters:	vector (`(n_points,)` ndarray) – The vector from which to create the points’ array.

h_points()¶

Convert poincloud to a homogeneous array: (n_dims + 1, n_points)

Type:	`type(self)`

norm(**kwargs)¶

Returns the norm of this PointCloud. This is a translation and rotation invariant measure of the point cloud’s intrinsic size - in other words, it is always taken around the point cloud’s centre.

By default, the Frobenius norm is taken, but this can be changed by setting kwargs - see numpy.linalg.norm for valid options.

Returns:	norm (float) – The norm of this `PointCloud`

range(boundary=0)¶

The range of the extent of the PointCloud.

Parameters:	boundary (float) – A optional padding distance that is used to extend the bounds from which the range is computed. Default is `0`, no extension is performed.
Returns:	range (`(n_dims,)` ndarray) – The range of the `PointCloud` extent in each dimension.

tojson()¶

Convert this TriMesh to a dictionary representation suitable for inclusion in the LJSON landmark format. Note that this enforces a simpler representation, and as such is not suitable for a permanent serialization of a TriMesh (to be clear, TriMesh‘s serialized as part of a landmark set will be rebuilt as a PointUndirectedGraph).

Returns:	json (dict) – Dictionary with `points` and `connectivity` keys.

vertex_normals()¶

Compute the per-vertex normals from the current set of points and triangle list. Only valid for 3D dimensional meshes.

Returns:	normals (`(n_points, 3)` ndarray) – Normal at each point.
Raises:	`ValueError` – If mesh is not 3D

view_widget(popup=False, browser_style='buttons', figure_size=(10, 8))¶

Visualization of the TriMesh using the visualize_pointclouds widget.

Parameters:	popup (bool, optional) – If `True`, the widget will be rendered in a popup window. browser_style (`{buttons, slider}`, optional) – It defines whether the selector of the TriMesh objects will have the form of plus/minus buttons or a slider. figure_size ((int, int) tuple, optional) – The initial size of the rendered figure.

has_landmarks¶

Whether the object has landmarks.

Type:	bool

landmarks¶

The landmarks object.

Type:	`LandmarkManager`

n_dims¶

The number of dimensions in the pointcloud.

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_points¶

The number of points in the pointcloud.

Type:	int

n_tris¶

The number of triangles in the triangle list.

Type:	int

TexturedTriMesh¶

class menpo.shape.TexturedTriMesh(points, tcoords, texture, trilist=None, copy=True)[source]¶

Bases: TriMesh

Combines a TriMesh with a texture. Also encapsulates the texture coordinates required to render the texture on the mesh.

Parameters:

points ((n_points, n_dims) ndarray) – The array representing the points.
tcoords ((N, 2) ndarray) – The texture coordinates for the mesh.
texture (Image) – The texture for the mesh.
trilist ((M, 3) ndarray or None, optional) – The triangle list. If None, a Delaunay triangulation of the points will be used instead.
copy (bool, optional) – If False, the points, trilist and texture will not be copied on assignment. In general this should only be used if you know what you are doing.

_view_2d(figure_id=None, new_figure=False, image_view=True, render_lines=True, line_colour='r', line_style='-', line_width=1.0, render_markers=True, marker_style='o', marker_size=20, marker_face_colour='k', marker_edge_colour='k', marker_edge_width=1.0, render_axes=True, 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), label=None)[source]¶

Visualization of the TriMesh in 2D. Currently, explicit textured TriMesh viewing is not supported, and therefore viewing falls back to untextured 2D TriMesh viewing.

Returns:	figure_id (object, optional) – The id of the figure to be used. new_figure (bool, optional) – If `True`, a new figure is created. image_view (bool, optional) – If `True` the TexturedTriMesh will be viewed as if it is in the image coordinate system. 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_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. label (str, optional) – The name entry in case of a legend.
Returns:	viewer (`PointGraphViewer2d`) – The viewer object.
Raises:	`warning` – 2D Viewing of Coloured TriMeshes is not supported, automatically falls back to 2D `TriMesh` viewing.

_view_landmarks_2d(group=None, with_labels=None, without_labels=None, figure_id=None, new_figure=False, image_view=True, 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))¶

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

Parameters:

group (str or``None`` optional) – The landmark group to be visualized. If None and there are more than one landmark groups, an error is raised.
with_labels (None or str or list of str, optional) – If not None, only show the given label(s). Should not be used with the without_labels kwarg.
without_labels (None or str or list of str, optional) – If not None, show all except the given label(s). Should not be used with the with_labels kwarg.
figure_id (object, optional) – The id of the figure to be used.
new_figure (bool, optional) – If True, a new figure is created.
image_view (bool, optional) – If True the PointCloud will be viewed as if it is in the image coordinate system.
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 both with_labels and without_labels are passed.
ValueError – If the landmark manager doesn’t contain the provided group label.

as_pointgraph(copy=True)¶

Converts the TriMesh to a PointUndirectedGraph.

Parameters:	copy (bool, optional) – If `True`, the graph will be a copy.
Returns:	pointgraph (`PointUndirectedGraph`) – The point graph.

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.

bounding_box()¶

Return the bounding box of this PointCloud as a directed graph. The the first point (0) will be nearest the origin for an axis aligned Pointcloud. In the case of an image, this ordering would appear as:

0<--3
|   ^
|   |
v   |
1-->2

Returns:	bounding_box (`PointDirectedGraph`) – The axis aligned bounding box of the PointCloud.

bounds(boundary=0)¶

The minimum to maximum extent of the PointCloud. An optional boundary argument can be provided to expand the bounds by a constant margin.

Parameters:	boundary (float) – A optional padding distance that is added to the bounds. Default is `0`, meaning the max/min of tightest possible containing square/cube/hypercube is returned.
Returns:	min_b (`(n_dims,)` ndarray) – The minimum extent of the `PointCloud` and boundary along each dimension max_b (`(n_dims,)` ndarray) – The maximum extent of the `PointCloud` and boundary along each dimension

centre()¶

The mean of all the points in this PointCloud (centre of mass).

Returns:	centre (`(n_dims)` ndarray) – The mean of this PointCloud’s points.

centre_of_bounds()¶

The centre of the absolute bounds of this PointCloud. Contrast with centre(), which is the mean point position.

Returns:	centre (`n_dims` ndarray) – The centre of the bounds of this PointCloud.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

distance_to(pointcloud, **kwargs)¶

Returns a distance matrix between this PointCloud and another. By default the Euclidean distance is calculated - see scipy.spatial.distance.cdist for valid kwargs to change the metric and other properties.

Parameters:	pointcloud (`PointCloud`) – The second pointcloud to compute distances between. This must be of the same dimension as this PointCloud.
Returns:	distance_matrix (`(n_points, n_points)` ndarray) – The symmetric pairwise distance matrix between the two PointClouds s.t. `distance_matrix[i, j]` is the distance between the i’th point of this PointCloud and the j’th point of the input PointCloud.

face_normals()¶

Compute the face normals from the current set of points and triangle list. Only valid for 3D dimensional meshes.

Returns:	normals (`(n_tris, 3)` ndarray) – Normal at each face.
Raises:	`ValueError` – If mesh is not 3D

from_mask(mask)[source]¶

A 1D boolean array with the same number of elements as the number of points in the TexturedTriMesh. This is then broadcast across the dimensions of the mesh and returns a new mesh containing only those points that were True in the mask.

Parameters:	mask (`(n_points,)` ndarray) – 1D array of booleans
Returns:	mesh (`TexturedTriMesh`) – A new mesh that has been masked.

from_vector(flattened)[source]¶

Builds a new TexturedTriMesh given the flattened 1D vector. Note that the trilist, texture, and tcoords will be drawn from self.

Parameters:	flattened (`(N,)` ndarray) – Vector representing a set of points. Returns – -------- – trimesh (`TriMesh`) – A new trimesh created from the vector with `self` trilist.

from_vector_inplace(vector)¶

Updates the points of this PointCloud in-place with the reshaped points from the provided vector. Note that the vector should have the form [x0, y0, x1, y1, ....., xn, yn] for 2D.

Parameters:	vector (`(n_points,)` ndarray) – The vector from which to create the points’ array.

h_points()¶

Convert poincloud to a homogeneous array: (n_dims + 1, n_points)

Type:	`type(self)`

norm(**kwargs)¶

Returns the norm of this PointCloud. This is a translation and rotation invariant measure of the point cloud’s intrinsic size - in other words, it is always taken around the point cloud’s centre.

By default, the Frobenius norm is taken, but this can be changed by setting kwargs - see numpy.linalg.norm for valid options.

Returns:	norm (float) – The norm of this `PointCloud`

range(boundary=0)¶

The range of the extent of the PointCloud.

Parameters:	boundary (float) – A optional padding distance that is used to extend the bounds from which the range is computed. Default is `0`, no extension is performed.
Returns:	range (`(n_dims,)` ndarray) – The range of the `PointCloud` extent in each dimension.

tcoords_pixel_scaled()[source]¶

Returns a PointCloud that is modified to be suitable for directly indexing into the pixels of the texture (e.g. for manual mapping operations). The resulting tcoords behave just like image landmarks do.

The operations that are performed are:

Flipping the origin from bottom-left to top-left

Scaling the tcoords by the image shape (denormalising them)

Permuting the axis so that

Returns:	tcoords_scaled (`PointCloud`) – A copy of the tcoords that behave like `Image` landmarks

Examples

Recovering pixel values for every texture coordinate:

>>> texture = texturedtrimesh.texture
>>> tc_ps = texturedtrimesh.tcoords_pixel_scaled()
>>> pixel_values_at_tcs = texture[tc_ps[: ,0], tc_ps[:, 1]]

tojson()¶

Convert this TriMesh to a dictionary representation suitable for inclusion in the LJSON landmark format. Note that this enforces a simpler representation, and as such is not suitable for a permanent serialization of a TriMesh (to be clear, TriMesh‘s serialized as part of a landmark set will be rebuilt as a PointUndirectedGraph).

Returns:	json (dict) – Dictionary with `points` and `connectivity` keys.

vertex_normals()¶

Compute the per-vertex normals from the current set of points and triangle list. Only valid for 3D dimensional meshes.

Returns:	normals (`(n_points, 3)` ndarray) – Normal at each point.
Raises:	`ValueError` – If mesh is not 3D

view_widget(popup=False, browser_style='buttons', figure_size=(10, 8))¶

Visualization of the TriMesh using the visualize_pointclouds widget.

Parameters:	popup (bool, optional) – If `True`, the widget will be rendered in a popup window. browser_style (`{buttons, slider}`, optional) – It defines whether the selector of the TriMesh objects will have the form of plus/minus buttons or a slider. figure_size ((int, int) tuple, optional) – The initial size of the rendered figure.

has_landmarks¶

Whether the object has landmarks.

Type:	bool

landmarks¶

The landmarks object.

Type:	`LandmarkManager`

n_dims¶

The number of dimensions in the pointcloud.

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_points¶

The number of points in the pointcloud.

Type:	int

n_tris¶

The number of triangles in the triangle list.

Type:	int

Group Operations¶

mean_pointcloud¶

menpo.shape.mean_pointcloud(pointclouds)[source]¶

Compute the mean of a list of PointCloud objects.

Parameters:	pointclouds (list of `PointCloud`) – List of point cloud objects from which we want to compute the mean.
Returns:	mean_pointcloud (`PointCloud`) – The mean point cloud.

`menpo.transform`¶

Homogeneous Transforms¶

Homogeneous¶

class menpo.transform.Homogeneous(h_matrix, copy=True, skip_checks=False)[source]¶

Bases: ComposableTransform, Vectorizable, VComposable, VInvertible

A simple n-dimensional homogeneous transformation.

Adds a unit homogeneous coordinate to points, performs the dot product, re-normalizes by division by the homogeneous coordinate, and returns the result.

Can be composed with another Homogeneous, so long as the dimensionality matches.

Parameters:	h_matrix (`(n_dims + 1, n_dims + 1)` ndarray) – The homogeneous matrix defining this transform. copy (bool, optional) – If False avoid copying `h_matrix`. Useful for performance. skip_checks (bool, optional) – If True avoid sanity checks on the `h_matrix`. Useful for performance.

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

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.

compose_after(transform)¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

from_vector(vector)[source]¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	transform (`type(self)`) – An new instance of this class.

pseudoinverse_vector(vector)¶

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()

Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters:	vector (`(n_parameters,)` ndarray) – A vectorized version of `self`
Returns:	pseudoinverse_vector (`(n_parameters,)` ndarray) – The pseudoinverse of the vector provided

set_h_matrix(value, copy=True, skip_checks=False)[source]¶

Updates h_matrix, optionally performing sanity checks.

Note that it won’t always be possible to manually specify the h_matrix through this method, specifically if changing the h_matrix could change the nature of the transform. See h_matrix_is_mutable for how you can discover if the h_matrix is allowed to be set for a given class.

Parameters:	value (ndarray) – The new homogeneous matrix to set copy (bool, optional) – If False do not copy the h_matrix. Useful for performance. skip_checks (bool, optional) – If True skip checking. Useful for performance.
Raises:	`NotImplementedError` – If `h_matrix_is_mutable` returns `False`.

composes_inplace_with¶: Homogeneous can swallow composition with any other Homogeneous, subclasses will have to override and be more specific.

composes_with¶: Any Homogeneous can compose with any other Homogeneous.

h_matrix_is_mutable¶

True iff set_h_matrix() is permitted on this type of transform. If this returns False calls to set_h_matrix() will raise a NotImplementedError.

Type:	bool

n_parameters¶

The length of the vector that this object produces.

Type:	int

Affine¶

class menpo.transform.Affine(h_matrix, copy=True, skip_checks=False)[source]¶

Bases: Homogeneous

Base class for all n-dimensional affine transformations. Provides methods to break the transform down into it’s constituent scale/rotation/translation, to view the homogeneous matrix equivalent, and to chain this transform with other affine transformations.

Parameters:	h_matrix (`(n_dims + 1, n_dims + 1)` ndarray) – The homogeneous matrix of the affine transformation. copy (bool, optional) – If `False` avoid copying `h_matrix` for performance. skip_checks (bool, optional) – If `True` avoid sanity checks on `h_matrix` for performance.

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

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.

compose_after(transform)¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

decompose()[source]¶

Decompose this transform into discrete Affine Transforms.

Useful for understanding the effect of a complex composite transform.

Returns:	transforms (list of `DiscreteAffine`) – Equivalent to this affine transform, such that: reduce(lambda x,y: x.chain(y), self.decompose()) == self

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	transform (`type(self)`) – An new instance of this class.

from_vector_inplace(p)[source]¶: Updates this Affine in-place from the new parameters. See from_vector for details of the parameter format

pseudoinverse_vector(vector)¶

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()

Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters:	vector (`(n_parameters,)` ndarray) – A vectorized version of `self`
Returns:	pseudoinverse_vector (`(n_parameters,)` ndarray) – The pseudoinverse of the vector provided

set_h_matrix(value, copy=True, skip_checks=False)¶

Updates h_matrix, optionally performing sanity checks.

Note that it won’t always be possible to manually specify the h_matrix through this method, specifically if changing the h_matrix could change the nature of the transform. See h_matrix_is_mutable for how you can discover if the h_matrix is allowed to be set for a given class.

Parameters:	value (ndarray) – The new homogeneous matrix to set copy (bool, optional) – If False do not copy the h_matrix. Useful for performance. skip_checks (bool, optional) – If True skip checking. Useful for performance.
Raises:	`NotImplementedError` – If `h_matrix_is_mutable` returns `False`.

composes_with¶: Any Homogeneous can compose with any other Homogeneous.

h_matrix_is_mutable¶

True iff set_h_matrix() is permitted on this type of transform. If this returns False calls to set_h_matrix() will raise a NotImplementedError.

Type:	bool

linear_component¶

The linear component of this affine transform.

Type:	`(n_dims, n_dims)` ndarray

n_parameters¶

n_dims * (n_dims + 1) parameters - every element of the matrix bar the homogeneous part.

Type:	int

Examples

2D Affine: 6 parameters:

[p1, p3, p5]
[p2, p4, p6]

3D Affine: 12 parameters:

[p1, p4, p7, p10]
[p2, p5, p8, p11]
[p3, p6, p9, p12]

translation_component¶

The translation component of this affine transform.

Type:	`(n_dims,)` ndarray

Similarity¶

class menpo.transform.Similarity(h_matrix, copy=True, skip_checks=False)[source]¶

Bases: Affine

Specialist version of an Affine that is guaranteed to be a Similarity transform.

Parameters:	h_matrix ((D + 1, D + 1) ndarray) – The homogeneous matrix of the similarity transform.

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

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.

compose_after(transform)¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

decompose()¶

Decompose this transform into discrete Affine Transforms.

Useful for understanding the effect of a complex composite transform.

Returns:	transforms (list of `DiscreteAffine`) – Equivalent to this affine transform, such that: reduce(lambda x,y: x.chain(y), self.decompose()) == self

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	transform (`type(self)`) – An new instance of this class.

from_vector_inplace(p)[source]¶

Returns an instance of the transform from the given parameters, expected to be in Fortran ordering.

Supports rebuilding from 2D parameter sets.

2D Similarity: 4 parameters:

[a, b, tx, ty]

Parameters:	p ((P,) ndarray) – The array of parameters.
Raises:	DimensionalityError, NotImplementedError – Only 2D transforms are supported.

pseudoinverse_vector(vector)¶

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()

Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters:	vector (`(n_parameters,)` ndarray) – A vectorized version of `self`
Returns:	pseudoinverse_vector (`(n_parameters,)` ndarray) – The pseudoinverse of the vector provided

set_h_matrix(value, copy=True, skip_checks=False)¶

Updates h_matrix, optionally performing sanity checks.

Note that it won’t always be possible to manually specify the h_matrix through this method, specifically if changing the h_matrix could change the nature of the transform. See h_matrix_is_mutable for how you can discover if the h_matrix is allowed to be set for a given class.

Parameters:	value (ndarray) – The new homogeneous matrix to set copy (bool, optional) – If False do not copy the h_matrix. Useful for performance. skip_checks (bool, optional) – If True skip checking. Useful for performance.
Raises:	`NotImplementedError` – If `h_matrix_is_mutable` returns `False`.

composes_with¶: Any Homogeneous can compose with any other Homogeneous.

linear_component¶

The linear component of this affine transform.

Type:	`(n_dims, n_dims)` ndarray

n_parameters¶

2D Similarity: 4 parameters:

[(1 + a), -b,      tx]
[b,       (1 + a), ty]

3D Similarity: Currently not supported

Returns:	int
Raises:	DimensionalityError, NotImplementedError – Only 2D transforms are supported.

translation_component¶

The translation component of this affine transform.

Type:	`(n_dims,)` ndarray

Rotation¶

class menpo.transform.Rotation(rotation_matrix, skip_checks=False)[source]¶

Bases: DiscreteAffine, Similarity

Abstract n_dims rotation transform.

Parameters:	rotation_matrix ((D, D) ndarray) – A valid, square rotation matrix

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

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.

axis_and_angle_of_rotation()[source]¶

Abstract method for computing the axis and angle of rotation.

Returns:	axis ((D,) ndarray) – The unit vector representing the axis of rotation angle_of_rotation (double) – The angle in radians of the rotation about the axis. The angle is signed in a right handed sense.

compose_after(transform)¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

decompose()¶

A DiscreteAffine is already maximally decomposed - return a copy of self in a list.

Returns:	transform (`DiscreteAffine`) – Deep copy of self.

classmethod from_2d_ccw_angle(theta, degrees=True)[source]¶

Convenience constructor for 2D CCW rotations about the origin

Parameters:	theta (float) – The angle of rotation about the origin degrees (bool, optional) – If `True` theta is interpreted as a degree. If `False`, theta is interpreted as radians.
Returns:	rotation (`Rotation`) – A 2D rotation transform.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	transform (`type(self)`) – An new instance of this class.

from_vector_inplace(p)[source]¶

Returns an instance of the transform from the given parameters, expected to be in Fortran ordering.

Supports rebuilding from 2D parameter sets.

2D Rotation: 1 parameter:

[theta]

Parameters:	p ((1,) ndarray) – The array of parameters.
Returns:	transform (`Rotation2D`) – The transform initialised to the given parameters.

pseudoinverse()[source]¶

The inverse rotation matrix.

Type:	(D, D) ndarray

pseudoinverse_vector(vector)¶

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()

Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters:	vector (`(n_parameters,)` ndarray) – A vectorized version of `self`
Returns:	pseudoinverse_vector (`(n_parameters,)` ndarray) – The pseudoinverse of the vector provided

set_h_matrix(value, copy=True, skip_checks=False)¶

Updates h_matrix, optionally performing sanity checks.

Note that it won’t always be possible to manually specify the h_matrix through this method, specifically if changing the h_matrix could change the nature of the transform. See h_matrix_is_mutable for how you can discover if the h_matrix is allowed to be set for a given class.

Parameters:	value (ndarray) – The new homogeneous matrix to set copy (bool, optional) – If False do not copy the h_matrix. Useful for performance. skip_checks (bool, optional) – If True skip checking. Useful for performance.
Raises:	`NotImplementedError` – If `h_matrix_is_mutable` returns `False`.

composes_with¶: Any Homogeneous can compose with any other Homogeneous.

linear_component¶

The linear component of this affine transform.

Type:	`(n_dims, n_dims)` ndarray

rotation_matrix¶

The rotation matrix.

Type:	(D, D) ndarray

translation_component¶

The translation component of this affine transform.

Type:	`(n_dims,)` ndarray

Translation¶

class menpo.transform.Translation(translation, skip_checks=False)[source]¶

Bases: DiscreteAffine, Similarity

An N-dimensional translation transform.

Parameters:	translation ((D,) ndarray) – The translation in each axis.

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

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.

compose_after(transform)¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

decompose()¶

A DiscreteAffine is already maximally decomposed - return a copy of self in a list.

Returns:	transform (`DiscreteAffine`) – Deep copy of self.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	transform (`type(self)`) – An new instance of this class.

pseudoinverse()[source]¶

The inverse translation (negated).

Returns:	`Translation`

pseudoinverse_vector(vector)¶

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()

Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters:	vector (`(n_parameters,)` ndarray) – A vectorized version of `self`
Returns:	pseudoinverse_vector (`(n_parameters,)` ndarray) – The pseudoinverse of the vector provided

set_h_matrix(value, copy=True, skip_checks=False)¶

Updates h_matrix, optionally performing sanity checks.

Note that it won’t always be possible to manually specify the h_matrix through this method, specifically if changing the h_matrix could change the nature of the transform. See h_matrix_is_mutable for how you can discover if the h_matrix is allowed to be set for a given class.

Parameters:	value (ndarray) – The new homogeneous matrix to set copy (bool, optional) – If False do not copy the h_matrix. Useful for performance. skip_checks (bool, optional) – If True skip checking. Useful for performance.
Raises:	`NotImplementedError` – If `h_matrix_is_mutable` returns `False`.

composes_with¶: Any Homogeneous can compose with any other Homogeneous.

linear_component¶

The linear component of this affine transform.

Type:	`(n_dims, n_dims)` ndarray

n_parameters¶

The number of parameters: n_dims

Type:	int

translation_component¶

The translation component of this affine transform.

Type:	`(n_dims,)` ndarray

Scale¶

menpo.transform.Scale(scale_factor, n_dims=None)[source]¶

Factory function for producing Scale transforms. Zero scale factors are not permitted.

A UniformScale will be produced if:

A float scale_factor and a n_dims kwarg are provided

A ndarray scale_factor with shape (n_dims, ) is provided with all elements being the same

A NonUniformScale will be provided if:

A ndarray scale_factor with shape (n_dims, ) is provided with at least two differing scale factors.

Parameters:

scale_factor (double or (D,) ndarray) – Scale for each axis.
n_dims (int) – The dimensionality of the output transform.

Returns:

scale (UniformScale or NonUniformScale) – The correct type of scale
Raises
——-
ValueError – If any of the scale factors is zero

UniformScale¶

class menpo.transform.UniformScale(scale, n_dims, skip_checks=False)[source]¶

Bases: DiscreteAffine, Similarity

An abstract similarity scale transform, with a single scale component applied to all dimensions. This is abstracted out to remove unnecessary code duplication.

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

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.

compose_after(transform)¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

decompose()¶

A DiscreteAffine is already maximally decomposed - return a copy of self in a list.

Returns:	transform (`DiscreteAffine`) – Deep copy of self.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	transform (`type(self)`) – An new instance of this class.

pseudoinverse()[source]¶

The inverse scale.

Type:	type(self)

pseudoinverse_vector(vector)¶

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()

Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters:	vector (`(n_parameters,)` ndarray) – A vectorized version of `self`
Returns:	pseudoinverse_vector (`(n_parameters,)` ndarray) – The pseudoinverse of the vector provided

set_h_matrix(value, copy=True, skip_checks=False)¶

Updates h_matrix, optionally performing sanity checks.

Note that it won’t always be possible to manually specify the h_matrix through this method, specifically if changing the h_matrix could change the nature of the transform. See h_matrix_is_mutable for how you can discover if the h_matrix is allowed to be set for a given class.

Parameters:	value (ndarray) – The new homogeneous matrix to set copy (bool, optional) – If False do not copy the h_matrix. Useful for performance. skip_checks (bool, optional) – If True skip checking. Useful for performance.
Raises:	`NotImplementedError` – If `h_matrix_is_mutable` returns `False`.

composes_with¶: Any Homogeneous can compose with any other Homogeneous.

linear_component¶

The linear component of this affine transform.

Type:	`(n_dims, n_dims)` ndarray

n_parameters¶

The number of parameters: 1

Type:	int

scale¶

The single scale value.

Type:	double

translation_component¶

The translation component of this affine transform.

Type:	`(n_dims,)` ndarray

NonUniformScale¶

class menpo.transform.NonUniformScale(scale, skip_checks=False)[source]¶

Bases: DiscreteAffine, Affine

An n_dims scale transform, with a scale component for each dimension.

Parameters:	scale (`(n_dims,)` ndarray) – A scale for each axis.

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

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.

compose_after(transform)¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

decompose()¶

A DiscreteAffine is already maximally decomposed - return a copy of self in a list.

Returns:	transform (`DiscreteAffine`) – Deep copy of self.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	transform (`type(self)`) – An new instance of this class.

from_vector_inplace(vector)[source]¶

Updates the NonUniformScale inplace.

Parameters:	vector ((D,) ndarray) – The array of parameters.

pseudoinverse()[source]¶

The inverse scale.

Type:	`NonUniformScale`

pseudoinverse_vector(vector)¶

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()

Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters:	vector (`(n_parameters,)` ndarray) – A vectorized version of `self`
Returns:	pseudoinverse_vector (`(n_parameters,)` ndarray) – The pseudoinverse of the vector provided

set_h_matrix(value, copy=True, skip_checks=False)¶

Updates h_matrix, optionally performing sanity checks.

Note that it won’t always be possible to manually specify the h_matrix through this method, specifically if changing the h_matrix could change the nature of the transform. See h_matrix_is_mutable for how you can discover if the h_matrix is allowed to be set for a given class.

Parameters:	value (ndarray) – The new homogeneous matrix to set copy (bool, optional) – If False do not copy the h_matrix. Useful for performance. skip_checks (bool, optional) – If True skip checking. Useful for performance.
Raises:	`NotImplementedError` – If `h_matrix_is_mutable` returns `False`.

composes_with¶: Any Homogeneous can compose with any other Homogeneous.

linear_component¶

The linear component of this affine transform.

Type:	`(n_dims, n_dims)` ndarray

n_parameters¶

The number of parameters: n_dims.

Type:	int

n_dims parameters - [scale_x, scale_y, ....] - The scalar values representing the scale across each axis.

scale¶

The scale vector.

Type:	(D,) ndarray

translation_component¶

The translation component of this affine transform.

Type:	`(n_dims,)` ndarray

Alignments¶

ThinPlateSplines¶

class menpo.transform.ThinPlateSplines(source, target, kernel=None)[source]¶

Bases: Alignment, Transform, Invertible

The thin plate splines (TPS) alignment between 2D source and target landmarks.

kernel can be used to specify an alternative kernel function. If None is supplied, the R2LogR2 kernel will be used.

Parameters:	source ((N, 2) ndarray) – The source points to apply the tps from target ((N, 2) ndarray) – The target points to apply the tps to kernel (`BasisFunction`, optional) – The kernel to apply. Default: `R2LogR2`
Raises:	`ValueError` – TPS is only with on 2-dimensional data

aligned_source()¶

The result of applying self to source

Type:	`PointCloud`

alignment_error()¶

The Frobenius Norm of the difference between the target and the aligned source.

Type:	float

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

compose_after(transform)¶

Returns a TransformChain that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

Parameters:	transform (`TransformChain`) – Transform to be applied before self Returns – -------- – transform – The resulting transform chain.

compose_before(transform)¶

Returns a TransformChain that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

Parameters:	transform (`TransformChain`) – Transform to be applied after self Returns – -------- – transform – The resulting transform chain.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

set_target(new_target)¶

Update this object so that it attempts to recreate the new_target.

Parameters:	new_target (`PointCloud`) – The new target that this object should try and regenerate.

n_dims¶

The number of dimensions of the target.

Type:	int

n_dims_output¶

The output of the data from the transform.

None if the output of the transform is not dimension specific.

Type:	int or `None`

n_points¶

The number of points on the target.

Type:	int

source¶

The source PointCloud that is used in the alignment.

The source is not mutable.

Type:	`PointCloud`

target¶

The current PointCloud that this object produces.

To change the target, use set_target().

Type:	`PointCloud`

PiecewiseAffine¶

menpo.transform.PiecewiseAffine¶: alias of CachedPWA

AlignmentAffine¶

class menpo.transform.AlignmentAffine(source, target)[source]¶

Bases: HomogFamilyAlignment, Affine

Constructs an Affine by finding the optimal affine transform to align source to target.

Parameters:	source (`PointCloud`) – The source pointcloud instance used in the alignment target (`PointCloud`) – The target pointcloud instance used in the alignment

Notes

We want to find the optimal transform M which satisfies

M a = b

where a and b are the source and target homogeneous vectors respectively.

(M a)' = b'
a' M' = b'
a a' M' = a b'

a a’ is of shape (n_dim + 1, n_dim + 1) and so can be inverted to solve for M.

This approach is the analytical linear least squares solution to the problem at hand. It will have a solution as long as (a a’) is non-singular, which generally means at least 2 corresponding points are required.

aligned_source()¶

The result of applying self to source

Type:	`PointCloud`

alignment_error()¶

The Frobenius Norm of the difference between the target and the aligned source.

Type:	float

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

as_non_alignment()[source]¶

Returns a copy of this affine without it’s alignment nature.

Returns:	transform (`Affine`) – A version of this affine with the same transform behavior but without the alignment logic.

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.

compose_after(transform)¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this HomogFamilyAlignment.

Returns:	new_transform (`type(self)`) – A copy of this object

decompose()¶

Decompose this transform into discrete Affine Transforms.

Useful for understanding the effect of a complex composite transform.

Returns:	transforms (list of `DiscreteAffine`) – Equivalent to this affine transform, such that: reduce(lambda x,y: x.chain(y), self.decompose()) == self

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	transform (`type(self)`) – An new instance of this class.

from_vector_inplace(p)¶: Updates this Affine in-place from the new parameters. See from_vector for details of the parameter format

pseudoinverse()¶

The pseudoinverse of the transform - that is, the transform that results from swapping source and target, or more formally, negating the transforms parameters. If the transform has a true inverse this is returned instead.

Returns:	transform (`type(self)`) – The inverse of this transform.

pseudoinverse_vector(vector)¶

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()

Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters:	vector (`(n_parameters,)` ndarray) – A vectorized version of `self`
Returns:	pseudoinverse_vector (`(n_parameters,)` ndarray) – The pseudoinverse of the vector provided

set_h_matrix(value, copy=True, skip_checks=False)[source]¶

Updates h_matrix, optionally performing sanity checks.

Note

Updating the h_matrix on an AlignmentAffine triggers a sync of the target.

Note that it won’t always be possible to manually specify the h_matrix through this method, specifically if changing the h_matrix could change the nature of the transform. See h_matrix_is_mutable for how you can discover if the h_matrix is allowed to be set for a given class.

Parameters:	value (ndarray) – The new homogeneous matrix to set copy (bool, optional) – If False do not copy the h_matrix. Useful for performance. skip_checks (bool, optional) – If `True` skip checking. Useful for performance.
Raises:	`NotImplementedError` – If `h_matrix_is_mutable` returns `False`.

set_target(new_target)¶

Update this object so that it attempts to recreate the new_target.

Parameters:	new_target (`PointCloud`) – The new target that this object should try and regenerate.

composes_with¶: Any Homogeneous can compose with any other Homogeneous.

h_matrix_is_mutable¶

True iff set_h_matrix() is permitted on this type of transform. If this returns False calls to set_h_matrix() will raise a NotImplementedError.

Type:	bool

linear_component¶

The linear component of this affine transform.

Type:	`(n_dims, n_dims)` ndarray

n_dims¶

The number of dimensions of the target.

Type:	int

n_parameters¶

n_dims * (n_dims + 1) parameters - every element of the matrix bar the homogeneous part.

Type:	int

Examples

2D Affine: 6 parameters:

[p1, p3, p5]
[p2, p4, p6]

3D Affine: 12 parameters:

[p1, p4, p7, p10]
[p2, p5, p8, p11]
[p3, p6, p9, p12]

n_points¶

The number of points on the target.

Type:	int

source¶

The source PointCloud that is used in the alignment.

The source is not mutable.

Type:	`PointCloud`

target¶

The current PointCloud that this object produces.

To change the target, use set_target().

Type:	`PointCloud`

translation_component¶

The translation component of this affine transform.

Type:	`(n_dims,)` ndarray

AlignmentSimilarity¶

class menpo.transform.AlignmentSimilarity(source, target, rotation=True)[source]¶

Bases: HomogFamilyAlignment, Similarity

Infers the similarity transform relating two vectors with the same dimensionality. This is simply the procrustes alignment of the source to the target.

Parameters:	source (`PointCloud`) – The source pointcloud instance used in the alignment target (`PointCloud`) – The target pointcloud instance used in the alignment rotation (boolean, optional) – If False, the rotation component of the similarity transform is not inferred. Default: True

aligned_source()¶

The result of applying self to source

Type:	`PointCloud`

alignment_error()¶

The Frobenius Norm of the difference between the target and the aligned source.

Type:	float

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

as_non_alignment()[source]¶

Returns a copy of this similarity without it’s alignment nature.

Returns:	transform (`Similarity`) – A version of this similarity with the same transform behavior but without the alignment logic.

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.

compose_after(transform)¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this HomogFamilyAlignment.

Returns:	new_transform (`type(self)`) – A copy of this object

decompose()¶

Decompose this transform into discrete Affine Transforms.

Useful for understanding the effect of a complex composite transform.

Returns:	transforms (list of `DiscreteAffine`) – Equivalent to this affine transform, such that: reduce(lambda x,y: x.chain(y), self.decompose()) == self

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	transform (`type(self)`) – An new instance of this class.

from_vector_inplace(p)[source]¶

Returns an instance of the transform from the given parameters, expected to be in Fortran ordering.

Supports rebuilding from 2D parameter sets.

2D Similarity: 4 parameters:

[a, b, tx, ty]

Parameters:	p ((P,) ndarray) – The array of parameters.
Raises:	DimensionalityError, NotImplementedError – Only 2D transforms are supported.

pseudoinverse()¶

The pseudoinverse of the transform - that is, the transform that results from swapping source and target, or more formally, negating the transforms parameters. If the transform has a true inverse this is returned instead.

Returns:	transform (`type(self)`) – The inverse of this transform.

pseudoinverse_vector(vector)¶

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()

Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters:	vector (`(n_parameters,)` ndarray) – A vectorized version of `self`
Returns:	pseudoinverse_vector (`(n_parameters,)` ndarray) – The pseudoinverse of the vector provided

set_h_matrix(value, copy=True, skip_checks=False)¶

Updates h_matrix, optionally performing sanity checks.

Note that it won’t always be possible to manually specify the h_matrix through this method, specifically if changing the h_matrix could change the nature of the transform. See h_matrix_is_mutable for how you can discover if the h_matrix is allowed to be set for a given class.

Parameters:	value (ndarray) – The new homogeneous matrix to set copy (bool, optional) – If False do not copy the h_matrix. Useful for performance. skip_checks (bool, optional) – If True skip checking. Useful for performance.
Raises:	`NotImplementedError` – If `h_matrix_is_mutable` returns `False`.

set_target(new_target)¶

Update this object so that it attempts to recreate the new_target.

Parameters:	new_target (`PointCloud`) – The new target that this object should try and regenerate.

composes_with¶: Any Homogeneous can compose with any other Homogeneous.

linear_component¶

The linear component of this affine transform.

Type:	`(n_dims, n_dims)` ndarray

n_dims¶

The number of dimensions of the target.

Type:	int

n_parameters¶

2D Similarity: 4 parameters:

[(1 + a), -b,      tx]
[b,       (1 + a), ty]

3D Similarity: Currently not supported

Returns:	int
Raises:	DimensionalityError, NotImplementedError – Only 2D transforms are supported.

n_points¶

The number of points on the target.

Type:	int

source¶

The source PointCloud that is used in the alignment.

The source is not mutable.

Type:	`PointCloud`

target¶

The current PointCloud that this object produces.

To change the target, use set_target().

Type:	`PointCloud`

translation_component¶

The translation component of this affine transform.

Type:	`(n_dims,)` ndarray

AlignmentRotation¶

class menpo.transform.AlignmentRotation(source, target)[source]¶

Bases: HomogFamilyAlignment, Rotation

aligned_source()¶

The result of applying self to source

Type:	`PointCloud`

alignment_error()¶

The Frobenius Norm of the difference between the target and the aligned source.

Type:	float

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

as_non_alignment()[source]¶

Returns a copy of this rotation without it’s alignment nature.

Returns:	transform (`Rotation`) – A version of this rotation with the same transform behavior but without the alignment logic.

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.

axis_and_angle_of_rotation()¶

Abstract method for computing the axis and angle of rotation.

Returns:	axis ((D,) ndarray) – The unit vector representing the axis of rotation angle_of_rotation (double) – The angle in radians of the rotation about the axis. The angle is signed in a right handed sense.

compose_after(transform)¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this HomogFamilyAlignment.

Returns:	new_transform (`type(self)`) – A copy of this object

decompose()¶

A DiscreteAffine is already maximally decomposed - return a copy of self in a list.

Returns:	transform (`DiscreteAffine`) – Deep copy of self.

from_2d_ccw_angle(theta, degrees=True)¶

Convenience constructor for 2D CCW rotations about the origin

Parameters:	theta (float) – The angle of rotation about the origin degrees (bool, optional) – If `True` theta is interpreted as a degree. If `False`, theta is interpreted as radians.
Returns:	rotation (`Rotation`) – A 2D rotation transform.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	transform (`type(self)`) – An new instance of this class.

from_vector_inplace(p)¶

Returns an instance of the transform from the given parameters, expected to be in Fortran ordering.

Supports rebuilding from 2D parameter sets.

2D Rotation: 1 parameter:

[theta]

Parameters:	p ((1,) ndarray) – The array of parameters.
Returns:	transform (`Rotation2D`) – The transform initialised to the given parameters.

pseudoinverse()¶

The pseudoinverse of the transform - that is, the transform that results from swapping source and target, or more formally, negating the transforms parameters. If the transform has a true inverse this is returned instead.

Returns:	transform (`type(self)`) – The inverse of this transform.

pseudoinverse_vector(vector)¶

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()

Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters:	vector (`(n_parameters,)` ndarray) – A vectorized version of `self`
Returns:	pseudoinverse_vector (`(n_parameters,)` ndarray) – The pseudoinverse of the vector provided

set_h_matrix(value, copy=True, skip_checks=False)¶

Updates h_matrix, optionally performing sanity checks.

Note that it won’t always be possible to manually specify the h_matrix through this method, specifically if changing the h_matrix could change the nature of the transform. See h_matrix_is_mutable for how you can discover if the h_matrix is allowed to be set for a given class.

Parameters:	value (ndarray) – The new homogeneous matrix to set copy (bool, optional) – If False do not copy the h_matrix. Useful for performance. skip_checks (bool, optional) – If True skip checking. Useful for performance.
Raises:	`NotImplementedError` – If `h_matrix_is_mutable` returns `False`.

set_target(new_target)¶

Update this object so that it attempts to recreate the new_target.

Parameters:	new_target (`PointCloud`) – The new target that this object should try and regenerate.

composes_with¶: Any Homogeneous can compose with any other Homogeneous.

linear_component¶

The linear component of this affine transform.

Type:	`(n_dims, n_dims)` ndarray

n_dims¶

The number of dimensions of the target.

Type:	int

n_points¶

The number of points on the target.

Type:	int

rotation_matrix¶

The rotation matrix.

Type:	(D, D) ndarray

source¶

The source PointCloud that is used in the alignment.

The source is not mutable.

Type:	`PointCloud`

target¶

The current PointCloud that this object produces.

To change the target, use set_target().

Type:	`PointCloud`

translation_component¶

The translation component of this affine transform.

Type:	`(n_dims,)` ndarray

AlignmentTranslation¶

class menpo.transform.AlignmentTranslation(source, target)[source]¶

Bases: HomogFamilyAlignment, Translation

aligned_source()¶

The result of applying self to source

Type:	`PointCloud`

alignment_error()¶

The Frobenius Norm of the difference between the target and the aligned source.

Type:	float

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

as_non_alignment()[source]¶

Returns a copy of this translation without it’s alignment nature.

Returns:	transform (`Translation`) – A version of this transform with the same transform behavior but without the alignment logic.

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.

compose_after(transform)¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this HomogFamilyAlignment.

Returns:	new_transform (`type(self)`) – A copy of this object

decompose()¶

A DiscreteAffine is already maximally decomposed - return a copy of self in a list.

Returns:	transform (`DiscreteAffine`) – Deep copy of self.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	transform (`type(self)`) – An new instance of this class.

pseudoinverse()¶

The pseudoinverse of the transform - that is, the transform that results from swapping source and target, or more formally, negating the transforms parameters. If the transform has a true inverse this is returned instead.

Returns:	transform (`type(self)`) – The inverse of this transform.

pseudoinverse_vector(vector)¶

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()

Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters:	vector (`(n_parameters,)` ndarray) – A vectorized version of `self`
Returns:	pseudoinverse_vector (`(n_parameters,)` ndarray) – The pseudoinverse of the vector provided

set_h_matrix(value, copy=True, skip_checks=False)¶

Updates h_matrix, optionally performing sanity checks.

Note that it won’t always be possible to manually specify the h_matrix through this method, specifically if changing the h_matrix could change the nature of the transform. See h_matrix_is_mutable for how you can discover if the h_matrix is allowed to be set for a given class.

Parameters:	value (ndarray) – The new homogeneous matrix to set copy (bool, optional) – If False do not copy the h_matrix. Useful for performance. skip_checks (bool, optional) – If True skip checking. Useful for performance.
Raises:	`NotImplementedError` – If `h_matrix_is_mutable` returns `False`.

set_target(new_target)¶

Update this object so that it attempts to recreate the new_target.

Parameters:	new_target (`PointCloud`) – The new target that this object should try and regenerate.

composes_with¶: Any Homogeneous can compose with any other Homogeneous.

linear_component¶

The linear component of this affine transform.

Type:	`(n_dims, n_dims)` ndarray

n_dims¶

The number of dimensions of the target.

Type:	int

n_parameters¶

The number of parameters: n_dims

Type:	int

n_points¶

The number of points on the target.

Type:	int

source¶

The source PointCloud that is used in the alignment.

The source is not mutable.

Type:	`PointCloud`

target¶

The current PointCloud that this object produces.

To change the target, use set_target().

Type:	`PointCloud`

translation_component¶

The translation component of this affine transform.

Type:	`(n_dims,)` ndarray

AlignmentUniformScale¶

class menpo.transform.AlignmentUniformScale(source, target)[source]¶

Bases: HomogFamilyAlignment, UniformScale

aligned_source()¶

The result of applying self to source

Type:	`PointCloud`

alignment_error()¶

The Frobenius Norm of the difference between the target and the aligned source.

Type:	float

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

as_non_alignment()[source]¶

Returns a copy of this uniform scale without it’s alignment nature.

Returns:	transform (`UniformScale`) – A version of this scale with the same transform behavior but without the alignment logic.

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.

compose_after(transform)¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this HomogFamilyAlignment.

Returns:	new_transform (`type(self)`) – A copy of this object

decompose()¶

A DiscreteAffine is already maximally decomposed - return a copy of self in a list.

Returns:	transform (`DiscreteAffine`) – Deep copy of self.

from_vector(vector)¶

Build a new instance of the object from it’s vectorized state.

self is used to fill out the missing state required to rebuild a full object from it’s standardized flattened state. This is the default implementation, which is which is a deepcopy of the object followed by a call to from_vector_inplace(). This method can be overridden for a performance benefit if desired.

Parameters:	vector (`(n_parameters,)` ndarray) – Flattened representation of the object.
Returns:	transform (`type(self)`) – An new instance of this class.

pseudoinverse()¶

The pseudoinverse of the transform - that is, the transform that results from swapping source and target, or more formally, negating the transforms parameters. If the transform has a true inverse this is returned instead.

Returns:	transform (`type(self)`) – The inverse of this transform.

pseudoinverse_vector(vector)¶

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()

Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters:	vector (`(n_parameters,)` ndarray) – A vectorized version of `self`
Returns:	pseudoinverse_vector (`(n_parameters,)` ndarray) – The pseudoinverse of the vector provided

set_h_matrix(value, copy=True, skip_checks=False)¶

Updates h_matrix, optionally performing sanity checks.

Note that it won’t always be possible to manually specify the h_matrix through this method, specifically if changing the h_matrix could change the nature of the transform. See h_matrix_is_mutable for how you can discover if the h_matrix is allowed to be set for a given class.

Parameters:	value (ndarray) – The new homogeneous matrix to set copy (bool, optional) – If False do not copy the h_matrix. Useful for performance. skip_checks (bool, optional) – If True skip checking. Useful for performance.
Raises:	`NotImplementedError` – If `h_matrix_is_mutable` returns `False`.

set_target(new_target)¶

Update this object so that it attempts to recreate the new_target.

Parameters:	new_target (`PointCloud`) – The new target that this object should try and regenerate.

composes_with¶: Any Homogeneous can compose with any other Homogeneous.

linear_component¶

The linear component of this affine transform.

Type:	`(n_dims, n_dims)` ndarray

n_dims¶

The number of dimensions of the target.

Type:	int

n_parameters¶

The number of parameters: 1

Type:	int

n_points¶

The number of points on the target.

Type:	int

scale¶

The single scale value.

Type:	double

source¶

The source PointCloud that is used in the alignment.

The source is not mutable.

Type:	`PointCloud`

target¶

The current PointCloud that this object produces.

To change the target, use set_target().

Type:	`PointCloud`

translation_component¶

The translation component of this affine transform.

Type:	`(n_dims,)` ndarray

Group Alignments¶

GeneralizedProcrustesAnalysis¶

class menpo.transform.GeneralizedProcrustesAnalysis(sources, target=None)[source]¶

Bases: MultipleAlignment

Class for aligning multiple source shapes between them.

After construction, the AlignmentSimilarity transforms used to map each source optimally to the target can be found at transforms.

Parameters:	sources (list of `PointCloud`) – List of pointclouds to be aligned. target (`PointCloud`) – The target `PointCloud` to align each source to. If None, then the mean of the sources is used. Default: None Raises – ------- – ValueError – Need at least two sources to align

mean_aligned_shape()[source]¶

Returns the mean of the aligned shapes.

Type:	PointCloud

mean_alignment_error()[source]¶

Returns the average error of the recursive procrustes alignment.

Type:	float

Composite Transforms¶

TransformChain¶

class menpo.transform.TransformChain(transforms)[source]¶

Bases: ComposableTransform

A chain of transforms that can be efficiently applied one after the other.

This class is the natural product of composition. Note that objects may know how to compose themselves more efficiently - such objects implement the ComposableTransform or VComposable interfaces.

Parameters:	transforms (list of `Transform`) – The list of transforms to be applied. Note that the first transform will be applied first - the result of which is fed into the second transform and so on until the chain is exhausted.

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

compose_after(transform)¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

composes_inplace_with¶

The Transform s that this transform composes inplace with natively (i.e. no TransformChain will be produced).

An attempt to compose inplace against any type that is not an instance of this property on this class will result in an Exception.

Type:	`Transform` or tuple of `Transform` s

composes_with¶

The Transform s that this transform composes with natively (i.e. no TransformChain will be produced).

If native composition is not possible, falls back to producing a TransformChain.

By default, this is the same list as composes_inplace_with.

Type:	`Transform` or tuple of `Transform` s

n_dims¶

The dimensionality of the data the transform operates on.

None if the transform is not dimension specific.

Type:	int or `None`

n_dims_output¶

The output of the data from the transform.

None if the output of the transform is not dimension specific.

Type:	int or `None`

Radial Basis Functions¶

R2LogR2RBF¶

class menpo.transform.R2LogR2RBF(c)[source]¶

Bases: RadialBasisFunction

The \(r^2 \log{r^2}\) basis function.

The derivative of this function is \(2 r (\log{r^2} + 1)\).

Note

\(r = \lVert x - c \rVert\)

Parameters:	c ((n_centres, n_dims) ndarray) – The set of centers that make the basis. Usually represents a set of source landmarks.

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

compose_after(transform)¶

Returns a TransformChain that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

Parameters:	transform (`TransformChain`) – Transform to be applied before self Returns – -------- – transform – The resulting transform chain.

compose_before(transform)¶

Returns a TransformChain that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

Parameters:	transform (`TransformChain`) – Transform to be applied after self Returns – -------- – transform – The resulting transform chain.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

n_dims¶: The RBF can only be applied on points with the same dimensionality as the centres.

n_dims_output¶: The result of the transform has a dimension (weight) for every centre

R2LogRRBF¶

class menpo.transform.R2LogRRBF(c)[source]¶

Bases: RadialBasisFunction

Calculates the \(r^2 \log{r}\) basis function.

The derivative of this function is \(r (1 + 2 \log{r})\).

Note

\(r = \lVert x - c \rVert\)

Parameters:	c ((n_centres, n_dims) ndarray) – The set of centers that make the basis. Usually represents a set of source landmarks.

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

compose_after(transform)¶

Returns a TransformChain that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

Parameters:	transform (`TransformChain`) – Transform to be applied before self Returns – -------- – transform – The resulting transform chain.

compose_before(transform)¶

Returns a TransformChain that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

Parameters:	transform (`TransformChain`) – Transform to be applied after self Returns – -------- – transform – The resulting transform chain.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

n_dims¶: The RBF can only be applied on points with the same dimensionality as the centres.

n_dims_output¶: The result of the transform has a dimension (weight) for every centre

Abstract Bases¶

Transform¶

class menpo.transform.Transform[source]¶

Bases: Copyable

Abstract representation of any spatial transform.

Provides a unified interface to apply the transform with apply_inplace() and apply().

All Transforms support basic composition to form a TransformChain.

There are two useful forms of composition. Firstly, the mathematical composition symbol o has the following definition:

let a(x) and b(x) be two transforms on x.
(a o b)(x) == a(b(x))

This functionality is provided by the compose_after() family of .. method:: (a.compose_after(b)).apply(x) == a.apply(b.apply(x))

Equally useful is an inversion the order of composition - so that over time a large chain of transforms can be built to do a useful job, and composing on this chain adds another transform to the end (after all other preceding transforms have been performed).

For instance, let’s say we want to rescale a PointCloud p around it’s mean, and then translate it some place else. It would be nice to be able to do something like:

t = Translation(-p.centre)  # translate to centre
s = Scale(2.0)  # rescale
move = Translate([10, 0 ,0])  # budge along the x axis
t.compose(s).compose(-t).compose(move)

In Menpo, this functionality is provided by the compose_before() family of methods:

(a.compose_before(b)).apply(x) == b.apply(a.apply(x))

For native composition, see the ComposableTransform subclass and the VComposable mix-in. For inversion, see the Invertible and VInvertible mix-ins. For alignment, see the Alignment mix-in.

apply(x, **kwargs)[source]¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)[source]¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

compose_after(transform)[source]¶

Returns a TransformChain that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

Parameters:	transform (`TransformChain`) – Transform to be applied before self Returns – -------- – transform – The resulting transform chain.

compose_before(transform)[source]¶

Returns a TransformChain that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

Parameters:	transform (`TransformChain`) – Transform to be applied after self Returns – -------- – transform – The resulting transform chain.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

n_dims¶

The dimensionality of the data the transform operates on.

None if the transform is not dimension specific.

Type:	int or `None`

n_dims_output¶

The output of the data from the transform.

None if the output of the transform is not dimension specific.

Type:	int or `None`

Transformable¶

class menpo.transform.base.Transformable[source]¶

Bases: Copyable

Interface for objects that know how be transformed by the Transform interface.

When Transform.apply_inplace is called on an object, the _transform_inplace() method is called, passing in the transforms’ _apply() function.

This allows for the object to define how it should transform itself.

_transform_inplace(transform)[source]¶

Apply the given transform function to self inplace.

Parameters:	transform (function) – Function that applies a transformation to the transformable object.
Returns:	transformed (`type(self)`) – The transformed object, having been transformed in place.

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

ComposableTransform¶

class menpo.transform.base.composable.ComposableTransform[source]¶

Bases: Transform

Transform subclass that enables native composition, such that the behavior of multiple Transform s is composed together in a natural way.

_compose_after_inplace(transform)[source]¶

Specialised inplace composition. This should be overridden to provide specific cases of composition as defined in composes_inplace_with.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`

_compose_before_inplace(transform)[source]¶

Specialised inplace composition. This should be overridden to provide specific cases of composition as defined in composes_inplace_with.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`

apply(x, **kwargs)¶

Applies this transform to x.

If x is Transformable, x will be handed this transform object to transform itself non-destructively (a transformed copy of the object will be returned).

If not, x is assumed to be an ndarray. The transformation will be non-destructive, returning the transformed version.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable` or `(n_points, n_dims)` ndarray) – The array or object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object or array

apply_inplace(x, **kwargs)¶

Applies this transform to a Transformable x destructively.

Any kwargs will be passed to the specific transform _apply() method.

Parameters:	x (`Transformable`) – The `Transformable` object to be transformed. kwargs (dict) – Passed through to `_apply()`.
Returns:	transformed (`type(x)`) – The transformed object

compose_after(transform)[source]¶

A Transform that represents this transform composed after the given transform:

c = a.compose_after(b)
c.apply(p) == a.apply(b.apply(p))

a and b are left unchanged.

This corresponds to the usual mathematical formalism for the compose operator, o.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied before `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_after_inplace(transform)[source]¶

Update self so that it represents this transform composed after the given transform:

a_orig = a.copy()
a.compose_after_inplace(b)
a.apply(p) == a_orig.apply(b.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied before `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

compose_before(transform)[source]¶

A Transform that represents this transform composed before the given transform:

c = a.compose_before(b)
c.apply(p) == b.apply(a.apply(p))

a and b are left unchanged.

An attempt is made to perform native composition, but will fall back to a TransformChain as a last resort. See composes_with for a description of how the mode of composition is decided.

Parameters:	transform (`Transform` or `TransformChain`) – Transform to be applied after `self` Returns – -------- – transform – If the composition was native, a single new `Transform` will be returned. If not, a `TransformChain` is returned instead.

compose_before_inplace(transform)[source]¶

Update self so that it represents this transform composed before the given transform:

a_orig = a.copy()
a.compose_before_inplace(b)
a.apply(p) == b.apply(a_orig.apply(p))

a is permanently altered to be the result of the composition. b is left unchanged.

Parameters:	transform (`composes_inplace_with`) – Transform to be applied after `self`
Raises:	`ValueError` – If `transform` isn’t an instance of `composes_inplace_with`

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

composes_inplace_with¶

The Transform s that this transform composes inplace with natively (i.e. no TransformChain will be produced).

An attempt to compose inplace against any type that is not an instance of this property on this class will result in an Exception.

Type:	`Transform` or tuple of `Transform` s

composes_with¶

The Transform s that this transform composes with natively (i.e. no TransformChain will be produced).

If native composition is not possible, falls back to producing a TransformChain.

By default, this is the same list as composes_inplace_with.

Type:	`Transform` or tuple of `Transform` s

n_dims¶

The dimensionality of the data the transform operates on.

None if the transform is not dimension specific.

Type:	int or `None`

n_dims_output¶

The output of the data from the transform.

None if the output of the transform is not dimension specific.

Type:	int or `None`

Invertible¶

class menpo.transform.base.invertible.Invertible[source]¶

Bases: object

Mix-in for invertible transforms. Provides an interface for taking the psuedo or true inverse of a transform.

Has to be implemented in conjunction with Transform.

pseudoinverse()[source]¶

The pseudoinverse of the transform - that is, the transform that results from swapping source and target, or more formally, negating the transforms parameters. If the transform has a true inverse this is returned instead.

Type:	`type(self)`

has_true_inverse¶

True if the pseudoinverse is an exact inverse.

Type:	bool

Alignment¶

class menpo.transform.base.alignment.Alignment(source, target)[source]¶

Bases: Targetable, Viewable

Mix-in for Transform that have been constructed from an optimisation aligning a source PointCloud to a target PointCloud.

This is naturally an extension of the Targetable interface - we just augment Targetable with the concept of a source, and related methods to construct alignments between a source and a target.

Note that to inherit from Alignment, you have to be a Transform subclass first.

Parameters:	source (`PointCloud`) – A PointCloud that the alignment will be based from target (`PointCloud`) – A PointCloud that the alignment is targeted towards

aligned_source()[source]¶

The result of applying self to source

Type:	`PointCloud`

alignment_error()[source]¶

The Frobenius Norm of the difference between the target and the aligned source.

Type:	float

copy()¶

Generate an efficient copy of this object.

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

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

Returns:	`type(self)` – A copy of this object

set_target(new_target)¶

Update this object so that it attempts to recreate the new_target.

Parameters:	new_target (`PointCloud`) – The new target that this object should try and regenerate.

n_dims¶

The number of dimensions of the target.

Type:	int

n_points¶

The number of points on the target.

Type:	int

source¶

The source PointCloud that is used in the alignment.

The source is not mutable.

Type:	`PointCloud`

target¶

The current PointCloud that this object produces.

To change the target, use set_target().

Type:	`PointCloud`

MultipleAlignment¶

class menpo.transform.groupalign.base.MultipleAlignment(sources, target=None)[source]¶

Bases: object

Abstract base class for aligning multiple source shapes to a target shape.

Parameters:	sources (list of `PointCloud`) – List of pointclouds to be aligned. target (`PointCloud`) – The target `PointCloud` to align each source to. If None, then the mean of the sources is used. Default: None Raises – ------- – ValueError – Need at least two sources to align

DiscreteAffine¶

class menpo.transform.homogeneous.affine.DiscreteAffine[source]¶

Bases: object

A discrete Affine transform operation (such as a Scale(), Translation or Rotation()). Has to be able to invertable. Make sure you inherit from DiscreteAffine first, for optimal decompose() behavior.

decompose()[source]¶

A DiscreteAffine is already maximally decomposed - return a copy of self in a list.

Returns:	transform (`DiscreteAffine`) – Deep copy of self.

Performance Specializations¶

Mix-ins that provide fast vectorized varients of methods.

VComposable¶

class menpo.transform.base.composable.VComposable[source]¶

Bases: object

Mix-in for Vectorizable ComposableTransform s.

Use this mix-in with ComposableTransform if the ComposableTransform in question is Vectorizable as this adds from_vector() variants to the ComposableTransform interface. These can be tuned for performance.

compose_after_from_vector_inplace(vector)[source]¶

Specialised inplace composition with a vector. This should be overridden to provide specific cases of composition whereby the current state of the transform can be derived purely from the provided vector.

Parameters:	vector (`(n_parameters,)` ndarray) – Vector to update the transform state with.

VInvertible¶

class menpo.transform.base.invertible.VInvertible[source]¶

Bases: Invertible

Mix-in for Vectorizable Invertible Transform s.

Prefer this mix-in over Invertible if the Transform in question is Vectorizable as this adds from_vector() variants to the Invertible interface. These can be tuned for performance, and are, for instance, needed by some of the machinery of fit.

pseudoinverse()¶

The pseudoinverse of the transform - that is, the transform that results from swapping source and target, or more formally, negating the transforms parameters. If the transform has a true inverse this is returned instead.

Type:	`type(self)`

pseudoinverse_vector(vector)[source]¶

The vectorized pseudoinverse of a provided vector instance. Syntactic sugar for:

self.from_vector(vector).pseudoinverse().as_vector()

Can be much faster than the explict call as object creation can be entirely avoided in some cases.

Parameters:	vector (`(n_parameters,)` ndarray) – A vectorized version of `self`
Returns:	pseudoinverse_vector (`(n_parameters,)` ndarray) – The pseudoinverse of the vector provided

has_true_inverse¶

True if the pseudoinverse is an exact inverse.

Type:	bool

`menpo.visualize`¶

Abstract Classes¶

Renderer¶

class menpo.visualize.Renderer(figure_id, new_figure)[source]¶

Bases: object

Abstract class for rendering visualizations. Framework specific implementations of these classes are made in order to separate implementation cleanly from the rest of the code.

It is assumed that the renderers follow some form of stateful pattern for rendering to Figures. Therefore, the major interface for rendering involves providing a figure_id or a bool about whether a new figure should be used. If neither are provided then the default state of the rendering engine is assumed to be maintained.

Providing both a figure_id and new_figure == True is not a valid state.

Parameters:	figure_id (object) – A figure id. Could be any valid object that identifies a figure in a given framework (str, int, float, etc.). new_figure (bool) – Whether the rendering engine should create a new figure.
Raises:	`ValueError` – It is not valid to provide a figure id AND request a new figure to be rendered on.

get_figure()[source]¶

Abstract method for getting the correct figure to render on. Should also set the correct figure_id for the figure.

Returns:	figure (object) – The figure object that the renderer will render on.

render(**kwargs)[source]¶

Abstract method to be overridden by the renderer. This will implement the actual rendering code for a given object class.

Parameters:	kwargs (dict) – Passed through to specific rendering engine.
Returns:	viewer (`Renderer`) – Pointer to self.

save_figure(**kwargs)[source]¶

Abstract method for saving the figure of the current figure_id to file. It will implement the actual saving code for a given object class.

Parameters:	kwargs (dict) – Options to be set when saving the figure to file.

Viewable¶

class menpo.visualize.Viewable[source]¶

Bases: object

Abstract interface for objects that can visualize themselves. This assumes that the class has dimensionality as the view method checks the n_dims property to wire up the correct view method.

LandmarkableViewable¶

class menpo.visualize.LandmarkableViewable[source]¶

Bases: object

Mixin for Landmarkable and Viewable objects. Provides a single helper method for viewing Landmarks and self on the same figure.

MatplotlibRenderer¶

class menpo.visualize.MatplotlibRenderer(figure_id, new_figure)[source]¶

Bases: Renderer

Abstract class for rendering visualizations using Matplotlib.

Parameters:	figure_id (int or `None`) – A figure id or `None`. `None` assumes we maintain the Matplotlib state machine and use plt.gcf(). new_figure (bool) – If `True`, it creates a new figure to render on.

get_figure()[source]¶

Gets the figure specified by the combination of self.figure_id and self.new_figure. If self.figure_id == None then plt.gcf() is used. self.figure_id is also set to the correct id of the figure if a new figure is created.

Returns:	figure (Matplotlib figure object) – The figure we will be rendering on.

render(**kwargs)¶

Abstract method to be overridden by the renderer. This will implement the actual rendering code for a given object class.

Parameters:	kwargs (dict) – Passed through to specific rendering engine.
Returns:	viewer (`Renderer`) – Pointer to self.

save_figure(filename, format='png', dpi=None, face_colour='w', edge_colour='w', orientation='portrait', paper_type='letter', transparent=False, pad_inches=0.1, overwrite=False)[source]¶

Method for saving the figure of the current figure_id to file.

Parameters:

filename (str or file-like object) – The string path or file-like object to save the figure at/into.
format (str) – The format to use. This must match the file path if the file path is a str.
dpi (int > 0 or None, optional) – The resolution in dots per inch.

face_colour (See Below, optional) –

The face colour of the figure rectangle. Example options

{``r``, ``g``, ``b``, ``c``, ``m``, ``k``, ``w``}
or
``(3, )`` `ndarray`
or
`list` of len 3

edge_colour (See Below, optional) –

The edge colour of the figure rectangle. Example options

{``r``, ``g``, ``b``, ``c``, ``m``, ``k``, ``w``}
or
``(3, )`` `ndarray`
or
`list` of len 3

orientation ({portrait, landscape}, optional) – The page orientation.

paper_type (See Below, optional) –

The type of the paper. Example options

{``letter``, ``legal``, ``executive``, ``ledger``,
 ``a0`` through ``a10``, ``b0` through ``b10``}

transparent (bool, optional) – If True, the axes patches will all be transparent; the figure patch will also be transparent unless face_colour and/or edge_colour are specified. This is useful, for example, for displaying a plot on top of a coloured background on a web page. The transparency of these patches will be restored to their original values upon exit of this function.
pad_inches (float, optional) – Amount of padding around the figure.
overwrite (bool, optional) – If True, the file will be overwritten if it already exists.

save_figure_widget(popup=True)[source]¶

Method for saving the figure of the current figure_id to file using menpo.visualize.widgets.base.save_matplotlib_figure() widget.

Parameters:	popup (bool, optional) – If `True`, the widget will appear as a popup window.

Widgets¶

visualize_images¶

menpo.visualize.visualize_images(images, figure_size=(10, 8), popup=False, browser_style='buttons')[source]¶

Widget that allows browsing through a list of Image (or subclass) objects.

The images can have a combination of different attributes, e.g. masked or not, landmarked or not, without multiple landmark groups and labels etc. The widget has options tabs regarding the visualized channels, the landmarks, the renderer (lines, markers, numbering, legend, figure, axes) and saving the figure to file.

Parameters:

images (list of Image or subclass) – The list of images to be visualized.
figure_size ((int, int), optional) – The initial size of the rendered figure.
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.

visualize_landmarks¶

menpo.visualize.visualize_landmarks(landmarks, figure_size=(10, 8), popup=False, browser_style='buttons')[source]¶

Widget that allows browsing through a list of LandmarkManager (or subclass) objects.

The managers can have a combination of different attributes, e.g. different landmark groups and labels etc. The widget has options tabs regarding the landmarks, the renderer (lines, markers, numbering, legend, figure, axes) and saving the figure to file.

Parameters:

landmarks (list of LandmarkManager or subclass) – The list of landmark managers to be visualized.
figure_size ((int, int), optional) – The initial size of the rendered figure.
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 landmark managers will have the form of plus/minus buttons or a slider.

visualize_landmarkgroups¶

menpo.visualize.visualize_landmarkgroups(landmarkgroups, figure_size=(10, 8), popup=False, browser_style='buttons')[source]¶

Widget that allows browsing through a list of LandmarkGroup (or subclass) objects.

The landmark groups can have a combination of different attributes, e.g. different labels, number of points etc. The widget has options tabs regarding the landmarks, the renderer (lines, markers, numbering, legend, figure, axes) and saving the figure to file.

Parameters:

landmarkgroups (list of LandmarkGroup or subclass) – The list of landmark groups to be visualized.
figure_size ((int, int), optional) – The initial size of the rendered figure.
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 landmark managers will have the form of plus/minus buttons or a slider.

visualize_pointclouds¶

menpo.visualize.visualize_pointclouds(pointclouds, figure_size=(10, 8), popup=False, browser_style='buttons')[source]¶

Widget that allows browsing through a list of PointCloud, PointGraph or TriMesh or subclasses.

The widget has options tabs regarding the renderer (lines, markers, figure, axes) and saving the figure to file.

Parameters:

pointclouds (list of PointCloud or PointGraph or TriMesh or subclasses) – The list of objects to be visualized.
figure_size ((int, int), optional) – The initial size of the rendered figure.
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 objects will have the form of plus/minus buttons or a slider.

features_selection¶

menpo.visualize.features_selection(popup=True)[source]¶

Widget that allows selecting a features function and its options. The widget supports all features from menpo.feature and has a preview tab. It returns a list of length 1 with the selected features function closure.

Parameters:	popup (bool, optional) – If `True`, the widget will appear as a popup window.
Returns:	features_function (list of length `1`) – The function closure of the features function using functools.partial. So the function can be called as: features_image = features_function[0](image)

save_matplotlib_figure¶

menpo.visualize.save_matplotlib_figure(renderer, popup=True)[source]¶

Widget that allows to save a figure, which was generated with Matplotlib, to file.

Parameters:	renderer (`MatplotlibRenderer`) – The Matplotlib renderer object. popup (bool, optional) – If `True`, the widget will appear as a popup window.

Print Utilities¶

print_dynamic¶

menpo.visualize.print_dynamic(str_to_print)[source]¶

Prints dynamically the provided str, i.e. the str is printed and then the buffer gets flushed.

Parameters:	str_to_print (str) – The string to print.

progress_bar_str¶

menpo.visualize.progress_bar_str(percentage, bar_length=20, bar_marker='=', show_bar=True)[source]¶

Returns an str of the specified progress percentage. The percentage is represented either in the form of a progress bar or in the form of a percentage number. It can be combined with the print_dynamic() function.

Parameters:	percentage (float) – The progress percentage to be printed. It must be in the range `[0, 1]`. bar_length (int, optional) – Defines the length of the bar in characters. bar_marker (str, optional) – Defines the marker character that will be used to fill the bar. show_bar (bool, optional) – If `True`, the str includes the bar followed by the percentage, e.g. `'[===== ] 50%'` If `False`, the str includes only the percentage, e.g. `'50%'`
Returns:	progress_str (str) – The progress percentage string that can be printed.
Raises:	`ValueError` – `percentage` is not in the range `[0, 1]` `ValueError` – `bar_length` must be an integer >= `1` `ValueError` – `bar_marker` must be a string of length 1

Examples

This for loop:

n_iters = 2000
for k in range(n_iters):
    print_dynamic(progress_bar_str(float(k) / (n_iters-1)))

prints a progress bar of the form:

[=============       ] 68%

print_bytes¶

menpo.visualize.print_bytes(num)[source]¶

Converts bytes to a sensible format to be printed. For example:

print_bytes(12345) returns '12.06 KB'
print_bytes(123456789) returns '117.74 MB'

Parameters:	num (int) – The size in bytes.
Raises:	`ValueError` – num must be int >= 0

Welcome¶

User Guide¶

Quick Start¶

Basic Installation¶

API Documentation¶

Notebooks¶

User Group and Issues¶

Introduction¶

Core Interfaces¶

Data containers¶

Menpo’s Data Types¶

Why have data types - what’s wrong with numpy arrays?¶

Key points¶

Working with Images and PointClouds¶

Menpo’s approach¶

Key Points¶

Vectorizing Objects¶

Key points¶

Visualizing Objects¶

Visualizing 2D Images¶

Visualizing A List Of 2D Images¶

Visualizing A 2D PointCloud¶

Visualizing In 3D¶

Changelog¶

0.4.0 (2015/02/04)¶

Github Pull Requests¶

v0.4.0a2 (2014/12/03)¶

Github Pull Requests¶

v0.4.0a1 (2014/10/31)¶

Github Pull Requests¶

v0.3.0 (2014/05/27)¶

Github Pull Requests¶

The Menpo API¶

menpo.base¶

Core¶

Copyable¶

Vectorizable¶

Targetable¶

Convenience¶

menpo_src_dir_path¶

menpo.io¶

Input¶

import_image¶

import_images¶

import_landmark_file¶

import_landmark_files¶

import_pickle¶

import_pickles¶

import_builtin_asset¶

Output¶

export_image¶

export_landmark_file¶

export_pickle¶

Path Operations¶

image_paths¶

landmark_file_paths¶

data_path_to¶

data_dir_path¶

ls_builtin_assets¶

menpo.image¶

Image Types¶

Image¶

BooleanImage¶

MaskedImage¶

Exceptions¶

ImageBoundaryError¶

menpo.feature¶

Features¶

no_op¶

gradient¶

gaussian_filter¶

igo¶

es¶

lbp¶

hog¶

daisy¶

Widget¶

features_selection_widget¶

menpo.landmark¶

Abstract Classes¶

`menpo.base`¶

`menpo.io`¶

`menpo.image`¶

`menpo.feature`¶

`menpo.landmark`¶

`menpo.math`¶

`menpo.model`¶

`menpo.shape`¶