3d_dataヘッダファイルパッケージ マニュアル

(The documentation of 3d_data header file package)
Last Update: 2021/12/17


3d_dataヘッダファイルパッケージには 3次元データに対して様々な処理を行うヘッダファイルをまとめてある。
Header files to perform various operations for 3-D data are included in 3d_data header file package.
ymaeda_opentoolsにおいて「3次元データ」とは 3次元空間内の直交座標系\((x,y,z)\)に沿って一定間隔で配置した 格子点上で与えられる実数値のデータセット
{\(f(x_0+i\Delta x,y_0+j\Delta y,z_0+k\Delta z)\in\myvector{R}\); \((x_0, y_0, z_0)\in\myvector{R^3}\), \((\Delta x,\Delta y,\Delta z)\in\myvector{R^3}\), \(i=0,1,2,\cdots,N_x-1\), \(j=0,1,2,\cdots,N_y-1\), \(k=0,1,2,\cdots,N_z-1\)}
のことである。 ここで\(N_x\), \(N_y\), \(N_z\)はそれぞれ \(x\), \(y\), \(z\)方向の格子点数を表す。 例えば3次元地震波速度構造や密度構造、ある時刻における波動場などの空間分布を 表すのに適している。
In ymaeda_opentools, a “3-D data” is defined as a data set of real numbers given at grid nodes which are evenly deployed along an orthogonal coordinate system \((x,y,z)\) in a 3-D space This class of dataset can be represented as
{\(f(x_0+i\Delta x,y_0+j\Delta y,z_0+k\Delta z)\in\myvector{R}\); \((x_0, y_0, z_0)\in\myvector{R^3}\), \((\Delta x,\Delta y,\Delta z)\in\myvector{R^3}\), \(i=0,1,2,\cdots,N_x-1\), \(j=0,1,2,\cdots,N_y-1\), \(k=0,1,2,\cdots,N_z-1\)},
where \(N_x\), \(N_y\), and \(N_z\) are the numbers of grid nodes along the \(x\)-, \(y\)-, and \(z\)-directions, respectively. The 3-D data is used to represent, for example, 3-D seismic velocity and density structures or the spatial distribution of a wavefield at a given time.
3次元データはstruct _3d_data型構造体を用いて表現する。 これは3次元データを表現するために必要な
をひとまとめにした構造体で3d_data/structure.hにおいて定義されている。
A 3-D data is expressed by a struct _3d_data-type structure. It has information on:
This structure is defined in 3d_data/structure.h.
struct _3d_data型構造体において、 データ値はvalueという名前のメンバに格納されるが、これは1次元配列である。 3次元配列にする方が分かりやすいが、 空間差分を取る処理などを\(x\), \(y\), \(z\)方向で分けずにまとめて書けるように 1次元配列にした。 メンバvalueの\(iN_yN_z+jN_z+k\)番目の要素が \(f(x_0+i\Delta x,y_0+j\Delta y,z_0+k\Delta z)\)を表す。 すなわち、3次元データをfという名前のstruct _3d_data型構造体に読み込んだとすると \(f(x_0+i\Delta x,y_0+j\Delta y,z_0+k\Delta z)\)の値は
f.value[i∗f.N[1]∗f.N[2]+j∗f.N[2]+k]
のように参照できる。 ここでf.N[1]は\(N_y\)を、f.N[2]は\(N_z\)を表すメンバである。
In the struct _3d_data-type structure, the data values are stored in a member with a name value, which is a 1-D array. Although a 3-D array is more comprehensive, the 1-D array was adopted to implement spatial differential operations without brunching for \(x\)-, \(y\)-, and \(z\)- directions. The (\(iN_yN_z+jN_z+k\))-th component of the member value of the structure represents the value \(f(x_0+i\Delta x,y_0+j\Delta y,z_0+k\Delta z)\). Therefore, if a 3-D data was read into a struct _3d_data-type structure of a name f, then the value \(f(x_0+i\Delta x,y_0+j\Delta y,z_0+k\Delta z)\) can be referred to as
f.value[i∗f.N[1]∗f.N[2]+j∗f.N[2]+k]
where f.N[1] and f.N[2] are members that represent \(N_y\) and \(N_z\), respectively.
しかし上の例のような書き方はコードを書く際にも読む際にも 格子点番号と配列要素番号の対応関係を頭に入れておかなければならず分かりにくい。 そこで、コーディング時にこの対応関係を意識しなくても済むように 関数形式マクロ_3dindexを用意している。 このマクロでは格子点番号\(i,j,k\)を与えれば 対応する配列要素番号\(iN_yN_z+jN_z+k\)が返される。 このマクロを用いることで、格子点番号と配列要素番号の対応関係を意識することなく
f.value[_3dindex(f,i,j,k)]
のようにして \(f(x_0+i\Delta x,y_0+j\Delta y,z_0+k\Delta z)\) の値を参照できる。
However, the reference method given above is not comprehensive, as the users must always keep in mind the relation between the grid node indices and the array index when writing and reading a code. To avoid it, a function-type macro _3dindex is available, which relates the grid node indices \(i,j,k\) and the array component index \(iN_yN_z+jN_z+k\). Using this macro, the value of \(f(x_0+i\Delta x,y_0+j\Delta y,z_0+k\Delta z)\) can be referred to as
f.value[_3dindex(f,i,j,k)]
without explicitly reminding the relation between the grid node indices and the array component index.
このヘッダファイルパッケージを作成した当初、この方法を思いつかず、 格子点番号と配列要素番号の対応関係を3次元整数配列を用いて表現していた。 この3次元整数配列はstruct _3d_data型構造体のメンバindexとして現在も残してあり、 これを用いれば\(f(x_0+i\Delta x,y_0+j\Delta y,z_0+k\Delta z)\)の値を
f.value[f.index[i][j][k]]
のように参照できる。 しかしマクロ_3dindexを用いる場合と比べてメモリが増えるだけでメリットは無いので 今後作成するコードではマクロ_3dindexを用いるべきであり、 メンバindexを残してあるのは昔に作成したコードが動くようにするためである。
When I first created this header file package, I did not have an idea to introduce the macro _3dindex. Instead, the relation between the grid node indices and the array component index was expressed by a 3-D array of integer. This array still remains as a member index of the struct _3d_data-type structure. Using it, the value of \(f(x_0+i\Delta x,y_0+j\Delta y,z_0+k\Delta z)\) can be referred to as
f.value[f.index[i][j][k]]
However, there is no advantage to use the member index compared to use the macro _3dindex. An additional memory is required by the use of the member index. Therefore, the macro _3dindex is recommended to be used in newly developed codes, while the member index is not removed to keep the old codes work.
3d_dataヘッダファイルパッケージ内のヘッダファイルを以下に示す。 各ヘッダファイルの詳細はリンクをクリックして参照のこと。
Header files in 3d_data header file package are listed below. For details of individual header files, click the links.

