Документация

Запись числового массива к набору данных HDF5

Этот пример создает массив и затем пишет массив в файл HDF5.

Карта HDF5 Синтаксис функций к синтаксису функции MATLAB

В большинстве случаев синтаксис низкоуровневых HDF5 функций MATLAB совпадает с синтаксисом соответствующих библиотечных функций HDF5. Например, следующее является функциональной подписью функции H5Fopen в библиотеке HDF5. В подписях функции HDF5 hid_t и herr_t являются типами HDF5, которые возвращают числовые значения, которые представляют идентификаторы объектов или ошибочные значения состояния.

hid_t H5Fopen(const char *name, unsigned flags, hid_t access_id) /* C syntax */

В MATLAB каждая функция в интерфейсе HDF5 является методом класса MATLAB. Следующее показывает подпись соответствующей функции MATLAB. Сначала обратите внимание, что, потому что это - метод класса, необходимо использовать запись через точку, чтобы вызвать функцию MATLAB: H5F.open Эта функция MATLAB принимает те же три аргумента как функцию HDF5: вектор символа, содержащий имя, HDF5-заданную константу для аргумента флагов и ID списка свойств HDF5. Вы используете списки свойств, чтобы задать характеристики многих различных объектов HDF5. В этом случае это - список свойств доступа к файлу. Обратитесь к документации HDF5, чтобы видеть, какие константы могут использоваться с конкретной функцией и отметить, что в MATLAB константы передаются как векторы символов.

file_id = H5F.open(name, flags, plist_id)

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

Отображение между типами данных HDF5 и типами данных MATLAB

Когда низкоуровневые функции HDF5 считывают данные из файла HDF5 или записывают данные к файлу HDF5, типам данных карты HDF5 функций к типам данных MATLAB автоматически.

Для атомарных типов данных, таких как обычно используемые двоичные форматы для чисел (целые числа и плавающая точка) и символы (ASCII), отображение является обычно прямым, потому что MATLAB поддерживает подобные типы. См. таблицу Mapping Between HDF5 Atomic Data Types и MATLAB Data Types для списка этих отображений.

Для составных типов данных, таких как агрегации одного или нескольких атомарных типов данных в структуры, многомерные массивы и типы данных переменной длины (одномерные массивы), отображение иногда неоднозначно со ссылкой на тип данных HDF5. В HDF5 набор данных 5 на 5, содержащий единственное значение uint8 в каждом элементе, отличен от набора данных 1 на 1, содержащего массив 5 на 5 значений uint8. В первом случае набор данных содержит 25 наблюдений за единственным значением. Во втором случае набор данных содержит единственное наблюдение с 25 значениями. В MATLAB оба из этих наборов данных представлены матрицей 5 на 5.

Если ваши данные являются набором комплексных данных, вы можете должны быть создать типы данных HDF5 непосредственно, чтобы убедиться, что у вас есть отображение, вы предназначаете. См. таблицу Mapping Between HDF5 Composite Data Types и MATLAB Data Types для списка отображений по умолчанию. Можно задать тип данных, когда вы записываете данные к файлу с помощью функции H5Dwrite. Смотрите, что тип данных HDF5 соединяет интерфейсом с документацией для получения дополнительной информации.

Создание отчетов о размерностях набора данных

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

Запись данных к набору данных HDF5 Используя низкоуровневые функции MATLAB

Этот пример показывает, как использовать низкоуровневые функции MATLAB® HDF5, чтобы записать набор данных в файл HDF5 и затем считать набор данных из файла.

Создайте массив 2х3 данных, чтобы записать в файл HDF5.

testdata = [1 3 5; 2 4 6];

Создайте новый файл с именем HDF5 my_file.h5 в системной папке временного файла. Используйте функцию H5F.create MATLAB, чтобы создать файл. Эта функция MATLAB соответствует функции HDF5, H5Fcreate. В качестве аргументов задайте имя, которое вы хотите присвоить файлу, типу доступа, который вы хотите к файлу ('H5F_ACC_TRUNC' в этом случае), и дополнительные дополнительные характеристики, заданные списком свойств создания файла и списком свойств доступа к файлу. В этом случае используйте значения по умолчанию для этих списков свойств ('H5P_DEFAULT'). Передайте константы C функции MATLAB как векторы символов.

filename = fullfile(tempdir,'my_file.h5');
fileID = H5F.create(filename,'H5F_ACC_TRUNC','H5P_DEFAULT','H5P_DEFAULT');

H5F.create возвращает идентификатор файла, соответствующий файлу HDF5.

