Интерфейс с объектом точки HDF-EOS
[out1,...,outN] = hdfpt(funcstr,input1,...,inputN)
hdfpt является шлюзом MATLAB ® к функциям Point в библиотеке HDF-EOS C, который разрабатывается и поддерживается EOSDIS (Система наблюдения Земли и информационная система). Набор данных Point включает в себя ряд записей данных, взятых через (возможно) нерегулярные интервалы времени и в различных географических точках. Каждая запись данных состоит из набора из одного или более значений данных, представляющих состояние момента времени и/или пространства.
[out1,...,outN] = hdfpt(funcstr,input1,...,inputN) возвращает один или несколько выходов, соответствующих функции Point в библиотеке HDF-EOS, указанной functstr.
Существует однозначное соответствие между функциями СТ в библиотеке HDF-EOS C и допустимыми значениями для funcstr. Например, hdfpt('detach',point_id) соответствует вызову библиотеки C PTdetach(point_id).
Модель программирования для доступа к набору данных точек через hdfpt является следующим:
Откройте файл и инициализируйте интерфейс СТ путем получения идентификатора файла из имени файла.
Открытие или создание набора данных точек путем получения идентификатора точки из имени точки.
Выполните необходимые операции с набором данных.
Закройте набор данных точек, установив идентификатор точки.
Завершите точечный доступ к файлу, установив идентификатор файла.
Для доступа к одноточечному набору данных, который уже существует в файле HDF-EOS, используйте следующие команды MATLAB:
fileid = hdfpt('open',filename,access);
pointid = hdfpt('attach',fileid,pointname);
% Optional operations on the data set...
status = hdfpt('detach',pointid);
status = hdfpt('close',fileid);Для одновременного доступа к нескольким файлам необходимо получить отдельный идентификатор файла для каждого открываемого файла. Для доступа к нескольким наборам данных точек необходимо получить отдельный идентификатор точки для каждого набора данных.
Важно правильно утилизировать идентификаторы точек и файлов, чтобы буферизованные операции были полностью записаны на диск. Если выйти из MATLAB или очистить все MEX-файлы с PT-идентификаторами по-прежнему открыты, MATLAB выдает предупреждение и автоматически удаляет их.
Обратите внимание, что идентификаторы файлов возвращены hdfpt не являются взаимозаменяемыми с идентификаторами файлов, возвращаемыми какой-либо другой функцией HDF-EOS или HDF.
Процедуры доступа инициализируют и завершают доступ к интерфейсу СТ и наборам данных точек (включая открывающие и закрывающие файлы).
Значение funcstr | Синтаксис функции | Описание |
|---|---|---|
'open' | file_id = hdfpt('open',filename,access) | Учитывая имя файла и требуемый режим доступа, открывает или создает HDF-файл для создания, чтения или записи точки. access может быть 'read', 'readwrite', или 'create'. file_id имеет значение -1, если операция завершается неуспешно. |
'create' | point_id = hdfpt('create',file_id,pointname) | Создание набора данных точек с указанным именем. pointname - символьный вектор или строковый скаляр, содержащий имя набора данных точек. point_id имеет значение -1, если операция завершается неуспешно. |
'attach' | point_id = hdfpt('attach',file_id,pointname) | Присоединение к существующему набору данных точек в файле. point_id имеет значение -1, если операция завершается неуспешно. |
'detach' | status = hdfpt('detach',point_id) | Отсоединяется от набора данных точек. |
'close' | status = hdfpt('close',file_id) | Закрывает файл. |
Процедуры определения позволяют пользователю устанавливать ключевые функции набора данных точек.
Значение funcstr | Синтаксис функции | Описание |
|---|---|---|
'deflevel' | status = hdfpt('deflevel',point_id,levelname,... | Определяет новый уровень в наборе данных точек. levelname - имя определяемого уровня. fieldList является массивом ячеек символьных векторов или строкового массива, содержащего имена полей на новом уровне. fieldTypes также является массивом ячеек символьных векторов или строкового массива, содержащего числовой тип для каждого поля в fieldList. Допустимые типы номеров: 'uchar8', 'uchar', 'char8', 'char', 'double', 'uint8', 'uint16', 'uint32', 'float', 'int8', 'int16', и 'int32'. fieldOrders - вектор, содержащий порядок для каждого поля. |
'deflinkage' | status = hdfpt('deflinkage',point_id,parent,child,linkfield) | Определяет поле связи между двумя соседними уровнями. parent - имя родительского уровня. child - имя дочернего уровня. linkfield - имя поля, определенного на обоих уровнях. |
Базовые процедуры ввода-вывода считывают и записывают данные и метаданные в набор точечных данных.
Значение funcstr | Синтаксис функции | Описание |
|---|---|---|
'writelevel' | status = hdfpt('writelevel',point_id,level,data) | Добавление новых записей к указанному уровню в наборе данных точек. level - требуемый индекс уровня (на основе нуля). data должно быть P-by-1 массив ячеек, где P - количество полей, определенных для указанного уровня. Каждая ячейка data должен содержать M(k)около-N матрица данных, где M(k) - порядок k-е поле (количество скалярных значений в поле) и N - количество записей. Класс MATLAB ячеек должен соответствовать типу данных HDF, определенному для соответствующих полей. Текстовые данные в MATLAB автоматически преобразуются в соответствии с любым типом символов HDF. Другие типы данных должны точно совпадать. |
'readlevel' | [data,status] = hdfpt('readlevel',point_id,... | Считывает данные с заданного уровня в наборе данных точек. level - индекс (отсчитываемый от нуля) требуемого уровня. fieldList является массивом ячеек символьных векторов или строкового массива, указывающего список полей для чтения. records - вектор, содержащий индексы (отсчитываемые от нуля) считываемых записей. data является P-by-1 массив ячеек, где P - количество запрашиваемых полей. Каждая ячейка data содержит M(k)около-N матрица данных, где M(k) - порядок k-е поле и N - количество записей, или length(records). |
'updatelevel' | status = hdfpt('updatelevel',point_id,... | Обновляет (корректирует) данные на определенном уровне набора данных точек. level - индекс (отсчитываемый от нуля) требуемого уровня. fieldList является массивом ячеек символьных векторов или строкового массива, указывающего список имен полей для обновления. records - вектор, содержащий индексы (на основе нуля) обновляемых записей. data является P-by-1 массив ячеек, где P - количество указанных полей. Каждая ячейка data должен содержать M(k)около-N матрица данных, где M(k) - порядок k-е поле (количество скалярных значений в поле) и N - количество записей, или length(records). Класс MATLAB ячеек должен соответствовать типу данных HDF, определенному для соответствующих полей. Текстовые данные в MATLAB автоматически преобразуются в соответствии с любым типом символов HDF. Другие типы данных должны точно совпадать. |
'writeattr' | status = hdfpt('writeattr',point_id,attrname,data) | Запись или обновление атрибута набора данных точек с указанным именем. Если атрибут еще не существует, он создается. |
'readattr' | [data,status] = hdfpt('readattr',point_id,attrname) | Считывает данные атрибута из указанного атрибута. |
Процедуры запроса возвращают информацию о данных, содержащихся в наборе данных точек.
Значение funcstr | Синтаксис функции | Описание |
|---|---|---|
'nlevels' | nlevels = hdfpt('nlevels',point_id) | Возвращает количество уровней в наборе данных точек. nlevels имеет значение -1, если операция завершается неуспешно. |
'nrecs' | nrecs = hdfpt('nrecs',point_id,level) | Возвращает количество записей на указанном уровне. nrecs имеет значение -1, если операция завершается неуспешно. |
'nfields' | [numfields,strbufsize] = hdfpt('nfields',point_id,level) | Возвращает число полей на указанном уровне. strbufsize - длина массива, содержащего имена полей. numfields равно -1 и strbufsize является [] если операция завершается неуспешно. |
'levelinfo' | [numfields,fieldList,field Type,fieldOrder] = ... | Возвращает информацию о полях для указанного уровня. fieldList является массивом ячеек символьных векторов или строкового массива, содержащего имена полей. fieldType - массив ячеек символьных векторов, которые определяют тип данных для каждого поля. fieldOrder - вектор, содержащий порядок (количество скалярных значений), связанный с каждым полем. Если операция завершается неуспешно, numfields равно -1, а остальные выходы пусты. |
'levelindx' | level = hdfpt('levelindx',point_id,levelname) | Возвращает индекс уровня (на основе нуля) уровня с указанным именем. level имеет значение -1, если операция завершается неуспешно. |
'bcklinkinfo' | [linkfield,status] = hdfpt('bcklinkinfo',point_id,level) | Возвращает поле связи на предыдущий уровень. status равно -1 и linkfield является [] если операция завершается неуспешно. |
'fwdlinkinfo' | [linkfield,status] = hdfpt('fwdlinkinfo',point_id,level) | Возвращает поле связи на следующий уровень. status равно -1 и linkfield является [] если операция завершается неуспешно. |
'getlevelname' | [levelname,status] = hdfpt('getlevelname',point_id,level) | Возвращает имя уровня, заданного индексом уровня. status равно -1 и levelname является [] если операция завершается неуспешно. |
'sizeof' | [byteSize,fieldLevels] = hdfpt('sizeof',point_id,fieldList) | Возвращает размер указанных полей в байтах и уровнях полей. fieldList является массивом ячеек символьных векторов или строкового массива, содержащего имена полей. byteSize - общий размер байтов указанных полей, и fieldLevels - вектор, содержащий индекс уровня, соответствующий каждому полю. byteSize равно -1 и fieldLevels является [] если операция завершается неуспешно. |
'attrinfo' | [numberType,count,status] = ... | Возвращает числовой тип и размер указанного атрибута в байтах. attrname - имя атрибута. numberType - символьный вектор, содержащий имя соответствующего типа данных HDF атрибута. count - количество байтов, используемых данными атрибута. status равно -1 и numberType и count являются [] если операция завершается неуспешно. |
'inqattrs' | [nattrs,attrnames] = hdfpt('inqattrs',point_id) | Получение информации об атрибутах, определенных в наборе данных точек. nattrs и attrnames - количество и имена всех определенных атрибутов соответственно. Если операция завершается неуспешно, nattrs равно -1 и attrnames является []. |
'inqpoint' | [numpoints,pointnames] = hdfpt('inqpoint',filename) | Извлеките номер и имена наборов данных точек, определенных в файле HDF-EOS. pointnames - массив ячеек символьных векторов, содержащих имена точек. numpoints равно -1 и pointnames является [] если операция завершается неуспешно. |
Местозаполнитель.
Значение funcstr | Синтаксис функции | Описание |
|---|---|---|
'getrecnums' | [outRecords,status] = hdfpt('getrecnums',... | Возвращает номера записей в outLevel соответствующей группе записей, указанной в inRecords в уровне inLevel. inLevel и outLevel аргументы являются индексами нулевого уровня. inRecords - вектор отсчитываемых от нуля индексов записей. status равно -1 и outRecords является [] если операция завершается неуспешно. |
Подпрограммы подмножества позволяют считывать данные из указанного географического региона.
Значение funcstr | Синтаксис функции | Описание |
|---|---|---|
'defboxregion' | region_id = hdfpt('defboxregion',point_id,cornerLon,cornerLat) | Определяет область прямоугольника долготы-широты для точки. cornerLon - двухэлементный вектор, содержащий долготы противоположных углов прямоугольника. cornerLat - двухэлементный вектор, содержащий широты противоположных углов коробки. region_idимеет значение -1, если операция завершается неуспешно. |
'defvrtregion' | period_id = hdfpt('defvrtregion',point_id,region_id,... | Определение вертикальной области для точки. vert_field - имя поля для подмножества. range - двухэлементный вектор, содержащий минимальное и максимальное вертикальные значения. period_id имеет значение -1, если операция завершается неуспешно. |
'regioninfo' | [byteSize,status] = hdfpt('regioninfo',point_id,... | Возвращает размер данных в байтах периода подмножества указанного уровня. fieldlist является массивом ячеек символьных векторов или строкового массива, указывающего список извлекаемых полей. status и byteSize равны -1, если операция завершается неуспешно. |
'regionrecs' | [numRec,recNumbers,status] = hdfpt('regionrecs',... | Возвращает номера записей в подмножестве указанного уровня. status и numrec равны -1 и recNumbers является [] если операция завершается неуспешно. |
'extractregion' | [data,status] = hdfpt('extractregion',point_id,... | Считывает данные из указанной области подмножества. fieldList является массивом ячеек символьных векторов или строкового массива, указывающего список запрашиваемых полей. data является P-by-1 массив ячеек, где P - количество запрашиваемых полей. Каждая ячейка data содержит M(k)около-N матрица данных, где M(k) - порядок k-е поле и N - количество записей. status равно -1 и data является [] если операция завершается неуспешно. |
'deftimeperiod' | period_id = hdfpt('deftimeperiod',point_id,startTime,stopTime) | Определяет период времени для набора данных точек. period_id имеет значение -1, если операция завершается неуспешно. |
'periodinfo' | [byteSize,status] = hdfpt('periodinfo',point_id,... | Извлекает размер в байтах подзаданного периода. fieldList - массив ячеек символьных векторов или строковый массив, задающий список имен полей. byteSize и status равны -1, если операция завершается неуспешно. |
'periodrecs' | [numRec,recNumbers,status] = hdfpt('periodrecs',... | Возвращает номера записей в пределах подзаданного периода времени указанного уровня. numRec и status равны -1, если операция завершается неуспешно. |
'extractperiod' | [data,status] = hdfpt('extractperiod',... | Считывает данные из указанного подзаданного периода времени. fieldList является массивом ячеек символьных векторов или строкового массива, указывающего список запрашиваемых полей. data является P-by-1 массив ячеек, где P - количество запрашиваемых полей. Каждая ячейка data содержит M(k)около-N матрица данных, где M(k) - порядок k-е поле и N - количество записей. status равно -1 и data является [] если операция завершается неуспешно. |
Большинство подпрограмм возвращают флаг, status, что равно 0 при успешном выполнении подпрограммы и -1 при сбое подпрограммы. Подпрограммы с синтаксисом, которые не содержат status возвращает информацию о сбое в одном из его выходов, как указано в синтаксисах функции.
levelName - вектор символов или строковый скаляр.
Некоторые функции библиотеки C принимают входные значения, определенные в терминах макросов C. Например, C PTopen() функция требует ввода в режиме доступа, который может быть DFACC_READ, DFACC_RDWR или DFACC_CREATE, когда эти символы определены в соответствующем файле заголовка C. При использовании определений макросов в библиотеке C в эквивалентных синтаксисах MATLAB используется текст, полученный из имен макросов. Можно либо использовать текст, содержащий все имя макроса, либо опустить общий префикс. Можно использовать верхний или нижний регистр. Например, вызов функции C:
status = PTopen("PointFile.hdf",DFACC_CREATE)status = hdfpt('open','PointFile.hdf','DFACC_CREATE') status = hdfpt('open','PointFile.hdf','dfacc_create') status = hdfpt('open','PointFile.hdf','CREATE') status = hdfpt('open','PointFile.hdf','create')
В случаях, когда функция C возвращает значение с определением макроса, эквивалентная функция MATLAB возвращает значение в виде текста, содержащего короткую форму макроса в нижнем регистре.
Типы номеров HDF определяются как: 'uchar8', 'uchar', 'char8', 'char', 'double', 'uint8', 'uint16', 'uint32', 'float', 'int8', 'int16', и 'int32'.
В случаях, когда библиотека HDF-EOS принимает NULL, используйте пустую матрицу ([]).