From c19ef0d6dddeaefb085d39ced54fca1e6ef86399 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 7 Dec 2023 10:47:14 -0500 Subject: [PATCH] DOC: clarify the default value of *radius* in Patch.contains_point ... and friends. closes #19807 Co-authored-by: Oscar Gustafsson Co-authored-by: Elliott Sales de Andrade --- lib/matplotlib/patches.py | 54 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 3 deletions(-) diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py index d1537322ab76..4e387229aee1 100644 --- a/lib/matplotlib/patches.py +++ b/lib/matplotlib/patches.py @@ -127,6 +127,29 @@ def contains(self, mouseevent, radius=None): """ Test whether the mouse event occurred in the patch. + Parameters + ---------- + mouseevent : `~matplotlib.backend_bases.MouseEvent` + Where the user clicked. + + radius : float, optional + Additional margin on the patch in target coordinates of + `.Patch.get_transform`. See `.Path.contains_point` for further + details. + + If `None`, the default value depends on the state of the object: + + - If `.Artist.get_picker` is a number, the default + is that value. This is so that picking works as expected. + - Otherwise if the edge color has a non-zero alpha, the default + is half of the linewidth. This is so that all the colored + pixels are "in" the patch. + - Finally, if the edge has 0 alpha, the default is 0. This is + so that patches without a stroked edge do not have points + outside of the filled region report as "in" due to an + invisible edge. + + Returns ------- (bool, empty dict) @@ -160,13 +183,26 @@ def contains_point(self, point, radius=None): ---------- point : (float, float) The point (x, y) to check, in target coordinates of - ``self.get_transform()``. These are display coordinates for patches + `.Patch.get_transform`. These are display coordinates for patches that are added to a figure or axes. + radius : float, optional Additional margin on the patch in target coordinates of - ``self.get_transform()``. See `.Path.contains_point` for further + `.Patch.get_transform`. See `.Path.contains_point` for further details. + If `None`, the default value depends on the state of the object: + + - If `.Artist.get_picker` is a number, the default + is that value. This is so that picking works as expected. + - Otherwise if the edge color has a non-zero alpha, the default + is half of the linewidth. This is so that all the colored + pixels are "in" the patch. + - Finally, if the edge has 0 alpha, the default is 0. This is + so that patches without a stroked edge do not have points + outside of the filled region report as "in" due to an + invisible edge. + Returns ------- bool @@ -214,9 +250,21 @@ def contains_points(self, points, radius=None): that are added to a figure or axes. Columns contain x and y values. radius : float, optional Additional margin on the patch in target coordinates of - ``self.get_transform()``. See `.Path.contains_point` for further + `.Patch.get_transform`. See `.Path.contains_point` for further details. + If `None`, the default value depends on the state of the object: + + - If `.Artist.get_picker` is a number, the default + is that value. This is so that picking works as expected. + - Otherwise if the edge color has a non-zero alpha, the default + is half of the linewidth. This is so that all the colored + pixels are "in" the patch. + - Finally, if the edge has 0 alpha, the default is 0. This is + so that patches without a stroked edge do not have points + outside of the filled region report as "in" due to an + invisible edge. + Returns ------- length-N bool array