wolfhece._companion_factory =========================== .. py:module:: wolfhece._companion_factory .. autoapi-nested-parse:: 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 --------------- .. py:class:: PointPickerCompanion(viewer: wolfhece.PyDraw.WolfMapViewer) Bases: :py:obj:`wolfhece._menu_companion_abc.AbstractCompanion` .. autoapi-inheritance-diagram:: wolfhece._companion_factory.PointPickerCompanion :parts: 1 :private-bases: 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 .. attribute:: points Collected world-coordinate pairs (snapped). :type: list[tuple[float, float]] .. attribute:: selected Index of the highlighted point (-1 = none). :type: int .. attribute:: Customisation .. attribute:: ------------- .. attribute:: 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 .. py:attribute:: COLOR_NORMAL :type: tuple :value: (1.0, 0.0, 0.0, 1.0) .. py:attribute:: COLOR_SELECTED :type: tuple :value: (1.0, 0.8, 0.0, 1.0) .. py:attribute:: CROSS_FRACTION :type: float :value: 0.01 .. py:attribute:: points :type: list[tuple[float, float]] :value: [] .. py:attribute:: selected :type: int :value: -1 .. py:method:: start() -> None Activate the point-picker action. .. py:method:: _rdown(viewer, ctx: wolfhece._viewer_plugin_handlers.MouseContext) -> None .. py:method:: _ldown(viewer, ctx: wolfhece._viewer_plugin_handlers.MouseContext) -> None .. py:method:: _key(viewer, kb: wolfhece._viewer_plugin_handlers.KeyboardSnapshot) -> bool .. py:method:: _paint(viewer) -> None .. py:class:: PolylineCompanion(viewer: wolfhece.PyDraw.WolfMapViewer) Bases: :py:obj:`wolfhece._menu_companion_abc.AbstractCompanion` .. autoapi-inheritance-diagram:: wolfhece._companion_factory.PolylineCompanion :parts: 1 :private-bases: 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 .. attribute:: vertices Ordered vertices of the recorded polyline. Empty after a cancelled interaction, populated after a successful Enter. :type: list[tuple[float, float]] .. attribute:: finished ``True`` once Enter has been pressed with ≥ 2 vertices. :type: bool .. attribute:: Customisation .. attribute:: ------------- .. attribute:: Override ``COLOR_LINE``, ``COLOR_VERTEX``, ``CROSS_FRACTION``, .. attribute:: ``LINE_WIDTH`` at the class level. .. py:attribute:: COLOR_LINE :type: tuple :value: (0.0, 0.5, 1.0, 1.0) .. py:attribute:: COLOR_VERTEX :type: tuple :value: (1.0, 1.0, 1.0, 1.0) .. py:attribute:: CROSS_FRACTION :type: float :value: 0.008 .. py:attribute:: LINE_WIDTH :type: float :value: 2.0 .. py:attribute:: vertices :type: list[tuple[float, float]] :value: [] .. py:attribute:: finished :type: bool :value: False .. py:method:: start() -> None Reset state and activate the polyline-recording action. .. py:method:: _rdown(viewer, ctx: wolfhece._viewer_plugin_handlers.MouseContext) -> None .. py:method:: _key(viewer, kb: wolfhece._viewer_plugin_handlers.KeyboardSnapshot) -> bool .. py:method:: _paint(viewer) -> None .. py:class:: MultiPolylineCompanion(viewer: wolfhece.PyDraw.WolfMapViewer) Bases: :py:obj:`wolfhece._menu_companion_abc.AbstractCompanion` .. autoapi-inheritance-diagram:: wolfhece._companion_factory.MultiPolylineCompanion :parts: 1 :private-bases: 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 .. attribute:: polylines All finalised polylines. :type: list[list[tuple[float, float]]] .. attribute:: current Vertices of the line currently being drawn. :type: list[tuple[float, float]] .. py:attribute:: COLOR_DONE :type: tuple :value: (0.2, 0.6, 1.0, 1.0) .. py:attribute:: COLOR_CURRENT :type: tuple :value: (1.0, 0.5, 0.0, 1.0) .. py:attribute:: COLOR_VERTEX :type: tuple :value: (1.0, 1.0, 1.0, 0.8) .. py:attribute:: CROSS_FRACTION :type: float :value: 0.007 .. py:attribute:: LINE_WIDTH :type: float :value: 1.5 .. py:attribute:: polylines :type: list[list[tuple[float, float]]] :value: [] .. py:attribute:: current :type: list[tuple[float, float]] :value: [] .. py:method:: start() -> None Reset state and activate the multi-polyline recording action. .. py:method:: _rdown(viewer, ctx: wolfhece._viewer_plugin_handlers.MouseContext) -> None .. py:method:: _key(viewer, kb: wolfhece._viewer_plugin_handlers.KeyboardSnapshot) -> bool .. py:method:: _paint(viewer) -> None .. py:class:: MultiPolylineZonesCompanion(viewer: wolfhece.PyDraw.WolfMapViewer, *, zones_id: str = 'multi_polyline', auto_attach: bool = True, zone_name_prefix: str = 'zone') Bases: :py:obj:`wolfhece._menu_companion_abc.AbstractCompanion` .. autoapi-inheritance-diagram:: wolfhece._companion_factory.MultiPolylineZonesCompanion :parts: 1 :private-bases: Record multiple polylines and store them in a :class:`~wolfhece.pyvertexvectors.Zones` object. Behaves like :class:`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 :attr:`zones` object as a new ``zone`` * **Esc** — discard the current in-progress vertices and stop the action; already-finalised lines in :attr:`zones` are preserved .. attribute:: zones The backing :class:`~wolfhece.pyvertexvectors.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 .. attribute:: 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 :class:`~wolfhece.pyvertexvectors.Zones` object. Defaults to ``'multi_polyline'``. :type zones_id: str :param auto_attach: When ``True`` (default) the :class:`~wolfhece.pyvertexvectors.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) .. py:attribute:: COLOR_DONE :type: tuple :value: (0.2, 0.6, 1.0, 1.0) .. py:attribute:: COLOR_CURRENT :type: tuple :value: (1.0, 0.5, 0.0, 1.0) .. py:attribute:: COLOR_VERTEX :type: tuple :value: (1.0, 1.0, 1.0, 0.8) .. py:attribute:: CROSS_FRACTION :type: float :value: 0.007 .. py:attribute:: LINE_WIDTH :type: float :value: 1.5 .. py:attribute:: _zones_id :value: 'multi_polyline' .. py:attribute:: _auto_attach :value: True .. py:attribute:: _zone_name_prefix :value: 'zone' .. py:attribute:: zones :type: Zones | None :value: None .. py:attribute:: current :type: list[tuple[float, float]] :value: [] .. py:method:: start() -> None Activate the multi-polyline action. Only *current* is cleared; any already-accepted lines in :attr:`zones` are preserved so that the session can be resumed. .. py:method:: attach_zones(id: str | None = None) -> Zones | None Manually add :attr:`zones` to the viewer. This is a no-op when *auto_attach* is ``True`` (attachment already happened) or when :attr:`zones` is ``None`` (no line accepted yet). :param id: Override the id used when registering with the viewer (defaults to the *zones_id* given at construction time). :return: The :class:`~wolfhece.pyvertexvectors.Zones` object, or ``None`` if nothing has been digitised yet. .. py:method:: clear_zones() -> None Discard all accepted lines and reset :attr:`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. .. py:method:: _ensure_zones() -> wolfhece.pyvertexvectors.Zones Return the Zones object, creating (and optionally attaching) it on the first call. .. py:method:: _finalise_current() -> None Move *current* vertices into a new zone+vector inside :attr:`zones`. .. py:method:: _rdown(viewer, ctx: wolfhece._viewer_plugin_handlers.MouseContext) -> None .. py:method:: _key(viewer, kb: wolfhece._viewer_plugin_handlers.KeyboardSnapshot) -> bool .. py:method:: _paint(viewer) -> None .. py:class:: PolygonCompanion(viewer: wolfhece.PyDraw.WolfMapViewer) Bases: :py:obj:`wolfhece._menu_companion_abc.AbstractCompanion` .. autoapi-inheritance-diagram:: wolfhece._companion_factory.PolygonCompanion :parts: 1 :private-bases: 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 .. attribute:: 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]]] .. attribute:: current Vertices of the polygon currently being drawn. :type: list[tuple[float, float]] .. py:attribute:: COLOR_DONE :type: tuple :value: (0.0, 0.8, 0.2, 1.0) .. py:attribute:: COLOR_CURRENT :type: tuple :value: (1.0, 0.5, 0.0, 1.0) .. py:attribute:: COLOR_VERTEX :type: tuple :value: (1.0, 1.0, 1.0, 0.8) .. py:attribute:: CROSS_FRACTION :type: float :value: 0.007 .. py:attribute:: LINE_WIDTH :type: float :value: 1.5 .. py:attribute:: polygons :type: list[list[tuple[float, float]]] :value: [] .. py:attribute:: current :type: list[tuple[float, float]] :value: [] .. py:method:: start() -> None Reset state and activate the polygon-recording action. .. py:method:: _rdown(viewer, ctx: wolfhece._viewer_plugin_handlers.MouseContext) -> None .. py:method:: _key(viewer, kb: wolfhece._viewer_plugin_handlers.KeyboardSnapshot) -> bool .. py:method:: _paint(viewer) -> None .. py:function:: point_picker(viewer: wolfhece.PyDraw.WolfMapViewer, **kwargs) -> PointPickerCompanion Create, register and activate a :class:`PointPickerCompanion`. :param viewer: The :class:`~wolfhece.PyDraw.WolfMapViewer` instance. :param kwargs: Forwarded to :class:`PointPickerCompanion` constructor (e.g. ``namespace=``, ``dialogs=``). :return: The activated companion. .. py:function:: polyline(viewer: wolfhece.PyDraw.WolfMapViewer, **kwargs) -> PolylineCompanion Create, register and activate a :class:`PolylineCompanion`. :param viewer: The :class:`~wolfhece.PyDraw.WolfMapViewer` instance. :param kwargs: Forwarded to the constructor. :return: The activated companion. .. py:function:: multi_polyline(viewer: wolfhece.PyDraw.WolfMapViewer, **kwargs) -> MultiPolylineCompanion Create, register and activate a :class:`MultiPolylineCompanion`. :param viewer: The :class:`~wolfhece.PyDraw.WolfMapViewer` instance. :param kwargs: Forwarded to the constructor. :return: The activated companion. .. py:function:: multi_polyline_zones(viewer: wolfhece.PyDraw.WolfMapViewer, zones_id: str = 'multi_polyline', auto_attach: bool = True, **kwargs) -> MultiPolylineZonesCompanion Create, register and activate a :class:`MultiPolylineZonesCompanion`. :param viewer: The :class:`~wolfhece.PyDraw.WolfMapViewer` instance. :param zones_id: Identifier of the :class:`~wolfhece.pyvertexvectors.Zones` object that will be added to the viewer. :param auto_attach: When ``True`` (default) the :class:`~wolfhece.pyvertexvectors.Zones` object is added to the viewer automatically on the first accepted polyline. :param kwargs: Forwarded to the constructor. :return: The activated companion. .. py:function:: polygon(viewer: wolfhece.PyDraw.WolfMapViewer, **kwargs) -> PolygonCompanion Create, register and activate a :class:`PolygonCompanion`. :param viewer: The :class:`~wolfhece.PyDraw.WolfMapViewer` instance. :param kwargs: Forwarded to the constructor. :return: The activated companion.