ENH: Support open polygonal chains in PolygonSelector

lucaznch · maf2310 · lucaznch · commit 870d2e6b2ce2 · 2026-05-05T23:39:59.000+01:00
Extend PolygonSelector with open polygonal chain support by adding a new parameter to explicitly control whether the chain is open or closed. The selection of an open polygonal chain is completed by pressing the Enter key after inserting a vertex. The existing interactive editing functionality also applies to open polygonal chains. Extend existing tests to cover the new mode. Closes #28421 Co-authored-by: Mafalda Botelho <mafaldabotelho@tecnico.ulisboa.pt>
diff --git a/lib/matplotlib/tests/test_widgets.py b/lib/matplotlib/tests/test_widgets.py
@@ -1441,22 +1441,36 @@ def polygon_remove_vertex(ax, xy):
     ]
 
 
+def polygon_complete_chain(ax, closed, xy):
+    if closed:
+        return [
+            *polygon_place_vertex(ax, xy)
+        ]
+    else:
+        return [
+            KeyEvent("key_press_event", ax.figure.canvas, "enter"),
+            KeyEvent("key_release_event", ax.figure.canvas, "enter"),
+        ]
+
+
 @pytest.mark.parametrize('draw_bounding_box', [False, True])
-def test_polygon_selector(ax, draw_bounding_box):
-    check_selector = functools.partial(
-        check_polygon_selector, draw_bounding_box=draw_bounding_box)
+@pytest.mark.parametrize('closed', [False, True])
+def test_polygon_selector(ax, draw_bounding_box, closed):
+    check_selector = functools.partial(check_polygon_selector,
+                                       draw_bounding_box=draw_bounding_box,
+                                       closed=closed)
 
-    # Simple polygon
+    # Simple polygonal chain.
     expected_result = [(50, 50), (150, 50), (50, 150)]
     event_sequence = [
         *polygon_place_vertex(ax, (50, 50)),
         *polygon_place_vertex(ax, (150, 50)),
         *polygon_place_vertex(ax, (50, 150)),
-        *polygon_place_vertex(ax, (50, 50)),
+        *polygon_complete_chain(ax, closed, (50, 50)),
     ]
     check_selector(event_sequence, expected_result, 1)
 
-    # Move first vertex before completing the polygon.
+    # Move first vertex before completing the polygonal chain.
     expected_result = [(75, 50), (150, 50), (50, 150)]
     event_sequence = [
         *polygon_place_vertex(ax, (50, 50)),
@@ -1468,11 +1482,11 @@ def test_polygon_selector(ax, draw_bounding_box):
         MouseEvent._from_ax_coords("button_release_event", ax, (75, 50), 1),
         KeyEvent("key_release_event", ax.figure.canvas, "control"),
         *polygon_place_vertex(ax, (50, 150)),
-        *polygon_place_vertex(ax, (75, 50)),
+        *polygon_complete_chain(ax, closed, (75, 50)),
     ]
     check_selector(event_sequence, expected_result, 1)
 
-    # Move first two vertices at once before completing the polygon.
+    # Move first two vertices at once before completing the polygonal chain.
     expected_result = [(50, 75), (150, 75), (50, 150)]
     event_sequence = [
         *polygon_place_vertex(ax, (50, 50)),
@@ -1484,31 +1498,31 @@ def test_polygon_selector(ax, draw_bounding_box):
         MouseEvent._from_ax_coords("button_release_event", ax, (100, 125), 1),
         KeyEvent("key_release_event", ax.figure.canvas, "shift"),
         *polygon_place_vertex(ax, (50, 150)),
-        *polygon_place_vertex(ax, (50, 75)),
+        *polygon_complete_chain(ax, closed, (50, 75)),
     ]
     check_selector(event_sequence, expected_result, 1)
 
