Les fichiers de données au format Gwyddion consistent 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.
Nous allons tout d'abord décrire la structure physique du fichier sans considérer l'interprétation possible des données contenues dans celui-ci.
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).
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.
Le reste du fichier consiste en un objet GwyContainer contenant toutes les données. Il est enregistré exactement de la même manière que tout autre objet, telle que décrit dans la section qui suit.
Un objet est constitué de trois parties (dans l'ordre suivant) :
NUL. Il s'agit
du nom dans le système de types GObject.
Chaque composant est constitué de trois parties (dans l'ordre suivant) :
NUL.
Les types atomiques de données sont listés dans le tableau suivant :
| Type | Caractère | Note |
|---|---|---|
| booléen | b | Stocké sous forme d'octet, zéro correspond à faux, et non nul ( normalement 1) correspond à vrai |
| caractère | c | |
| entier 32 bits | i | |
| entier 64 bits | q | |
| double | d | Nombre fini à virgule flottante en double précision IEEE 754, i.e. les fichiers ne doivent pas contenir des infinités et des non-nombres |
| chaîne de caractères | s |
Se terminant par NUL
|
| objet | o | 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. Les tableaux sont enregistrés sous la forme d'une valeur non signée en 32 bits (donnant le nombre d'éléments), suivie des valeurs des éléments. Les types de tableaux de données sont listés dans la table suivante :
| Type | Caractère | Note |
|---|---|---|
| tableau de caractères | C |
Ne se terminant pas par NUL
|
| tableau d'entiers 32 bits | I | |
| tableau d'entiers 64 bits | Q | |
| tableau de doubles | D | |
| tableau de chaînes de caractères | S | |
| tableau d'objects | O | O majuscule, et non zéro |
Les noms (clés) des objets dans un GwyContainer représentant
un fichier Gwyddion ressemblent fortement aux noms de fichiers UNIX, i.e.
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 parfois 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. 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.
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é | Type | Signification |
|---|---|---|
/0/data | GwyDataField | Données du canal. |
/0/data/title | chaîne de caractères | Titre du canal, tel qu'affiché dans le navigateur de données. |
/0/data/visible | booléen | Détermine si le canal doit être affiché lors du chargement du fichier. |
/0/base/palette | chaîne de caractères | Nom du gradient de fausses couleurs utilisé pour afficher le canal. |
/0/base/range-type | entier 32 bits | Type de visualisation (tel que défini par l'outil Visualisation des couleurs), la valeur provient de la liste GwyLayerBasicRangeType. |
/0/base/min | double | Valeur minimum utilisée pour la plage d'affichage définie par l'utilisateur. |
/0/base/max | double | Valeur maximum utilisée pour la plage d'affichage définie par l'utilisateur. |
/0/mask | GwyDataField | Données du masque. Les dimensions en pixels de ces données doivent correspondre à celles des données du canal. |
/0/mask/red | double | Composante rouge de la couleur du masque. |
/0/mask/green | double | Composante verte de la couleur du masque. |
/0/mask/blue | double | Composante bleue de la couleur du masque. |
/0/mask/alpha | double | Composante alpha (opacité) de la couleur du masque. |
/0/show | GwyDataField | Données de présentation. Les dimensions en pixels de ces données doivent correspondre à celles des données du canal. |
/0/meta | GwyContainer | 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/select/ | une 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 :
| Composant | Type | Signification |
|---|---|---|
xres | entier 32 bits | Taille horizontale en pixels. |
yres | entier 32 bits | Taille verticale en pixels. |
xreal | double | Dimension horizontale en unités physiques. |
yreal | double | Dimension verticale en unités physiques. |
xoff | double | Décalage horizontal du coin supérieur gauche en unités physiques. Il n'apparaît normalement que s'il est non nul. |
yoff | double | 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_xy | GwySIUnit | Unités des dimensions latérales. |
si_unit_z | GwySIUnit | Unités des valeurs de hauteur. |
data | tableau 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.
|
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é | Type | Signification |
|---|---|---|
/0/graph/graph/1 | GwyGraphModel | Objet de données de graphe. |
/0/graph/graph/1/visible | boolé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 :
| Composant | Type | Signification |
|---|---|---|
curves | tableau de GwyGraphCurveModels | Courbes de graphes individuelles. |
title | chaîne de caractères | Titre du graphe tel qu'affiché dans le navigateur de données. |
x_unit | GwySIUnit | Unités des abscisses. |
y_unit | GwySIUnit | Unités des ordonnées. |
top_label | chaîne de caractères | Label de l'axe du haut. |
bottom_label | chaîne de caractères | Label de l'axe du bas. |
left_label | chaîne de caractères | Label de l'axe de gauche. |
right_label | chaîne de caractères | Label de l'axe de droite. |
x_is_logarithmic | booléen | Spécifie si l'échelle des abscisses est logarithmique. |
y_is_logarithmic | booléen | Spécifie si l'échelle des ordonnées est logarithmique. |
x_min | double | Valeur minimum des abscisses définie par l'utilisateur. |
x_min_set | boolé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_max | double | Valeur maximum des abscisses définie par l'utilisateur. |
x_max_set | boolé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_min | double | Valeur minimum des ordonnées définie par l'utilisateur. |
y_min_set | boolé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_max | double | Valeur maximum des ordonnées définie par l'utilisateur. |
y_max_set | boolé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-type | entier 32 bits | Type de la grille affichée. La valeur provient de la liste GwyGraphGridType. |
label.has_frame | booléen | Spécifie si le graphe a une grille. |
label.frame_thickness | entier 32 bits | Epaisseur de la grille du graphe. |
label.reverse | booléen | Spécifie s'il faut inverser la grille du graphe. |
label.visible | booléen | Spécifie si le label du graphe est visible. |
label.position | entier 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 :
| Composant | Type | Signification |
|---|---|---|
xdata | array of doubles |
Points d'abscisse. Le nombre doit correspondre à
ydata.
|
ydata | array of doubles |
Points d'ordonnée. Le nombre doit correspondre à xdata.
|
description | chaîne de caractères | Description de la courbe (nom). |
type | entier 32 bits | Mode de la courbe (points, ligne, etc.) La valeur provient de la listeThe value is from GwyGraphCurveType. |
color.red | double | Composante rouge de la couleur de la courbe. |
color.green | double | Composante verte de la couleur de la courbe. |
color.blue | double | Composante bleue de la couleur de la courbe. |
point_type | entier 32 bits | Type de symbole représentant les points de données. La valeur provient de la liste GwyGraphPointType. |
point_size | entier 32 bits | Taille des symboles représentant les points. |
line_type | entier 32 bits | Type de lignes connectant les points. La valeur provient de la liste GwyGraphLineType. |
line_size | entier 32 bits | Epaisseur des lignes reliant les points. |
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é | Type | Signification |
|---|---|---|
/sps/0 | GwySpectra | 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 :
| Composant | Type | Signification |
|---|---|---|
title | chaîne de caractères | Titre du spectre tel qu'affiché dans le navigateur de donnée. |
si_unit_xy | GwySIUnit | Unités des coordonnées de position du spectre. |
coords | tableau 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.
|
data | tableau de GwyDataLines | Courbes de spectres individuels. |
selected | taleau 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. Les composants de GwyDataLine sont résumées dans le tableau suivant :
| Composant | Type | Signification |
|---|---|---|
res | entier 32 bits | Nombre de points de données. |
real | double | Longueur en unités physiques. |
off | double | Décalage du début en unités physiques. Il n'apparaît normalement que s'il est non nul. |
si_unit_x | GwySIUnit | Unités des abscisses. |
si_unit_y | GwySIUnit | Unités des valeurs des données. |
data | tableau de doubles |
Données de ligne, enregistrées sous forme d'un tableau de
res, allant de gauche à droite.
|
Les composants d'un GwySIUnit sont résumés dans le tableau qui suit :
| Composant | Type | Signification |
|---|---|---|
unitstr | chaî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.
| Composant | Type | Signification |
|---|---|---|
max | entier 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()).
|
data | tableau 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. |