175 lines
6.9 KiB
Markdown
175 lines
6.9 KiB
Markdown
# INTEGRAZIONE: usare `python-map-manager` come git submodule in GeoElevation
|
|
|
|
Questo documento spiega come integrare `python-map-manager` in un progetto esistente
|
|
(ad esempio il repository `geoelevation`) come sottoprogetto (git submodule) e come
|
|
usarlo a runtime.
|
|
|
|
Nota: `python-map-manager` è pensato per essere GUI-agnostico — la logica core non
|
|
dipende da Tkinter/OpenCV; il demo `debug_tool.py` è separato e opzionale.
|
|
|
|
1) Aggiungere come git submodule
|
|
|
|
Dal repository principale (`geoelevation`) esegui (PowerShell):
|
|
|
|
```powershell
|
|
# posizionati nella root del repo geoelevation
|
|
cd C:\path\to\geoelevation
|
|
|
|
# aggiungi il submodule (sostituisci <REPO_URL> con l'URL del repo python-map-manager)
|
|
git submodule add <REPO_URL> submodules/python-map-manager
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
Se preferisci tenere il codice direttamente nella tree, puoi copiare la cartella,
|
|
ma usare un submodule mantiene la separazione e facilita aggiornamenti futuri.
|
|
|
|
2) Installare le dipendenze nell'ambiente del progetto
|
|
|
|
`python-map-manager` usa alcune librerie opzionali (Pillow, requests, mercantile, pyproj, ecc.).
|
|
Nel progetto principale, installa i requisiti del submodule nel virtualenv del progetto:
|
|
|
|
```powershell
|
|
python -m pip install -r submodules/python-map-manager/requirements.txt
|
|
```
|
|
|
|
3) Rendere importabile il package nel codice di `geoelevation`
|
|
|
|
Opzioni possibili:
|
|
|
|
- Aggiungere il submodule al `PYTHONPATH` (semplice, non richiede packaging):
|
|
|
|
- Esempio (PowerShell) per lanciare script dalla root del progetto:
|
|
|
|
```powershell
|
|
$env:PYTHONPATH = "$PWD\submodules\python-map-manager"; python -m your_app
|
|
```
|
|
|
|
- O aggiungere ad `sys.path` all'avvio dell'applicazione (es. in `geoelevation/__main__.py`):
|
|
|
|
```python
|
|
import os, sys
|
|
pkg_root = os.path.join(os.path.dirname(__file__), '..', 'submodules', 'python-map-manager')
|
|
if pkg_root not in sys.path:
|
|
sys.path.insert(0, pkg_root)
|
|
```
|
|
|
|
- (Opzionale) Se preferisci installare come pacchetto editable (richiede un `pyproject`/`setup`):
|
|
|
|
```powershell
|
|
pip install -e submodules/python-map-manager
|
|
```
|
|
|
|
4) Esempio rapido di utilizzo in `geoelevation`
|
|
|
|
```python
|
|
from map_manager.engine import MapEngine
|
|
|
|
# creare engine (cache_dir può essere un percorso gestito da geoelevation)
|
|
engine = MapEngine(service_name='osm', cache_dir='path/to/cache', enable_online=True)
|
|
|
|
# chiamata semplice (sincrona) per ottenere immagine area
|
|
img = engine.get_image_for_area((w, s, e, n), zoom=12)
|
|
|
|
# usare progress callback (esempio):
|
|
def progress_cb(done, total, last_tile_duration, from_cache, tile_coords):
|
|
# attenzione: callback può essere invocato da thread di lavoro
|
|
# se aggiornate UI dovete marshalare sull'UI thread (es. root.after in Tkinter)
|
|
print(f"{done}/{total} tiles — last {last_tile_duration:.2f}s — from_cache={from_cache} coords={tile_coords}")
|
|
|
|
img = engine.get_image_for_area((w, s, e, n), zoom=None, max_size=800, progress_callback=progress_cb)
|
|
```
|
|
|
|
5) Note su threading e UI
|
|
|
|
- `stitch_map_image` invoca il `progress_callback` dal thread dove viene eseguito
|
|
(cioè il thread che chiama `get_image_for_area` / `stitch_map_image`).
|
|
- Nel demo `debug_tool.py` le chiamate a `get_image_for_area` sono eseguite in un
|
|
worker thread e il callback marshala gli aggiornamenti con `root.after(...)`.
|
|
- Se integrate nelle GUI di `geoelevation`, assicuratevi di marshalarle similmente.
|
|
|
|
6) Dipendenze e packaging
|
|
|
|
- Se il vostro progetto usa un singolo `requirements.txt` o un `pyproject.toml`,
|
|
considerate aggiungere le dipendenze del submodule (contenute in
|
|
`submodules/python-map-manager/requirements.txt`) al file di dipendenze principale.
|
|
- Raccomando di usare un virtualenv isolato per lo sviluppo e i test.
|
|
|
|
7) Test e CI
|
|
|
|
- I test presenti in `python-map-manager/tests` possono essere eseguiti dalla root
|
|
del submodule. Quando integrate come submodule, nel CI aggiungete uno step che:
|
|
- installa le dipendenze
|
|
- esegue i test (es. `python -m pytest python-map-manager/tests`)
|
|
|
|
Domande frequenti (FAQ)
|
|
- Q: Il demo GUI è obbligatorio? A: No, è solo un tool per sviluppatori.
|
|
- Q: La libreria farà richieste in parallelo? A: Attualmente il comportamento di default
|
|
è sequenziale; possiamo abilitare download concorrenti come opzione sicura.
|
|
|
|
Se vuoi, posso aggiungere un esempio `geoelevation` che mostra come inizializzare
|
|
il `MapEngine` dal codice del progetto e integrare la pulizia della cache nei
|
|
comandi di gestione di `geoelevation`.
|
|
# Integration Guide — using `python-map-manager` from `geoelevation`
|
|
|
|
This document explains how to integrate the local `python-map-manager` package into the `geoelevation` application as a Git submodule (or as a local package) and shows example usage of the new public API (`MapEngine`, `MapVisualizer`).
|
|
|
|
1) Add as a git submodule (optional)
|
|
|
|
From the `geoelevation` repository root, add the external repo as a submodule:
|
|
|
|
```powershell
|
|
git submodule add -b master <URL_REPO> external/python-map-manager
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
If you're working locally and prefer to keep the module inside the same repo for now, copy the `python-map-manager` directory under `external/` or keep it at repo root.
|
|
|
|
2) Make the package importable
|
|
|
|
Options:
|
|
- Add the submodule path to `PYTHONPATH` at runtime, or
|
|
- Install the package into your environment (editable install) during development:
|
|
|
|
```powershell
|
|
python -m pip install -e external\python-map-manager
|
|
# or, for local-only testing
|
|
$env:PYTHONPATH+=';C:\path\to\geoelevation\external\python-map-manager'
|
|
```
|
|
|
|
3) Minimal usage example
|
|
|
|
In code, import the engine and visualizer:
|
|
|
|
```python
|
|
from map_manager.engine import MapEngine
|
|
from map_manager.visualizer import MapVisualizer
|
|
|
|
engine = MapEngine(service_name='osm', cache_dir='map_tile_cache', enable_online=True)
|
|
visual = MapVisualizer(engine)
|
|
|
|
# Example: get an image for a bbox (west,south,east,north)
|
|
bbox = (7.0, 45.0, 8.0, 46.0)
|
|
img = engine.get_image_for_area(bbox, max_size=1024) # choose zoom automatically
|
|
if img is not None:
|
|
visual.show_pil_image(img)
|
|
|
|
# For callbacks: set a click handler
|
|
def on_map_click(lat, lon):
|
|
elevation = query_elevation(lat, lon) # your app logic
|
|
print('Elevation', elevation)
|
|
|
|
visual.set_click_callback(on_map_click)
|
|
```
|
|
|
|
4) Integration points in `geoelevation`
|
|
|
|
- Replace internal `map_viewer` usage with the submodule API:
|
|
- Where `map_viewer` previously called tile download/stitching, replace with `MapEngine.get_image_for_area` or `get_image_for_point`.
|
|
- Where UI components called directly into `ElevationManager`, change to use `MapVisualizer` callbacks (subscribe your callback to `visual.set_click_callback`).
|
|
|
|
5) Notes and recommendations
|
|
|
|
- Keep `MapEngine` independent of `ElevationManager` — pass callbacks into `MapVisualizer` from `geoelevation` so the submodule does not import application business logic.
|
|
- For headless or server usage, do not import/use `MapVisualizer`; `MapEngine` works without OpenCV.
|
|
- Add `python-map-manager/requirements.txt` to your environment or include its dependencies in the main project's dependency list.
|