Main Content

このページの内容は最新ではありません。最新版の英語を参照するには、ここをクリックします。

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 を介したポイント データセットへのアクセスのプログラミング モデルは次のとおりです。

  1. ファイルを開き、ファイル名からファイル ID を取得し、PT インターフェイスを初期化します。

  2. ポイント データセットを開くか、ポイント名からポイント ID を取得してポイント データセットを作成します。

  3. 必要な操作をデータセットで実行します。

  4. ポイント ID を破棄して、ポイント データセットを閉じます。

  5. ファイル 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 ベース)。dataP 行 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 ベース) を含むベクトルです。dataP 行 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 ベース) を含むベクトルです。dataP 行 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 になり、numberTypecount[] になります。
'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 のレコード番号を返します。inLeveloutLevel の各引数は 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 配列です。操作が失敗すると statusbyteSize は -1 になります。
'regionrecs'[numRec,recNumbers,status] = hdfpt('regionrecs',...
point_id,region_id,level)
指定されたレベルのサブセット領域内のレコード番号を返します。操作が失敗すると statusnumrec は -1 になり、recNumbers[] になります。
'extractregion'[data,status] = hdfpt('extractregion',point_id,...
region_id,level,fieldList)
指定のサブセット化された領域からデータを読み取ります。fieldList は要求されたフィールドのリストを指定する文字ベクトルの cell 配列または string 配列です。dataP 行 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 配列です。操作が失敗すると byteSizestatus は -1 になります。
'periodrecs'[numRec,recNumbers,status] = hdfpt('periodrecs',...
point_id,period_id,level)
指定されたレベルのサブセット化された時間間隔内のレコード番号を返します。操作が失敗すると numRecstatus は -1 になります。
'extractperiod'[data,status] = hdfpt('extractperiod',...
point_id,period_id,level,fieldList)
指定のサブセット化された時間間隔からデータを読み取ります。fieldList は要求されたフィールドのリストを指定する文字ベクトルの cell 配列または string 配列です。dataP 行 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 より前に導入