-    # Move first vertex after completing the polygon.
+    # Move first vertex after completing the polygonal chain.
     expected_result = [(85, 50), (150, 50), (50, 150)]
     event_sequence = [
         *polygon_place_vertex(ax, (60, 50)),
         *polygon_place_vertex(ax, (150, 50)),
         *polygon_place_vertex(ax, (50, 150)),
-        *polygon_place_vertex(ax, (60, 50)),
+        *polygon_complete_chain(ax, closed, (60, 50)),
         MouseEvent._from_ax_coords("motion_notify_event", ax, (60, 50)),
         MouseEvent._from_ax_coords("button_press_event", ax, (60, 50), 1),
         MouseEvent._from_ax_coords("motion_notify_event", ax, (85, 50)),
         MouseEvent._from_ax_coords("button_release_event", ax, (85, 50), 1),
     ]
     check_selector(event_sequence, expected_result, 2)
 
-    # Move all vertices after completing the polygon.
+    # Move all vertices after completing the polygonal chain.
     expected_result = [(75, 75), (175, 75), (75, 175)]
     event_sequence = [
         *polygon_place_vertex(ax, (50, 50)),
         *polygon_place_vertex(ax, (150, 50)),
         *polygon_place_vertex(ax, (50, 150)),
-        *polygon_place_vertex(ax, (50, 50)),
+        *polygon_complete_chain(ax, closed, (50, 50)),
         KeyEvent("key_press_event", ax.figure.canvas, "shift"),
         MouseEvent._from_ax_coords("motion_notify_event", ax, (100, 100)),
         MouseEvent._from_ax_coords("button_press_event", ax, (100, 100), 1),
@@ -1536,11 +1550,11 @@ def test_polygon_selector(ax, draw_bounding_box):
         *polygon_place_vertex(ax, (50, 50)),
         *polygon_place_vertex(ax, (150, 50)),
         *polygon_place_vertex(ax, (50, 150)),
-        *polygon_place_vertex(ax, (50, 50)),
+        *polygon_complete_chain(ax, closed, (50, 50)),
     ]
     check_selector(event_sequence, expected_result, 1)
 
-    # Try to place vertex out-of-bounds, then reset, and start a new polygon.
+    # Try to place vertex out-of-bounds, then reset, and start a new polygonal chain.
     expected_result = [(50, 50), (150, 50), (50, 150)]
     event_sequence = [
         *polygon_place_vertex(ax, (50, 50)),
@@ -1550,7 +1564,7 @@ def test_polygon_selector(ax, draw_bounding_box):
         *polygon_place_vertex(ax, (50, 50)),
         *polygon_place_vertex(ax, (150, 50)),
         *polygon_place_vertex(ax, (50, 150)),
-        *polygon_place_vertex(ax, (50, 50)),
+        *polygon_complete_chain(ax, closed, (50, 50)),
     ]
     check_selector(event_sequence, expected_result, 1)
 
@@ -1599,35 +1613,37 @@ def test_rect_visibility(fig_test, fig_ref):
 # Change the order that the extra point is inserted in
 @pytest.mark.parametrize('idx', [1, 2, 3])
 @pytest.mark.parametrize('draw_bounding_box', [False, True])
-def test_polygon_selector_remove(ax, idx, draw_bounding_box):
+@pytest.mark.parametrize('closed', [False, True])
+def test_polygon_selector_remove(ax, idx, draw_bounding_box, closed):
     verts = [(50, 50), (150, 50), (50, 150)]
     event_sequence = [polygon_place_vertex(ax, verts[0]),
                       polygon_place_vertex(ax, verts[1]),
                       polygon_place_vertex(ax, verts[2]),
                       # Finish the polygon
-                      polygon_place_vertex(ax, verts[0])]
+                      polygon_complete_chain(ax, closed, verts[0])]
     # Add an extra point
     event_sequence.insert(idx, polygon_place_vertex(ax, (200, 200)))
     # Remove the extra point
     event_sequence.append(polygon_remove_vertex(ax, (200, 200)))
     # Flatten list of lists
     event_sequence = functools.reduce(operator.iadd, event_sequence, [])
     check_polygon_selector(event_sequence, verts, 2,
-                           draw_bounding_box=draw_bounding_box)
+                           draw_bounding_box=draw_bounding_box, closed=closed)
 
 
 @pytest.mark.parametrize('draw_bounding_box', [False, True])
