Формат файлов Gwyddion

Файл данных собственного формата Gwyddion (GWY) состоит из древовидной структуры объектов, переведённых в последовательный вид. В общем случае эти объекты могут быть различного вида и включать в себя другие объекты (вследствие древовидной структуры). В понимании работы может сильно помочь gwydump, простой демонстратор структуры файла, который доступен на сайте проекта, если с ним поработать какое-то время и посмотреть содержимое различных файлов. Если вы планируете читать и/или писать файлы GWY в другом программном обеспечении, можно также взглянуть на libgwyfile, небольшую самостоятельную встраиваемую библиотеку для работы с файлами GWY.

Два слоя

Это описание формата файла задаёт на самом деле две различные вещи, которые иногда полезно различать:

  • Физическое представление файлов: порядок байтов, типы данных и их представление, как определяются размеры различных частей блока данных, как объекты с данными представляются в виде вложенного дерева, и т.д. Называется общий формат файла GWY в libgwyfile. Можно использовать этот формат для чего-то полностью отличающегося от данных СЗМ в каком-то совершенно другом программном обеспечении – и всё равно это будет называться формат файла GWY.
  • Представление конкретных данных СЗМ в Gwyddion, задающее дальнейшие условия поверх физической структуры и интерпретации. Например, мы описываем, что изображения сохраняются как объекты, называемые GwyDataField, в которых разрешения сохраняются таким образом, данные изображения сохраняются таким образом, и т.д. В libgwyfile это называется формат файла Gwyddion GWY.

Обычно должно быть достаточно понятно, когда мы говорим об общем формате, и когда о специфичных для Gwyddion объектах данных (иногда это будет явно указано). Мы начнём с физической структуры файла.

Порядок байтов

Все данные хранятся в формате младший байт сначала (little-endian, также известный как LSB или Intel).

Заголовок файла

Заголовок файла состоит из четырёх байтов (магическое число) со значениями символов ASCII GWYP.

Это новый формат файла, также существует более старая версия формата с заголовком GWYO. Она не будет здесь обсуждаться, поскольку в настоящее время практически перестала использоваться.

Данные файла

Остальная часть файла Gwyddion состоит из переведённых в последовательную форму (сериализованных) объектов GwyContainer, которые содержат все данные. Они сохраняются точно так же, как и любые другие объекты, что описано в следующей секции.

В общем случае файл GWY может содержать какой-то другой объект в качестве объекта верхнего уровня.

Размещение объекта

Объект состоит из трёх частей (в следующем порядке):

  1. Имя типа, сохранённое в виде завершенной NUL строки символов ASCII. Это имя типа в системе типов GObject. В общем случае имя должно быть правильным идентификатором языка C.
  2. Размер переведённых в последовательную форму данных в виде 32-битного целого без знака. Не включает в себя размер имени типа и размер себя.
  3. Список компонентов. Компонентами называются поименованные части данных объекта, каждая определённого типа данных: атомарного типа, массива атомарных типов или ещё одного объекта. Они сохраняются без определённого порядка.

Компоненты

Каждый компонент состоит из трёх частей (в следующем порядке):

  1. Имя, сохраненное в виде завершенной NUL строки в кодировке UTF-8.
  2. Тип, сохранённый как один байт без знака (символ). Таблица возможных типов компонент представлена ниже.
  3. Данные, сохранённые в формате, который подходит для определённого типа.

Компоненты нередко называются элементы (items) в libgwyfile и библиотеках Gwyddion.

Пропуск неизвестного (или неинтересного) компонента в процессе чтения файла GWY может осуществляться тем, что сначала читается название и тип компонента. Затем есть несколько вариантов:

  • Если тип является атомарным и имеет фиксированный размер число байт, которые нужно пропустить, задаёт таблица типов.
  • Для строк необходимо пропустить после завершающего символа NUL.
  • Если тип является объектом, необходимо прочесть его имя и размер, и размер тогда говорит сколько байт нужно пропустить дальше.
  • Если тип это массив простых атомарных типов, тогда необходимо прочитать длину массива и затем умножить размер атомарного типа на длину. Это даёт число байт, которое необходимо пропустить.
  • Для массива строк, необходимо прочитать длину массива и повторить пропуск строки (перемещение за NUL) в соответствии с длиной массива.
  • Наконец, наиболее сложный сценарий это массив объектов, где нужно прочесть длину массива и затем повторить пропуск объекта заданное число раз.

