Fichiers à Champ Simple

Le format Gwyddion natif contient toutes les informations et états que Gwyddion doit sauver, il est par conséquent assez complexe. Il est en général peu pratique de sauver des fichiers au format .gwy pour des logiciels tiers ou pour des scripts générant des données pour Gwyddion.

Le format Gwyddion à Champ Simple (.gsf, Gwyddion Simple Field) peut être utilisé dans ce genre de situation. Il s'agit d'un format à un seul canal pur des données 2D, qui a été conçu de manière à être simple et efficace à lire et écrire, avec un en-tête facilement lisible, suffisamment expressif, et ne nécessitant pas de champs spécifiques à un instrument ou une application (il peut toutefois les supporter de manière optionnelle).

Le format GSF peut être lu ou écrit à partir de la version 2.20.

Structure générale

Un fichier GSF consiste en quatre parties, dans l'ordre suivant :

ligne magique

Le fichier commence par une « ligne magique » qui permet d'identifier le type de fichier.

texte d'en-tête

L'en-tête est constitué de lignes sous la forme

nom = valeur

permet de définir différents paramètres.

remplissage par octets NUL

L'en-tête se termine par un à quatre octets NUL, permettant d'aligner le début des données sur un multiple de 4.

données binaires

Les données binaires sont données au format 32 bits à virgule flottante.

Ligne magique

Les fichiers GSF démarrent avec la ligne

Gwyddion Simple Field 1.0

terminée par le caractère saut de ligne (\n, ASCII 0x0a).

Texte d'en-tête

Chaque ligne d'en-tête est donnée sous la forme

nom = valeur

dans laquelle tout espace avant le nom, autour du signe égal, et en fin de ligne est ignoré. Les noms des champs sont sensibles à la casse et suivent les règles usuelles des langages de programmation concernant les identifiants.

De la même manière que pour la ligne magique, les lignes d'en-tête se terminent par le caractère saut de ligne, tel qu'utilisé sur les système Unix. Cela signifie que l'en-tête doit être lu et écrit en mode binaire pour garantir la préservation des caractères de fin de ligne sur d'autres systèmes d'exploitation (et ne pas changer la taille de l'en-tête, par exemple par une transformation LF → CRLF).

Tous caractères non ASCII pouvant apparaître par exemple dans le titre des données sont encodés au format UTF-8. Le caractère NUL ne peut apparaître dans l'en-tête.

Champs d'en-tête :

NomTypeValeur
XResObligatoire Taille horizontale en pixels, entier positif.
YResObligatoire Taille verticale en pixels, entier positif.
XRealOptionnel Taille horizontale en unités physiques (données par XYUnits), nombre positif en virgule flottante. Il vaut par défaut 1.0 s'il n'est pas précisé.
YRealOptionnel Taille verticale en unités physiques (données par XYUnits), nombre positif en virgule flottante. Il vaut par défaut 1.0 s'il n'est pas précisé.
XOffsetOptionnel Décalage horizontal en unités physiques (données par XYUnits), nombre en virgule flottante. Il vaut par défaut 0.0 s'il n'est pas précisé.
YOffsetOptionnel Décalage vertical en unités physiques (données par XYUnits), nombre en virgule flottante. Il vaut par défaut 0.0 s'il n'est pas précisé.
TitreOptionnel Titre des données du canal. Il n'y a pas de valeur par défaut, les applications peuvent afficher ‘Inconnu’ ou quelque chose de similaire s'il n'est pas donné.
XYUnitsOptionnel Unités latérales, c'est-à-dire les unités physiques des dimensions et des décalages. Elle doivent être données en unités de base, c'est-à-dire m ou A sans préfixe en puissance de 10 (Gwyddion peut le gérer mais cela pourrait poser un problème pour d'autres logiciels). Il n'y a pas d'unité par défaut. Cela signifie que pour des données SPM vous spécifierez normalement m pour XYUnits car les dimensions latérales sont en mètres.
ZUnitsOptionnel Unités de hauteur, c'est-à-dire des valeurs des données. Voir XYUnits ci-dessus pour plus de détails.

Les nombres en virgule flottante peuvent être donnés au format scientifique, par exemple 1.23e-4. Ils doivent être donnés selon le standard C/POSIX, c'est-à-dire que le point est utilisé comme séparateur de décimale (et non la virgule ou d'autres séparateurs).

L'en-tête peut contenir d'autres champs, en plus de ceux listés précédemment. Gwyddion les chargera dans les metadonnées. Les champs les plus communs peuvent être par exemple Commentaire, Date ou Direction.

Les champs peuvent être donnés dans n'importe quel ordre, il est toutefois recommandé de démarrer avec les champs oligatoires, puis continuer avec champs optionnels et enfin terminer avec les champs utilisateur.

Voici un exemple d'en-tête simple (incluant aussi la ligne magique) :

Gwyddion Simple Field 1.0
XRes = 400
YRes = 400
XReal = 5e-05
YReal = 5e-05
XYUnits = m
ZUnits = V
Title = ADC2

Remplissage par octets NUL

Le texte d'en-tête est suivi de un à quatre octets NUL (\0, ASCII 0x00) qui (a) le termine et (b) aligne le début des données avec un décalage par rapport au début de fichier égal à un multiple de 4. Plus précisément, soit N la longueur totale de la ligne magique et du texte d'en-tête, les données débutent au multiple de 4 supérieur à N le plus proche.

Ce remplissage au multiple de 4 garantit un alignement de l'accès mémoire lorsque le fichier est mis en mémoire. Le nombre d'octets NUL est uniquement déterminé par le reste de la longueur modulo quatre (N mod 4):

ResteNombre d'octets NUL
04
13
22
31

Données binaires

Les valeurs des données sont enregistrées en virgule flottante simple précision IEEE 32 bits, avec un arrangement des octets petit-boutiste (LSB ou Intel). Les valeurs sont enregistrées par ligne, en allant du haut vers le bas, chaque ligne allant de gauche à droite.

L'unité physique de ces valeurs est donnée par ZUnits.

La tailles des données de l'image vaut exactement 4*XRes*YRes octets et plus aucune donnée n'est présente ensuite.