-def test_polygon_selector_remove_first_point(ax, draw_bounding_box):
+@pytest.mark.parametrize('closed', [False, True])
+def test_polygon_selector_remove_first_point(ax, draw_bounding_box, closed):
     verts = [(50, 50), (150, 50), (50, 150)]
     event_sequence = [
         *polygon_place_vertex(ax, verts[0]),
         *polygon_place_vertex(ax, verts[1]),
         *polygon_place_vertex(ax, verts[2]),
-        *polygon_place_vertex(ax, verts[0]),
+        *polygon_complete_chain(ax, closed, verts[0]),
         *polygon_remove_vertex(ax, verts[0]),
     ]
     check_polygon_selector(event_sequence, verts[1:], 2,
-                           draw_bounding_box=draw_bounding_box)
+                           draw_bounding_box=draw_bounding_box, closed=closed)
 
 
 @pytest.mark.parametrize('draw_bounding_box', [False, True])
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -4002,7 +4002,7 @@ def _onmove(self, event):
 
 class PolygonSelector(_SelectorWidget):
     """
-    Select a polygon region of an Axes.
+    Select a polygonal region or chain within an Axes.
 
     Place vertices with each mouse click, and make the selection by completing
     the polygon (clicking on the first vertex). Once drawn individual vertices
@@ -4015,6 +4015,7 @@ class PolygonSelector(_SelectorWidget):
       polygon has been completed.
     - Hold the *shift* key and click and drag anywhere in the Axes to move
       all vertices.
+    - Press *enter* to finalize the selection of an open polygonal chain.
     - Press the *esc* key to start a new polygon.
 
     For the selector to remain responsive you must keep a reference to it.
@@ -4064,6 +4065,9 @@ class PolygonSelector(_SelectorWidget):
         Properties to set for the box. See the documentation for the *props*
         argument to `RectangleSelector` for more info.
 
+    closed : bool, default: True
+        Whether to select a closed polygonal region or an open polygonal chain.
+
     Examples
     --------
     :doc:`/gallery/widgets/polygon_selector_simple`
@@ -4079,7 +4083,7 @@ class PolygonSelector(_SelectorWidget):
     def __init__(self, ax, onselect=None, *, useblit=False,
                  props=None, handle_props=None, grab_range=10,
                  draw_bounding_box=False, box_handle_props=None,
-                 box_props=None):
+                 box_props=None, closed=True):
         # The state modifiers 'move', 'square', and 'center' are expected by
         # _SelectorWidget but are not supported by PolygonSelector
         # Note: could not use the existing 'move' state modifier in-place of
@@ -4113,14 +4117,16 @@ def __init__(self, ax, onselect=None, *, useblit=False,
         self.grab_range = grab_range
 
         self.set_visible(True)
-        self._draw_box = draw_bounding_box
+        self._draw_box = draw_bounding_box and closed
         self._box = None
 
         if box_handle_props is None:
             box_handle_props = {}
         self._box_handle_props = self._handle_props.update(box_handle_props)
         self._box_props = box_props
 
+        self.closed = closed
+
     def _get_bbox(self):
         return self._selection_artist.get_bbox()
 
@@ -4188,7 +4194,7 @@ def _handles_artists(self):
 
     def _remove_vertex(self, i):
         """Remove vertex with index i."""
-        if (len(self._xys) > 2 and
+        if (self.closed and len(self._xys) > 2 and
                 self._selection_completed and
                 i in (0, len(self._xys) - 1)):
             # If selecting the first or final vertex, remove both first and
@@ -4200,9 +4206,11 @@ def _remove_vertex(self, i):
             self._xys.append(self._xys[0])
         else:
             self._xys.pop(i)
-        if len(self._xys) <= 2:
-            # If only one point left, return to incomplete state to let user
-            # start drawing again
+        if ((self.closed and len(self._xys) <= 2)
+            or (not self.closed and len(self._xys) == 0)):
+            # If only one point left for polygon or
+            # or no points left for open polygonal chain,
+            # return to incomplete state to let user start drawing again.
             self._selection_completed = False
             self._remove_box()
 
@@ -4229,7 +4237,7 @@ def _release(self, event):
             self._active_handle_idx = -1
 
         # Complete the polygon.
-        elif len(self._xys) > 3 and self._xys[-1] == self._xys[0]:
+        elif self.closed and len(self._xys) > 3 and self._xys[-1] == self._xys[0]:
             self._selection_completed = True
             if self._draw_box and self._box is None:
                 self._add_box()
@@ -4238,7 +4246,10 @@ def _release(self, event):
         elif (not self._selection_completed
               and 'move_all' not in self._state
               and 'move_vertex' not in self._state):
-            self._xys.insert(-1, (event.xdata, event.ydata))
+            if self.closed:
+                self._xys.insert(-1, (event.xdata, event.ydata))
+            else:
+                self._xys.append((event.xdata, event.ydata))
 
         if self._selection_completed:
             self.onselect(self.verts)
@@ -4270,7 +4281,7 @@ def _onmove(self, event):
             self._xys[idx] = (event.xdata, event.ydata)
             # Also update the end of the polygon line if the first vertex is
             # the active handle and the polygon is completed.
-            if idx == 0 and self._selection_completed:
+            if idx == 0 and self.closed and self._selection_completed:
                 self._xys[-1] = (event.xdata, event.ydata)
 
         # Move all vertices.
@@ -4286,8 +4297,8 @@ def _onmove(self, event):
               or 'move_vertex' in self._state or 'move_all' in self._state):
             return
 
-        # Position pending vertex.
-        else:
+        # Position pending polygon vertex.
+        elif self.closed:
             # Calculate distance to the start vertex.
             x0, y0 = \
                 self._selection_artist.get_transform().transform(self._xys[0])
@@ -4298,6 +4309,15 @@ def _onmove(self, event):
             else:
                 self._xys[-1] = (event.xdata, event.ydata)
 
+        # Position pending open polygonal chain vertex.
+        else:
+            if len(self._xys) == 0:
+                # After removal of the only vertex in open polygonal chain,
+                # add a new vertex at the current cursor position.
+                self._xys.append((event.xdata, event.ydata))
+            else:
+                self._xys[-1] = (event.xdata, event.ydata)
+
         self._draw_polygon()
 
     def _on_key_press(self, event):
@@ -4320,6 +4340,13 @@ def _on_key_release(self, event):
                  or event.key == self._state_modifier_keys.get('move_all'))):
             self._xys.append((event.xdata, event.ydata))
             self._draw_polygon()
+        elif (not self.closed and not self._selection_completed
+              and event.key == 'enter' and len(self._xys) > 1):
+            # Complete the open polygonal chain.
+            self._xys.pop()
+            self._selection_completed = True
+            self._draw_polygon()
+            self.onselect(self.verts)
         # Reset the polygon if the released key is the 'clear' key.
         elif event.key == self._state_modifier_keys.get('clear'):
             event = self._clean_event(event)
@@ -4336,7 +4363,7 @@ def _draw_polygon_without_update(self):
         # Only show one tool handle at the start and end vertex of the polygon
         # if the polygon is completed or the user is locked on to the start
         # vertex.
-        if (self._selection_completed
+        if (self.closed and self._selection_completed
                 or (len(self._xys) > 3
                     and self._xys[-1] == self._xys[0])):
             self._polygon_handles.set_data(xs[:-1], ys[:-1])
@@ -4351,7 +4378,7 @@ def _draw_polygon(self):
     @property
     def verts(self):
         """The polygon vertices, as a list of ``(x, y)`` pairs."""
-        return self._xys[:-1]
+        return self._xys[:-1] if self.closed else self._xys
 
     @verts.setter
     def verts(self, xys):
@@ -4361,7 +4388,7 @@ def verts(self, xys):
         This will remove any preexisting vertices, creating a complete polygon
         with the new vertices.
         """
-        self._xys = [*xys, xys[0]]
+        self._xys = [*xys, xys[0]] if self.closed else [*xys]
         self._selection_completed = True
         self.set_visible(True)
         if self._draw_box and self._box is None:
diff --git a/lib/matplotlib/widgets.pyi b/lib/matplotlib/widgets.pyi
@@ -470,7 +470,8 @@ class PolygonSelector(_SelectorWidget):
         grab_range: float = ...,
         draw_bounding_box: bool = ...,
         box_handle_props: dict[str, Any] | None = ...,
-        box_props: dict[str, Any] | None = ...
+        box_props: dict[str, Any] | None = ...,
+        closed: bool = ...,
     ) -> None: ...
     def onmove(self, event: Event) -> bool: ...
     @property
