diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py index 5e56c8737f76..bcaba10d35cd 100644 --- a/lib/matplotlib/patches.py +++ b/lib/matplotlib/patches.py @@ -154,10 +154,47 @@ def contains(self, mouseevent, radius=None): def contains_point(self, point, radius=None): """ - Returns ``True`` if the given *point* is inside the path - (transformed with its transform attribute). + Return whether the given point is inside the patch. + + Parameters + ---------- + point : (float, float) + The point (x, y) to check in target coordinates of + ``self.get_transform()``. For patches added to a figure or axes, + these are display coordinates. + radius : float, optional + Adds an additional margin on the patch in coordinates of transform. + target. See `.Path.contains_point` for further details. + + Returns + ------- + bool + + Notes + ----- + The proper use of this method depends on the transform of the patch. + Isolated patches do not have a transform. In this, the patch creation + coordinates and the point coordinates match. The follow checks that + the center of a circle is within the circle + + >>> center = 0, 0 + >>> c = Circle(center, radius=1) + >>> c.contains_point(center) + True + + The convention of checking against the transformed patch stems from + the fact that this method is predominantly used to check if display + coordinates (e.g. from mouse events) are within the patch. If you want + to do the above check with data coordinates, you have to properly + transform them first: + + >>> center = 0, 0 + >>> c = Circle(center, radius=1) + >>> plt.gca().add_patch(c) + >>> transformed_center = c.get_transform().transform(center) + >>> c.contains_point(transformed_center) + True - *radius* allows the path to be made slightly larger or smaller. """ radius = self._process_radius(radius) return self.get_path().contains_point(point, @@ -166,12 +203,26 @@ def contains_point(self, point, radius=None): def contains_points(self, points, radius=None): """ - Returns a bool array which is ``True`` if the (closed) path - contains the corresponding point. - (transformed with its transform attribute). + Return whether the given points are inside the patch. - *points* must be Nx2 array. - *radius* allows the path to be made slightly larger or smaller. + Parameters + ---------- + points : (N, 2) array + The points to check in target coordinates of + ``self.get_transform()``. For patches added to a figure or axes, + these are display coordinates. Columns contain x and y values. + radius : float, optional + Adds an additional margin on the patch in coordinates of transform. + target. See `.Path.contains_points` for further details. + + Returns + ------- + length-N bool array + + Notes + ----- + The proper use of this method depends on the transform of the patch. + See the notes on `.Patch.contains_point`. """ radius = self._process_radius(radius) return self.get_path().contains_points(points, diff --git a/lib/matplotlib/path.py b/lib/matplotlib/path.py index b3c745b75bd1..69af3d4c2fbb 100644 --- a/lib/matplotlib/path.py +++ b/lib/matplotlib/path.py @@ -450,12 +450,27 @@ def transformed(self, transform): def contains_point(self, point, transform=None, radius=0.0): """ - Returns whether the (closed) path contains the given point. + Return whether the (closed) path contains the given point. - If *transform* is not ``None``, the path will be transformed before - performing the test. - - *radius* allows the path to be made slightly larger or smaller. + Parameters + ---------- + point : (float, float) + The point (x, y) to check. + transform : `matplotlib.transforms.Transform`, optional + If not ``None``, *point* will be compared to self transformed + by *transform*; i.e. for a correct check, *transform* should + transform the path into the coordinate system of *point*. + radius : float, default: 0. + Adds an additional margin on the path in coordinates of *point*. + The path is extended tangentially by *radius/2*; i.e. if you would + draw the path with a linewidth of *radius*, all points on the line + would still be considered to be contained in the area. Conversely, + negative values shrink the area; points on the imaginary line + will be considered outside the area. + + Returns + ------- + bool """ if transform is not None: transform = transform.frozen() @@ -470,13 +485,27 @@ def contains_point(self, point, transform=None, radius=0.0): def contains_points(self, points, transform=None, radius=0.0): """ - Returns a bool array which is ``True`` if the (closed) path contains - the corresponding point. + Return whether the (closed) path contains the given point. - If *transform* is not ``None``, the path will be transformed before - performing the test. - - *radius* allows the path to be made slightly larger or smaller. + Parameters + ---------- + points : (N, 2) array + The points to check. Columns contain x and y values. + transform : `matplotlib.transforms.Transform`, optional + If not ``None``, *points* will be compared to self transformed + by *transform*; i.e. for a correct check, *transform* should + transform the path into the coordinate system of *points*. + radius : float, default: 0. + Adds an additional margin on the path in coordinates of *points*. + The path is extended tangentially by *radius/2*; i.e. if you would + draw the path with a linewidth of *radius*, all points on the line + would still be considered to be contained in the area. Conversely, + negative values shrink the area; points on the imaginary line + will be considered outside the area. + + Returns + ------- + length-N bool array """ if transform is not None: transform = transform.frozen()