Development Guide

This section is intended for developers who want to contribute to the WOLF project. It provides guidelines and best practices for developing new features, fixing bugs, and maintaining the codebase.

Note

This section is under construction. It will be completed in the coming months. Please, be patient.

Contents:

• Structure interne
  • pyvertexvectors
• Native Crash — Re-entrant Import Under the Python Import Lock
  • Symptom
  • Root Cause
  • Fix Applied
  • Preventing Re-entrant Import Crashes in General
  • Detection Method
  • References
• Dialog Provider
  • Overview
  • Class reference
  • MockDialogProvider (testing)
  • Usage in tests
  • Migration guide
• Add Object Pipeline
  • Overview
  • Class-level constants
  • Public method: add_object
  • Pipeline phases
  • Handler contract
  • Adding a new object type: step-by-step guide
  • Reference: helper methods
  • Checklist
• Mouse Action System
  • Overview
  • The ActionKind enumeration
  • Starting and ending an action
  • Mouse handler architecture: dispatch tables
  • What remains inline in On_Mouse_Motion
  • What remains inline in On_Mouse_Button (wheel)
  • _endactions
  • Action groups (frozenset)
  • Adding a new action: step-by-step guide
  • Checklist
• Active-Object Slots (ActiveSlot)
  • Overview
  • ActiveSlot internals
  • Declared slots
  • The _active_slots registry
  • Adding a new active slot: step-by-step guide
  • Interaction with add_object
  • The _check_active guard helper
  • Convention summary
  • Checklist
• Scripting wolfhece from a VSCode Jupyter Notebook
  • How it works
  • Two entry points
  • Section A — Minimal viewer (WolfMapViewer)
  • Section B — Full production stack (MapManager)
  • Section C — Useful scripting patterns
  • Section D — Comparison with the standalone app (wolf.py)
  • Section E — Closing
• Plugin System
  • Overview
  • Runtime architecture (viewer ↔ manager ↔ plugin ↔ proxy)
  • Plugin layout
  • Loading pipeline
  • Trust system
  • AbstractUICompanion ABC
  • Ready-made factories
  • Creating a new plugin
  • Testing plugins
  • Adding a plugin to the built-in tier
  • API reference
• Action plugin — minimal example
  • Workflow
  • 1 — Imports and wx startup
  • 2 — Creating the MapViewer
  • 3 — Defining the plugin: position capture
  • 4 — Activating the action
  • 5 — Inspecting the collected points
  • 6 — Deactivating and cleaning up
  • 7 — Advanced example: motion handler (live preview)
• Action plugin — complete reference
  • 1 — wx startup
  • 2 — Create the MapViewer
  • 3 — Plugin state
  • 4 — Handler definitions
  • 5 — Register and activate
  • 6 — Inspect markers
  • 7 — Export markers as numpy array
  • 8 — Deactivate and clean up
  • Appendix — Available hooks summary
• Plugin overload — replacing and restoring an existing handler
  • 1 — wx startup
  • 2 — Viewer
  • 3 — Case 1: simple registration (new action)
  • 4 — Case 2: replacement without saving (overload=False)
  • 5 — Case 3: overload with saving (overload=True)
  • 6 — Live check
  • 7 — Unregister: automatic restoration of v2
  • 8 — Cascaded overloads
  • 9 — Final cleanup
  • API summary
• Menu-less companion - minimal example
  • Why skip a menu?
  • What AbstractUICompanion does for you
  • 1 - Start wx
  • 2 - Create the viewer
  • 3 - The companion class
  • 4 - Instantiate and start
  • 5 - Inspect collected points
  • 6 - Stop and clean up
  • Summary - full class
• Companion plugin — minimal example
  • What changes compared to the raw API?
  • Workflow
  • 1 — wx startup
  • 2 — Create the MapViewer
  • 3 — The companion class
  • 4 — Instantiate and attach the menu
  • 5 — Activate from the notebook (alternative to using the menu)
  • 6 — Inspect the collected points
  • 7 — Live coordinate display
  • 8 — Cleanup
  • Summary — companion vs raw API
  • 9 — Example: declarative multi-step action (MultiStepSpec)
• Companion plugin — complete reference
  • What the companion adds vs the raw API
  • Public API (call from notebook cells)
  • Proxy helpers (inside companion methods)
  • OpenGL paint pattern
  • Event handler signatures
• Companion plugin — overload and restore
  • The overload scenario
  • Overload rules (same as raw API)
  • 1 — wx startup
  • 2 — Viewer
  • 3 — Base companion (permanent handler)
  • 4 — Diagnostic companion (temporary overload)
  • 5 — Install the diagnostic handler
  • 6 — Live check
  • 7 — Remove the diagnostic handler (restores the base)
  • 8 — Cascaded overloads (same rules as raw API)
  • 9 — Final cleanup
  • Summary — overload with companions
• Companion factory — interactive geometry selection
  • Common interaction for all companions
  • Minimal usage (one-liner)
  • 1 — wx startup
  • 2 — Create the viewer
  • 3 — Import the factory
  • A — PointPickerCompanion: selecting individual points
  • B — PolylineCompanion: polyline input
  • C — MultiPolylineCompanion: multiple polylines in one session
  • D — MultiPolylineZonesCompanion: polylines in a Zones object
  • E — PolygonCompanion: closed polygon input
  • F — Customization: override class attributes
  • G — Extension: add click behavior
  • Quick reference summary