FR:Mkgmap/help/splitter

From OpenStreetMap Wiki
Jump to navigation Jump to search

Le format utilisé par Garmin pour ses cartes a une taille limitée. Ceci implique de partitionner un fichier .osm couvrant une région détaillée en un nombre de fichiers (tuiles) plus petits. L'application splitter s'occupe de ce partitionnement. Il y a au moins 2 phases nécessaires pour le processus complet. Le premier est de calculer la couverture de chaque tuile à partir de la distribution des nœuds. Le deuxième écrit tous les nœuds, chemins (et implicitement polygones) et relations du fichier .osm original dans chaque tuile calculée dans la première phase. Avec l'option --keep-complete=true, 2 phases supplémentaires sont utilisées pour éviter les chemins ou polygones coupés.

Les deux fonctions principales sont :

  • taille variable des tuiles afin de ne pas avoir un nombre important de petites tuiles
  • jonction exacte des tuiles sans débordement ni trou

Premier pas

Vous aurez tout d'abord besoin de beaucoup de mémoire sur votre ordinateur si vous souhaitez partitionner une grande zone. Certaines options vous aident à configurer l'utilisation de la mémoire. Avec le paramétrage par défaut, vous avez besoin de 4-5 octets pour chaque point et chemin. Ceci donne l'impression que ce n'est pas beaucoup mais il y a plusieurs milliards de points dans le ficher complet de OSM et de ce fait vous ne pourrez pas partitionner le fichier de la planète entière d'un seul coup sur une machine 32 bits puisque le mémoire de tas (heap) deJava est de 2 Go. Il est possible sur une machine 64 bits d'élever le tas à 7 Go de faire plusieurs passes.

Le fichier Europe OSM de Cloudmade ou Geofabrik peut être partitionné dans la limite des 2 Go évoquée précédemment si vous avez suffisamment de mémoire. A l'aide du paramétrage par défaut vous obtiendrez plus de 750 tuiles. Le fichier Europe représente environ la moitié du fichier complet.

Le partitionnement d'un pays, même particulièrement bien couvert comment l'Allemagne ou le Royaume-Uni, sera possible sur une machine modeste voire même un netbook.

Téléchargement

Télécharger splitter depuis le serveur de mkgmap.

Le code source est disponible également sur ce même serveur.

Utilisation

Splitter nécessite Java 1.6 ou plus. L'archive ZIP contient plusieurs répertoires contenant des librairies mais aussi une documentation. L'appel de splitter se fait par la commande suivante :

java -jar splitter.jar file.osm > splitter.log

Si vous n'avez pas beaucoup de mémoire sur votre machine, l'option -Xmx sera peut-être nécessaire pour limiter l'usage de celle-ci par Java.

Lors du partitionnement, plusieurs tuiles OSM en format binaire (fichiers .osm.pbf) seront générées qui peuvent être lues par mkgmap. D'autres fichiers également sont générés :

  • Le fichier template.args contient la liste complète des tuiles générées et peut être utilisé par la suite par mkgmap pour la compilation à l'aide de l'option -c. Vous pouvez par exemple modifier ce fichier pour changer la description par défaut des tuiles et remplacer le "OSM Map" par une valeur appropriée.
  • Le fichier areas.list contient la liste des boites de délimitation qui ont été calculées lors de la première phase. Vous pouvez utiliser ou réutiliser ce fichier lors d'appel de splitter à l'aide de l'option --split-file ceci afin de réutiliser le même paramétrage des tuiles que précédemment. Ceci peut être utile pour générer des cartes ayants le même aspect lors d'actualisation des données sources OSM. Vous pouvez également réutiliser ce fichier pour gagner du temps puisque environ un tiers du temps utiliser par splitter est nécessaire pour calculer les boites de délimitation des tuiles. Bien entendu si les données sources augmentent radicalement vous risqueriez d'avoir un débordement d'une ou plusieurs tuiles, dans ce cas vous devez recalculer les boites de délimitation.
  • Le fichier areas.poly contient le polygone de découpage des tuiles. Voire l'option --polygon-file.
  • Le fichier densities-out.txt contient des informations pour le débogage.

Vous pouvez également utiliser des fichiers compressés gzip ou bzip/bz2. Notez que ceci peut ralentir considérablement le processus de partitionnement (particulièrement vrai pour les fichiers bz2) car la décompression des fichiers utilisera beaucoup de ressources du microprocesseur. Si vous souhaitez partitionner un fichier compressé plusieurs fois, il serait judicieux de convertir celui-ci en format binaire (pbf ou o5m). Le format o5m est plus rapide à lire mais demande plus d'espace disque.

options

Veuillez-vous référer à la documentation de splitter. Celle-ci est mise à jour régulièrement, là où les versions sur cette Wiki sont parfois obsolètes.