Создайте набор данных в файле, чтобы содержать переменную MATLAB. В модели программирования HDF5 необходимо задать тип данных и размерность (пространство данных) набора данных как отдельные сущности. Во-первых, используйте функцию H5T.copy, чтобы задать тип данных, используемый по условию набор, в этом случае, double. Эта функция MATLAB соответствует функции HDF5, H5Tcopy.

datatypeID = H5T.copy('H5T_NATIVE_DOUBLE');

H5T.copy возвращает идентификатор типа данных.

Создайте пространство данных с помощью H5S.create_simple, который соответствует функции HDF5, H5Screate_simple. Первый входной параметр, 2, является рангом пространства данных. Второй входной параметр является массивом, задающим размер каждой размерности набора данных. Поскольку HDF5 хранит данные в главном строкой порядке, и массив MATLAB организован в порядке развертывания по столбцам, необходимо инвертировать упорядоченное расположение степеней размерности перед использованием H5Screate_simple, чтобы сохранить размещение данных. Можно использовать fliplr с этой целью.

dims = size(testdata);
dataspaceID = H5S.create_simple(2,fliplr(dims),[]);

H5S.create_simple возвращает идентификатор пространства данных, dataspaceID. Обратите внимание на то, что другие программы, которые используют главное строкой упорядоченное расположение (такое как H5DUMP от HDF Group) могут сообщить, что размер набора данных 3 2 вместо 2 3.

Создайте набор данных с помощью H5D.create, который соответствует функции HDF5, H5Dcreate. Задайте идентификатор файла, имя, которое вы хотите присвоить набору данных, идентификатору типа данных, идентификатору пространства данных и идентификатору списка свойств создания набора данных в качестве аргументов. 'H5P_DEFAULT' задает настройки списка свойств по умолчанию.

dsetname = 'my_dataset';  
datasetID = H5D.create(fileID,dsetname,datatypeID,dataspaceID,'H5P_DEFAULT');

H5D.create возвращает идентификатор набора данных, datasetID.

Запишите данные в набор данных с помощью H5D.write, который соответствует функции HDF5, H5Dwrite. Входные параметры являются идентификатором набора данных, идентификатором типа данных оперативной памяти, идентификатором пространства памяти, идентификатором пространства данных, идентификатором списка свойств передачи и именем переменной MATLAB, чтобы записать в набор данных. Константа, 'H5ML_DEFAULT', задает автоматическое отображение с типами данных HDF5. Константа, 'H5S_ALL', говорит H5D.write писать все данные в файл.

H5D.write(datasetID,'H5ML_DEFAULT','H5S_ALL','H5S_ALL',...
    'H5P_DEFAULT',testdata);

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

H5D.close(datasetID);
H5S.close(dataspaceID);
H5T.close(datatypeID);
H5F.close(fileID);

Откройте файл HDF5 в порядке считать набор данных, который вы записали. Используйте H5F.open, чтобы открыть файл для доступа только для чтения. Эта функция MATLAB соответствует функции HDF5, H5Fopen.

fileID = H5F.open(filename,'H5F_ACC_RDONLY','H5P_DEFAULT');

Откройте набор данных, чтобы считать использование H5D.open, который соответствует функции HDF5, H5Dopen. Задайте в качестве аргументов идентификатор файла и имя набора данных, заданного ранее в примере.

datasetID = H5D.open(fileID,dsetname);

Считайте данные в MATLAB workspace с помощью H5D.read, который соответствует функции HDF5, H5Dread. Входные параметры являются идентификатором набора данных, идентификатором типа данных оперативной памяти, идентификатором пространства памяти, идентификатором пространства данных и идентификатором списка свойств передачи.

returned_data = H5D.read(datasetID,'H5ML_DEFAULT',...
    'H5S_ALL','H5S_ALL','H5P_DEFAULT');

Сравните исходную переменную MATLAB, testdata, с переменной, просто созданной, returned_data.

isequal(testdata,returned_data)

ans = logical
   1

Эти две переменные являются тем же самым.

Запись большого набора данных

Чтобы записать большой набор данных, необходимо использовать большую возможность библиотеки HDF5. Для этого создайте список свойств и используйте функцию H5P.set_chunk, чтобы установить размер фрагмента в списке свойств. Предположим, что размерностями вашего набора данных является [2^16 2^16], и размер фрагмента 1024 1024. Вы затем передаете список свойств в качестве последнего аргумента к функции создания набора данных, H5D.create, вместо того, чтобы использовать значение H5P_DEFAULT.

dims = [2^16 2^16];
plistID = H5P.create('H5P_DATASET_CREATE'); % create property list

chunk_size = min([1024 1024], dims); % define chunk size 
H5P.set_chunk(plistID, fliplr(chunk_size)); % set chunk size in property list

datasetID = H5D.create(fileID, dsetname, datatypeID, dataspaceID, plistID); 

Сохранение правильного размещения данных

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