Ce chapitre décrit une utilisation avancée de Thérion:

• le compilateur de xtherion
• comprendre les erreurs d’exécution
• utilisation du debuggeur

Le panneau de la fenêtre de compilation de xtherion a quatre contrôles:

• “Settings”, (paramètres) pour les paramètres d’exécution de therion. Ceux-ci ont été décrit dans le chapitre 1.3.
• “Survey structure” (structure de la topo) présente l’organisation hiérarchique des fichiers de données de la topo surveys;
• “Survey info” (infos de la topo) affiche quelques infos sur la topo quand vous cliquez sur le bouton “Survey structure”;
• “Map structure” (structure de la carte) affiche la structure de la carte (map) de la topographie.

Les dessins suivants montrent l’exemple de présentation qui a deux topos. Les informations pour le premier, s1, sont affichées dans le contrôle “Survey info” control. Il y a quatre cartes.

select (thconfig command)
Quand vous double-cliquez sur une ligne de la topo dans le contrôle “Map structure”, xtherion insert une commande “select” pour cette carte dans le fichier de configuration (au début du fichier) [thwiki 14].

Cette section décrit quelques erreurs et problèmes que vous pouvez avoir en utilisant therion. Elle indique les solutions pour les résoudre a La Mode Thérion.

Cela arrive lorsque vous cliquez deux fois (double-clique) sur la même ligne pendant que vous définissez une surface. Dans ce cas, le contour de la surface calcule par therion risque ne plus être celui que vous attendez.

Pour éviter cette erreur, contrôlez dans le contrôle “Areas” (surfaces) la liste des lignes formant le contour de la surface. Quand vous cliquez deux fois sur la même ligne, il apparaît dans la liste deux lignes identiques consécutives. Pour résoudre ce problème, sélectionnez une des deux lignes, et dans le panneau, appuyez sur le bouton “Delete” du menu “Area control”.

Répéter deux fois le même point de contrôle sur la ligne n’est pas une erreur, mais le résultat (le tracé de la ligne) peut être différent de votre souhait.

Dans le contrôle “Line” vous pouvez controler la liste des points qui composent la ligne, et vérifier si l’un d’eux apparaît 2 fois. Si c’est le cas, vous pouvez en supprimer un via le menu “Line edit | delete point”, après avoir sélectionné le point (ou éditer le fichier .th2 avec un éditeur de texte).

cursor
Tous les éléments graphiques doivent apparaître dans un scrap, cad entre une commande scrap et sa commande endscrap. Quand vous insérez un élément graphique dans le dessin, une nouvelle ligne est ajoutée à la position du curseur dans la liste du contrôle des “Objets”, et le nouvel élément est inséré sur cette ligne. Le curseur est la “ligne noire” entre les lignes de la liste.

Quand le curseur est entre “endscrap” et “endoffile” le nouvel élément est placé en dehors de tout scrap. La seule chose que vous pouvez insérer ici est un nouveau scrap. En fait un scrap ne peut être inséré dans un autre scrap. xtherion met le curseur ici a chaque fois que vous ouvrez un fichier, prêt à ajouter un nouveau scrap.

De toute façon, ce n’est pas la bonne solution (ajouter un nouveau scrap) pour faire des corrections sur le dessin d’un scrap existant. Vous devez déplacer le curseur dans le scrap en cliquant sur l’élément après lequel vous voulez ajouter les nouveaux objets. Ainsi le curseur apparaitra après celui-ci.

S’il vous arrive d’ajouter des éléments en dehors d’un scrap, therion affiche une erreur lors de la compilation,

     missing scrap before line command
  

(il manque un scrap avant la ligne de commande). Pour corriger cette erreur, ouvrez le contrôle “Objects”, sélectionnez la ligne “endscrap”, et déplacez-la vers le bas en utilisant le bouton “Move down” jusqu'à ce qu’il n’y ait plus d’éléments hors du scrap.

Quand il y a des stations topo dupliquées (ex : un même nom de station topo affecté à plus d’un point) therion ne se plaint pas, mais la carte ne ressemble pas a ce que vous voulez. D’un autre coté, quand des points topos ont de mauvais noms (cad des noms qui n’existent pas parmi les stations topos) “therion” donne un message d’erreur (XXX est le mauvais nom de point)

      invalid station reference -- XXX
  

