Родные для Gwyddion файлы данных состоят из древоподобной структуры сериализованных объектов. В общем случае эти объекты могут быть различного вида и включать в себя другие объекты (вследствие древовидной структуры). В понимании работы может сильно помочь gwydump, простой демонстратор структуры файла, который доступен на сайте проекта, если с ним поработать какое-то время и посмотреть содержимое различных файлов.
Прежде всего, мы описываем физическую структуру файла безотносительно возможной интерпретации содержимого.
Все данные хранятся в формате младший сначала (little-endian, также известном, как LSB или Intel).
Заголовок файла состоит из четырёх байтов (магическое число) со значениями символов ASCII GWYP.
Это новый формат файла, также существует более старая версия формата с заголовком GWYO. Она не будет обсуждаться здесь.
Остальная часть файла состоит из переведённых в последовательную форму (сериализованных) объектов GwyContainer, которые содержат все данные. Они сохраняются точно так же, как и любые другие объекты, что описано в следующей секции.
Объект состоит из трёх частей (в следующем порядке):
NUL строки символов ASCII. Это имя типа в системе типов GObject.Каждый компонент состоит из трёх частей (в следующем порядке):
NUL строки.Доступные атомарные типы данных приведены в нижеследующей таблице:
| Тип | Символ | Примечание |
|---|---|---|
| булев | b | Сохраняется как байт, ноль = false, не ноль (обычно 1) = true |
| символ | c | |
| 32битное целое | i | |
| 64битное целое | q | |
| double | d | конечное число с плавающей точкой двойной точности по стандарту IEEE 754, т.е. файлы не должны содержать бесконечных чисел и не числовых значений (NaN). |
| строка | s | NUL-завершенная |
| объект | o | Переведённый в последовательную форму объект, как описано выше |
Каждый атомарный тип, кроме булевого (boolean) имеет своего двойника в виде массива. Символ типа для всех массивов тот же, что и для атомарного типа, только он написан в верхнем регистре. Массивы хранятся как 32-битная длина массива без знака (число элементов), затем значения элементов. Список типов данных для массивов приведён ниже:
| Тип | Символ | Примечание |
|---|---|---|
| массив символов | C | Не NUL-завершенный |
| массив 32битных целых | I | |
| массив 64битных целых | Q | |
| массив double | D | |
| массив строк | S | |
| массив объектов | O | Буква O в верхнем регистре, не ноль |
Имена (ключи) объектов в GwyContainer, представленные в файле Gwyddion сильно напоминают имена файлов в UNIX, т.е. они записываются в виде разделённых / путей и образуют древовидную структуру. Например, название первого канала, под номером 0, сохраняется под ключом /0/data/title. Следует отметить, что некоторые данные и дополнительная информация сохраняются под ключами с нелогичными названиями, обычно это происходит по историческим причинам.
Следующие разделы описывают организацию интересующик нас данных и информации в GwyContainer. Этот список не обязательно будет полным. Однако, поскольку все элементы данных в файле единообразно указывают свои имена, тип и размер в байтах всегда можно пропустить неизвестные типы данных или те типы данных, что не нужны, и извлекать только требуемые.
Следующая таблица содержит общие ключи данных, относящихся к каналам в контейнере верхнего уровня для канала номер 0. Для других каналов число 0 должно быть заменено на соответствующий номер канала. Следует отметить, что каналы нередко нумеруются последовательно начиная с 0, однако, они могут иметь любые номера и множество номеров каналов не обязательно должно быть последовательно и непрерывно.
| Ключ | Тип | Значение |
|---|---|---|
/0/data | GwyDataField | Данные канала. |
/0/data/title | строка | Имя канала, как оно показывается в просмотре данных |
/0/data/visible | булев | Должен ли канал показываться в окне при открытии файла данных |
/0/base/palette | строка | Имя градиента псевдоцвета используемого при отображении канала. |
/0/base/range-type | 32битное целое | Тип отображения псевдоцвета (как задано инструментом «диапазон псевдоцвета»), значение из множества GwyLayerBasicRangeType. |
/0/base/min | double | Минимальное значение для заданного пользователем отображаемого диапазона. |
/0/base/max | double | Максимальное значение для заданного пользователем отображаемого диапазона. |
/0/mask | GwyDataField | Данные маски. Размеры в пикселях этого поля данных должны соответствовать данным канала. |
/0/mask/red | double | Красный компонент цвета маски. |
/0/mask/green | double | Зелёный компонент цвета маски. |
/0/mask/blue | double | Синий компонент цвета маски. |
/0/mask/alpha | double | Компонент Alpha (прозрачность) цвета маски. |
/0/show | GwyDataField | Данные презентации. Размеры в пикселях этого поля данных должны соответствовать данным канала. |
/0/meta | GwyContainer | Метаданные канала. Ключи это имена, которые будут отображаться в окне просмотра метаданных, строковые значения – значения данных. |
/0/select/ | подкласс GwySelection | Данные выделения. Каждый тип выделения имеет (обычно) отдельный тип объекта и сохраняется под отдельным именем; конкретное имя foo будет тем же, что показано в менеджер выделенного. |
Каналы представлены как объекты GwyDataField. Компоненты GwyDataField представлены в следующей таблице:
| Компонент | Тип | Значение |
|---|---|---|
xres | 32битное целое | Горизонтальный размер в пикселях. |
yres | 32битное целое | Вертикальный размер в пикселях. |
xreal | double | Горизонтальный размер в физических единицах. |
yreal | double | Вертикальный размер в физических единицах. |
xoff | double | Горизонтальное смещение верхнего левого угла в физических единицах. Обычно записывается только если не равно нулю. |
yoff | double | Вертикальное смещение верхнего левого угла в физических единицах. Обычно записывается только если не равно нулю. |
si_unit_xy | GwySIUnit | Единица измерения горизонтальных размеров. |
si_unit_z | GwySIUnit | Единица измерения значений данных. |
data | массив double | Данные поля, сохранённые как плоский массив размера xres×yres, сверху вниз и слева направо. |
Следующая таблица содержит общие ключи данных, относящихся к графикам в контейнере верхнего уровня для графика номер 1. Для других графиков число 1 должно быть заменено на соответствующий номер графика. Следует отметить, что графики нередко нумеруются последовательно начиная с единицы, но они могут иметь любые положительные номера, не обязательно последовательные. Число 0 в префиксе номеров графика является историческим артефактом, ничего сейчас не значит и всегда должно быть 0.
| Ключ | Тип | Значение |
|---|---|---|
/0/graph/graph/1 | GwyGraphModel | Данные объекта Graph model |
/0/graph/graph/1/visible | булев | Должен ли график отображаться при открытии файла. |
Графики представлены как объекты GwyGraphModel. Компоненты GwyGraphModel сведены в следующую таблицу:
| Компонент | Тип | Значение |
|---|---|---|
curves | массив GwyGraphCurveModel | Отдельные кривые графиков. |
title | строка | Название графика как оно отображается в окне просмотра данных. |
x_unit | GwySIUnit | Единицы абсциссы. |
y_unit | GwySIUnit | Единицы ординаты. |
top_label | строка | Подпись верхней оси. |
bottom_label | строка | Подпись нижней оси. |
left_label | строка | Подпись левой оси. |
right_label | строка | Подпись правой оси. |
x_is_logarithmic | булев | Логарифмический масштаб абсциссы. |
y_is_logarithmic | булев | Логарифмический масштаб ординаты. |
x_min | double | Заданное пользователем минимальное значение абсциссы. |
x_min_set | булев | Нужно ли использовать заданное пользователем минимальное значение абсциссы (или диапазон определяется автоматически). |
x_max | double | Заданное пользователем максимальное значение абсциссы. |
x_max_set | булев | Нужно ли использовать заданное пользователем максимальное значение абсциссы (или диапазон определяется автоматически). |
y_min | double | Заданное пользователем минимальное значение ординаты. |
y_min_set | булев | Нужно ли использовать заданное пользователем минимальное значение ординаты (или диапазон определяется автоматически). |
y_max | double | Заданное пользователем максимальное значение ординаты. |
y_max_set | булев | Нужно ли использовать заданное пользователем максимальное значение ординаты (или диапазон определяется автоматически). |
grid-type | 32битное целое | Тип отображаемой сетки. Значение из множества GwyGraphGridType. |
label.has_frame | булев | Отображать рамку вокруг легенды. |
label.frame_thickness | 32битное целое | Толщина рамки легенды. |
label.reverse | булев | Отображать легенду в обратном порядке. |
label.visible | булев | нужно ли отображать легенду. |
label.position | 32битное целое | Расположение (угол) в котором будет помещена легенда. Значение из множества GwyGraphLabelPosition. |
Кривые графиков представлены как объекты GwyGraphCurveModel. Компоненты GwyGraphCurveModel сведены в следующую таблицу:
| Компонент | Тип | Значение |
|---|---|---|
xdata | массив double | Точки абсциссы. Число точек должно соответствовать ydata. |
ydata | массив double | Точки ординаты. Число точек должно соответствовать xdata. |
description | строка | Описание кривой (имя). |
тип | 32битное целое | Режим отображения кривой (точки, линии и т.п.) Значение из множества GwyGraphCurveType. |
color.red | double | Красный компонент цвета кривой. |
color.green | double | Зелёный компонент цвета кривой. |
color.blue | double | Синий компонент цвета кривой. |
point_type | 32битное целое | Тип символов, представляющих точки данных. Значение из множества GwyGraphPointType. |
point_size | 32битное целое | Размер символов, представляющих точки данных. |
line_type | 32битное целое | Тип линий, соединяющих точки данных. Значение из множества GwyGraphLineType. |
line_size | 32битное целое | Толщина линии, соединяющей точки данных. |
Следующая таблица содержит общие ключи данных, относящихся к спектроскопии в контейнере верхнего уровня для набора спектров номер 0. Для других спектров число 0 надо заменить соответствующим номером набора спектров. Следует отметить. что наборы спектров нередко нумеруются последовательно начиная с 0, хотя они могут иметь любые номера, которые не обязательно должны идти последовательно.
| Ключ | Тип | Значение |
|---|---|---|
/sps/0 | GwySpectra | Данные спектроскопии. |
Наборы спектров одного типа представлены как объекты GwySpectra. Компоненты GwySpectra сведены в следующую таблицу:
| Компонент | Тип | Значение |
|---|---|---|
title | строка | Название спектров как оно отображается в окне просмотра данных. |
si_unit_xy | GwySIUnit | Единицы измерения координат места, где снимались спектры. |
coords | массив double | Координаты точек, где снимались спектры, в физических единицах. Каждый спектр занимает два элемента: горизонтальную и вертикальную координату. Количество координат должно соответствовать числу кривых в data. |
data | массив элементов GwyDataLine | Отдельные кривые спектров. |
selected | массив 32битных целых | Индексы выбранных кривых спектров. |
Отдельные кривые в спектрах представлены как объекты GwyDataLine. Компоненты GwyDataLine сведены в следующую таблицу:
| Компонент | Тип | Значение |
|---|---|---|
res | 32битное целое | Число точек данных. |
real | double | Длина в физических единицах. |
off | double | Смещение начала в физических единицах. Обычно записывается только если не равно нулю. |
si_unit_x | GwySIUnit | Единицы измерения абсциссы. |
si_unit_y | GwySIUnit | Единица измерения значений данных. |
data | массив double | Данные линии, сохранённые как массив res, слева направо . |
Компоненты GwySIUnit представлены в следующей таблице:
| Компонент | Тип | Значение |
|---|---|---|
unitstr | строка | Текстовое представление единицы измерения, например, "A" или "m^-1" (как базовые единицы СИ, префиксы игнорируются). |
Компоненты GwySelection сведены в следующую таблицу. Некоторые типы выделенного могут содержать другие элементы данных; обратитесь к документации к конкретному типу выделенного о том, как интерпретировать данные.
| Компонент | Тип | Значение |
|---|---|---|
max | 32битное целое | Максимальное число объектов. которое может быть в выделенном (число, установленное gwy_selection_set_max_objects()). |
data | массив double | Данные выделения. Число элементов, которые формируют один объект выделения определяется типом выбранного. |