Типы данных

Доступные атомарные типы данных приведены в нижеследующей таблице:

ТипСимволРазмерПримечание
булевb1 байтНоль это false, не ноль (обычно 1) это true
символc1 байт 
32битное целоеi4 байта 
64битное целоеq8 байт 
вещественное двойной точностиd8 байтКонечное число с плавающей точкой двойной точности по стандарту IEEE 754, т.е. файлы не должны содержать бесконечных чисел и нечисловых значений (NaN).
строкаsпеременныйNUL-завершенная и кодированная в UTF-8
объектoпеременныйВложенный переведённый в последовательную форму объект, как описано выше

Каждый атомарный тип, кроме булевого (boolean) имеет своего двойника в виде массива. Символ типа для всех массивов тот же, что и для атомарного типа, только он написан в верхнем регистре. Массивы хранятся как 32-битная длина массива без знака (число элементов), затем значения элементов. Число элементов должно быть положительным, пустые массивы не сохраняются. Список типов данных для массивов приведён в следующей таблице:

ТипСимволПримечание
массив символовCВ общем случае ни NUL-завершенная, ни кодированная в UTF-8 (s используется для текстовых строк).
массив 32битных целыхI 
массив 64битных целыхQ 
массив вещественных чисел двойной точностиD 
массив строкS 
массив объектовOБуква O в верхнем регистре, не ноль

GwyContainer верхнего уровня

GwyContainer это общий похожий на словарь объект данных который может содержать произвольные компоненты произвольных типов. Это позволяет достаточно разумно включать непредусмотренные заранее структуры данных в файлы GWY.

Имена (ключи) объектов в GwyContainer, представленные в файле Gwyddion сильно напоминают имена файлов в UNIX, т.е. они записываются в виде разделённых / путей и образуют древовидную структуру. Например, название первого изображения, под номером 0, сохраняется под ключом /0/data/title. Следует отметить, что некоторые данные и дополнительная информация сохраняются под ключами с нелогичными названиями, обычно это происходит по историческим причинам.

Следующие разделы описывают организацию интересующик нас данных и информации в GwyContainer верхнего уровня. Этот список не обязательно будет полным. Однако, поскольку все элементы данных в файле единообразно указывают свои имена, тип и размер в байтах всегда можно пропустить неизвестные типы данных или те типы данных, которые не нужны, и извлекать только требуемые.

Изображения

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

КлючТипЗначение
/0/dataGwyDataFieldДанные канала.
/0/data/titleстрокаИмя канала, как оно показывается в просмотре данных
/0/data/visibleбулевДолжно ли изображение показываться в окне при открытии файла данных
/0/data/realsquareбулевДолжно ли изображение показываться в окне в режиме Равные масштабы осей (или, наоборот, в режиме Квадратные пиксели).
/0/base/paletteстрокаИмя градиента псевдоцвета используемого при отображении изображения.
/0/base/range-type32битное целоеТип отображения псевдоцвета (как задано инструментом «диапазон псевдоцвета»), значение из множества GwyLayerBasicRangeType.
/0/base/minвещественное двойной точностиМинимальное значение для заданного пользователем отображаемого диапазона.
/0/base/maxвещественное двойной точностиМаксимальное значение для заданного пользователем отображаемого диапазона.
/0/maskGwyDataFieldДанные маски. Размеры в пикселях этого поля данных должны соответствовать данным изображения.
/0/mask/redвещественное двойной точностиКрасный компонент цвета маски.
/0/mask/greenвещественное двойной точностиЗелёный компонент цвета маски.
/0/mask/blueвещественное двойной точностиСиний компонент цвета маски.
/0/mask/alphaвещественное двойной точностиКомпонент Alpha (прозрачность) цвета маски.
/0/showGwyDataFieldДанные презентации. Размеры в пикселях этого поля данных должны соответствовать данным изображения.
/0/metaGwyContainerМетаданные канала. Ключи это имена, которые будут отображаться в окне просмотра метаданных, строковые значения – значения данных.
/0/data/logGwyStringListЖурнал работы с каналом. Он имеет формат тип::function(param=value, …)@time.
/0/select/fooподкласс GwySelectionДанные выделенных объектов. Каждый тип выделения имеет (обычно) отдельный тип объекта и сохраняется под отдельным именем; конкретное имя foo будет тем же, что показано в менеджер выделенного.

Каналы представлены как объекты GwyDataField. Компоненты GwyDataField представлены в следующей таблице:

КомпонентТипЗначение
xres32битное целоеГоризонтальный размер в пикселях.
yres32битное целоеВертикальный размер в пикселях.
xrealвещественное двойной точностиГоризонтальный размер в физических единицах.
yrealвещественное двойной точностиВертикальный размер в физических единицах.
xoffвещественное двойной точностиГоризонтальное смещение верхнего левого угла в физических единицах. Обычно записывается только если не равно нулю.
yoffвещественное двойной точностиВертикальное смещение верхнего левого угла в физических единицах. Обычно записывается только если не равно нулю.
si_unit_xyGwySIUnitЕдиница измерения горизонтальных размеров.
si_unit_zGwySIUnitЕдиница измерения значений данных.
dataмассив вещественных чисел двойной точностиДанные поля, сохранённые как плоский массив размера xres×yres, сверху вниз и слева направо.

Графики

Следующая таблица содержит общие ключи данных, относящихся к графикам в контейнере верхнего уровня для графика номер 1. Для других графиков число 1 должно быть заменено на соответствующий номер графика. Следует отметить, что графики нередко нумеруются последовательно начиная с единицы, но они могут иметь любые положительные номера, не обязательно последовательные. Число 0 в префиксе номеров графика является историческим артефактом, ничего сейчас не значит и всегда должно быть 0.

КлючТипЗначение
/0/graph/graph/1GwyGraphModelДанные объекта Graph model
/0/graph/graph/1/visibleбулевДолжен ли график отображаться при открытии файла.

Графики представлены как объекты GwyGraphModel. Компоненты GwyGraphModel сведены в следующую таблицу:

КомпонентТипЗначение
curvesмассив из GwyGraphCurveModelОтдельные кривые графиков.
titleстрокаНазвание графика как оно отображается в окне просмотра данных.
x_unitGwySIUnitЕдиницы абсциссы.
y_unitGwySIUnitЕдиницы ординаты.
top_labelстрокаПодпись верхней оси.
bottom_labelстрокаПодпись нижней оси.
left_labelстрокаПодпись левой оси.
right_labelстрокаПодпись правой оси.
x_is_logarithmicбулевЛогарифмический масштаб абсциссы.
y_is_logarithmicбулевЛогарифмический масштаб ординаты.
x_minвещественное двойной точностиЗаданное пользователем минимальное значение абсциссы.
x_min_setбулевНужно ли использовать заданное пользователем минимальное значение абсциссы (или диапазон определяется автоматически).
x_maxвещественное двойной точностиЗаданное пользователем максимальное значение абсциссы.
x_max_setбулевНужно ли использовать заданное пользователем максимальное значение абсциссы (или диапазон определяется автоматически).
y_minвещественное двойной точностиЗаданное пользователем минимальное значение ординаты.
y_min_setбулевНужно ли использовать заданное пользователем минимальное значение ординаты (или диапазон определяется автоматически).
y_maxвещественное двойной точностиЗаданное пользователем максимальное значение ординаты.
y_max_setбулевНужно ли использовать заданное пользователем максимальное значение ординаты (или диапазон определяется автоматически).
grid-type32битное целоеТип отображаемой сетки. Значение из множества GwyGraphGridType.
label.has_frameбулевОтображать рамку вокруг легенды.
label.frame_thickness32битное целоеТолщина рамки легенды.
label.reverseбулевОтображать легенду в обратном порядке.
label.visibleбулевнужно ли отображать легенду.
label.position32битное целоеРасположение (угол) в котором будет помещена легенда. Значение из множества GwyGraphLabelPosition.

Кривые графиков представлены как объекты GwyGraphCurveModel. Компоненты GwyGraphCurveModel сведены в следующую таблицу:

