wolfhece._companion_factory

Pre-built companion classes for common interactive-selection patterns.

All four classes are ready to use as-is or to subclass. Override the COLOR_* / *_FRACTION class attributes to change the visual style without writing any method code.

Quick-start

from wolfhece._companion_factory import point_picker, polyline, multi_polyline, polygon

# One-liner: create + register + activate
comp = point_picker(viewer)
# … right-click on the map …
print(comp.points)
comp.destroy()

Interaction summary

Companion	Add vertex	Finish / accept	Cancel / stop
PointPickerCompanion	Right-click	(already done)	Esc or stop()
PolylineCompanion	Right-click	Enter (≥ 2 pts)	Esc (discard)
MultiPolylineCompanion	Right-click	Enter (≥ 2 pts)	Esc stops action
PolygonCompanion	Right-click	Enter (≥ 3 pts)	Esc (discard)

All companions:

• left-click selects the nearest already-placed vertex (PointPickerCompanion only)

• Ctrl+Z undoes the last vertex (PointPickerCompanion only)

• comp.stop() deactivates the action; collected data is preserved

• comp.destroy() deactivates + unregisters all handlers

Module Contents

class wolfhece._companion_factory.PointPickerCompanion(viewer: wolfhece.PyDraw.WolfMapViewer)

Bases: wolfhece._menu_companion_abc.AbstractCompanion

Collect isolated (x, y) points via right-click.

Interaction

• Right-click — add a point at the snapped cursor position

• Left-click — select the nearest point (highlighted in gold)

• Ctrl+Z — remove the last point

• Esc — deactivate the action; collected points are preserved

points

Collected world-coordinate pairs (snapped).

Type:

list[tuple[float, float]]

selected

Index of the highlighted point (-1 = none).

Type:

int

Customisation

-------------

Override the class attributes to change colours/size without subclassing::

class MyPicker(PointPickerCompanion):

COLOR_NORMAL = (0.0, 0.6, 1.0, 1.0) # blue COLOR_SELECTED = (1.0, 1.0, 0.0, 1.0) # yellow CROSS_FRACTION = 0.015

COLOR_NORMAL: tuple = (1.0, 0.0, 0.0, 1.0)

COLOR_SELECTED: tuple = (1.0, 0.8, 0.0, 1.0)

CROSS_FRACTION: float = 0.01

points: list[tuple[float, float]] = []

selected: int = -1

start() → None

Activate the point-picker action.

_rdown(viewer, ctx: wolfhece._viewer_plugin_handlers.MouseContext) → None

_ldown(viewer, ctx: wolfhece._viewer_plugin_handlers.MouseContext) → None

_key(viewer, kb: wolfhece._viewer_plugin_handlers.KeyboardSnapshot) → bool

_paint(viewer) → None

class wolfhece._companion_factory.PolylineCompanion(viewer: wolfhece.PyDraw.WolfMapViewer)

Bases: wolfhece._menu_companion_abc.AbstractCompanion

Record a single polyline vertex by vertex.

Interaction

• Right-click — append a vertex

• Enter / Return — finalise the polyline (requires ≥ 2 vertices)

• Esc — discard all vertices and deactivate

vertices

Ordered vertices of the recorded polyline. Empty after a cancelled interaction, populated after a successful Enter.

Type:

list[tuple[float, float]]

finished

True once Enter has been pressed with ≥ 2 vertices.

Type:

bool

Customisation

-------------

Override ``COLOR_LINE``, ``COLOR_VERTEX``, ``CROSS_FRACTION``,

``LINE_WIDTH`` at the class level.

COLOR_LINE: tuple = (0.0, 0.5, 1.0, 1.0)

COLOR_VERTEX: tuple = (1.0, 1.0, 1.0, 1.0)

CROSS_FRACTION: float = 0.008

LINE_WIDTH: float = 2.0

vertices: list[tuple[float, float]] = []

finished: bool = False

start() → None

Reset state and activate the polyline-recording action.

_rdown(viewer, ctx: wolfhece._viewer_plugin_handlers.MouseContext) → None

_key(viewer, kb: wolfhece._viewer_plugin_handlers.KeyboardSnapshot) → bool

