From 4e2195ae2eb7db6f8a86d1de43978304bba7de49 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Sat, 7 Sep 2019 20:44:55 +0200 Subject: [PATCH] Update docstrings of contains_point(s) methods --- lib/matplotlib/patches.py | 67 ++++++++++++++++++++++++++++++++++----- lib/matplotlib/path.py | 51 ++++++++++++++++++++++------- 2 files changed, 99 insertions(+), 19 deletions(-) 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() pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy