PointCloud¶

class
menpo.shape.
PointCloud
(points, copy=True)[source]¶ Bases:
Shape
An Ndimensional 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 Ccontiguous  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=5, marker_face_colour='r', marker_edge_colour='k', marker_edge_width=1.0, render_numbering=False, numbers_horizontal_align='center', numbers_vertical_align='bottom', numbers_font_name='sansserif', numbers_font_size=10, numbers_font_style='normal', numbers_font_weight='normal', numbers_font_colour='k', render_axes=True, axes_font_name='sansserif', axes_font_size=10, axes_font_style='normal', axes_font_weight='normal', axes_x_limits=None, axes_y_limits=None, axes_x_ticks=None, axes_y_ticks=None, figure_size=(7, 7), 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_markers (bool, optional) – If
True
, the markers will be rendered.  marker_style (See Below, optional) –
The style of the markers. Example options
{., ,, o, v, ^, <, >, +, x, D, d, s, p, *, h, H, 1, 2, 3, 4, 8}
 marker_size (int, optional) – The size of the markers in points.
 marker_face_colour (See Below, optional) – The face (filling) colour of the markers.
Example options
{r, g, b, c, m, k, w} or (3, ) ndarray
 marker_edge_colour (See Below, optional) – The edge colour of the markers.
Example options
{r, g, b, c, m, k, w} or (3, ) ndarray
 marker_edge_width (float, optional) – The width of the markers’ edge.
 render_numbering (bool, optional) – If
True
, the landmarks will be numbered.  numbers_horizontal_align (
{center, right, left}
, optional) – The horizontal alignment of the numbers’ texts.  numbers_vertical_align (
{center, top, bottom, baseline}
, optional) – The vertical alignment of the numbers’ texts.  numbers_font_name (See Below, optional) –
The font of the numbers. Example options
{serif, sansserif, 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_axes (bool, optional) – If
True
, the axes will be rendered.  axes_font_name (See Below, optional) – The font of the axes.
Example options
{serif, sansserif, cursive, fantasy, monospace}
 axes_font_size (int, optional) – The font size of the axes.
 axes_font_style ({
normal
,italic
,oblique
}, optional) – The font style of the axes.  axes_font_weight (See Below, optional) – The font weight of the axes.
Example options
{ultralight, light, normal, regular, book, medium, roman, semibold, demibold, demi, bold, heavy, extra bold, black}
 axes_x_limits (float or (float, float) or
None
, optional) – The limits of the x axis. If float, then it sets padding on the right and left of the PointCloud as a percentage of the PointCloud’s width. If tuple or list, then it defines the axis limits. IfNone
, then the limits are set automatically.  axes_y_limits ((float, float) tuple or
None
, optional) – The limits of the y axis. If float, then it sets padding on the top and bottom of the PointCloud as a percentage of the PointCloud’s height. If tuple or list, then it defines the axis limits. IfNone
, then the limits are set automatically.  axes_x_ticks (list or tuple or
None
, optional) – The ticks of the x axis.  axes_y_ticks (list or tuple or
None
, optional) – The ticks of the y axis.  figure_size ((float, float) tuple or
None
, optional) – The size of the figure in inches.  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_markers=True, marker_style='s', marker_size=7, marker_face_colour='k', marker_edge_colour='k', marker_edge_width=1.0, render_lines_lms=True, line_colour_lms=None, line_style_lms='', line_width_lms=1, render_markers_lms=True, marker_style_lms='o', marker_size_lms=5, marker_face_colour_lms=None, marker_edge_colour_lms=None, marker_edge_width_lms=1.0, render_numbering=False, numbers_horizontal_align='center', numbers_vertical_align='bottom', numbers_font_name='sansserif', numbers_font_size=10, numbers_font_style='normal', numbers_font_weight='normal', numbers_font_colour='k', render_legend=False, legend_title='', legend_font_name='sansserif', 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='sansserif', axes_font_size=10, axes_font_style='normal', axes_font_weight='normal', axes_x_limits=None, axes_y_limits=None, axes_x_ticks=None, axes_y_ticks=None, figure_size=(7, 7))[source]¶ Visualize the landmarks. This method will appear on the PointCloud as
view_landmarks
.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 notNone
, only show the given label(s). Should not be used with thewithout_labels
kwarg.  without_labels (
None
or str or list of str, optional) – If notNone
, show all except the given label(s). Should not be used with thewith_labels
kwarg.  figure_id (object, optional) – The id of the figure to be used.
 new_figure (bool, optional) – If