Quelque chose de similaire se passe quand vous affectez le affectez un mauvais nom de station : la topo de la grotte est déformée car les scraps sont assembles pour coller les mesures topographiques (données centerline).

Le debugger est utile pour voir les différentes positions ou les scraps sont placées lorsque therion composes la carte. Il peut être utile de mettre en commentaire la commande “join” durant le debug, pour inhiber les transformations causées par la transformation du join [thwiki 4].

S’il vous arrive de mettre un élément graphique dans un scrap et de réaliser que vous le voulez dans un autre scrap, vous devez le déplacer d’un scrap a l’autre.

Ceci est assez simple si les scraps sont dans le même fichier. Ouvrez le fichier dans l’éditeur de carte de xtherion et déplacez les éléments en utilisant le bouton “Move” du contrôle “Objects”.

Il est possible de deplacer des elements graphiques entre deux fichier, mais cette operation necessite beaucoup d’attention, c’est pourquoi il est generalement plus simple de supprimer l’element dans un fichier et de le redessiner dans le second. Si vous voulez essayer quand meme, voici comment faire. Comme l’editeur de carte de xtherion ne peut ouvrir qu’une carte a la fois, vous devrez utiliser l’editeur de texte de “xterion” (saisie des points topo). Cela est possible car les fichiers de carte sont des fichiers texte avec des instructions pour dessiner les topos.

Ouvrez les deux fichiers et utilisez le champ “id” pour identifier l’élément que vous voulez déplacer d’un fichier a l’autre. Coupez la ligne du premier fichier et collez-la dans le second. Généralement cela suffit : l’élément graphique est positionne dans une structure de référence. Même si les deux scrap ont le même “-scale”, la position de la structure est donnée par la position des points de type “station”.

Maintenant vous pouvez ouvrir le second fichier avec l’éditeur de carte de xtherion et positionner l’élément, que vous venez de coller, a la bonne position (dans le dessin).

Les fichiers temporaires de therion, MetaPost et pdfTeX sont placés dans le répertoire temporaire “/tmp/thPID” ou PID est le numéro du processus du logiciel de therion.

debug
Quand therion est appelé avec l’option “-d” (debug) sur la ligne de commande, il crée le répertoire /tmp/thTMPDIR et stocke ici les fichiers intermédiaires. Ce répertoire n’est pas supprimé par therion, et les fichiers présents ne sot pas non plus effacés à la fin de l’exécution. Vous devez les supprimer manuellement.

A. Atkinson a rencontre le problème suivant : il a scrap avec un triangle blanc (en arrière plan) dans le scrap.

outline
S. Mudrak repond a son mail avec une solution pour contourner le problème:

Quand j’ajoute “wall -subtype invisible” comme indique dans le dessin, alors
le problème est résolu. De même, avec “border -subtype invisible -outline out”.
Therion ne connecte pas toujours les murs dans le bon ordre.
J’en suis désolé, il doit y avoir quelques bugs dans le programme de “outline finding”
(la recherche des murs extérieurs) mais c’est tres difficile a trouver, et
généralement, utiliser l’option “invisible outlines” résout le problème.

Pour éviter cela, évitez d’utiliser des lignes courtes (avec seulement 2 points) ayant des sous-types (subtypes) généraux. Cela cause des erreurs quand \tt{therion} analyse les murs et cherche la continuation la plus proche et identifie une ligne qui n’est pas “la bonne”, mais saute sur une autre ligne débutant assez prêt de ce bout de ligne. Utilisez plutôt le sous type “point_of_line” et tracez des murs les plus longs possibles. (M. Sluka).

debug
therion est un langage, un ensemble de règles, cad, une syntaxe, pour décrire le dessin d’une topographie en fichier texte. Ecrire des fichiers therion, que ce soit des fichiers de configuration ou de données, ressemble a l’écriture d’un programme pour un ordinateur (en utilisant un langage de programmation). En fait, un projet therion doit être compilé pour produire un résultat : la topo de la grotte, le modèle 3D, etc. Tout comme un programme pour ordinateur doit être compile pour générer un exécutable. Le résultat de la compilation de “therion” ne sont pas des exécutables, mais des documents (pdf, .3d) qui peuvent être affichés et/ou imprimés.