_paint(viewer) → None

class wolfhece._companion_factory.MultiPolylineCompanion(viewer: wolfhece.PyDraw.WolfMapViewer)

Bases: wolfhece._menu_companion_abc.AbstractCompanion

Record multiple polylines in a single session.

Interaction

• Right-click — append a vertex to the current in-progress line

• Enter / Return — finalise the current line (≥ 2 vertices) and start a new one

• Esc — discard the current in-progress line and deactivate; already-finalised lines are preserved

polylines

All finalised polylines.

Type:

list[list[tuple[float, float]]]

current

Vertices of the line currently being drawn.

Type:

list[tuple[float, float]]

COLOR_DONE: tuple = (0.2, 0.6, 1.0, 1.0)

COLOR_CURRENT: tuple = (1.0, 0.5, 0.0, 1.0)

COLOR_VERTEX: tuple = (1.0, 1.0, 1.0, 0.8)

CROSS_FRACTION: float = 0.007

LINE_WIDTH: float = 1.5

polylines: list[list[tuple[float, float]]] = []

current: list[tuple[float, float]] = []

start() → None

Reset state and activate the multi-polyline recording action.

_rdown(viewer, ctx: wolfhece._viewer_plugin_handlers.MouseContext) → None

_key(viewer, kb: wolfhece._viewer_plugin_handlers.KeyboardSnapshot) → bool

_paint(viewer) → None

class wolfhece._companion_factory.MultiPolylineZonesCompanion(viewer: wolfhece.PyDraw.WolfMapViewer, *, zones_id: str = 'multi_polyline', auto_attach: bool = True, zone_name_prefix: str = 'zone')

Bases: wolfhece._menu_companion_abc.AbstractCompanion

Record multiple polylines and store them in a Zones object.

Behaves like MultiPolylineCompanion for the interaction, but instead of keeping the results in a plain Python list each accepted polyline is immediately written into a Zones → zone → vector hierarchy and — when auto_attach is enabled — added to the viewer so that it appears in the layers panel and can be exported.

Interaction

• Right-click — append a vertex to the current in-progress line

• Enter / Return — finalise the current line (≥ 2 vertices); it is added to the zones object as a new zone

• Esc — discard the current in-progress vertices and stop the action; already-finalised lines in zones are preserved

zones

The backing Zones object. None until the first line is accepted. Once created it is the same object that is attached to the viewer (when auto_attach is True).

Type:

Zones | None

current

Vertices of the line currently being digitised.

Type:

list[tuple[float, float]]

param viewer:

The map viewer.

param zones_id:

Identifier string for the Zones object. Defaults to 'multi_polyline'.

type zones_id:

str

param auto_attach:

When True (default) the Zones object is added to the viewer via viewer.add_object('vector', …) on the first accepted polyline.

type auto_attach:

bool

param zone_name_prefix:

Prefix for the generated zone names (zone_001, zone_002, …).

type zone_name_prefix:

str

param Customisation:

param ————-:

param Override the class attributes to change colours/line width:::

class MyZonesCompanion(MultiPolylineZonesCompanion):

COLOR_DONE = (0.9, 0.2, 0.2, 1.0) COLOR_CURRENT = (1.0, 0.8, 0.0, 1.0)

COLOR_DONE: tuple = (0.2, 0.6, 1.0, 1.0)

COLOR_CURRENT: tuple = (1.0, 0.5, 0.0, 1.0)

COLOR_VERTEX: tuple = (1.0, 1.0, 1.0, 0.8)

CROSS_FRACTION: float = 0.007

LINE_WIDTH: float = 1.5

_zones_id = 'multi_polyline'

_auto_attach = True

_zone_name_prefix = 'zone'

zones: Zones | None = None

current: list[tuple[float, float]] = []

start() → None

Activate the multi-polyline action.

Only current is cleared; any already-accepted lines in zones are preserved so that the session can be resumed.

attach_zones(id: str | None = None) → Zones | None

Manually add zones to the viewer.

This is a no-op when auto_attach is True (attachment already happened) or when zones is None (no line accepted yet).

Parameters:

id – Override the id used when registering with the viewer (defaults to the zones_id given at construction time).

