Format des fichiers Gwyddion

Un fichier de données au format Gwyddion (GWY) consiste en une structure en arborescence de plusieurs objets sérialisés. En général ces objets peuvent être de différents types ou même contenir d'autres objets (ce qui explique l'arborescence). L'utilisation de gwydump, peut être très instructive pour examiner le contenu de divers fichiers, il s'agit d'un simple visualisateur de structure de fichier disponible sur le site internet du projet. Si vous comptez lire et/ou écrire des fichiers GWY dans un autre logiciel, jetez un œil à libgwyfile, une petite librairie sans dépendance et intégrable dédiée à la manipulation de fichiers GWY.

Les deux couches

Cette description du format de fichier spécifie en réalité deux aspects différents qu'il est utile de distinguer :

  • La structure physique des fichiers : ordre des octets, types de données et leur représentation, manière dont les tailles de certaines données sont déterminées, agencement des objets sous forme d'arbre, etc. Il s'agit du format de fichier générique GWY dans libgwyfile. Il peut être en principe utilisé pour des données n'ayant rien à voir avec des mesures SPM et utilisé dans un tout autre logiciel – mais il s'agira toujours du format de fichier GWY.
  • La représentation de données SPM particulières par Gwyddion, définissant des conventions supplémentaires sur la structure physique et l'interprétation des données. Par exemple, nous y décriront que les images sont enregistrées sous forme d'objet appelé GwyDataField ayant des résolutions enregistrées de telle manière, ques les données des images sont enregistrées de telle manière, etc. Il s'agit alors du format de fichier Gwyddion GWY dans libgwyfile.

La distinction entre le format générique et les objets spécifiques à Gwyddion est normalement plutôt évidente (elle est de temps en temps notée explicitement). Nous commencerons par la structure des fichiers.

Ordre des octets

Toutes les données sont enregistrées avec l'ordre des octets little-endian (« petit-boutiste » ou « miniboutiste », aussi connu sous le nom LSB ou Intel).

En-tête de Fichier

L'en-tête de fichier est constitué de quatre octets (nombre magique) avec avec les valeurs ASCII correspondant aux caractères GWYP.

Il s'agit du nouveau format de fichier, une version plus ancienne contenant l'en-tête maqigue GWYO existe aussi. Ce point ne sera pas discuté ici, car ce format est tout simplement éteint.

Données

Le reste du fichier Gwyddion consiste en un objet GwyContainer contenant toutes les données. Cet objet de premier niveau est enregistré exactement de la même manière que tout autre objet, tel que décrit dans la section qui suit.

Un fichier GWY générique peut avoir un autre objet en tant qu'objet de premier niveau.

Structure d'un Objet

