hdfpt
HDF-EOS 点对象的接口
语法
[out1,...,outN] = hdfpt(funcstr,input1,...,inputN)
说明
hdfpt
是 HDF-EOS C 库中的 Point 函数的 MATLAB® 入口,由 EOSDIS(地球观测系统数据和信息系统)开发和维护。点数据集包含(可能)在不规则时间区间和分散的地理位置获取的一系列数据记录。每个数据记录都包含一个由一个或多个数据值构成的集合,表示时间和/或空间中点的状态。
[out1,...,outN] = hdfpt(funcstr,input1,...,inputN)
返回与 HDF-EOS 库中由 functstr
指定的 Point 函数对应的一个或多个输出。
HDF-EOS C 库中的 PT 函数与 funcstr
的有效值之间存在一对一的对应关系。例如,hdfpt('detach',point_id)
对应于 C 库调用 PTdetach(point_id)
。
编程模型
通过 hdfpt
访问点数据集的编程模型如下所示:
通过从文件名中获取文件 id 来打开文件并初始化 PT 接口。
通过从点名称中获取点 id 来打开或创建一个点数据集。
对数据集执行需要的操作。
通过处置点 id 来关闭点数据集。
通过处置文件 id 来终止对文件的点访问。
要访问 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);
要同时访问多个文件,请为每个打开的文件获取一个单独的文件标识符。要访问多个点数据集,请为每个数据集获取一个单独的点 id。
务必正确处置点 id 和文件 id,以便缓冲的操作完全写入磁盘。如果退出 MATLAB 或清除所有 MEX 文件,但仍打开 PT 标识符,则 MATLAB 将发出警告并自动处置这些标识符。
请注意,hdfpt
返回的文件标识符不可与任何其他 HDF-EOS 或 HDF 函数返回的文件标识符互换。
访问例程
访问例程初始化以及终止对 PT 接口和点数据集的访问(包括打开和关闭文件)。
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 是同时在这两个级别定义的字段的名称。 |
基本 I/O 例程
基本 I/O 例程读取数据和元数据并将其写入到一个点数据集。
funcstr 的值 | 函数语法 | 说明 |
---|---|---|
'writelevel' | status = hdfpt('writelevel',point_id,level,data) | 将新记录追加到点数据集中的指定级别。level 是需要的级别索引(从 0 开始)。data 必须为 P ×1 元胞数组,其中 P 是为指定级别定义的字段数。data 的每个元胞必须包含一个 M(k) ×N 数据矩阵,其中 M(k) 是第 k 个字段的阶数(字段中标量值的数目),N 是记录数。元胞的 MATLAB 类必须与为对应字段定义的 HDF 数据类型匹配。MATLAB 中的文本数据将会自动转换,以便与任何 HDF 字符类型匹配。其他数据类型必须完全匹配。 |
'readlevel' | [data,status] = hdfpt('readlevel',point_id,... | 读取点数据集中给定级别的数据。level 是所需级别的索引(从 0 开始)。fieldList 是一个字符向量元胞数组或字符串数组,指定要读取的字段的列表。records 是一个向量,包含要读取的记录的索引(从 0 开始)。data 是一个 P ×1 元胞数组,其中 P 是所请求字段的数目。data 的每个元胞包含一个 M(k) ×N 数据矩阵,其中 M(k) 是第 k 个字段的阶数,N 是记录数或 length(records) 。 |
'updatelevel' | status = hdfpt('updatelevel',point_id,... | 更新(更正)点数据集特定级别的数据。level 是所需级别的索引(从 0 开始)。fieldList 是一个字符向量元胞数组或字符串数组,指定要更新的字段名称的列表。records 是一个向量,包含要更新的记录的索引(从 0 开始)。data 是一个 P ×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) | 返回具有指定名称的级别的级别索引(从 0 开始)。如果操作失败,则 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 中对应于级别 inLevel 中 inRecords 指定的记录组的记录数。inLevel 和 outLevel 参数是从 0 开始的级别索引。inRecords 是包含从 0 开始的记录索引的向量。如果操作失败,则 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 ×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 ×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
的情况下,可以使用空矩阵 ([]
)。
版本历史记录
在 R2006a 之前推出