PR summary

PolygonSelector is a widget class used to select a polygonal region within an Axes. More precisely, it enables the selection of a closed polygonal chain, i.e., a sequence of vertices connected by line segments where the first and last vertices are connected. These chains may be non-self-intersecting or self-intersecting. Before or after a polygon is defined, the class provides interactive editing capabilities such as repositioning and removing vertices.

An open polygonal chain is a sequence of vertices connected by line segments but where the first and last vertices are not connected. The proposed feature is to enable both programmatic and interactive selection of open polygonal chains within a widget class, including both non-self-intersecting and self-intersecting chains.

The approach is to extend the current PolygonSelector class by adding a new parameter,

PolygonSelector(..., closed=True)

to explicitly control whether the polygonal chain is open or closed. By default the parameter selects closed polygonal regions, preserving the current behavior.

The selection of an open polygonal chain is completed by pressing the Enter key after inserting a vertex. The existing interactive editing functionality is preserved and applies consistently to both modes.

Why is this change necessary / what problem does it solve?

PolygonSelector currently supports only closed polygonal regions, while LassoSelector provides freeform selection without vertex control. There is no widget that supports structured, vertex-based selection of open polygonal chains, which are useful for tasks such as defining paths, annotations, or piecewise geometries where closure is not desired.

What is the reasoning for this implementation?

Several implementation approaches were considered in addition to the current one:

1. Introduce an OpenPolygonalChainSelector class dedicated to open chains.

2. Introduce a PolygonalChainSelector class supporting both open and closed chains.

3. Introduce an internal _PolygonalChainSelector base class to provide common functionality for the existing PolygonSelector and a new OpenPolygonalChainSelector.

Other design approaches were also considered:

1. For a class supporting both chain types, infer whether the chain is open or closed based on user interaction, instead of relying on a new explicit parameter.

2. Use the Strategy behavioral design pattern in the current implementation to remove the conditional branches (if self.closed ... else ...) added to handle open and closed chain behavior.

The chosen approach is the simplest one. It introduces a minimal API change and serves as an effective starting point. It preserves the current default behavior and has explicit, predictable behavior, which facilitates testing and documentation. The main drawback is a slight semantic mismatch, as PolygonSelector now supports both closed and open chains.

Example

Co-authored-by: @maf2310

Closes #28421

AI Disclosure

AI was used to help proofread the grammar of this PR description and to understand some parts of the existing codebase during development. The code changes and design decisions were developed independently.

PR checklist

• "closes #0000" is in the body of the PR description to link the related issue
• new and changed code is tested
• Plotting related features are demonstrated in an example
• New Features and API Changes are noted with a directive and release note
• Documentation complies with general and docstring guidelines