Простые файлы XYZ

Хотя Gwyddion не работает с произвольными данными в формате XYZ и необработанные данные XYZ при импорте интерполируются на регулярную сетку, возникла необходимость создать файловый формат, подобный по духу формату простого поля Gwyddion (.gsf), но представляющий данные в формате XYZ. Такой файловый формат, названный Gwyddion XYZ Field (.gxyzf), описывается в данном разделе.

Следует отметить, что Z просто оболзначает в данном случае ординату. Значения Z в файле могут быть в действительности реальными координатами по Z (высотами), но также могут быть токами, напряжениеями и т.п.

Файлы GXYZF могут быть записаны Gwyddion версии 2.31 или более поздней. Они также могут читаться начиная с этой версии, хотя выравнивание по сетке может быть достаточно грубым.

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

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

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

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

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

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

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

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

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

Заголовок заканчивается NUL-байтами от одного до восьми, выравнивающими начало данных на смещение, кратное 8.

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

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

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

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

Gwyddion XYZ Field 1.0

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

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

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

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

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

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

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

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

НазваниеТипЗначение
NChannelsОбязательноЧисло каналов значений (Z), положительное целое. Данные, сохраняемые для каждой точки также включают в себя координаты X и Y, но они не учитываются в NChannels.
NPointsОбязательноЧисло точек данных в файле.
XYUnitsОпциональноПространственные единицы измерения, т.е. единицы для значений X и Y. Должны быть заданы как основные единицы измерения, такие как m или A без десятичных префиксов (Gwyddion может разрешить эту ситуацию, но это может вызывать проблемы с другим программным обеспечением). По умолчанию единиц измерения нет. Это означает, что для данных СЗМ вы наверное захотите задать XYUnits как m поскольку латеральные размеры измеряются в метрах.
ZUnits1, ZUnits2, …ОпциональноЕдиницы измерения значений, т.е. единицы значений данных для индивидуальных каналов. Каналы нумеруются от 1 до NChannels. См. XYUnits выше для дополнительной информации.
Title1, Title2, …ОпциональноНазвания отдельных каналов. Каналы нумеруются от 1 до NChannels. У названий нет значения по умолчанию, пприложения могут показывать ‘Unknown’ или что-то подобное если название не задано.
XResОпциональноПодсказка, указывающая предпочитаемый горизонтальный размер в пикселях если данные интерполируются на сетку, положительное целое. Программы чтения данных могут не учитывать её и интерполировать данные на сетку иного разрешения.
YResОпциональноПодсказка, указывающая предпочитаемый горизонтальный размер в пикселях, если данные интерполируются на сетку, положительное целое. Программы чтения данных могут не учитывать её и интерполировать данные на сетку с другим разрешением.

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

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

Простой образец заголовка файла с двумя каналами (также включает в себя магисческую строку):

Gwyddion XYZ Field 1.0 NChannels = 2 NPoints = 457884 XYUnits = m ZUnits1 = m ZUnits2 = V Title1 = Height Title2 = ADC2

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

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

Дополнение до кратного 8 обеспечивает выравнивание данных при доступе к памяти при прямом отображении файла в память. Число нулевых байтов однозначно определяется остатком после деления длины заголовка на 8 (N mod 8):

ОстатокЧисло выравнивающих символов NUL
08
17
26
35
44
53
62
71

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

Значения данных хранятся как 64битные числа с плавающей точкой двойной точности стандарта IEEE, порядок байтов от младшего к старшему (little-endian, LSB или Intel). Точки хранятся в произвольном порядке. Каждая точка хранится как блок NChannels+2 значений: X, Y и затем все значения ординат в порядке следования каналов.

Физические единицы измерения значений задаются XYUnits для X и Y и затем ZUnits1, ZUnits2, … для значений ординат.

Размер данных ровно 8*NPoints*(NChannels+2) байт и после них в файле не должно быть данных.