Quand quelqu’un écrit un programme d’ordinateur, il peut faire des erreurs et le programme ne fait pas ce qu’il attend. Il/elle a besoin de corriger ses erreurs, le processus d’identification des erreurs et de correction s’appelle “débogage”. Quelque chose de similaire se produit avec le projet therion et le process pour corriger les erreurs dans un projet therion est également appelé “débogage”.

Parfois les erreurs sont simple (ex : oublier l’option “-subtype presumed” pour une ligne “wall”), et le résultat n’est pas correcte, mais il est “presque” bon. D’autres fois, les erreurs sont plus sérieuses, comme donner de mauvais noms aux points “station”, et le résultat devient très mauvais. Le résultat peu être tellement différent de ce que l’on attend que le débogage de l’erreur devient difficile sans outils de “débogue”.

Pour les programmes informatique, le débogage des erreurs se produit en deux phase : lors de la compilation et lors de l’exécution (cad, durant l’exécution du programme). La même chose se produit pour therion. Dans le premier cas “xtherion” lui-même, ou le programme graphique, détecte une erreur et la pointe en rouge dans la fenêtre de compilation. Cela correspond au compilateur de langages informatiques qui détectent les erreurs syntaxiques et les indique lors de la compilation. S’il n’y a pas d’erreur de syntaxe, la compilation est bonne et “xtherion” écrit “OK” en vert.

Mais les erreurs les plus difficiles sont les erreurs “sémantiques”. Le compilateur ne peut pas les pointer, car la syntaxe est correcte. Le problème est que les instructions désignen ce que vous ne voudriez pas, et le dessin n’est pas ce qui est attendu. Le compilateur ne peut pas lire dans votre cerveau, il se contente de lire les instructions que vous avez écris dans le fichier, et, dans ce cas précis, il ne trouve rien de mal. Dans le cas d’un programme informatique (normal), vous pouvez exécuter le programme dans un débogueur pour suivre les diverses étapes d’exécution jusqu'à ce que vous découvriez pourquoi le programme ne fait pas ce que vous “attendez”, et trouviez la cause de l’erreur.

Pour therion une erreur sémantique signifie, par exemple, que la topo de la grotte ne correspond pas à ce que l’on attend (lac au mauvais endroit, mur de galerie du mauvais style). Et nous voyons qu’il y a une erreur quand nous visualisons la topo (ou le modèle 3D). Malheureusement, xtherion n’est pas WYSIWYG, et il ne présente pas les données tel que vous les voyez sur la sortie (fichier PDF, ou 3D). Ceci est inévitable car therion génère différents types de sorties. De plus, les données d’entrées sont transformées par “therion” durant le processus de génération des résultats.

Therion offre deux fonctions de débogage : l’option de ligne de commande “-d” et l’option de layout “debug on”.

Quand vous positionnez l’option “debug on” dans le layout, therion incluse dans le document pdf génère les étapes intermédiaires de la transformation des scraps. Celles-ci sont dessinées avec différentes couleurs.

• lignes rouges: les scraps original (après rotation et remise à l’échelle);
• lignes bleues: les scraps ajustées à la position des points “station” (avant les joins de scrap);
• points en rouge: positions originales des points “station”;
• points jaune connectés par des lignes jaunes: positions initiales des paires de points ayant la distorsion maximale;
• points noir connectes par des lignes noirs: positions finales des paires de points ayant la distorsion maximale;
• points orange: points ayant le changement maximal (de position), dans la transformation;
• lignes jaunes entre points jaunes et noires: déplacement de ces points.

Mais alors, comment interpréter ces informations?

1. La distortion maximale d'un scrap est proportionnelle à la distance entre un point noir et son point jaune correspondant (ils sont reliés par un trait jaune).
2. Si les points noirs sont confondus sous leurs points jaunes correspondants c'est quee la distortion du scrap n'est pas significative.

L’option de layout “debug” peut également avoir d’autres valeurs:

• “off” désactive le débogage
• “on” active le débogage
• “all” affiche toutes les informations de débogage
• “first” affiche le dessin après la première étage de transformation (la partie linéaire);
• “second” affiche le dessin après la seconde étape de transformation;
• “scrap-names” affiche les noms de scraps;
• “station-names” affiche le nom des stations.

