hdfpt

HDF-EOS ポイントオブジェクトへのインターフェイス

構文

[out1,...,outN] = hdfpt(funcstr,input1,...,inputN)

説明

hdfpt は HDF-EOS C ライブラリのポイント関数への MATLAB^® ゲートウェイです。これは EOSDIS (Earth Observing System Data and Information System) によって開発され維持されています。ポイントデータセットは、散布した地理的位置でおそらく不定期に取得される一連のデータレコードから構成されています。各データレコードは、時間か空間 (または両方) のポイントの状態を表す 1 つ以上のデータ値のセットから構成されています。

[out1,...,outN] = hdfpt(funcstr,input1,...,inputN) は、functstr で指定された HDF-EOS ライブラリのポイント関数に対応する 1 つ以上の出力値を返します。

HDF-EOS C ライブラリの PT 関数と funcstr の有効値の間には 1 対 1 の対応があります。たとえば、hdfpt('detach',point_id) はC ライブラリの呼び出し PTdetach(point_id) に相当します。

プログラミングモデル

hdfpt を介したポイントデータセットへのアクセスのプログラミングモデルは次のとおりです。

ファイルを開き、ファイル名からファイル ID を取得し、PT インターフェイスを初期化します。
ポイントデータセットを開くか、ポイント名からポイント ID を取得してポイントデータセットを作成します。
必要な操作をデータセットで実行します。
ポイント ID を破棄して、ポイントデータセットを閉じます。
ファイル ID を破棄して、ファイルへのポイントアクセスを停止します。

HDF-EOS ファイル内に既に存在する 1 つのポイントデータセットにアクセスするには、次の 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 を正しく破棄することが重要です。PT 識別子がまだ開いている状態で MATLAB を終了したり、MEX ファイルをすべてクリアした場合、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` はポイントデータセットの名前を含む文字ベクトルまたは string スカラーです。操作が失敗すると、`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,... fieldList,fieldTypes,fieldOrders)`	ポイントデータセット内に新規レベルを定義します。`levelname` は定義するレベルの名前です。`fieldList` は新規レベルのフィールド名を含む文字ベクトルの cell 配列または string 配列です。`fieldTypes` も文字ベクトルの cell 配列または string 配列であり、`fieldList` の各フィールドの数値型を含みます。有効な数値型は `'uchar8'`、`'uchar'`、`'char8'`、`'char'`、`'double'`、`'uint8'`、`'uint16'`、`'uint32'`、`'float'`、`'int8'`、`'int16'`、`'int32'` です。`fieldOrders` は各フィールドの次数を含むベクトルです。
`'deflinkage'`	`status = hdfpt('deflinkage',point_id,parent,child,linkfield)`	2 つの隣接するレベルの間のリンクフィールドを定義します。`parent` は親レベル名です。`child` は子レベル名です。`linkfield` は両方のレベルで定義されるフィールドの名前です。

基本 I/O ルーチン

基本 I/O ルーチンでは、ポイントデータセットでのデータやメタデータの読み取りや書き込みを行います。

`funcstr` の値	関数構文	説明
`'writelevel'`	`status = hdfpt('writelevel',point_id,level,data)`	ポイントデータセット内で指定されたレベルに新規レコードを追加します。`level` は目的のレベルインデックスです (0 ベース)。`data` は `P` 行 1 列の cell 配列で、`P` は指定されたレベルに定義されているフィールド数です。`data` の各セルには `M(k)` 行 `N` 列のデータ行列が格納されていなければなりません。ここで `M(k)` は `k` 番目のフィールドの次数 (フィールドのスカラー値の数) で、`N` はレコード数です。セルの MATLAB クラスは、対応するフィールドに定義された HDF データ型に一致しなければなりません。MATLAB のテキストデータは HDF char 型のいずれかと一致するように自動変換されます。その他のデータ型は厳密に一致しなければなりません。
`'readlevel'`	`[data,status] = hdfpt('readlevel',point_id,... level,fieldList,records)`	ポイントデータセット内の指定されたレベルからデータを読み取ります。`level` は目的のレベルのインデックスです (0 ベース)。`fieldList` は、読み取るフィールドのリストを指定する文字ベクトルの cell 配列または string 配列です。`records` は読み取るレコードのインデックス (0 ベース) を含むベクトルです。`data` は `P` 行 1 列の cell 配列で、`P` は要求されたフィールドの数です。`data` の各セルには `M(k)` 行 `N` 列のデータ行列が格納されています。ここで `M(k)` は `k` 番目のフィールドの次数で、`N` はレコード数、すなわち `length(records)` です。
`'updatelevel'`	`status = hdfpt('updatelevel',point_id,... level,fieldList,records,data)`	ポイントデータセット内の特定のレベルにあるデータを更新 (修正) します。`level` は目的のレベルのインデックスです (0 ベース)。`fieldList` は、更新するフィールド名のリストを指定する文字ベクトルの cell 配列または string 配列です。`records` は更新するレコードのインデックス (0 ベース) を含むベクトルです。`data` は `P` 行 1 列の cell 配列で、`P` は指定されたフィールドの数です。`data` の各セルには `M(k)` 行 `N` 列のデータ行列が格納されていなければなりません。ここで `M(k)` は `k` 番目のフィールドの次数 (フィールドのスカラー値の数) で、`N` はレコード数、すなわち `length(records)` です。セルの MATLAB クラスは、対応するフィールドに定義された HDF データ型に一致しなければなりません。MATLAB のテキストデータは HDF char 型のいずれかと一致するように自動変換されます。その他のデータ型は厳密に一致しなければなりません。
`'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] = ... hdfpt('levelinfo',point_id,level)`	指定されたレベルのフィールドに関する情報を返します。`fieldList` はフィールド名を含む文字ベクトルの cell 配列または string 配列です。`fieldType` は各フィールドのデータ型を定義する文字ベクトルの cell 配列です。`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` はフィールド名を含む文字ベクトルの cell 配列または string 配列です。`byteSize` は指定されたフィールドの合計サイズ (バイト単位) で、`fieldLevels` は各フィールドに対応するレベルインデックスを含むベクトルです。操作が失敗すると `byteSize` は -1 になり、`fieldLevels` は `[]` になります。
`'attrinfo'`	`[numberType,count,status] = ... hdfpt('attrinfo',point_id,attrname)`	指定された属性の数値型とサイズ (バイト単位) を返します。`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` はポイント名を含む文字ベクトルの cell 配列です。操作が失敗すると `numpoints` は -1 になり、`pointnames` は `[]` になります。