◆特殊なヘッダファイル (Special header files)

ヘッダファイル名
Header file name 		機能・用途
Purpose
3d_data/index.h 3d_dataヘッダファイルパッケージ内の 他のヘッダファイル一式をインクルードするためのヘッダファイル。
A header file to include all the other header files in 3d_data header file package.
3d_data/macro.h 3d_dataヘッダファイルパッケージ用のマクロの定義。
Definitions of macros for 3d_data header file package.
3d_data/structure.h 3d_dataヘッダファイルパッケージ用の構造体の定義。
Definitions of structures for 3d_data header file package.
3d_data/prototype.h 3d_dataヘッダファイルパッケージ内の関数のプロトタイプ。
Prototypes of functions in 3d_data header file package.

◆通常のヘッダファイル (Normal header files)

ヘッダファイル名
Header file name 		機能・用途
Purpose
3d_data/convert.h struct _3d_data型構造体と他の形式のデータの間の変換を行う関数。
Functions to make conversion between a struct _3d_data-type structure and other data types.
3d_data/differentiate.h struct _3d_data型構造体で表現された3次元データの 空間微分のための計算を行う関数。
Functions to conduct calculations for spatial differentiation of a 3-D data expressed by a struct _3d_data-type structure.
3d_data/info.h struct _3d_data型構造体から情報を取り出す関数。
Functions to extract an information from a struct _3d_data-type structure.
3d_data/initialize.h struct _3d_data型構造体のメンバindex,valueの動的メモリの確保・解放と 各メンバの初期化を行う関数。
Functions to allocate and release dynamic memories for members index and value of a struct _3d_data-type structure, and to initialize members of the structure.
3d_data/interpolate.h struct _3d_data型構造体で表現された3次元データの補間を行う関数。
Functions to interpolate a 3-D data represented by a struct _3d_data-type structure.
3d_data/operation.h struct _3d_data型構造体に対する様々な演算を行う関数。
Functions to perform various operations for a struct _3d_data-type structure.
3d_data/readwrite.h struct _3d_data型構造体のファイル入出力を行う関数。
Functions to read and write a struct _3d_data-type structure from/to a file.
3d_data/section.h struct _3d_data型構造体で表された3次元データを元に 2次元断面データを作成する関数。
Functions to create a 2-D section data from a 3-D data represented by a struct _3d_data-type structure.