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

Встроенный формат файлов 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 если не задано.
TitleОпциональноЗаголовок данных/канала. Не имеет значения по умолчанию, приложения могут отображать ‘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). Данные сохраняются по строкам, сверху вниз и в каждой строке слева направо.

Подобно файлам GWY, данные не должны содержать бесконечных значений и значений NaN (не число). Gwyddion заменяет и показывает в виде маски такие данные при импорте начиная с версии 2.57, но поведение в более ранних версиях не определено.

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

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