## Objectif

TopoScan_V2 charge une image de topo, définit une entrée géographique, cale l’image en distance et/ou en GPS, puis crée un réseau de visées manuel exploitable en cartographie ou dans VisualTopo.

KML Google Earth / SIG TROX / TRO VisualTopo Projet JSON réouvrable

## Workflow recommandé

1. Charger l’image : `Projet > Charger image...`.
2. Définir l’entrée : bouton `Entrée` dans `Paramétrage` (panneau latéral droit), puis cliquer sur l’entrée et saisir latitude / longitude WGS84.
3. Définir l’échelle en 2 points ou 3 points selon la qualité de l’image.
4. Ajouter des points GPS de recalage pour servir de cible de recalage à l’export.
5. Saisir les visées avec Continuer, Branche ou Bouclage.
6. Contrôler la synthèse : ouvrir l’onglet `Synthèse` puis vérifier entrée, échelle, recalage export, longueur cumulée.
7. Exporter en KML et/ou TROX via `Actions rapides`.
8. Sauver le projet JSON pour reprendre le travail.

## Interface

### Zone image

Affiche la topo scannée, les croix d’entrée, points GPS, stations et segments.

### Panneau latéral

Actions rapides, paramétrage, saisie manuelle, puis une zone en onglets Tableau des visées / Synthèse.

### Barre d’état

Indication du mode (entrée, échelle, tracé…), coordonnées pixel, consignes et messages d’export.

Un libellé Mode : … dans le panneau résume l’action en cours (définition d’entrée, échelle, ancrage, ou inactif).

## Menu Projet

Commande | Fonction
--- | ---
`Charger image...` | Ouvre une image PNG, JPG, TIFF ou BMP.
`Charger projet JSON...` | Recharge image, entrée, ancrages, échelle, stations, visées, préférences d’affichage et vue.
`Sauver projet JSON...` | Sauvegarde l’état courant.
`Quitter` | Ferme l’application.

## Paramétrage

### Entrée

L’entrée crée automatiquement la station `0`. Elle est indispensable pour exporter, car elle fournit le point de départ géographique du réseau.

1. Cliquer le bouton Entrée dans `Paramétrage` (panneau latéral droit).
2. Cliquer dans l’image sur l’emplacement de l’entrée (l’enfoncement du bouton compte ; les coordonnées sont prises dès l’appui sur la partie visible de l’image).
3. Saisir latitude et longitude en WGS84, degrés décimaux, dans la boîte de dialogue.

Format attendu : latitude entre -90 et +90, longitude entre -180 et +180. La virgule décimale est acceptée.

### Points GPS de recalage

Les points GPS de recalage servent uniquement de cibles de recalage sur demande à l’export KML ou TROX/TRO. Ils ne déclenchent aucun calage automatique et ne remplacent pas l’échelle image.

1. Cliquer le bouton `Recalage GPS...` dans `Paramétrage`.
2. Cliquer `Ajouter`, puis cliquer l’emplacement du point connu dans l’image.
3. Saisir nom, latitude et longitude WGS84.

Après ajout d’un point, la liste Recalage GPS... se met à jour immédiatement.

Important : sans recalage demandé au moment de l’export, ces points sont ignorés. Le KML et le TROX restent basés sur `entrée GPS + échelle image`.

Avec 3 points GPS de recalage ou plus, le diagnostic de déformation peut aider à repérer une carte scannée tordue, mais ce diagnostic ne modifie pas l’export.

## Échelle image

### Mode 2 points

À utiliser si l’image est presque droite, nord vers le haut, pixels supposés carrés.

1. `Définir l’échelle X/Y (2 pts)` ou Echelle 2 pts.
2. Cliquer G à gauche.
3. Cliquer D à droite.
4. Saisir la distance réelle en mètres.

### Mode 3 points

Mode recommandé si l’image peut être tournée, inclinée ou si les axes X/Y doivent être définis proprement.

1. `Définir l’échelle X/Y (3 pts)` ou Echelle 3 pts.
2. Cliquer HG : haut gauche / référence nord.
3. Cliquer BG : bas gauche / origine.
4. Cliquer BD : bas droite / axe X.
5. Saisir les distances réelles X et Y.