Une autre technique de débogage intéressante est de calculer seulement quelques morceaux de la topo pour être sur qu’ils sont correcte. Ceci peut être réalisé en utilisant l’option de configuration “select”, et/ou organiser les topos hiérarchiquement.

On peut créer un layout de débogage pour masquer les informations distrayantes et souligner celles qui nous intéressent:

layout LayoutDistortion
## experimental Bruce Mutton 26Feb2017
## Hides most objects and emphasises maximal drawing errors (but not necessarily survey loop errors)
## Points jaunes et noirs indiquent la distortion maximale du scrap

## Appliquer un fond blanc pour réduire la confusion visuelle
  colour map-bg 100 #blanc
  colour map-fg 100 #blanc 
  symbol-colour group all 80 # 1 = black symbols, 80 = light grey
  colour preview-below 80 
  colour preview-above 80  
  opacity 10 #davantage transparent
  
  debug all #Tout débuguer
  #ou pour avoir un controle supplémentaire...
  # debug first   # lignes rouges
  # debug second  # lignes bleues
  # debug scrap-names #afficher le nom des scraps
  # debug station-names #afficher les stations topo
  
## Pour la taille du texte  
  ## Use scale base-scale pair to control text size ratios 2:1 to 10:1 OK
  scale 1 1000        
  base-scale 1 200 
  #set base-scale to smaller number to reduce text size (but increases relative yellow/black dot size)
  
## Cacher les caractéristiques que l'on ne veut pas afficher  
  symbol-hide group all  #hides ALL except passage infill colour, and preview-above, below
  symbol-show group cave-centreline
  symbol-show group surface-centreline
  symbol-show line map-connection
  symbol-hide group text
  
## Si toutes les lignes ci-dessous sont mises en commentaire, seules ces entités sont visibles;
## - centreline and yellow/black spots
## - scrap names
## - full centrelines and all station names for only those centrelines included in a map definition
 
  symbol-show line wall #this adds scrap outlines and red/blue morphing lines to output
  
  # symbol-show point cave-station #optional, sets up for showing cave only
  # symbol-show point surface-station  #optional, sets up for showing surface only
  
  # symbol-show point station #shows and labels all stations and red debug spots
  # symbol-show point station:fixed #shows and labels fixed stations only and red debug spots

endlayout LayoutDistortion

La commande therion peut être invoquée avec l’option de debug, “-d”. Si vous utilisez “xtherion” écrivez “-d” dans la zone de texte “command options” du panneau “Settings” de la fenêtre de compilation.

Quand therion est exécuté en mode de débogage, il enregistre les fichiers temporaires dans le répertoire $TMP/thTMPDIR [thwiki 10]. Dans les messages d’erreur MetaPost, sont affichés les numéros de lignes du fichier “data.mp”, qui le fichier généré par therion pour MetaPost. Visualiser ce fichier peut être utile afin de trouver la cause de l’erreur qui est pointée par MetaPost [thwiki 16-17].

Les fichiers “data.*” sont des fichiers postscript générés par MetaPost. Le nombre dans leur extension correspond aux nombres écrits par MetaPost dans ses résultats. Vous pouvez les visualiser avec un visualisateur postscrip (ou les convertir en pdf et afficher ce fichier avec un visualisateur pdf). Ajoutez une commande postscript “X Y translate” au début du fichier pour décaler l’image au milieu de la page, si vous ne pouvez rien voir. Par exemple “200 200 translate”.

Therion et les programmes externes qu’il utilise peut détecter plusieurs erreurs dans les fichiers de données, et générer des messages d’erreur très utiles. Ces messages sont utiles pour clarifier les problèmes à l’utilisateur afin de corriger le problème.

Cette annexe liste plusieurs messages d’erreurs, et explique ce qu’ils signifient, et comment les corriger. Les messages sont listes par ordre alphabetique. Malheureusement, les messages sont uniquement en anglais. Pour traduire les messages d’erreurs, il ne faudrait pas uniquement le faire pour therion (et xtherion), mais egalement pour cavern, mpost, pdfetex et tex.

