Improve smoothness by protecting visible tiles

Thyphoon desktop centering fixes

.gitignore

@@ -1,2 +1,3 @@
+
 PBMap.pb.bak
 *.exe

Demo.pb

@@ -33,8 +33,6 @@
 
 XIncludeFile "PBMap.pb"
 
-InitNetwork()
-
 CompilerIf #PB_Compiler_Thread = #False
   MessageRequester("Warning !", "You must enable 'Create ThreadSafe Executable' in compiler options", #PB_MessageRequester_Ok )
   End
@@ -70,6 +68,7 @@ Enumeration
   #Gdt_Degrees
   #Gdt_EditMode 
   #Gdt_ClearDiskCache
+  #Gdt_TestClusters
   #TextGeoLocationQuery
   #StringGeoLocationQuery
 EndEnumeration
@@ -85,6 +84,40 @@ Structure Location
   Latitude.d
 EndStructure
 
+; =============================================================================
+; SECTION : Constantes de demo clustering
+; OBJECTIF : Centraliser les coordonnees d'Eragny pour le test
+; POURQUOI : Faciliter le reglage et la maintenance
+; =============================================================================
+#ERAGNY_LAT = 49.0176
+#ERAGNY_LON = 2.0979
+
+; =============================================================================
+; SECTION : Test clustering
+; OBJECTIF : Generer un nuage de marqueurs autour d'Eragny
+; POURQUOI : Visualiser et valider le clustering
+; COMMENT : Distribution simple autour du centre
+; =============================================================================
+Procedure AddClusterTestMarkers(MapGadget.i)
+  Protected i.i
+  Protected Lat.d, Lon.d
+  
+  PBMap::ClearMarkers(MapGadget)
+  PBMap::SetOption(MapGadget, "EnableClusters", "1")
+  PBMap::SetOption(MapGadget, "ClusterPixelSize", "60")
+  PBMap::SetOption(MapGadget, "ClusterMinCount", "2")
+  
+  PBMap::SetLocation(MapGadget, #ERAGNY_LAT, #ERAGNY_LON, 13)
+  
+  For i = 0 To 49
+    Lat = #ERAGNY_LAT + (Random(100) - 50) / 10000.0
+    Lon = #ERAGNY_LON + (Random(100) - 50) / 10000.0
+    PBMap::AddMarker(MapGadget, Lat, Lon, "", "Cluster", RGBA(Random(255), Random(255), Random(255), 255))
+  Next
+  
+  PBMap::Refresh(MapGadget)
+EndProcedure
+
 Procedure UpdateLocation(*Location.Location)
   SetGadgetText(#StringLatitude, StrD(*Location\Latitude))
   SetGadgetText(#StringLongitude, StrD(*Location\Longitude))
@@ -169,6 +202,7 @@ Procedure ResizeAll()
   ResizeGadget(#Gdt_Degrees, WindowWidth(#Window_0)-170, #PB_Ignore, #PB_Ignore, #PB_Ignore)
   ResizeGadget(#Gdt_EditMode, WindowWidth(#Window_0)-170, #PB_Ignore, #PB_Ignore, #PB_Ignore)
   ResizeGadget(#Gdt_ClearDiskCache, WindowWidth(#Window_0)-170, #PB_Ignore, #PB_Ignore, #PB_Ignore)
+  ResizeGadget(#Gdt_TestClusters, WindowWidth(#Window_0)-170, #PB_Ignore, #PB_Ignore, #PB_Ignore)
   ResizeGadget(#TextGeoLocationQuery, WindowWidth(#Window_0)-170, #PB_Ignore, #PB_Ignore, #PB_Ignore)
   ResizeGadget(#StringGeoLocationQuery, WindowWidth(#Window_0)-170, #PB_Ignore, #PB_Ignore, #PB_Ignore)
   PBMap::Refresh(#Map)
@@ -205,8 +239,9 @@ If OpenWindow(#Window_0, 260, 225, 700, 571, "PBMap", #PB_Window_SystemMenu | #P
   ButtonGadget(#Gdt_Degrees, 530, 420, 150, 30, "Show/Hide Degrees", #PB_Button_Toggle)
   ButtonGadget(#Gdt_EditMode, 530, 450, 150, 30, "Edit mode ON/OFF", #PB_Button_Toggle)
   ButtonGadget(#Gdt_ClearDiskCache, 530, 480, 150, 30, "Clear disk cache", #PB_Button_Toggle)
-  TextGadget(#TextGeoLocationQuery, 530, 515, 150, 15, "Enter an address")
+  ButtonGadget(#Gdt_TestClusters, 530, 510, 150, 30, "Test clusters Eragny")
-  StringGadget(#StringGeoLocationQuery, 530, 530, 150, 20, "")
+  TextGadget(#TextGeoLocationQuery, 530, 545, 150, 15, "Enter an address")
+  StringGadget(#StringGeoLocationQuery, 530, 560, 150, 20, "")
   SetActiveGadget(#StringGeoLocationQuery)
   AddKeyboardShortcut(#Window_0, #PB_Shortcut_Return, #MenuEventGeoLocationStringEnter)
   ; *** TODO : code to remove when the SetActiveGadget(-1) will be fixed
@@ -341,6 +376,8 @@ If OpenWindow(#Window_0, 260, 225, 700, 571, "PBMap", #PB_Window_SystemMenu | #P
             EndIf
           Case #Gdt_ClearDiskCache
             PBMap::ClearDiskCache(#Map)
+          Case #Gdt_TestClusters
+            AddClusterTestMarkers(#Map)
           Case #StringGeoLocationQuery
             Select EventType()
               Case #PB_EventType_Focus
@@ -373,8 +410,9 @@ If OpenWindow(#Window_0, 260, 225, 700, 571, "PBMap", #PB_Window_SystemMenu | #P
 EndIf
 
 
-; IDE Options = PureBasic 5.73 LTS (Windows - x64)
+; IDE Options = PureBasic 6.21 (Windows - x64)
-; CursorPosition = 7
+; CursorPosition = 35
+; FirstLine = 31
 ; Folding = --
 ; EnableThread
-; EnableXP
+; EnableXP

PBMap_doc_fr.md

@@ -0,0 +1,461 @@
+# PBMap - Documentation FR (usage simple et complet)
+
+Ce document explique comment utiliser `pbmap/PBMap.pb` facilement, avec un demarrage rapide, des exemples et le detail de chaque procedure publique.
+
+## Demarrage rapide
+
+Objectif: afficher une carte, ajouter un marqueur et deplacer la vue.
+
+```purebasic
+IncludeFile "pbmap/PBMap.pb"
+
+EnableExplicit
+InitNetwork()
+
+UseModule PBMap
+
+Enumeration
+  #Win
+  #Map
+EndEnumeration
+
+If OpenWindow(#Win, 100, 100, 900, 600, "PBMap demo", #PB_Window_SystemMenu)
+  #Map = MapGadget(#PB_Any, 0, 0, 900, 600, 1, #Win)
+
+  ; Options utiles
+  SetOption(#Map, "ShowScale", "1")
+  SetOption(#Map, "ShowZoom", "1")
+  SetOption(#Map, "ShowMarkersLegend", "1")
+
+  ; Position de depart
+  SetLocation(#Map, 48.8566, 2.3522, 12)
+
+  ; Ajout d'un marqueur
+  AddMarker(#Map, 48.8566, 2.3522, "1", "Paris", RGBA(255, 80, 80, 255))
+
+  Repeat
+    Select WaitWindowEvent()
+      Case #PB_Event_CloseWindow
+        Break
+    EndSelect
+  ForEver
+EndIf
+```
+
+Notes importantes:
+- Activez "Create ThreadSafe Executable" dans les options du compilateur.
+- Appelez `InitNetwork()` avant les telechargements HTTP.
+- Les tuiles sont telechargees automatiquement via HTTP/HTTPS.
+
+## Ce que PBMap permet de faire
+
+- Afficher une carte (tuiles OSM/HERE/GeoServer).
+- Gerer des marqueurs (ajout, selection, edition).
+- Gerer des traces GPX (chargement, affichage, suppression).
+- Changer la vue (zoom, angle, centrage).
+- Configurer le cache disque et memoire.
+- Ajouter des callbacks pour reagir aux mouvements et aux clics.
+- Utiliser un clustering de marqueurs pour une meilleure lisibilite.
+
+## Configuration rapide des options utiles
+
+```purebasic
+PBMap::SetOption(#Map, "Verbose", "1")
+PBMap::SetOption(#Map, "ShowMarkersLegend", "1")
+PBMap::SetOption(#Map, "TileLifetime", "1209600") ; 2 semaines
+PBMap::SetOption(#Map, "EnableClusters", "1")
+PBMap::SetOption(#Map, "ClusterPixelSize", "60")
+PBMap::SetOption(#Map, "ClusterMinCount", "2")
+```
+
+## API publique - procedures et exemples
+
+Les exemples supposent l'existence d'une carte `#Map`.
+
+### SetDebugLevel(Level.i)
+Definit le niveau de debug (0..5).
+```purebasic
+PBMap::SetDebugLevel(3)
+```
+
+### SetOption(MapGadget.i, Option.s, Value.s)
+Change une option via une cle texte.
+```purebasic
+PBMap::SetOption(#Map, "ShowZoom", "1")
+```
+
+### GetOption(MapGadget.i, Option.s)
+Lit une option sous forme de chaine.
+```purebasic
+Debug PBMap::GetOption(#Map, "ShowZoom")
+```
+
+### LoadOptions(MapGadget.i, PreferencesFile.s = "PBMap.prefs")
+Charge les options depuis un fichier.
+```purebasic
+PBMap::LoadOptions(#Map, "PBMap.prefs")
+```
+
+### SaveOptions(MapGadget.i, PreferencesFile.s = "PBMap.prefs")
+Sauvegarde les options.
+```purebasic
+PBMap::SaveOptions(#Map, "PBMap.prefs")
+```
+
+### AddOSMServerLayer(MapGadget.i, LayerName.s, Order.i, ServerURL.s)
+Ajoute une couche OSM.
+```purebasic
+PBMap::AddOSMServerLayer(#Map, "OSM", 1, "https://tile.openstreetmap.org/")
+```
+
+### AddHereServerLayer(...)
+Ajoute une couche HERE (necessite AppId/AppCode).
+```purebasic
+PBMap::AddHereServerLayer(#Map, "HERE", 2, "APP_ID", "APP_CODE")
+```
+
+### AddGeoServerLayer(...)
+Ajoute une couche GeoServer.
+```purebasic
+PBMap::AddGeoServerLayer(#Map, "WMS", 3, "layer-name", "http://localhost:8080/")
+```
+
+### IsLayer(MapGadget.i, Name.s)
+Teste si une couche existe.
+```purebasic
+If PBMap::IsLayer(#Map, "OSM")
+  Debug "Layer OSM ok"
+EndIf
+```
+
+### DeleteLayer(MapGadget.i, Name.s)
+Supprime une couche.
+```purebasic
+PBMap::DeleteLayer(#Map, "WMS")
+```
+
+### EnableLayer(MapGadget.i, Name.s)
+Active une couche.
+```purebasic
+PBMap::EnableLayer(#Map, "OSM")
+```
+
+### DisableLayer(MapGadget.i, Name.s)
+Desactive une couche.
+```purebasic
+PBMap::DisableLayer(#Map, "HERE")
+```
+
+### SetLayerAlpha(MapGadget.i, Name.s, Alpha.d)
+Change la transparence d'une couche (0..1).
+```purebasic
+PBMap::SetLayerAlpha(#Map, "WMS", 0.5)
+```
+
+### GetLayerAlpha(MapGadget.i, Name.s)
+Lit la transparence d'une couche.
+```purebasic
+Debug PBMap::GetLayerAlpha(#Map, "WMS")
+```
+
+### BindMapGadget(MapGadget.i, TimerNB = 1, Window = -1)
+Attache PBMap a un Canvas existant.
+```purebasic
+PBMap::BindMapGadget(#MyCanvas, 1, #Win)
+```
+
+### SetCallBackLocation(MapGadget.i, *CallBackLocation)
+Callback: appel lors d'un changement de position (lat/lon).
+```purebasic
+Procedure OnMove(*Pos.PBMap::GeographicCoordinates)
+  Debug StrD(*Pos\Latitude) + ", " + StrD(*Pos\Longitude)
+EndProcedure
+PBMap::SetCallBackLocation(#Map, @OnMove())
+```
+
+### SetCallBackMainPointer(MapGadget.i, CallBackMainPointer.i)
+Callback pour dessiner le pointeur principal.
+```purebasic
+Procedure DrawPointer(x.i, y.i)
+  ; custom drawing
+EndProcedure
+PBMap::SetCallBackMainPointer(#Map, @DrawPointer())
+```
+
+### SetCallBackDrawTile(MapGadget.i, *CallBackLocation)
+Callback pour personnaliser le dessin d'une tuile.
+```purebasic
+Procedure DrawTile(x.i, y.i, image.i, alpha.d)
+  ; custom drawing
+EndProcedure
+PBMap::SetCallBackDrawTile(#Map, @DrawTile())
+```
+
+### SetCallBackMarker(MapGadget.i, *CallBackLocation)
+Callback appele quand un marqueur a ete deplace (selection).
+```purebasic
+Procedure OnMarkerChange(*Marker.PBMap::Marker)
+  Debug *Marker\Identifier
+EndProcedure
+PBMap::SetCallBackMarker(#Map, @OnMarkerChange())
+```
+
+### SetCallBackLeftClic(MapGadget.i, *CallBackLocation)
+Callback lors d'un clic gauche sur la carte.
+```purebasic
+Procedure OnLeftClick(*Pos.PBMap::GeographicCoordinates)
+  Debug StrD(*Pos\Latitude)
+EndProcedure
+PBMap::SetCallBackLeftClic(#Map, @OnLeftClick())
+```
+
+### SetCallBackModifyTileFile(MapGadget.i, *CallBackLocation)
+Callback pour modifier un fichier de tuile apres telechargement.
+```purebasic
+Procedure.s OnTileFile(FileName.s, Url.s)
+  ProcedureReturn FileName
+EndProcedure
+PBMap::SetCallBackModifyTileFile(#Map, @OnTileFile())
+```
+
+### MapGadget(MapGadget.i, X.i, Y.i, Width.i, Height.i, TimerNB = 1, Window = -1)
+Cree un canvas + PBMap.
+```purebasic
+#Map = PBMap::MapGadget(#PB_Any, 0, 0, 800, 600, 1, #Win)
+```
+
+### FreeMapGadget(MapGadget.i)
+Libere une carte.
+```purebasic
+PBMap::FreeMapGadget(#Map)
+```
+
+### GetLatitude(MapGadget.i)
+Latitude courante.
+```purebasic
+Debug StrD(PBMap::GetLatitude(#Map))
+```
+
+### GetLongitude(MapGadget.i)
+Longitude courante.
+```purebasic
+Debug StrD(PBMap::GetLongitude(#Map))
+```
+
+### GetMouseLatitude(MapGadget.i)
+Latitude sous la souris.
+```purebasic
+Debug StrD(PBMap::GetMouseLatitude(#Map))
+```
+
+### GetMouseLongitude(MapGadget.i)
+Longitude sous la souris.
+```purebasic
+Debug StrD(PBMap::GetMouseLongitude(#Map))
+```
+
+### GetAngle(MapGadget.i)
+Angle actuel.
+```purebasic
+Debug StrD(PBMap::GetAngle(#Map))
+```
+
+### GetZoom(MapGadget.i)
+Zoom actuel.
+```purebasic
+Debug PBMap::GetZoom(#Map)
+```
+
+### GetMode(MapGadget.i)
+Mode utilisateur courant.
+```purebasic
+Debug PBMap::GetMode(#Map)
+```
+
+### SetMode(MapGadget.i, Mode.i = #MODE_DEFAULT)
+Definit le mode.
+```purebasic
+PBMap::SetMode(#Map, PBMap::#MODE_HAND)
+```
+
+### SetMapScaleUnit(MapGadget.i, ScaleUnit = PBMap::#SCALE_KM)
+Definit l'unite d'echelle.
+```purebasic
+PBMap::SetMapScaleUnit(#Map, PBMap::#SCALE_NAUTICAL)
+```
+
+### SetLocation(MapGadget.i, Latitude.d, Longitude.d, Zoom = -1, Mode.i = #PB_Absolute)
+Centre la carte.
+```purebasic
+PBMap::SetLocation(#Map, 48.8566, 2.3522, 12)
+```
+
+### SetAngle(MapGadget.i, Angle.d, Mode = #PB_Absolute)
+Change l'angle.
+```purebasic
+PBMap::SetAngle(#Map, 15.0, #PB_Absolute)
+```
+
+### SetZoom(MapGadget.i, Zoom.i, Mode.i = #PB_Relative)
+Change le zoom.
+```purebasic
+PBMap::SetZoom(#Map, 1, #PB_Relative)
+```
+
+### SetZoomToArea(MapGadget.i, MinY.d, MaxY.d, MinX.d, MaxX.d)
+Zoom sur une zone.
+```purebasic
+PBMap::SetZoomToArea(#Map, 48.80, 48.90, 2.30, 2.40)
+```
+
+### SetZoomToTracks(MapGadget.i, *Tracks)
+Zoom automatique sur une trace.
+```purebasic
+PBMap::SetZoomToTracks(#Map, *Track)
+```
+
+### NominatimGeoLocationQuery(MapGadget.i, Address.s, *ReturnPosition = 0)
+Geocodage d'une adresse via Nominatim.
+```purebasic
+Define Pos.PBMap::GeographicCoordinates
+PBMap::NominatimGeoLocationQuery(#Map, "Paris", @Pos)
+```
+
+### LoadGpxFile(MapGadget.i, FileName.s)
+Charge un fichier GPX.
+```purebasic
+Define *Track = PBMap::LoadGpxFile(#Map, "track.gpx")
+```
+
+### SaveGpxFile(MapGadget.i, FileName.s, *Track)
+Sauvegarde une trace GPX.
+```purebasic
+PBMap::SaveGpxFile(#Map, "export.gpx", *Track)
+```
+
+### ClearTracks(MapGadget.i)
+Supprime toutes les traces.
+```purebasic
+PBMap::ClearTracks(#Map)
+```
+
+### DeleteTrack(MapGadget.i, *Ptr)
+Supprime une trace.
+```purebasic
+PBMap::DeleteTrack(#Map, *Track)
+```
+
+### DeleteSelectedTracks(MapGadget.i)
+Supprime les traces selectionnees.
+```purebasic
+PBMap::DeleteSelectedTracks(#Map)
+```
+
+### SetTrackColour(MapGadget.i, *Ptr, Colour.i)
+Change la couleur d'une trace.
+```purebasic
+PBMap::SetTrackColour(#Map, *Track, RGBA(0, 200, 0, 200))
+```
+
+### AddMarker(MapGadget.i, Latitude.d, Longitude.d, Identifier.s = "", Legend.s = "", Color.l = -1, CallBackPointer.i = -1)
+Ajoute un marqueur.
+```purebasic
+PBMap::AddMarker(#Map, 48.86, 2.35, "A", "Point A", RGBA(255, 80, 80, 255))
+```
+
+### ClearMarkers(MapGadget.i)
+Supprime tous les marqueurs.
+```purebasic
+PBMap::ClearMarkers(#Map)
+```
+
+### DeleteMarker(MapGadget.i, *Ptr)
+Supprime un marqueur.
+```purebasic
+PBMap::DeleteMarker(#Map, *Marker)
+```
+
+### DeleteSelectedMarkers(MapGadget.i)
+Supprime les marqueurs selectionnes.
+```purebasic
+PBMap::DeleteSelectedMarkers(#Map)
+```
+
+### Drawing(MapGadget.i)
+Force un rendu immediat.
+```purebasic
+PBMap::Drawing(#Map)
+```
+
+### FatalError(MapGadget.i, msg.s)
+Affiche une erreur et termine.
+```purebasic
+PBMap::FatalError(#Map, "Erreur critique")
+```
+
+### Error(MapGadget.i, msg.s)
+Affiche une erreur simple.
+```purebasic
+PBMap::Error(#Map, "Erreur")
+```
+
+### Refresh(MapGadget.i)
+Demande un rafraichissement.
+```purebasic
+PBMap::Refresh(#Map)
+```
+
+### ClearDiskCache(MapGadget.i)
+Vide le cache disque.
+```purebasic
+PBMap::ClearDiskCache(#Map)
+```
+
+## Clustering des marqueurs (explication)
+
+Le clustering regroupe les marqueurs proches en un seul cercle.
+- `EnableClusters`: active ou non.
+- `ClusterPixelSize`: taille de la grille (en pixels).
+- `ClusterMinCount`: nombre minimum pour afficher un cluster.
+
+Double-clic sur un cluster: zoom sur le centre du cluster.
+
+## Astuces pratiques
+
+- Activez `Verbose` pour diagnostiquer les chargements de tuiles.
+- Utilisez `TileLifetime` pour gerer l'expiration du cache.
+- Si vous avez beaucoup de marqueurs, activez le clustering.
+- Pour des couches multiples, ajustez `SetLayerAlpha`.
+- Si l'interface devient lente, reduisez `MaxThreads` ou `MaxDownloadSlots`.
+
+## Exemple complet (avec clustering)
+
+```purebasic
+IncludeFile "pbmap/PBMap.pb"
+InitNetwork()
+UseModule PBMap
+
+Enumeration
+  #Win
+EndEnumeration
+
+OpenWindow(#Win, 0, 0, 1000, 700, "PBMap clustering", #PB_Window_SystemMenu)
+Define MapId = MapGadget(#PB_Any, 0, 0, 1000, 700, 1, #Win)
+
+SetOption(MapId, "EnableClusters", "1")
+SetOption(MapId, "ClusterPixelSize", "60")
+SetOption(MapId, "ClusterMinCount", "2")
+
+SetLocation(MapId, 48.8566, 2.3522, 10)
+
+AddMarker(MapId, 48.85, 2.34, "1", "A", RGBA(255, 80, 80, 255))
+AddMarker(MapId, 48.86, 2.35, "2", "B", RGBA(255, 80, 80, 255))
+AddMarker(MapId, 48.87, 2.36, "3", "C", RGBA(255, 80, 80, 255))
+
+Repeat
+  Select WaitWindowEvent()
+    Case #PB_Event_CloseWindow
+      Break
+  EndSelect
+ForEver
+```

README.md

@@ -1,19 +1,22 @@
-# PBMap 0.91
+# PBMap 0.98
+
 Open source tiled map software.
 
 Module to develop tiled map applications in PureBasic, like  like OpenStreetMap(c), Google Maps(c), Here(c), ...
 
 
+
 Functional example based on OpenStreetMap(c) services
 
 OSM copyright : http://www.openstreetmap.org/copyright
 
 
+
 This code is free, but any user should mention the origin of this code.
 
 Official forums topics :
-http://www.purebasic.fr/english/viewtopic.php?f=27&t=66320 (english)
+http://www.purebasic.fr/english/viewtopic.php?f=27\&t=66320 (english)
-http://www.purebasic.fr/french/viewtopic.php?f=3&t=16160 (french)
+http://www.purebasic.fr/french/viewtopic.php?f=3\&t=16160 (french)
 
 Contributors :
 Thyphoon
@@ -27,3 +30,4 @@ André
 falsam
 
 Special thanks to Fred and Fantaisie Software's team
+