True
, a new figure is created.  image_view (bool, optional) – If
True
the PointCloud will be viewed as if it is in the image coordinate system.  render_markers (bool, optional) – If
True
, the markers will be rendered.  marker_style (See Below, optional) –
The style of the markers. Example options
{., ,, o, v, ^, <, >, +, x, D, d, s, p, *, h, H, 1, 2, 3, 4, 8}
 marker_size (int, optional) – The size of the markers in points.
 marker_face_colour (See Below, optional) –
The face (filling) colour of the markers. Example options
{r, g, b, c, m, k, w} or (3, ) ndarray
 marker_edge_colour (See Below, optional) –
The edge colour of the markers. Example options
{r, g, b, c, m, k, w} or (3, ) ndarray
 marker_edge_width (float, optional) – The width of the markers’ edge.
 render_lines_lms (bool, optional) – If
True
, the edges of the landmarks will be rendered.  line_colour_lms (See Below, optional) –
The colour of the lines of the landmarks. Example options:
{r, g, b, c, m, k, w} or (3, ) ndarray
 line_style_lms (
{, , ., :}
, optional) – The style of the lines of the landmarks.  line_width_lms (float, optional) – The width of the lines of the landmarks.
 render_markers – If
True
, the markers of the landmarks will be rendered.  marker_style –
The style of the markers of the landmarks. Example options
{., ,, o, v, ^, <, >, +, x, D, d, s, p, *, h, H, 1, 2, 3, 4, 8}
 marker_size – The size of the markers of the landmarks in points.
 marker_face_colour –
The face (filling) colour of the markers of the landmarks. Example options
{r, g, b, c, m, k, w} or (3, ) ndarray
 marker_edge_colour –
The edge colour of the markers of the landmarks. Example options
{r, g, b, c, m, k, w} or (3, ) ndarray
 marker_edge_width – The width of the markers’ edge of the landmarks.
 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, sansserif, 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, sansserif, 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, sansserif, cursive, fantasy, monospace}
 axes_font_size (int, optional) – The font size of the axes.
 axes_font_style (
{normal, italic, oblique}
, optional) – The font style of the axes.  axes_font_weight (See Below, optional) –
The font weight of the axes. Example options
{ultralight, light, normal, regular, book, medium, roman, semibold,demibold, demi, bold, heavy, extra bold, black}
 axes_x_limits (float or (float, float) or
None
, optional) – The limits of the x axis. If float, then it sets padding on the right and left of the PointCloud as a percentage of the PointCloud’s width. If tuple or list, then it defines the axis limits. IfNone
, then the limits are set automatically.  axes_y_limits ((float, float) tuple or
None
, optional) – The limits of the y axis. If float, then it sets padding on the top and bottom of the PointCloud as a percentage of the PointCloud’s height. If tuple or list, then it defines the axis limits. IfNone
, then the limits are set automatically.  axes_x_ticks (list or tuple or
None
, optional) – The ticks of the x axis.  axes_y_ticks (list or tuple or
None
, optional) – The ticks of the y axis.  figure_size ((float, float) tuple or
None
optional) – The size of the figure in inches.
Raises: ValueError
– If bothwith_labels
andwithout_labels
are passed.ValueError
– If the landmark manager doesn’t contain the provided group label.
 group (str or``None`` optional) – The landmark group to be visualized. If

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 a bounding box from two corner points as a directed graph. In the case of a 2D pointcloud, first point (0) should be nearest the origin. In the case of an image, this ordering would appear as:
0<3  ^   v  1>2
In the case of a pointcloud, the ordering will appear as:
3<2  ^   v  0>1
In the case of a 3D pointcloud, the first point (0) should be the near closest to the origin and the second point is the far opposite corner.
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 thePointCloud
and boundary along each dimension  max_b (
(n_dims,)
ndarray) – The maximum extent of thePointCloud
and boundary along each dimension
 min_b (

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.

constrain_to_bounds
(bounds)[source]¶ Returns a copy of this PointCloud, constrained to lie exactly within the given bounds. Any points outside the bounds will be ‘snapped’ to lie exactly on the boundary.
Parameters: bounds ( (n_dims, n_dims)
tuple of scalars) – The bounds to constrain this pointcloud within.Returns: constrained ( PointCloud
) – The constrained pointcloud.

copy
()¶ Generate an efficient copy of this object.
Note that Numpy arrays and other
Copyable
objects onself
will be deeply copied. Dictionaries and sets will be shallow copied, and everything else will be assigned (no copy will be made).Classes that store state other than numpy arrays and immutable types should overwrite this method to ensure all state is copied.
Returns: type(self)
– A copy of this object

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 booleansReturns: 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 adeepcopy
of the object followed by a call tofrom_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)¶ Deprecated. Use the nonmutating API,
from_vector
.For internal usage in performancesensitive spots, see _from_vector_inplace()
Parameters: vector ( (n_parameters,)
ndarray) – Flattened representation of this object