Le mode 3 points calcule une base métrique X/Y et une correction nord. Il est en général préférable pour un calage soigné et pour l’export TROX. L’échelle 2 points suffit souvent en plus d’une entrée et fournit déjà un calage métrique pour les longueurs et azimuts.

## Saisie manuelle du réseau

La saisie repose sur `VDEPART`, station existante, et `VARRIVE`, station prévue ou existante selon le mode.

### Continuer depuis VDEPART

Crée une suite dans la même série. Exemple : depuis `0`, le premier clic crée `0 → 1`, puis le logiciel prépare `1 → 2`.

### Nouvelle branche

Crée une branche annexe avec préfixe alphabétique : `A0`, `A1`, `A2`. Le logiciel choisit le premier préfixe disponible.

### Tableau des visées

Chaque segment ajouté apparaît avec départ, arrivée, longueur et azimut si le calage métrique est disponible. Les boutons permettent de supprimer le dernier segment ou la ligne sélectionnée.

## Bouclage

Le bouclage relie deux stations déjà existantes sans cliquer sur l’image.

1. Saisir une station existante dans `VDEPART`.
2. Saisir une autre station existante dans `VARRIVE`.
3. Cliquer `Bouclage`.

Le départ et l’arrivée doivent exister et être différents.

## Exports

### KML

Le KML exporte l’entrée et les segments en coordonnées latitude / longitude. Il nécessite une entrée GPS et une échelle image exploitable. Les points GPS de recalage ne sont jamais appliqués automatiquement.

Règle anti-régression : sans recalage demandé à l’export, le KML utilise uniquement `entrée GPS + échelle image`. Les points GPS de recalage restent ignorés.

À l’export, l’option Recalage KML peut être activée : une station topo et un point GPS de recalage sont choisis dans des listes déroulantes. En KML, l’entrée est la référence absolue : elle reste fixe. Le recalage applique uniquement une rotation autour de l’entrée, sans translation globale.

L’angle appliqué est calculé avec l’azimut GPS `Entrée → point GPS de recalage` moins l’azimut topo `Entrée → station topo`, dans la base métrique de l’échelle image. Cela évite d’appliquer deux fois un recalage.

### TROX / TRO VisualTopo

Le TROX exporte les visées avec longueur et azimut. Il nécessite une entrée et une échelle image fiable en 2 ou 3 points. Les points GPS de recalage ne servent pas de calage métrique automatique.

Les longueurs `Long` des visées TROX sont exportées en mètres, avec 6 décimales. Les coordonnées de l’entrée sont exportées en UTM (WGS84), écrites dans `X`/`Y`, en kilomètres. La zone UTM est ajoutée au nom de cavité (ex. `[UTM 31N]`).

Important VisualTopo : choisir une projection UTM / WGS84 de la zone correspondante (ex. `UTM WGS84 Zone 31N`) et non `UTM / ED50`.

Nord géographique : après import du TROX, dans VisualTopo ouvrir `Cavité` → `Options` et régler le nord en géographique (pas magnétique), pour rester cohérent avec les azimuts issus de l’image calée dans TopoScan.

Résumé TROX : `DeclinAuto="M"` (déclinaison manuelle, pas magnétique automatique). Sans recalage : `Declin="0.0000"` sur `Param` et `Pte="0.00"` sur toutes les visées. Avec recalage : l’angle calculé (ex. `-26.5300`) est écrit dans l’attribut `Declin` de la ligne `Param` (ligne bleue). Ce n’est pas une déclinaison magnétique si la cavité est en nord géographique.

Si Recalage TROX/TRO est activé à l’export, l’angle est dérivé de la direction `Entrée → station topo choisie` par rapport au GPS `Entrée → point GPS de recalage cible`. L’angle de correction du recalage est calculé automatiquement (azimut GPS moins azimut topo, nord géographique, entre −180° et +180°). Les `Pte` des visées restent à `0.00` (plan).

