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.
Cette description du format de fichier spécifie en réalité deux aspects différents qu'il est utile de distinguer :
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.
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, car ce format est tout simplement éteint.
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.
Un objet est constitué de trois parties (dans l'ordre suivant) :
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.
Chaque composant est constitué de trois parties (dans l'ordre suivant) :
NUL.
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. Il y a ensuite plusieurs possibilités :
NUL final.
NUL suivant) en fonction de la taille du tableau.
Les types atomiques de données sont listés dans le tableau suivant :
| Type | Caractère | Taille | Note |
|---|---|---|---|
| booléen | b | 1 octet | Zéro si faux, et non nul (normalement 1) si vrai. |
| caractère | c | 1 octet | |
| entier 32 bits | i | 4 octets | |
| entier 64 bits | q | 8 octets | |
| double | d | 8 octets | 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ères | s | variable |
Se terminant par NUL encodé au format UTF-8.
|
| objet | o | variable | Objet imbriqué et sérialisé 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 :
| Type | Caractère | Note |
|---|---|---|
| tableau de caractères | C |
En général non terminé par NUL ni codé en
UTF-8 (s est utilisé pour les chaînes de texte).
|
| 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'objets | O | O majuscule, et non zéro. |
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 de la première image, numérotée 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.
Le tableau qui suit résume les clés des données relatives à l'image 0 dans le conteneur de premier niveau. Pour les autres images, il suffit de remplacer le nombre 0 par le numéro de l'image correspondante. Notez que les imagese sont généralement numérotés de manière séquentielle, en partant de 0, toutefois les images peuvent avoir n'importe quel numéro, et l'ensemble des numéros des images ne sont pas nécessairement contigus.
| Clé | Type | Signification |
|---|---|---|
/0/data | GwyDataField | Données de l'image. |
/0/data/title | chaîne de caractères | Titre de l'image, tel qu'affiché dans le navigateur de données. |
/0/data/visible | booléen | Détermine si l'image doit être affichée lors du chargement du fichier. |
/0/data/realsquare | booléen | Détermine si l'image doit être affichée avec les pixels réels (par opposition aux pixels carrés). |
/0/base/palette | chaîne de caractères | Nom du gradient de fausses couleurs utilisé pour afficher l'image. |
/0/base/range-type | entier 32 bits | Type de visualisation (tel que défini par l'outil Affichage 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 de l'image. |
/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 de l'image. |
/0/meta | GwyContainer | Métadonnées de l'image. 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/log | GwyStringList |
Journal de modification de l'image sous forme d'une liste de
chaînes de caractères. Elles sont le format
|
/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 images sont représentées 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 | tableau de doubles |
Points d'abscisse. Le nombre doit correspondre à
ydata.
|
ydata | tableau de 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. 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 :
| 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.
|
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é | Type | Signification |
|---|---|---|
/brick/0 | GwyBrick | Données volumiques. |
/brick/0/preview | GwyDataField | Données bi-dimensionnelles affichées lorsque les données volumiques sont prévisualisées. |
/brick/0/title | chaîne de caractères | Titre des données volumiques, affiché dans le navigateur de données. |
/brick/0/visible | boolé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/palette | chaîne de caractères | Nom du gradient de couleurs utilisé pour afficher les données de prévisualisation. |
/brick/0/meta | GwyContainer | 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/log | GwyStringList |
Journal de modification du volume sous forme d'une liste de
chaîne de caractères. Elles ont le format
|
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 :
| Composant | Type | Signification |
|---|---|---|
xres | entier 32 bits | Taille horizontale en pixels. |
yres | entier 32 bits | Taille verticale en pixels. |
zres | entier 32 bits | Profondeur (nombre de niveaux) en pixels. |
xreal | double | Dimension horizontale en unités physiques. |
yreal | double | Dimension verticale en unités physiques. |
zreal | double | Profondeur en unités physiques. |
xoff | double | Décalage horizontal du coin en haut à gauche, en unités physiques. Il n'apparaît que s'il est non nul. |
yoff | double | Décalage vertical du coin en haut à gauche, en unités physiques. Il n'apparaît que s'il est non nul. |
zoff | double | 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_x | GwySIUnit | Unités des dimensions latérales horizontales. |
si_unit_y | GwySIUnit | Unités des dimensions latérales verticales. |
si_unit_z | GwySIUnit | Unités des dimensions de profondeur. |
si_unit_w | GwySIUnit | Unités des valeurs. |
data | tableau 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.
|
calibration | GwyDataLine |
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é.
|
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é | Type | Signification |
|---|---|---|
/xyz/0 | GwySurface | Données XYZ. |
/xyz/0/preview | GwyDataField | 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/title | chaîne de caractères | Titre des données XYZ, tel qu'affiché dans le navigateur de données. |
/xyz/0/visible | booléen | Détermine si les données XYZ doivent être affichées dans une fenêtre une fois le fichier chargé. |
/xyz/0/preview/palette | chaîne de caractères | Nom du gradient de couleur utilisé pour afficher l'aperçu des données. |
/xyz/0/meta | GwyContainer | 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/log | GwyStringList |
Journal des données XYZ, sous forme d'une liste d'entrées.
Celles-ci sont au format
|
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 :
| Composant | Type | Signification |
|---|---|---|
si_unit_xy | GwySIUnit | Unités des dimensions latérales. |
si_unit_z | GwySIUnit | Unités de valeur des données. |
data | tableau 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.
|
Le GwyContainer principal contient aussi d'autres éléments qui ne se rapportent à aucun canal, graphe ou d'autre type de données.
| Clef | Type | Signification |
|---|---|---|
/filename | chaî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. |
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. |
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.