ユーティリティルーチン

プレースホルダー。

`funcstr` の値	関数構文	説明
`'getrecnums'`	`[outRecords,status] = hdfpt('getrecnums',... point_id,inLevel,outLevel,inRecords)`	レベル `inLevel` での `inRecords` によって指定されるレコードグループに対応する `outLevel` のレコード番号を返します。`inLevel` と `outLevel` の各引数は 0 ベースのレベルインデックスです。`inRecords` は 0 ベースのレコードインデックスのベクトルです。操作が失敗すると `status` は -1 になり、`outRecords` は `[]` になります。

サブセットルーチン

サブセットルーチンを使用すると、指定された地理領域からデータを読み取ることができます。

`funcstr` の値	関数構文	説明
`'defboxregion'`	`region_id = hdfpt('defboxregion',point_id,cornerLon,cornerLat)`	ポイントの緯度経度ボックス領域を定義します。`cornerLon` はボックスの対角頂点の経度を含む 2 要素ベクトルです。`cornerLat` はボックスの対角頂点の緯度を含む 2 要素ベクトルです。操作が失敗すると `region_id` は -1 になります。
`'defvrtregion'`	`period_id = hdfpt('defvrtregion',point_id,region_id,... vert_field,range)`	ポイントの垂直領域を定義します。`vert_field` はサブセットするフィールドの名前です。`range` は最大と最小の垂直値を含む 2 要素ベクトルです。操作が失敗すると `period_id` は -1 になります。
`'regioninfo'`	`[byteSize,status] = hdfpt('regioninfo',point_id,... region_id,level,fieldList)`	指定されたレベルのサブセット化された期間のデータサイズ (バイト単位) を返します。`fieldlist` は抽出するフィールドのリストを指定する文字ベクトルの cell 配列または string 配列です。操作が失敗すると `status` と `byteSize` は -1 になります。
`'regionrecs'`	`[numRec,recNumbers,status] = hdfpt('regionrecs',... point_id,region_id,level)`	指定されたレベルのサブセット領域内のレコード番号を返します。操作が失敗すると `status` と `numrec` は -1 になり、`recNumbers` は `[]` になります。
`'extractregion'`	`[data,status] = hdfpt('extractregion',point_id,... region_id,level,fieldList)`	指定のサブセット化された領域からデータを読み取ります。`fieldList` は要求されたフィールドのリストを指定する文字ベクトルの cell 配列または string 配列です。`data` は `P` 行 1 列の cell 配列で、`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,... period_id,level,fieldList)`	サブセット化された期間のサイズ (バイト単位) を取得します。`fieldList` はフィールド名のリストを指定する文字ベクトルの cell 配列または string 配列です。操作が失敗すると `byteSize` と `status` は -1 になります。
`'periodrecs'`	`[numRec,recNumbers,status] = hdfpt('periodrecs',... point_id,period_id,level)`	指定されたレベルのサブセット化された時間間隔内のレコード番号を返します。操作が失敗すると `numRec` と `status` は -1 になります。
`'extractperiod'`	`[data,status] = hdfpt('extractperiod',... point_id,period_id,level,fieldList)`	指定のサブセット化された時間間隔からデータを読み取ります。`fieldList` は要求されたフィールドのリストを指定する文字ベクトルの cell 配列または string 配列です。`data` は `P` 行 1 列の cell 配列で、`P` は要求されたフィールドの数です。`data` の各セルには `M(k)` 行 `N` 列のデータ行列が格納されています。ここで `M(k)` は `k` 番目のフィールドの次数で、`N` はレコード数です。操作が失敗すると `status` は -1 になり、`data` は `[]` になります。

入力引数と出力引数

大部分のルーチンはフラグ status を返します。ルーチンが成功すると 0 になり、ルーチンが失敗すると -1 になります。構文に status を含まないルーチンの場合は、各関数構文で示したように、いずれかの出力で失敗に関する情報を返します。

levelName は、文字ベクトルまたは string スカラーです。

C ライブラリ関数には、C マクロで定義されている入力値を受け入れるものがあります。たとえば、C 関数 PTopen() は、DFACC_READ、DFACC_RDWR、DFACC_CREATE のいずれかであるアクセスモード入力を必要とします。これらのシンボルは、適宜、C ヘッダーファイルで定義されます。C ライブラリでマクロ定義が使用される場合に、同等の MATLAB 構文ではマクロ名から派生したテキストを使用します。マクロ名全体を含むテキストを使用することも、共通の接頭辞を省略することもできます。大文字も小文字も使用できます。たとえば、次の C 関数呼び出しがあるとします。

status = PTopen("PointFile.hdf",DFACC_CREATE)

これは次の MATLAB 関数呼び出しと同等です。

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 より前に導入

参考

matlab.io.hdfeos.sw