Un objet est constitué de trois parties (dans l'ordre suivant) :

  • Nom du type d'objet, enregistré sous la forme d'une chaîne de caractères ASCII se terminant par NUL. Dans un fichier Gwyddion il s'agit du nom dans le système de types GObject. De manière générale, le nom doit être un identifiant C valide.
  • Tailles des données sérialisées, enregistrée sous la forme d'un entier non signé de 32 bits. Il n'inclue pas la taille du nom du type ni sa propre taille.
  • La liste des composants. Ceux-ci sont des parties nommées des données de l'objet, un pour chaque type de données : un type atomique, un tableau de types atomiques, ou encore un objet. Ils ne sont enregistrés dans aucun ordre particulier.

Composants

Chaque composant est constitué de trois parties (dans l'ordre suivant) :

  • Le nom, enregistré sous la forme d'une chaîne de caractères codés en UTF-8 se terminant par NUL.
  • Le type, enregistré sous la forme d'un unique octet non signé (caractère). La table des types de composants est présentée plus bas.
  • Les données, enregistrées sous la forme adéquate en fonction du type.

Les composants sont souvent appelés éléments dans libgwyfile ainsi que les librairies Gwyddion.

Sauter un composant inconnu (ou inintéressant) lors de la lecture d'un fichier GWY est possible en lisant au préalable le nom et le type de celui-ci. Si le type est atomique, vous saurez alors le nombre d'octets à sauter en vous basant sur la table des types. Si le type est un tableau de types atomiques, il vous faudra lire la taille du tableau, et la multiplier par la taille du type atomique. Si le type est un objet, il vous faudra lire le nom et la taille, cette dernière vous donnant directement le nombre d'octets à sauter par la suite. En dernier lieu, le cas le plus complexe correspond à un tableau d'objets pour lequel il vous faudra lire sa taille et répéter le saut d'objet le nombre de fois correspondant.

Types de Données

Les types atomiques de données sont listés dans le tableau suivant :

TypeCaractèreNote
booléenb Stocké sous forme d'octet, zéro correspond à faux, et non nul ( normalement 1) correspond à vrai
caractèrec 
entier 32 bitsi 
entier 64 bitsq 
doubled Nombre fini à virgule flottante en double précision IEEE 754, c'est-à-dire que les fichiers ne doivent pas contenir des infinis et des non-nombres
chaîne de caractèress Se terminant par NUL encodé au format UTF-8
objeto Objet tel que décrit plus haut

Chaque type atomique, sauf le booléen, possède son tableau équivalent. Les types de caractère des tableaux sont les mêmes que leur équivalent atomique, à part le fait qu'ils sont en majuscule. Un tableau est enregistré sous la forme d'une valeur non signée en 32 bits donnant le nombre d'éléments, suivie des valeurs des éléments. Le nombre d'élément doit être positif ; les tableaux vides ne sont pas enregistrés. Les types de données de tableaux sont listés dans la table suivante :

TypeCaractèreNote
tableau de caractèresC Ne se terminant pas par NUL
tableau d'entiers 32 bitsI 
tableau d'entiers 64 bitsQ 
tableau de doublesD 
tableau de chaînes de caractèresS 
tableau d'objetsOO majuscule, et non zéro

Conteneur GwyContainer de premier niveau

GwyContainer est un objet général apparenté à un dictionnaire pouvant recevoir des composants arbitraires de types arbitraires. Ceci permet d'incorporer des structures de données imprévues de manière relativement saine dans des fichiers GWY.

Les noms (clés) des objets dans un GwyContainer représentant un fichier Gwyddion GWY ressemblent fortement aux noms de fichiers UNIX, c'est-à-dire qu'ils sont sous la forme de de chemins séparés par le caractère /, et présentent une structure arborescente. Par exemple, le titre du premier canal, numéroté 0, est enregistré dans la clé /0/data/title. Notez que certaines données ou informations se trouvent dans des clés qui peuvent parfois semblert illogiques, la raison est en général de nature historique.

Les sections qui suivent décrivent l'organisation des données et informations intéressantes présentes dans le GwyContainer de premier niveau. La liste n'est pas nécessairement exhaustive. Toutefois, comme tous les éléments d'un fichier spécifient toujours leur nom, type et taille en octets, il est toujours possible de sauter des types de données inconnus ou des données n'ayant pas d'intérêt pour vous, et n'extraire que les éléments souhaités.

Canaux

Le tableau qui suit résume les clés des données relatives au canal 0 dans le conteneur de premier niveau. Pour les autres canaux, il suffit de remplacer le nombre 0 par le numéro du canal correspondant. Notez que les canaux sont généralement numérotés de manière séquentielle, en partant de 0, toutefois les canaux peuvent avoir n'importe quel numéro, et l'ensemble des numéros des canaux ne sont pas nécessairement contigus.

CléTypeSignification
/0/dataGwyDataField Données du canal.
/0/data/titlechaîne de caractères Titre du canal, tel qu'affiché dans le navigateur de données.
/0/data/visiblebooléen Détermine si le canal doit être affiché lors du chargement du fichier.
/0/data/realsquarebooléen Détermine si le canal doit être affiché avec les pixels réels (par opposition aux pixels carrés).
/0/base/palettechaîne de caractères Nom du gradient de fausses couleurs utilisé pour afficher le canal.
/0/base/range-typeentier 32 bits Type de visualisation (tel que défini par l'outil Visualisation des couleurs), la valeur provient de la liste GwyLayerBasicRangeType.
/0/base/mindouble Valeur minimum utilisée pour la plage d'affichage définie par l'utilisateur.
/0/base/maxdouble Valeur maximum utilisée pour la plage d'affichage définie par l'utilisateur.
/0/maskGwyDataField Données du masque. Les dimensions en pixels de ces données doivent correspondre à celles des données du canal.
/0/mask/reddouble Composante rouge de la couleur du masque.
/0/mask/greendouble Composante verte de la couleur du masque.
/0/mask/bluedouble Composante bleue de la couleur du masque.
/0/mask/alphadouble Composante alpha (opacité) de la couleur du masque.
/0/showGwyDataField Données de présentation. Les dimensions en pixels de ces données doivent correspondre à celles des données du canal.
/0/metaGwyContainer Métadonnées du canal. Les clés correspondent directement aux noms affichées dans le navigateur de métadonnées, et les chaînes de caractères en sont les valeurs.
/0/data/logGwyStringList Journal de modification du canal sous forme d'une liste de chaînes de caractères. Elles sont le format type::fonction(param=valeur, …)@date.
/0/select/fooune sous-classe de GwySelection Données de sélection. Chaque type de sélection a (généralement) un type d'objet différent et est enregistré sous un nom différent ; le nom spécifique foo est identique à celui affiché dans le gestionnaire de sélection.

Les canaux sont représentés sous forme d'objets GwyDataField. Les composants de GwyDataField sont résumés dans le tableau suivant :

ComposantTypeSignification
xresentier 32 bits Taille horizontale en pixels.
yresentier 32 bits Taille verticale en pixels.
xrealdouble Dimension horizontale en unités physiques.
yrealdouble Dimension verticale en unités physiques.
xoffdouble Décalage horizontal du coin supérieur gauche en unités physiques. Il n'apparaît normalement que s'il est non nul.
yoffdouble Décalage vertical du coin supérieur gauche en unités physiques. Il n'apparaît normalement que s'il est non nul.
si_unit_xyGwySIUnit Unités des dimensions latérales.
si_unit_zGwySIUnit Unités des valeurs de hauteur.
datatableau de doubles Données, enregistrées sous forme d'un tableau de taille xres×yres, allant du haut vers le bas et de gauche à droite.

Graphes

Les tableaux qui suivent donnent les clés les plus courantes relatives aux données des graphes dans le conteneur de premier niveau du graphe numéro 1. Pour les autres graphes le numéro 1 doit être remplacé par le numéro de graphe correspondant. Notez que les graphes sont généralement numérotés de manière séquentielle, en partant de 1, toutefois ils peuvent avoir n'importe quel numéro positifs, et l'ensemble des numéros des graphes n'est pas nécessairement contigu. Le numéro 0 utilisé en prefixe des clés des graphes est de nature historique, il n'a pas de signification particulière et vaut toujours 0.

CléTypeSignification
/0/graph/graph/1GwyGraphModel Objet de données de graphe.
/0/graph/graph/1/visiblebooléen Détermine si le graphe doit être affiché lors du chargement du fichier.

Les graphes sont représentés par des objets GwyGraphModel. Les composants de GwyGraphModel sont résumés dans la table qui suit :

ComposantTypeSignification
curvestableau de GwyGraphCurveModels Courbes de graphes individuelles.
titlechaîne de caractères Titre du graphe tel qu'affiché dans le navigateur de données.
x_unitGwySIUnit Unités des abscisses.
y_unitGwySIUnit Unités des ordonnées.
top_labelchaîne de caractères Label de l'axe du haut.
bottom_labelchaîne de caractères Label de l'axe du bas.
left_labelchaîne de caractères Label de l'axe de gauche.
right_labelchaîne de caractères Label de l'axe de droite.
x_is_logarithmicbooléen Spécifie si l'échelle des abscisses est logarithmique.
y_is_logarithmicbooléen Spécifie si l'échelle des ordonnées est logarithmique.
x_mindouble Valeur minimum des abscisses définie par l'utilisateur.
x_min_setbooléen Spécifie si la valeur minimum des abscisses définie par l'utilisateur doit être utilisée (dans le ca contraire la plage est déterminée automatiquement).
x_maxdouble Valeur maximum des abscisses définie par l'utilisateur.
x_max_setbooléen Spécifie si la valeur maximum des abscisses définie par l'utilisateur doit être utilisée (dans le ca contraire la plage est déterminée automatiquement).
y_mindouble Valeur minimum des ordonnées définie par l'utilisateur.
y_min_setbooléen Spécifie si la valeur mimimum des ordonnées définie par l'utilisateur doit être utilisée (dans le ca contraire la plage est déterminée automatiquement).
y_maxdouble Valeur maximum des ordonnées définie par l'utilisateur.
y_max_setbooléen Spécifie si la valeur maximum des ordonnées définie par l'utilisateur doit être utilisée (dans le ca contraire la plage est déterminée automatiquement).
grid-typeentier 32 bits Type de la grille affichée. La valeur provient de la liste GwyGraphGridType.
label.has_framebooléen Spécifie si le graphe a une grille.
label.frame_thicknessentier 32 bits Epaisseur de la grille du graphe.
label.reversebooléen Spécifie s'il faut inverser la grille du graphe.
label.visiblebooléen Spécifie si le label du graphe est visible.
label.positionentier 32 bits Position (coin) dans lequel est placé le label du graphe. La valeur provient de la liste GwyGraphLabelPosition.

Les courbes de graphes sont représentées par des objets GwyGraphCurveModel. Les composants de GwyGraphCurveModel sont résumés dans la table qui suit :

ComposantTypeSignification
xdatatableau de doubles Points d'abscisse. Le nombre doit correspondre à ydata.
ydatatableau de doubles Points d'ordonnée. Le nombre doit correspondre à xdata.
descriptionchaîne de caractères Description de la courbe (nom).
typeentier 32 bits Mode de la courbe (points, ligne, etc.) La valeur provient de la listeThe value is from GwyGraphCurveType.
color.reddouble Composante rouge de la couleur de la courbe.
color.greendouble Composante verte de la couleur de la courbe.
color.bluedouble Composante bleue de la couleur de la courbe.
point_typeentier 32 bits Type de symbole représentant les points de données. La valeur provient de la liste GwyGraphPointType.
point_sizeentier 32 bits Taille des symboles représentant les points.
line_typeentier 32 bits Type de lignes connectant les points. La valeur provient de la liste GwyGraphLineType.
line_sizeentier 32 bits Epaisseur des lignes reliant les points.

Spectre

Le tableau qui suit résume les clés les plus courantes relatives aux données des spectres dans le conteneur de premier niveau de l'ensemble des spectres 0. Pour les autres ensemble de spectres il faut remplacer le nombre 0 par le numéro de l'ensemble de spectres correspondant. Notez que les ensemles despectres sont généralement numérotés de manière séqentielle, en partant de 0, toutefois ceux-ci peuvent avoir n'importe quel numéro, et l'ensemble des numéros des spectres ne sont pas nécessairement contigus.

CléTypeSignification
/sps/0GwySpectra Données de spectre.

Les spectres d'un type donné sont représentés par des objets GwySpectra. Les composants de GwySpectra sont résumés dans le tableau qui suit :

ComposantTypeSignification
titlechaîne de caractères Titre du spectre tel qu'affiché dans le navigateur de donnée.
si_unit_xyGwySIUnit Unités des coordonnées de position du spectre.
coordstableau de doubles Coordonnées des points où les spectres ont été mesurés, en unités physiques. Chaque spectre comporte deux éléments : les coordonnées horizontale et verticale. Le nombre de coordonnées doit correspondre au nombre de courbes dans data.
datatableau de GwyDataLines Courbes de spectres individuels.
selectedtaleau d'entiers 32 bits Indices des courbes de spectres sélectionnées.

Les courbes individuelles des spectres sont représentées par des objets GwyDataLine. L'objet GwyDataLine est la contrepartie uni-dimensionnelle de l'objet GwyDataField et est aussi utilisé pour d'autres données uni-dimensionnelles. Les composants de GwyDataLine sont résumées dans le tableau suivant :

ComposantTypeSignification
resentier 32 bits Nombre de points de données.
realdouble Longueur en unités physiques.
offdouble Décalage du début en unités physiques. Il n'apparaît normalement que s'il est non nul.
si_unit_xGwySIUnit Unités des abscisses.
si_unit_yGwySIUnit Unités des valeurs des données.
datatableau de doubles Données de ligne, enregistrées sous forme d'un tableau de res, allant de gauche à droite.

Données volumiques

La table qui suit présente les clefs relatives aux données volumiques présentes dans le conteneur de premier niveau des données volumiques numérotées 0. Pour d'autres données volumiques, le 0 doit être remplacé par leur numéro correspondant. Notez que les données volumiques sont généralement numérotées de manière séquentielle, en partant de 0, toutefois elles peuvent avoir n'importe quel nombre, et l'ensemble des numéros des données volumiques n'est pas nécessairement contigu.

CléTypeSignification
/brick/0GwyBrick Données volumiques.
/brick/0/previewGwyDataField Données bi-dimensionnelles affichées lorsque les données volumiques sont prévisualisées.
/brick/0/titlechaîne de caractères Titre des données volumiques, affiché dans le navigateur de données.
/brick/0/visiblebooléen Spécifie si les données volumiques doivent être affichées dans une fenêtre lors de l'ouverture du fichier.
/brick/0/preview/palettechaîne de caractères Nom du gradient de couleurs utilisé pour afficher les données de prévisualisation.
/brick/0/metaGwyContainer Métadonnées des données volumiques. Les clés sont directement les noms affichés dans le navigateur de métadonnées et les chaînes de caractères en sont les valeurs.
/brick/0/logGwyStringList Journal de modification du volume sous forme d'une liste de chaîne de caractères. Elles ont le format type::fonction(param=valeur, …)@date.

Les données volumiques sont représentées par des objets GwyBrick. Les composants d'un GwyBrick sony résumées dans dans la table qui suit :

ComposantTypeSignification
xresentier 32 bits Taille horizontale en pixels.
yresentier 32 bits Taille verticale en pixels.
zresentier 32 bits Profondeur (nombre de niveaux) en pixels.
xrealdouble Dimension horizontale en unités physiques.
yrealdouble Dimension verticale en unités physiques.
zrealdouble Profondeur en unités physiques.
xoffdouble Décalage horizontal du coin en haut à gauche, en unités physiques. Il n'apparaît que s'il est non nul.
yoffdouble Décalage vertical du coin en haut à gauche, en unités physiques. Il n'apparaît que s'il est non nul.
zoffdouble Décalage de profondeur du coin en haut à gauche, en unités physiques. Il n'apparaît que s'il est non nul.
si_unit_xGwySIUnit Unités des dimensions latérales horizontales.
si_unit_yGwySIUnit Unités des dimensions latérales verticales.
si_unit_zGwySIUnit Unités des dimensions de profondeur.
si_unit_wGwySIUnit Unités des valeurs.
datatableau de doubles Champ de données, enregistrées selon un tableau de dimensions xres×yres×zres, du plan zéro au dernier plan, de haut en bas et de gauche à droite.
calibrationGwyDataLine Calibration de l'axe z permettant de réprésenter un échantillonnage non linéaire de cette dimension. Le nombre de points doit être égal à zres. Ce composant n'est présent que si un échantillonnage non linéaire est utilisé.

Données XYZ

Le tableau qui suit résume les clés communes aux données de type XYZ dans le conteneur de premier niveau pour les données XYZ de numéro 0. Pour les autres données XYZ, le numéro 0 doit être remplacé par le numéro des données XYZ correspondant. Notez que les données XYZ sont généralement numérotées de manière séquentielle, en partant de 0. Toutefois, elles peuvent avoi n'importe quel numéro et l'ensemble des numéros des données XYZ n'a pas à être contigu.

CléTypeSignification
/xyz/0GwySurface Données XYZ.
/xyz/0/previewGwyDataField Aperçu régularisé donné lorsque les données XYZ sont affichées dans une fenêtre. Notez que, bien que les aperçus des données XYZ soient enregistrés dans les fichiers GWY, ceux-ci sont normalement re-créés et mis à jour lorsque les données sont affichées, il est donc inutile de les ajouter lorsque vous écrivez un fichier GWY.
/xyz/0/titlechaîne de caractères Titre des données XYZ, tel qu'affiché dans le navigateur de données.
/xyz/0/visiblebooléen Détermine si les données XYZ doivent être affichées dans une fenêtre une fois le fichier chargé.
/xyz/0/preview/palettechaîne de caractères Nom du gradient de couleur utilisé pour afficher l'aperçu des données.
/xyz/0/metaGwyContainer Métadonnées des données XYZ. Les clés sont directement les noms affichés dans le navigateur de métadonnées et les chaînes de caractères en sont les valeurs.
/xyz/0/logGwyStringList Journal des données XYZ, sous forme d'une liste d'entrées. Celles-ci sont au format type::fonction(paramètre=valeur, …)@heure.

Les données XYZ sont représentées sous forme d'objets GwySurface. Les composants d'une GwySurface sont résumés dans le tableau suivant :

ComposantTypeSignification
si_unit_xyGwySIUnit Unités des dimensions latérales.
si_unit_zGwySIUnit Unités de valeur des données.
datatableau de doubles Données XYZ, enregistrées sous forme d'un tableau dont la dimension est un multiple de 3. Chaque triplet XYZ est enregistré d'un seul tenant, ce qui donne l'ordre suivant : x₀, y₀, z₀, x₁, y₁, z₁, x₂, y₂, z₂, etc.

Autres éléments

Le GwyContainer principal contient aussi d'autres éléments qui ne se rapportent à aucun canal, graphe ou d'autre type de données.

ClefTypeSignification
/filenamechaîne de caractères Le nom du fichier avec lequel le GwyContainer est associé. S'il est sauvé dans un fichier, alors cet élément contiendra le nom du fichier. S'il n'est pas enregistré, cet élément contiendra le nom du fichier à partir duquel les données ont été chargées ou importées. Il peut aussi être non défini, dans le cas de données nouvellement synthétisées par exemple.

Objets auxiliaires

Les composants d'un GwySIUnit sont résumés dans le tableau qui suit :

ComposantTypeSignification
unitstrchaîne de caractères Représentation textuelle des unités, par exemple "A" ou "m^-1" (pour les unités SI, les préfixes sont ignorés).

Les composants d'un GwySelection sont résumés dans le tableau suivant. Certains types de sélection peuvent avoir d'autres éléments de données ; référez-vous à la documentation des classes de sélection spécifiques pour savoir comment interpréter les données.

ComposantTypeSignification
maxentier 32 bits Nombre maximum d'objets qu'une sélection peut détenir (il s'agit du nombre défini par gwy_selection_set_max_objects()).
datatableau de doubles Données de sélection. Le nombre d'éléments formant un objet sélection est déterminé par le type de sélection.

Les composants d'un GwyStringList sont résumés dans la table suivante. Notez que les GwyStringLists sont utilisés pour représenter les entrées du journal de modification, les chaînes ont la structure spécifique décrite plus haut.

ComposantTypeSignification
stringstableau chaînes de caractères Liste des chaînes de caractères.