`A` en déclinaison automatique côté VisualTopo appliquerait une déclinaison magnétique estimée (souvent ~15–20° en France), en général inadaptée à ces exports.

À la fin de l’export, une boîte récapitule les paramètres et l’entrée UTM.

## Préférences

Le menu `Préférences` règle :

- la couleur du tracé (segments du réseau) ;
- la couleur des noms de repères topo (étiquettes des stations et des points d’ancrage `R#:…`, hors entrée en orange) ;
- la taille du texte des mêmes repères (`Taille des noms (repères topo)`) : 7 à 18 pt (9 pt par défaut), police Segoe UI en gras.

Ces réglages sont enregistrés dans le projet JSON (`display_preferences` : noms de couleurs, taille de police `topo_label_font_size`).

## Contrôles et diagnostics

Indicateur | Interprétation
--- | ---
Entrée | Confirme la station `0` et ses coordonnées WGS84.
Échelle image | Affiche distances X/Y, pixels mesurés et correction nord.
Recalage export | Indique si un recalage KML/TROX/TRO a été demandé et calculé.
Contrôle déformation | Avec 3 points de recalage alignés, signale une éventuelle déformation de la carte scannée.
Réseau | Nombre de visées et longueur cumulée si le calcul métrique est disponible.

## Erreurs fréquentes

Le point de départ n’existe pas encore
La station saisie dans `VDEPART` n’a pas encore été créée. Démarrez depuis `0` après avoir défini l’entrée, ou utilisez une station déjà visible.
Le KML nécessite l’entrée GPS et une échelle image
Le logiciel ne peut pas convertir les pixels en coordonnées géographiques. Ajoutez des recalages GPS ou définissez une échelle utilisable.
Le TROX nécessite une échelle image (2 ou 3 points)
Les longueurs et azimuts ne sont pas fiables sans base en mètres. Définissez une échelle image avant l’export.
Plan VisualTopo en étoile
Vérifiez UTM WGS84, `DeclinAuto="M"`, cohérence du `Declin` sur `Param` (0 sans recalage TopoScan, angle calculé avec recalage), et surtout `Cavité` → `Options` → nord géographique. Désactivez la déclinaison magnétique automatique dans les paramètres de mesure si les azimuts sont déjà géographiques.
Une déclinaison ~18° apparaît sans recalage TopoScan
C’est en général la déclinaison magnétique automatique de VisualTopo (modèle type IGRF), pas un bug de longueur de visée. Le fichier TopoScan utilise `DeclinAuto="M"` et `Declin="0.0000"` sans recalage ; si vous voyez encore une déclinaison calculée, désactivez la case correspondante dans Paramètres de mesure ou réimportez un TROX généré par la version corrigée de TopoScan.
Image absente après chargement JSON
Le projet conserve le chemin de l’image. Si l’image a été déplacée, replacez-la au même endroit ou rechargez une image et sauvegardez à nouveau.

## Souris et raccourcis

Action | Effet
--- | ---
Clic gauche | Ajoute un point selon le mode actif : entrée et ancrage au press dans l’image ; échelle et visée au relâchement d’un simple clic (sans glisser pour annuler l’action).
Glisser clic gauche | Déplace l’image (panoramique) en mode neutre ou en saisie de visée. En entrée, ancrage ou échelle, le panoramique se fait plutôt au clic droit (glisser) pour ne pas mélanger avec la pose de points.
Glisser clic droit | Déplace l’image dans tous les modes.
Molette | Zoom avant / arrière centré sur le pointeur.
Échap | Annule le mode courant, vide une saisie d’échelle en cours et remet l’affichage du mode sur inactif pour le tracé.

## Contacter l'auteur

Pour questions, retours d’expérience ou signalement de problèmes concernant TopoScan_V2 :

pascal.mouneyrat@gmail.com

Dans l’application : menu `Aide` → `Contacter l'auteur` → `Écrire à …` ouvre votre logiciel de messagerie par défaut.

## Conseil de production

Pour un résultat propre : entrée, échelle 3 points, points GPS de recalage si disponibles, sauvegarde JSON avant export, puis contrôle du KML dans Google Earth ou QGIS.