КомпонентТипЗначение
xdataмассив вещественных чисел двойной точностиТочки абсциссы. Число точек должно соответствовать ydata.
ydataмассив вещественных чисел двойной точностиТочки ординаты. Число точек должно соответствовать xdata.
descriptionстрокаОписание кривой (имя).
тип32битное целоеРежим отображения кривой (точки, линии и т.п.) Значение из множества GwyGraphCurveType.
color.redвещественное двойной точностиКрасный компонент цвета кривой.
color.greenвещественное двойной точностиЗелёный компонент цвета кривой.
color.blueвещественное двойной точностиСиний компонент цвета кривой.
point_type32битное целоеТип символов, представляющих точки данных. Значение из множества GwyGraphPointType.
point_size32битное целоеРазмер символов, представляющих точки данных.
line_type32битное целоеТип линий, соединяющих точки данных. Значение из множества GwyGraphLineType.
line_size32битное целоеТолщина линии, соединяющей точки данных.

Спектры

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

КлючТипЗначение
/sps/0GwySpectraДанные спектроскопии.

Наборы спектров одного типа представлены как объекты GwySpectra. Компоненты GwySpectra сведены в следующую таблицу:

КомпонентТипЗначение
titleстрокаНазвание спектров как оно отображается в окне просмотра данных.
si_unit_xyGwySIUnitЕдиницы измерения координат места, где снимались спектры.
coordsмассив вещественных чисел двойной точностиКоординаты точек, где снимались спектры, в физических единицах. Каждый спектр занимает два элемента: горизонтальную и вертикальную координату. Количество координат должно соответствовать числу кривых в data.
dataмассив из GwyDataLineОтдельные кривые спектров.
selectedмассив 32битных целыхИндексы выбранных кривых спектров.

Отдельные кривые в спектрах представлены как объекты GwyDataLine. Объект GwyDataLine является одномерным аналогом GwyDataField и используется также для других одномерных данных. Компоненты GwyDataLine сведены в следующую таблицу:

КомпонентТипЗначение
res32битное целоеЧисло точек данных.
realвещественное двойной точностиДлина в физических единицах.
offвещественное двойной точностиСмещение начала в физических единицах. Обычно записывается только если не равно нулю.
si_unit_xGwySIUnitЕдиницы измерения абсциссы.
si_unit_yGwySIUnitЕдиница измерения значений данных.
dataмассив вещественных чисел двойной точностиДанные линии, сохранённые как массив res, слева направо .

Объёмные данные

Следующая таблица сводит воедино общие ключи для объёмных данных в контейнере верхнего уровня для объёмных данных с номером 0. Для других объёмных данных, число 0 должно быть заменено соответствующим номером объёмных данных. Следует отметить, что объёмные данные обычно нумеруются последовательно, начиная с 0, однако, они могут иметь любые номера и множество номеров объёмных данных не обязательно должно быть непрерывным.

КлючТипЗначение
/brick/0GwyBrickОбъёмные данные.
/brick/0/previewGwyDataFieldДвумерные данные, демонстрируемые при показе объёмных данных в окне.
/brick/0/titleстрокаИмя объёмных данных, как оно показывается в браузере данных
/brick/0/visibleбулевСледует ли отображать объёмные данные в окне при загрузке файлов.
/brick/0/preview/paletteстрокаИмя градиента псевдоцвета используемого при отображении изображения предпросмотра.
/brick/0/metaGwyContainerМетаданные объёмных данных. Ключи это имена, которые будут отображаться в окне просмотра метаданных, строковые значения – значения данных.
/brick/0/logGwyStringListЖурнал работы с объёмными данными. Он имеет формат тип::function(param=value, …)@time.

Объёмные данные представлены как объекты GwyBrick. Компоненты GwyBrick представлены в следующей таблице:

КомпонентТипЗначение
xres32битное целоеГоризонтальный размер в пикселях.
yres32битное целоеВертикальный размер в пикселях.
zres32битное целоеГлубина (число уровней) в пикселях.
xrealвещественное двойной точностиГоризонтальный размер в физических единицах.
yrealвещественное двойной точностиВертикальный размер в физических единицах.
zrealвещественное двойной точностиРазмер глубины в физических единицах.
xoffвещественное двойной точностиГоризонтальное смещение верхнего левого угла в физических единицах. Обычно записывается только если не равно нулю.
yoffвещественное двойной точностиВертикальное смещение верхнего левого угла в физических единицах. Обычно записывается только если не равно нулю.
zoffвещественное двойной точностиСмещение по глубине верхнего левого угла в физических единицах. Обычно записывается только если не равно нулю.
si_unit_xGwySIUnitЕдиница измерения горизонтальных размеров.
si_unit_yGwySIUnitЕдиница измерения вертикальных пространственных размеров.
si_unit_zGwySIUnitЕдиница измерения размеров по глубине.
si_unit_wGwySIUnitЕдиница измерения значений данных.
dataмассив вещественных чисел двойной точностиДанные поля, сохранённые как плоский массив размера xres×yres×zres, с нулевой до последней плоскости, сверху вниз и слева направо.
calibrationGwyDataLineКалибровка оси z, представляющая нелинейные отсчёты шкалы в этом направлении. Число точек должно быть равно zres. Этот компонент присутствует только если используется нелинейная дискретизация вдоль этой оси.

Данные XYZ

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

КлючТипЗначение
/xyz/0GwySurfaceДанные XYZ.
/xyz/0/previewGwyDataFieldРастеризованное изображение предпросомтра которое показывается при отображении данных XYZ в окне. Следует отметить, что хотя изображения предпросмотра сохраняются в файлах GWY, они обычно являются создаётся заново и обновляется при показе данных так что добавлять их при записи файла GWY редко будет полезным занятием.
/xyz/0/titleстрокаИмя данных XYZ, как оно показывается в окне браузера данных.
/xyz/0/visibleбулевСледует ли отображать данные XYZ в окне при загрузке файлов.
/xyz/0/preview/paletteстрокаИмя градиента псевдоцвета используемого при отображении изображения предпросмотра.
/xyz/0/metaGwyContainerМетаданные данных XYZ. Ключи это имена, которые будут отображаться в окне просмотра метаданных, строковые значения – значения данных.
/xyz/0/logGwyStringListЖурнал работы с объёмными данными. Он имеет формат тип::function(param=value, …)@time.

Данные XYZ представлены как объекты GwySurface. Компоненты GwySurface представлены в следующей таблице:

КомпонентТипЗначение
si_unit_xyGwySIUnitЕдиница измерения горизонтальных размеров.
si_unit_zGwySIUnitЕдиница измерения значений данных.
dataмассив вещественных чисел двойной точностиДанные XYZ, сохранённые как плоский массив с длиной кратной 3. Каждый триплет XYZ сохраняется вместе, что приводит к следующему порядку следования данных: x₀, y₀, z₀, x₁, y₁, z₁, x₂, y₂, z₂, и т.д.

Другие элементы

Основной GwyContainer также содержит элементы, которые не относятся ни к одному из отдельных каналов, графиков или данных других типов.

КлючТипЗначение
/filenameстрокаИмя файла, с которым GwyContainer в данный момент связан. Если он был сохранён в файл, то этот элемент содержит соответствующее имя файла. В противном случае данный элемент содержит имя файла, из которого данные были загружены или импортированы. Элемент может быть не задан, например, в случае только что созданных синтетических данных.

Вспомогательные объекты

Компоненты GwySIUnit представлены в следующей таблице:

КомпонентТипЗначение
unitstrстрокаТекстовое представление единицы измерения, например, "A" или "m^-1" (как базовые единицы СИ, префиксы игнорируются).

Компоненты GwySelection сведены в следующую таблицу. Некоторые типы выделенного могут содержать другие элементы данных; обратитесь к документации к конкретному типу выделенного о том, как интерпретировать данные.

КомпонентТипЗначение
max32битное целоеМаксимальное число объектов. которое может быть в выделенном (число, установленное gwy_selection_set_max_objects()).
dataмассив вещественных чисел двойной точностиДанные выделения. Число элементов, которые формируют один объект выделения определяется типом выбранного.

Компоненты типа GwyStringList сведены в следующую таблицу. Если GwyStringList используется для представления журнала, строки будут иметь определённую структуру, описанную выше.

КомпонентТипЗначение
stringsмассив строкСписок строковых элементов.