--boundary-tags=use-exclude-list
Indique une liste séparée par virgules des index de relations. Utilisé pour filtrer les polygones multiples (multipolygons) et relations de frontière lors du traitement des chemins et relation connus pour poser des problèmes dans le partitionnement. Voir également l’option --wanted-admin-level. Par défaut: use-exclude-list
--cache=
Obsolète, n’a plus aucune influence maintenant
--description=OSM Map
indique la description à écrire dans le fichier template.args.
--geonames-file=
Le nom du fichier GeoNames à utiliser pour déterminer les noms des tuiles. Typiquement cities15000.zip du site geonames
--keep-complete=true
Utiliser keep-complete=false pour désactiver les 2 phases supplémentaires entre le découpage et la distribution finale (non recommandé). Le première de ces phases, appelée gen-problem-list, détecte tous les chemins et relations qui coupent la limite d’une ou plusieurs tuiles. La seconde de ces phases, appelée handle-problem-list, rassemble les coordonnées de ces chemins et relations et calcul tous les fichiers de sortie qui coupent ou incluent ces coordonnées. L’information est transmise à la distribution finale à l’aide de 3 fichiers temporaires. Ceci évite des polygones cassés, mais sachez que cela implique la lecture supplémentaire des fichiers d’entrées au moins 2 fois.

N’utilisez pas cette option avec --overlap à moins que vous ayez une bonne raison de le faire.

--mapid=63240001
Définit le nom pour les tuiles. Dans cet exemple la première tuile sera appelée 63240001.osm.pbf et la suivante 63240002.osm.pbf etc.
--max-areas=2048
Le nombre maximum de zones qui peut être traité durant la deuxième phase de la procédure. Ce nombre doit se situer entre 1 et 9999. Un nombre plus élevé implique moins de traitement sur le fichier source et de ce fait sera plus rapide, mais demande plus de mémoire. Si vous n’avez plus de mémoire et que vous ne voulez pas augmenter la valeur de --max-nodes, essayer au contraire de réduire cette valeur. Ce changement n’aura pas d’influence sur la sortie mais aura uniquement une influence sur la manière de gérer la mémoire. Notez que la première phase a une mémoire fixe indépendamment de ce paramètre, donc si vous n’avez plus de mémoire avant la création du fichier areas.list, vous devriez soit augmenter la mémoire utilisée par Java avec -Xmx ou réduire la taille du fichier d’entrée que vous essayez de partitionner.
--max-nodes=1600000
Le nombre maximum de nœuds dans chaque fichier de sortie (tuile). La valeur par défaut est assez conservatrice, vous pouvez augmenter cette valeur sensiblement avant d’avoir un message d’erreur 'map too big' . Plus la valeur est grande, moins de mémoire sera utilisé pendant la phase de partitionnement.
--max-threads
Le nombre maximum de threads utilisé par splitter. Par défaut la valeur est automatique
--mixed
Spécifie si le fichier d’entrée osm a des nœuds, chemin et relation imbriqués ou si les index sont strictement triés. Pour accroitre la performance ; utilisez la fonction de tri de osmosis.
--no-trim
Ne rogne pas les espaces en dehors des limite des tuiles. Cette option est ignorée lorsque l’option --polygon-file est utilisée.
--output=pbf
Défini le format de sortie des fichiers de sorties. Les valeurs possibles sont xml, pbf, o5m et simulate. La valeur par défaut est pbf, qui produit des fichiers de plus petites tailles. Le format o5m est plus rapide à écrire mais créer des fichiers environ 40% plus gros. L’option simulate est utilisée pour le débogage.
--output-dir=.
Définit le répertoire de sortie où seront écrit les fichiers de sortie (tuiles). Si le répertoire indiqué n’existe pas, splitter essaie de le créer. Par défaut le répertoire actuel est utilisé.
--overlap=
Obsolète depuis la version r279. Avec l’option keep-complete=false, splitter devrait inclure des nœuds en dehors de limite de la tuile, de façon que mkgmap pourra couper soigneusement à la limite. La valeur est en unités de carte. Une valeur de 2000 correspond à environ 0,04 degrés de latitude ou longitude. Si l’option --keep-complete=true est active et --overlap a une valeur, un warning sera indiqué car la combinaison des 2 options n’a que très rarement du sens.
--polygon-file
Indique le nom du fichier polygone dans le format osmosis polygon. Splitter utilise ce fichier pour calculer les zones (première phase). Il calcule tout d’abord une grille en utilisant la résolution indiquée (--resolution). Le fichier d’entrée est lu et pour chaque nœud un compteur est incrémenté pour la zone concerné de la grille. Avec l’utilisation de cette option, les nœuds et même les zones complètes de la grille se trouvant en dehors des zones de limite indiquées seront ignorés.
--precomp-sea
Définit le nom du répertoire contenant les tuiles précompilées pour les mers/océans. Le traitement est identique à celui effectué par mkgmap. Utilisez cette option si vous utilisez un polygone de découpage ou l’option --no-trim=true et mkgmap créé des fichiers *.img vides avec un message du type "There is not enough room in a single garmin map for all the input data".
--problem-file
Défini le nom d’un fichier contenant les chemins et relations connus pour poser des problèmes dans le partitionnement. Utilisez cette option si --keep-complete demande trop de mémoire et l’option --overlap ne résout pas votre problème.
Syntaxe du fichier :
    way:<id> # commentaire...
    rel:<id> # commentaire...