h_points
()[source]¶ Convert poincloud to a homogeneous array:
(n_dims + 1, n_points)
Type: type(self)

has_nan_values
()¶ Tests if the vectorized form of the object contains
nan
values or not. This is particularly useful for objects with unknown values that have been mapped tonan
values.Returns: has_nan_values (bool) – If the vectorized object contains nan
values.

classmethod
init_2d_grid
(shape, spacing=None)[source]¶ Create a pointcloud that exists on a regular 2D grid. The first dimension is the number of rows in the grid and the second dimension of the shape is the number of columns.
spacing
optionally allows the definition of the distance between points (uniform over points). The spacing may be different for rows and columns.Parameters:  shape (tuple of 2 int) – The size of the grid to create, this defines the number of points across each dimension in the grid. The first element is the number of rows and the second is the number of columns.
 spacing (int or tuple of 2 int, optional) – The spacing between points. If a single int is provided, this
is applied uniformly across each dimension. If a tuple is
provided, the spacing is applied nonuniformly as defined e.g.
(2, 3)
gives a spacing of 2 for the rows and 3 for the columns.
Returns: shape_cls (type(cls)) – A PointCloud or subclass arranged in a grid.

classmethod
init_from_depth_image
(depth_image)[source]¶ Return a 3D point cloud from the given depth image. The depth image is assumed to represent height/depth values and the XY coordinates are assumed to unit spaced and represent image coordinates. This is particularly useful for visualising depth values that have been recovered from images.
Parameters: depth_image ( Image
or subclass) – A single channel image that contains depth values  as commonly returned by RGBD cameras, for example.Returns: depth_cloud ( type(cls)
) – A new 3D PointCloud with unit XY coordinates and the given depth values as Z coordinates.

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

with_dims
(dims)[source]¶ Return a copy of this shape with only particular dimensions retained.
Parameters: dims (valid numpy array slice) – The slice that will be used on the dimensionality axis of the shape under transform. For example, to go from a 3D shape to a 2D one, [0, 1] could be provided or np.array([True, True, False]). Returns: copy of self, with only the requested dims

has_landmarks
¶ Whether the object has landmarks.
Type: bool

landmarks
¶ The landmarks object.
Type: LandmarkManager

lms
¶ Deprecated. Maintained for compatibility, will be removed in a future version. Returns a copy of this object, which previously would have held the ‘underlying’
PointCloud
subclass.Type: self

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