Returns:

The Zones object, or None if nothing has been digitised yet.

clear_zones() → None

Discard all accepted lines and reset zones to None.

This does not remove the object from the viewer if it was already attached — call viewer.get_obj_from_id(…) and remove it manually if needed.

_ensure_zones() → wolfhece.pyvertexvectors.Zones

Return the Zones object, creating (and optionally attaching) it on the first call.

_finalise_current() → None

Move current vertices into a new zone+vector inside zones.

_rdown(viewer, ctx: wolfhece._viewer_plugin_handlers.MouseContext) → None

_key(viewer, kb: wolfhece._viewer_plugin_handlers.KeyboardSnapshot) → bool

_paint(viewer) → None

class wolfhece._companion_factory.PolygonCompanion(viewer: wolfhece.PyDraw.WolfMapViewer)

Bases: wolfhece._menu_companion_abc.AbstractCompanion

Record one or more closed polygons.

Interaction

• Right-click — append a vertex to the current polygon

• Enter / Return — close and finalise the current polygon (≥ 3 vertices)

• Esc — discard the current in-progress polygon; finalised polygons are kept

polygons

All finalised polygons. The closing segment (last → first vertex) is implicit — it is drawn but not stored as a duplicate vertex.

Type:

list[list[tuple[float, float]]]

current

Vertices of the polygon currently being drawn.

Type:

list[tuple[float, float]]

COLOR_DONE: tuple = (0.0, 0.8, 0.2, 1.0)

COLOR_CURRENT: tuple = (1.0, 0.5, 0.0, 1.0)

COLOR_VERTEX: tuple = (1.0, 1.0, 1.0, 0.8)

CROSS_FRACTION: float = 0.007

LINE_WIDTH: float = 1.5

polygons: list[list[tuple[float, float]]] = []

current: list[tuple[float, float]] = []

start() → None

Reset state and activate the polygon-recording action.

_rdown(viewer, ctx: wolfhece._viewer_plugin_handlers.MouseContext) → None

_key(viewer, kb: wolfhece._viewer_plugin_handlers.KeyboardSnapshot) → bool

_paint(viewer) → None

wolfhece._companion_factory.point_picker(viewer: wolfhece.PyDraw.WolfMapViewer, **kwargs) → PointPickerCompanion

Create, register and activate a PointPickerCompanion.

Parameters:

• viewer – The WolfMapViewer instance.

• kwargs – Forwarded to PointPickerCompanion constructor (e.g. namespace=, dialogs=).

Returns:

The activated companion.

wolfhece._companion_factory.polyline(viewer: wolfhece.PyDraw.WolfMapViewer, **kwargs) → PolylineCompanion

Create, register and activate a PolylineCompanion.

Parameters:

• viewer – The WolfMapViewer instance.

• kwargs – Forwarded to the constructor.

Returns:

The activated companion.

wolfhece._companion_factory.multi_polyline(viewer: wolfhece.PyDraw.WolfMapViewer, **kwargs) → MultiPolylineCompanion

Create, register and activate a MultiPolylineCompanion.

Parameters:

• viewer – The WolfMapViewer instance.

• kwargs – Forwarded to the constructor.

Returns:

The activated companion.

wolfhece._companion_factory.multi_polyline_zones(viewer: wolfhece.PyDraw.WolfMapViewer, zones_id: str = 'multi_polyline', auto_attach: bool = True, **kwargs) → MultiPolylineZonesCompanion

Create, register and activate a MultiPolylineZonesCompanion.

Parameters:

• viewer – The WolfMapViewer instance.

• zones_id – Identifier of the Zones object that will be added to the viewer.

• auto_attach – When True (default) the Zones object is added to the viewer automatically on the first accepted polyline.

• kwargs – Forwarded to the constructor.

Returns:

The activated companion.

wolfhece._companion_factory.polygon(viewer: wolfhece.PyDraw.WolfMapViewer, **kwargs) → PolygonCompanion

Create, register and activate a PolygonCompanion.

Parameters:

• viewer – The WolfMapViewer instance.

• kwargs – Forwarded to the constructor.

Returns:

The activated companion.