exemple:
    way:2784765 # Ferry Guernsey - Jersey
--problem-report
Définit le nom du fichier à écrire avec la liste des erreurs lors de l’utilisation de l’option --keep-complete. Vous pouvez réutiliser ce fichier avec l’option --problem-file mais ne faites ceci uniquement si vous utilisez la même valeur pour max-nodes et resolution.
--resolution=13
Définit la résolution à laquelle la carte de densité (première phase) sera générée. La valeur se situe entre 1 et 24. La valeur par défaut est 13. Augmente la valeur de 13 à 14 augmente la mémoire requise pour la phase de partitionnement d’un facteur 4. Cette valeur est ignorée lors de l’utilisation de l’option --split-file.
--split-file=areas.list
Utilise une liste des zones calculées précédemment au lieur de recalculer ces zones depuis le départ. Le fichier peut aussi avoir le format *.kml.
--status-freq=xxx
Indique l’utilisation de la mémoire par l’environnement Java toutes les xxx secondes. Mettre la valeur 0 pour désactiver cet affichage. Par défaut la valeur est 120.
--stop-after=xxx
Débogage : s’arrête après la phase xxx, xxx peut avoir les valeurs split, gen-problem-list, ou handle-problem-list. La valeur par défaut est dist ce qui veut dire que toutes les phases sont exécutées.
--wanted-admin-level
Spécifie la valeur du niveau administratif le plus bas à utiliser pour compléter le partitionnement. Est utilisé pour filtrer les relations aux limites des tuiles. La valeur par défaut 5 conserve toutes les relations ayant un admin_level de 5 ou plus (5 à 11). Cette option est ignorée lors de l’utilisation de --keep-complete=false.
--write-kml
Définit le nom du fichier kml pour écrire les zones. Ce fichier est supplémentaire au fichier areas.list (qui lui est toujours générer).

Options spéciales

--version
Si la paramètre --version est trouvé quelque part dans les options, splitter affichera simplement la version et quittera l’exécution. L’information concernant la version ressemble à :
 splitter 279 compiled 2013-01-12T01:45:02+0000
--help
Si le paramètre --help est trouvé quelque part dans les options, splitter affichera la liste de toutes les options avec une petite aide et quittera l’exécution.

Amélioration

Amélioration pour de meilleurs performances

Quelques astuces pour ceux qui utilisent splitter avec des fichiers larges.

  • Pour une exécution plus rapide avec --keep-complete=true, convertissez le fichier d’entrée en format o5m utilisant :
osmconvert --drop-version file.osm -o=file.o5m
L’option --drop-version est optionnelle mais ne conserve que les données nécessaires par splitter et mkgmap
  • Si vous avez toujours de piètres performances, regardez dans le fichier splitter.log et cherchez le mot Distributing. Vous pourriez trouver quelque chose comme :
Processing 1502 areas in 3 passes, 501 areas at a time
Ceci veut dire que splitter doit lire le fichier 3 fois car le nombre de zones indiquées est beaucoup plus petit que celui trouvé. Si vous avez encore suffisamment de mémoire, augmentez le nombre de zone par exemple --max-areas=2048. Recommencer à exécuter splitter et vous devriez cette fois trouver quelque chose comme :
Processing 1502 areas in a single pass
  • Plus de zone demande plus de mémoire. Vérifiez que splitter a suffisamment de mémoire (mémoire tas ou heap) et éventuellement adapter celle-ci avec l’option -Xmx de Java.
  • Si possible utilisez 2 disques différents pour les fichiers d’entrée et de sortie en particulier si vous utilisez des fichiers aux format o5m.
  • Si vous utilisez mkgmap r2415 ou plus que vous n’avez pas de problèmes avec l’espace disque, vous devriez utiliser l’option --output=o5m pour augmenter les performances.

Amélioration avec une mémoire faible

Si votre machine a moins de 1 Go de mémoire (par exemple un netbook), vous pouvez utiliser splitter mais il faudra être patient si vous utilisez l’option --keep-complete et voulez partitionner un fichier comme l’Allemagne. Si nécessaire réduisez le nombre de zones à 50 à l’aide de l’option max-areas. Vous aurez à utiliser l’option --keep-complete=false pour partitionner une zone telle que l’Europe.

Notes

  • Il n’y a plus de limite supérieure pour le nombre de zones à générer (antérieurement limité à 255). Plus de zones implique plus de relecture du fichier d’entrée et de ce fait une exécution plus longue de splitter.
  • Il n’y a plus de limite quant au nombre de zones auxquelles un chemin ou une relation appartient (antérieurement limité à 4).