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
  • Plugin layout
  • Loading pipeline
  • Trust system
  • AbstractCompanion 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
• Companion sans menu — exemple minimal
  • Pourquoi se passer de menu ?
  • Ce que fait AbstractCompanion pour vous
  • 1 — Démarrage wx
  • 2 — Créer le viewer
  • 3 — La classe compagnon
  • 4 — Instancier et démarrer
  • 5 — Inspecter les points collectés
  • 6 — Arrêter et nettoyer
  • Récapitulatif — classe complète
• 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
• Companion plugin — complete reference
  • What the companion adds vs the raw API
  • Public API (call from notebook cells)
  • Protected helpers (use inside the companion class only)
  • OpenGL paint helpers (no import OpenGL required)
  • Dialog helpers (no import wx required)
  • Event handler signatures
  • MouseContext quick reference
  • KeyboardSnapshot quick reference
• 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 — sélection interactive de géométries
  • Interaction commune à tous
  • Usage minimal (one-liner)
  • 1 — Démarrage wx
  • 2 — Créer le viewer
  • 3 — Importer la factory
  • A — PointPickerCompanion : sélection de points isolés
  • B — PolylineCompanion : saisie d’une polyligne
  • C — MultiPolylineCompanion : plusieurs polylignes en une session
  • D — MultiPolylineZonesCompanion : polylignes dans un objet Zones
  • E — PolygonCompanion : saisie de polygones fermés
  • F — Personnalisation : surcharger les attributs de classe
  • G — Extension : ajouter un comportement au clic
  • Récapitulatif — référence rapide