Error: area borders X and Y don't intersect in scrap Z (Erreur : les bordures X et Y de la surface ne se recoupent pas dans le scrap Z) C’est un message de MetaPost, qui n’est pas intercepté par xtherion (car MetaPost renvoie tout de même un résultat “OK”). Vous devez ouvrir le fichier contenant le scrap en question et trouver les lignes qui génèrent l’erreur (utiliser le panneau “Search” de l’éditer de carte). Il est probable que les deux lignes soient consécutives dans la liste des contours de la surface, mais qu’elles ne se coupent pas (ou pas assez), comme indiqué par MetaPost. Vous devez corriger une des deux lignes (ou les deux).

Warning: scrap outline intersect itself in scrap Z (Attention : les lignes extérieures du scrap se recoupent dans le scrap Z) Il s’agit d’une erreur MetaPost. Elle est affichée par xtherion dans la fenêtre de sortie, mais il indique tout de même un résultat “OK”. Vous devez ouvrir le fichier contenant le scrap et trouver la ligne de bordure (outlline). Si votre scrap est repartis sur plusieurs fichiers, cela pourra être dur de trouver où elle est. xtherion ne peut pas vous aider, car il n’a aucune information sur le fichier ayant généré l’erreur. Vous pouvez utiliser un outil de recherche de texte (ex : grep) pour retrouver le fichier avec ce scrap.

Un cas où la ligne outline se recoupe dans un scrap arrive quand une ligne “wall” (parois de grotte) a une boucle à cause de manettes de courbure trop longues, comme dans la figure ci-dessous.

Parfois un “scrap outline intersect itself” peut être cause par un “join” de scraps. Quand therion doit joindre deux scrap, il déforme les lignes de jonctions des deux scrap pour assouplir leur contacte. Un léger mauvais placement d’un point topo dans un scrap peut provoquer une boucle au bout d’une ligne ce qui donnera cette erreur.

Si vous compilez le projet avec l’option debug (“-d” sur la ligne de commande de therion), le fichier postscript du scrap ayant l’erreur est “$(thTMPDIR)/data.XX”. Ou “XX” est le nombre entre crochet qui suit le message d’erreur dans les traces de MetaPost. Vous pouvez voir le scrap avec un visualisateur postscript ou en le convertissant en PDF (puis avec un visualisateur PDF) Vous aurez peut être besoin d’éditer le fichier postcript pour ajouter la ligne “200 200 translate” au début du fichier.

Dans ce cas, vous pouvez voir la ligne, calculée par Metapost, dans le scrap, et pointer la localisation de l’erreur.

Path X and Y don't intersect (les chemins X et Y ne se coupent pas) A FAIRE

The angle between two identical points is undefined (l’angle entre deux points identiques est indéfini) A FAIRE

