Файлы с простым полем

Встроенный формат файлов Gwyddion сохраняет всю информацию и состояние, которые нужно хранить программе и, следовательно, устроен достаточно сложно. Часто не является разумным сохранять файлы в формате .gwy в других программах и скриптах, создающих входные файлы для программы Gwyddion.

Вместо этого можно использовать формат файла Простое поле Gwyddion (.gsf) для этих целей. Это формат с одним каналом для двумерных данных, который разработан чтобы его можно было просто и эффективно читать и писать, с читаемым человеком заголовком, достаточно выразительный и избегающий специфичных для прибора или приложения полей (хотя опционально формат может их содержать).

GSF может быть прочитан и записан Gwyddion версии 2.20 и выше.

Общая структура

Файл GSF состоит из четырёх частей в следующем порядке:

магическая строка

Файлы начинаются с «магической строки», определяющей тип файла.

текстовый заголовок

Заголовок состоит из строк в формате

имя = значение

определяющих отдельные параметры.

Выравнивание с помощью NUL

Заголовок заканчивается от одного до четырёх байтов NUL, выравнивая начало данных кратно 4.

двоичные данные

Двоичные данные хранятся в 32-битном формате с плавающей точкой.

Магическая строка

Файлы GSF начинаются со строки

Gwyddion Simple Field 1.0

завершенной символом перевода строки (\n, ASCII 0x0a).

Текстовый заголовок

Каждая строка заголовка имеет формат

имя = значение

где любой пробельный символ перед именем, вокруг знака равенства и в конце значения игнорируется. Имена полей чувствительны к регистру и следуют обычным правилам для идентификаторов в языках программирования.

Подобно магической строке, строки в текстовом заголовке заканчиваются символом перевода строки, как принято в Unix. Это означает, что заголовок должен читаться и писаться в двоичном режиме для сохранения символов перевода строки на других системах (и неизменности размера заголовка, например при преобразовании LF → CRLF).

Любые символы не из алфавита ASCII, которые могут попасться, например, в имени канала, представлены в кодировке UTF-8. Символ NUL не может встречаться в заголовке.

Поля заголовка:

НазваниеТипЗначение
XResОбязательноеГоризонтальный размер в пикселях, положительное целое.
YResОбязательноеВертикальный размер в пикселях, положительное целое.
XRealОпциональноеГоризонтальный размер в физических единицах (заданных XYUnits), положительное число с плавающей точкой. По умолчанию равно 1.0 если не задано.
YRealОпциональноеВертикальный размер в физических единицах (заданных XYUnits), положительное число с плавающей точкой. По умолчанию равно 1.0 если не задано.
XOffsetОпциональноеГоризонтальное смещение в физических единицах (заданных XYUnits), положительное число с плавающей точкой. По умолчанию равно 0.0 если не задано.
YOffsetОпциональноеВертикальное смещение в физических единицах (заданных XYUnits), положительное число с плавающей точкой. По умолчанию равно 0.0 если не задано.
ЗаголовокОпциональноеЗаголовок данных/канала. Не имеет значения по умолчанию, приложения могут отображать ‘Unknown’ или нечто подобное если не задан.
XYUnitsОпциональноеПространственные единицы, т.е. единицы физических размеров и смещений. Они должны быть заданы как базовые единицы, которыми являются m или A без префикса, обозначающего степень 10 (Gwyddion с этим справится, но это может создавать проблемы другим программам). По умолчанию величины безразмерные. Это означает, что для данных СЗМ вы обычно захотите задать XYUnits как m поскольку пространственные размеры измеряются в метрах.
ZUnitsОпциональноеЕдиницы значения, т.е. единицы значений данных. См. XYUnits выше для дополнительной информации.

Числа с плавающей точкой могут быть в научном формате, т.е. 1.23e-4. Они представлены в стандартной локали C/POSIX, десятичным разделителем является точка (не запятая и не другие разделители).

Заголовок может содержать другие поля помимо описанных выше. Gwyddion загрузит их в метаданные. Общие информационные поля могут включать Комментарий, Дату или Направление.

Поля могут идти в любом порядке, тем не менее, рекомендуется начинать с обязательных полей, затем привести опциональные и закончить нестандартными.

Пример простого заголовка (также включает магическую строку):

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

Выравнивание с помощью NUL

За текстовым заголовком идёт от одного до четырёх байтов NUL (\0, ASCII 0x00), которые (a) завершают его и (b) выравнивают начало двоичных данных от начала файла на величину, кратную 4. Точнее, обозначив N общую длину магической строки и текстового заголовка, данные начинаются в ближайшем числе, кратном 4 и большем, чем N.

Это кратное 4 выравнивание гарантирует выровненный доступ к памяти при отображении файла непосредственно в память. Количество байтов NUL однозначно определяется остатком от деления длины на 4 (N mod 4):

ОстатокЧисло выравнивающих символов NUL
04
13
22
31

Двоичные данные

Значения данных хранятся как 32-битные числа с плавающей точкой IEEE одинарной точности, в формате следования байтов начиная с младшего (LSB, or Intel). Данные сохраняются по строкам, сверху вниз и в каждой строке слева направо.

Физические величины этих значений - ZUnits.

Размер данных изображения точно 4*XRes*YRes и после них в файле больше нет данных.