can not connect 1@subsurvey.survey to centerline network (impossible de connecter le point 1@subsurvey.survey a la liste des visees topo (bloc centerline) Cela peut indiquer une erreur dans une commande “point” de type “station”: la station topo correspondante n’est pas présente dans les données centerline (fichiers .th). Une autre possibilité est que le bloc de données centerline (qui contient ce point) n’est pas connecté aux autres, cad, il manque une commande “equate” entre 2 points topo.

duplicate object name – scrap1 (nom d’objets dupliqué – scrap1) Cette erreur peut se produire lorsque les scraps sont repartis dans plusieurs fichiers, et que vous avez oublié de donner un nom à des scraps. xtherion nomme les scraps par défaut en suivant le modèle, “scrap1” 2, 3 et ainsi de suite. C’est pourquoi si vous ne renommez pas les scraps, deux d’entre eux peuvent avoir le même nom. Pour résoudre ce problème, il suffit de renommer les scraps.

incompatible scrap projection (projection du scrap incompatible). La projection choisie pour le scrap est incohérente avec la topo. Contrôlez l’option “-proj” dans le panneau de paramètres du “scrap” (projection plan de sélectionnée alors que vous avez dessine une coupe, …).

line (.th command)
invalid line type - subtype combination (Type de ligne ou sous type de ligne incompatible) Ce message indique que la commande “line” a un paramètre “-subtype” avec une option incorrecte vis-à-vis du type de la ligne. Le nom de la ligne est affiche lorsque vous cliquez sur le message. xtherion affiche automatiquement l’éditeur de carte et sélectionne la ligne en erreur.

names
invalid name format (format de nom incorrect) Ce message est suivit par le nom en erreur. L’erreur peut être qu’il y a plus d’un espace dans le nom, car un seul espace est autorise par nom (comme dans le nom/prénom d’une personne). Par exemple, “M. Dupont (SCC)”. Pour résoudre l’erreur, remplacez les espaces supplémentaires par des slash '/': “M. Dupont/(SCC)”.

station (type)
invalid station reference (nom de station invalid) Le nom d’une station topo est incorrect. Ce message est suivit par le nom de la station en question. xtherion bascule automatiquement dans l’éditeur de carte et pointe la station (elle est sélectionnée), ainsi vous pouvez corriger l’erreur.

MetaPost capacity exceeded, sorry [main memory size=3000001]. (Dépassement des capacités de MetaPost, desole) Vous devez découper votre scrap en scraps plus petits car la taille limite de mémoire pour le programme MetaPost est dépassée.

missing scrap before line command (début de scrap absent avant une ligne de commande) Des éléments graphiques ont été insérés en dehors d’un scrap. Ouvrez la carte “.th2” dans l’éditeur de carte et contrôlez la liste des éléments dans le panneau “Objects”.

missing survey before equate command (il manque un survey avant le commande equate) La commande “equate” doit être placée dans un bloc survey. Les topos (surveys) doivent être ordonnés hiérarchiquement, et le bloc survey avec la commande “equate” doit voir (cad, contenir) les stations topo auxquelles il se réfère. Ces points peuvent appartenir directement au survey, ou a des sous blocs survey (blocs topo) inclus dans le premier bloc.

Par exemple:

    survey X
      survey A
        1 ...
      endsurvey A
 
      survey B
        2 ...
      endsurvey B
 
      equate 1@A 2@B
    endsurvey X
  

Un autre exemple:

    survey X
      survey A
        1 ...
      endsurvey A
      
      2 ...
 
      equate 2 1@A
    endsurvey X
  

station (type)
no reference station found in scrap (pas de stations topo dans le scrap) Ce message est suivit du nom du scrap. Il indique que le scrap n’a pas de point “station” (point topo) qui le relie aux données topo. C’est pourquoi il ne peut être positionné sur le plan. Positionnez le scrap en insérant des points de type “station” ou ajoutez l’option “-name” aux points (station) que vous avez déjà placés (sans leur mettre de nom).

not enough layout option arguments (pas assez d’argument pour l’option layout) Ce message est suivit par le nom de l’option de layout a qui il manque des arguments. Corrigez le fichier de configuration en ajoutant les arguments manquant de l’option.

object does not exist (l’objet n’existe pas) Ce message est suivit du nom (id) de l’objet qui est référence mais non définie. Vous pouvez vous être trompé dans le nom, ou vous pouvez avoir oublié d’inclure (commande “input”) le fichier qui contient cette objet. L’erreur peut aussi provenir d’un objet surface qui fait référence a une série de lignes, mais lors d’une mise a jour, vous avez coupée en 2 une ligne, changeant ainsi son nom. La surface ne retrouve plus alors sa ligne de bordure.

projection mishmash (erreur de projection) La projection d’un élément sur la topo ne correspond pas : tous les éléments ajoutes sur la topo doivent avoir la même projection (plan, coupe)

strange path in … (chemin incorrecte) Ce message indique la présence d’une ligne avec uniquement deux points coïncidents. Regarder particulièrement les lignes n'ayant que 2 points (généralement des lignes droites) mais ayant l'option “close” (bouclage) activée. Votre ligne fait alors une boucle sur les 2 points et vous ne le voyez pas. Il faut alors désactiver l'option et supprimer le 3ème point de la ligne (celui qui fait le bouclage sur le premier).

survey does not exist (la topo n’existe pas) Le nom (id) que vous utilisez n’est pas celui de cette topo.

unknown option – input test-layout.th (option inconnue – input test-layout.th) Dans le fichier de configuration la commande input a été utilisée dans un bloc layout. Déplacez le la ligne hors du bloc layout.