tkPlot3d.py ライブラリ技術ドキュメント

ライブラリの機能や目的

tkPlot3d.py は、Pythonの matplotlib ライブラリを拡張し、3Dデータの可視化を容易にするためのユーティリティ関数を提供するライブラリです。特に、科学技術計算やデータ分析の分野で、3次元空間におけるデータ分布、表面、等値面などを効率的にプロットすることを目的としています。

主な機能は以下の通りです。

• 3Dプロットにおける軸のスケーリングやアスペクト比の調整。

• カスタムカラーマップの作成と適用。

• 3D表面プロット (plot_surface3d)。

• marching_cubes アルゴリズムを用いた3D等値面プロット (plot_isosurface3d)。

• 3D空間における散布図プロット (plot_scatter3d)。

• 3D空間の特定平面上での2D等高線プロット (plot_contour2d_xy, plot_contour2d_yz, plot_contour2d_zx)。

• カラーバーの生成と設定。

このライブラリは、複雑な matplotlib の3Dプロット設定をカプセル化し、ユーザーがより簡潔なコードで高品質な3Dグラフィックを生成できるようにすることで、可視化の課題を解決します。

importする方法

tkPlot3d.py ライブラリを他のPythonプログラムから利用するには、通常のモジュールとしてimportします。

例えば、すべての関数をimportするには次のように記述します。

import tkPlot3d

特定の関数のみをimportする場合は、次のように記述します。

from tkPlot3d import plot_surface3d, plot_isosurface3d

必要な非標準ライブラリとインストール方法

tkPlot3d.py を実行するために、以下の非標準ライブラリが必要です。

• numpy: 数値計算を効率的に行うためのライブラリ。

• matplotlib: プロットとグラフ描画のための主要ライブラリ。特に3Dプロット機能 (mpl_toolkits.mplot3d) を利用します。

• scikit-image: 画像処理ライブラリ。特に3D等値面生成のための marching_cubes アルゴリズムを利用します。

これらのライブラリは pip コマンドを使用してインストールできます。

pip install numpy matplotlib scikit-image

importできる変数と関数

このライブラリでは、以下の関数がimport可能です。直接importできる変数は公開されていません。

関数

get_max_xyz(x, y, z)

入力された3つの配列 x, y, z の全ての要素をフラット化し、その中の最大絶対値を返します。これは3Dプロットの軸範囲を立方体状に統一する際に便利です。

• 引数:

  • x (numpy.ndarray): X座標データを含む配列。

  • y (numpy.ndarray): Y座標データを含む配列。

  • z (numpy.ndarray): Z座標データを含む配列。

• 戻り値:

  • float: x, y, z の全ての要素の中で最も大きい絶対値。

set_cubic_scale(ax, maxx)

指定されたMatplotlibの3D軸 ax のX、Y、Z軸の表示範囲を \([-maxx, maxx]\) に設定し、アスペクト比を1:1:1の立方体状に統一します。

• 引数:

  • ax (matplotlib.axes.Axes): Matplotlibの3D Axesオブジェクト。

  • maxx (float): 各軸の最大範囲（絶対値）。軸範囲は \([-maxx, maxx]\) となります。

• 戻り値:

  • None

make_cmap(colors, cmap_name = 'custom_cmap', nbins = 100)

色のリストからカスタムカラーマップを作成します。nbins が None または colors の長さ以下の場合、ListedColormap を使用し、それ以外の場合は LinearSegmentedColormap を使用します。 注記: この関数は matplotlib.colors.ListedColormap を利用しますが、現在の tkPlot3d.py ソースコード内では ListedColormap が直接importされていません。この関数を呼び出す場合は、別途 from matplotlib.colors import ListedColormap を実行する必要があるかもしれません。

• 引数:

  • colors (list): カラーマップを構成する色のリスト（例: [(R, G, B), ...], ['red', 'green', 'blue']）。

  • cmap_name (str, オプション): 作成するカスタムカラーマップの名前。デフォルトは 'custom_cmap'。

  • nbins (int, オプション): カラーマップの色のセグメント数。デフォルトは 100。

• 戻り値:

  • matplotlib.colors.Colormap: 作成されたカスタムカラーマップオブジェクト。

make_color_map(x, colors, cmap_name = 'custom_cmap', nbins = 100)

データ配列 x に基づいて、指定された色のリストからセグメント化されたカラーマップを作成し、正規化された x の値に対応する色を返します。

• 引数:

  • x (numpy.ndarray): カラーマッピングの基準となる数値データ。

  • colors (list): カラーマップを構成する色のリスト。

  • cmap_name (str, オプション): 作成するカスタムカラーマップの名前。デフォルトは 'custom_cmap'。

  • nbins (int, オプション): カラーマップの色のセグメント数。デフォルトは 100。

• 戻り値:

  • numpy.ndarray: x の各要素に対応するRGBAカラー値の配列。

make_colors(x, colors, vmin = None, vmax = None, cmap_name = 'custom_cmap', nbins = 100)

データ配列 x の値に基づいて、指定されたカスタムカラーマップを適用し、RGBAカラー値の配列を返します。データの最小値 (vmin) と最大値 (vmax) を指定して正規化できます。 注記: この関数は内部で make_colors 自身を再帰的に呼び出す形になっています。これは誤りである可能性が高く、通常は make_color_map を呼び出すことを意図していると考えられます。現在のコードでは、この関数が実際に機能することは期待できません。

• 引数:

  • x (numpy.ndarray): カラーマッピングの基準となる数値データ。

  • colors (list): カラーマップを構成する色のリスト。

  • vmin (float, オプション): 正規化範囲の最小値。指定されない場合、x の最小値が使用されます。

  • vmax (float, オプション): 正規化範囲の最大値。指定されない場合、x の最大値が使用されます。

  • cmap_name (str, オプション): 作成するカスタムカラーマップの名前。デフォルトは 'custom_cmap'。

  • nbins (int, オプション): カラーマップの色のセグメント数。デフォルトは 100。

• 戻り値:

  • numpy.ndarray: x の各要素に対応するRGBAカラー値の配列。

make_colorbar(ax, x, cmap, vmin = None, vmax = None, label = None, shrink = 0.5, aspect = 10.0, ticks = None, ticklabels = None)

指定されたMatplotlibのAxesオブジェクト ax にカラーバーを追加します。データ x の値範囲とカラーマップ cmap に基づいてカラーバーが生成されます。

• 引数:

  • ax (matplotlib.axes.Axes): カラーバーを配置するMatplotlibのAxesオブジェクト。

  • x (numpy.ndarray): カラーバーのスケール基準となる数値データ。

  • cmap (matplotlib.colors.Colormap または str): 使用するカラーマップオブジェクトまたは名前。

  • vmin (float, オプション): カラーバーの最小値。指定されない場合、x の最小値が使用されます。

  • vmax (float, オプション): カラーバーの最大値。指定されない場合、x の最大値が使用されます。

  • label (str, オプション): カラーバーのラベル。

  • shrink (float, オプション): Axesに対するカラーバーのサイズ比。デフォルトは 0.5。

  • aspect (float, オプション): カラーバーのアスペクト比。デフォルトは 10.0。

  • ticks (list または numpy.ndarray, オプション): カラーバーに表示する目盛りの位置のリスト。

  • ticklabels (list または numpy.ndarray, オプション): ticks に対応する目盛りラベルのリスト。

• 戻り値:

  • matplotlib.colorbar.Colorbar: 作成されたカラーバーオブジェクト。

set_light(x, azdeg = 315, altdeg = 45, cmap = "viridis", vert_exag = 0.1, blend_mode = 'soft')

データ x に対して、指定された光源設定とカラーマップを適用し、シェーディングされたRGB配列を生成します。これは3D表面プロットに陰影を加えるために使用されます。

• 引数:

  • x (numpy.ndarray): シェーディングの基準となるデータ（通常はZデータや高さ情報）。

  • azdeg (float, オプション): 光源の方位角（度）。デフォルトは 315。

  • altdeg (float, オプション): 光源の高度角（度）。デフォルトは 45。

  • cmap (str または matplotlib.colors.Colormap, オプション): 使用するカラーマップ。デフォルトは "viridis"。

  • vert_exag (float, オプション): 垂直方向の強調度。デフォルトは 0.1。

  • blend_mode (str, オプション): ブレンドモード（'soft', 'hsv', 'overlay' など）。デフォルトは 'soft'。

• 戻り値:

  • numpy.ndarray: シェーディングが適用されたRGBカラー値の配列。

show_color_bar(fig, ax, scale, cmap, shrink = 0.5, aspect = 10.0)

指定された fig と ax にカラーバーを追加します。scale データと cmap に基づいてカラーバーが生成されます。

• 引数:

  • fig (matplotlib.figure.Figure): MatplotlibのFigureオブジェクト。

  • ax (matplotlib.axes.Axes): カラーバーを配置するMatplotlibのAxesオブジェクト。

  • scale (numpy.ndarray): カラーバーのスケール基準となる数値データ。

  • cmap (matplotlib.colors.Colormap または str): 使用するカラーマップ。

  • shrink (float, オプション): Axesに対するカラーバーのサイズ比。デフォルトは 0.5。

  • aspect (float, オプション): カラーバーのアスペクト比。デフォルトは 10.0。

• 戻り値:

  • matplotlib.colorbar.Colorbar: 作成されたカラーバーオブジェクト。

plot_surface3d(ax, X, Y, Z, color = None, cmap = None, facecolors = None, edgecolor = 'black', alpha = 0.7, shade = True, xlabel = 'X', ylabel = 'Y', zlabel = 'Z')

指定された3D Axesオブジェクト ax に表面プロットを描画します。

• 引数:

  • ax (matplotlib.axes.Axes): Matplotlibの3D Axesオブジェクト。

  • X (numpy.ndarray): X座標のメッシュデータ。

  • Y (numpy.ndarray): Y座標のメッシュデータ。

  • Z (numpy.ndarray): Z座標のメッシュデータ。

  • color (str, オプション): 表面の色。cmap や facecolors が指定されていない場合。

  • cmap (str または matplotlib.colors.Colormap, オプション): 表面のカラーマップ。

  • facecolors (numpy.ndarray, オプション): 表面の各面のRGBAカラー値の配列。

  • edgecolor (str, オプション): 表面のエッジの色。デフォルトは 'black'。

  • alpha (float, オプション): 表面の透明度。デフォルトは 0.7。

  • shade (bool, オプション): シェーディングを適用するかどうか。デフォルトは True。

  • xlabel (str, オプション): X軸のラベル。デフォルトは 'X'。

  • ylabel (str, オプション): Y軸のラベル。デフォルトは 'Y'。

  • zlabel (str, オプション): Z軸のラベル。デフォルトは 'Z'。

• 戻り値:

  • None

plot_isosurface3d(ax, X, Y, Z, F, levels, origin, spacing, colors = None, edgecolor = 'k', alpha = 0.3, linewidth = 0.1, phase = None, custom_colors = None, nbins = 100, cmap_name = 'custom color', minx = None, maxx = None, miny = None, maxy = None, minz = None, maxz = None)

skimage.measure.marching_cubes アルゴリズムを使用して、3Dボリュームデータ F から指定された levels の等値面を抽出し、3D Axesオブジェクト ax にプロットします。位相データに基づいてカスタムカラーマップを適用することも可能です。

• 引数:

  • ax (matplotlib.axes.Axes): Matplotlibの3D Axesオブジェクト。

  • X (numpy.ndarray): X座標のグリッドデータ。

  • Y (numpy.ndarray): Y座標のグリッドデータ。

  • Z (numpy.ndarray): Z座標のグリッドデータ。

  • F (numpy.ndarray): 等値面を抽出する対象の3Dボリュームデータ。

  • levels (list または float): 抽出する等値面のレベル（値）。

  • origin (tuple または list): ボリュームデータの原点 (x, y, z)。

  • spacing (tuple または list): ボリュームデータのグリッド間隔 (dx, dy, dz)。

  • colors (list, オプション): 各等値面に適用する色のリスト。custom_colors が指定されていない場合に使用されます。

  • edgecolor (str, オプション): 等値面のエッジの色。デフォルトは 'k' (黒)。

  • alpha (float, オプション): 等値面の透明度。デフォルトは 0.3。

  • linewidth (float, オプション): 等値面のエッジの線幅。デフォルトは 0.1。

  • phase (numpy.ndarray, オプション): 位相データ。custom_colors と共に使用され、等値面の色を位相に応じて変化させます。

  • custom_colors (list, オプション): 位相データに基づいてカスタムカラーマップを生成するための色のリスト。

  • nbins (int, オプション): カスタムカラーマップの色のセグメント数。デフォルトは 100。

  • cmap_name (str, オプション): カスタムカラーマップの名前。デフォルトは 'custom color'。

  • minx, maxx, miny, maxy, minz, maxz (float, オプション): 軸の表示範囲。指定されない場合、X, Y, Z のデータ範囲から自動的に決定されます。

• 戻り値:

  • None

contour3d(ax, X, Y, F, nbins = 50, cmap = "viridis", xlabel = 'X', ylabel = 'Y', zlabel = 'Z')

3D Axesオブジェクト ax に3次元等高線プロットを描画します。

• 引数:

  • ax (matplotlib.axes.Axes): Matplotlibの3D Axesオブジェクト。

  • X (numpy.ndarray): X座標のメッシュデータ。

  • Y (numpy.ndarray): Y座標のメッシュデータ。

  • F (numpy.ndarray): Z座標または等高線の値のメッシュデータ。

  • nbins (int, オプション): 等高線の数。デフォルトは 50。

  • cmap (str または matplotlib.colors.Colormap, オプション): 等高線に使用するカラーマップ。デフォルトは "viridis"。

  • xlabel (str, オプション): X軸のラベル。デフォルトは 'X'。

  • ylabel (str, オプション): Y軸のラベル。デフォルトは 'Y'。

  • zlabel (str, オプション): Z軸のラベル。デフォルトは 'Z'。

• 戻り値:

  • None

plot_scatter3d(ax, x, y, z, minx, maxx, miny, maxy, minz, maxz, cmap = None, c = None, norm = None, marker = 'o', size = 0.5, alpha = 1.0)

3D Axesオブジェクト ax に3次元散布図をプロットします。

• 引数:

  • ax (matplotlib.axes.Axes): Matplotlibの3D Axesオブジェクト。

  • x (numpy.ndarray): X座標データ。

  • y (numpy.ndarray): Y座標データ。

  • z (numpy.ndarray): Z座標データ。

  • minx, maxx, miny, maxy, minz, maxz (float): 軸の表示範囲。

  • cmap (str または matplotlib.colors.Colormap, オプション): マーカーの色に使用するカラーマップ。

  • c (numpy.ndarray または str, オプション): マーカーの色データ、または単一の色指定。

  • norm (matplotlib.colors.Normalize, オプション): カラーマップ正規化オブジェクト。

  • marker (str, オプション): マーカーのスタイル。デフォルトは 'o' (円)。

  • size (float, オプション): マーカーのサイズ。デフォルトは 0.5。

  • alpha (float, オプション): マーカーの透明度。デフォルトは 1.0。

• 戻り値:

  • matplotlib.collections.Path3DCollection: 作成された散布図コレクションオブジェクト。

plot_contour2d_xy(ax, x, y, offsetz, f, cmap, levels, alpha)

3D空間内のXY平面に平行な位置 (offsetz) に2次元等高線塗りつぶしプロット (contourf) を描画します。

• 引数:

  • ax (matplotlib.axes.Axes): Matplotlibの3D Axesオブジェクト。

  • x (numpy.ndarray): X座標のメッシュデータ。

  • y (numpy.ndarray): Y座標のメッシュデータ。

  • offsetz (float): Z軸方向のオフセット（等高線が描画されるZ座標）。

  • f (numpy.ndarray): 等高線の値のメッシュデータ。

  • cmap (str または matplotlib.colors.Colormap): 等高線に使用するカラーマップ。

  • levels (int または list): 等高線の数または特定のレベル。

  • alpha (float): 等高線塗りつぶしの透明度。

• 戻り値:

  • None

plot_contour2d_yz(ax, offsetx, y, z, f, cmap, levels, alpha)

3D空間内のYZ平面に平行な位置 (offsetx) に2次元等高線塗りつぶしプロット (contourf) を描画します。

• 引数:

  • ax (matplotlib.axes.Axes): Matplotlibの3D Axesオブジェクト。

  • offsetx (float): X軸方向のオフセット（等高線が描画されるX座標）。

  • y (numpy.ndarray): Y座標のメッシュデータ。

  • z (numpy.ndarray): Z座標のメッシュデータ。

  • f (numpy.ndarray): 等高線の値のメッシュデータ。

  • cmap (str または matplotlib.colors.Colormap): 等高線に使用するカラーマップ。

  • levels (int または list): 等高線の数または特定のレベル。

  • alpha (float): 等高線塗りつぶしの透明度。

• 戻り値:

  • None

plot_contour2d_zx(ax, x, offsety, z, f, cmap, levels, alpha)

3D空間内のZX平面に平行な位置 (offsety) に2次元等高線塗りつぶしプロット (contourf) を描画します。

• 引数:

  • ax (matplotlib.axes.Axes): Matplotlibの3D Axesオブジェクト。

  • x (numpy.ndarray): X座標のメッシュデータ。

  • offsety (float): Y軸方向のオフセット（等高線が描画されるY座標）。

  • z (numpy.ndarray): Z座標のメッシュデータ。

  • f (numpy.ndarray): 等高線の値のメッシュデータ。

  • cmap (str または matplotlib.colors.Colormap): 等高線に使用するカラーマップ。

  • levels (int または list): 等高線の数または特定のレベル。

  • alpha (float): 等高線塗りつぶしの透明度。

• 戻り値:

  • None

plot_contours_xyz_by_func(ax, func, minx, maxx, nmesh = 100, posx = 0.1, posy = 0.1, posz = 0.1, offsetx = None, offsety = None, offsetz = None, cmap = None, levels = 20, alpha = 0.3)

関数 func(x, y, z) が定義する3Dデータに基づいて、X、Y、Z軸に平行な3つの平面に2D等高線塗りつぶしプロットを描画します。

• 引数:

  • ax (matplotlib.axes.Axes): Matplotlibの3D Axesオブジェクト。

  • func (callable): 3つの引数 (x, y, z) を受け取り、スカラー値を返す関数。

  • minx (float): 描画範囲の最小値。

  • maxx (float): 描画範囲の最大値。

  • nmesh (int, オプション): メッシュ点の数。デフォルトは 100。

  • posx, posy, posz (float, オプション): 各平面を通過する座標位置の割合（minx から maxx の範囲で）。デフォルトは 0.1。

  • offsetx, offsety, offsetz (float, オプション): 各平面が描画される絶対座標オフセット。指定されない場合、minx または maxx が使用されます。

  • cmap (str または matplotlib.colors.Colormap, オプション): 等高線に使用するカラーマップ。

  • levels (int または list, オプション): 等高線の数または特定のレベル。デフォルトは 20。

  • alpha (float, オプション): 等高線塗りつぶしの透明度。デフォルトは 0.3。

• 戻り値:

  • None

main scriptとして実行したときの動作

tkPlot3d.py が直接Pythonスクリプトとして実行された場合 (python tkPlot3d.py)、main() 関数が呼び出されます。

main() 関数は以下の処理を行います。

1. トーラスのパラメータ設定: 大半径 \(R=3\)、小半径 \(r=1\) を定義します。

2. メッシュグリッドの生成: \(0\) から \(2\pi\) までの範囲で theta と phi のパラメータ変数（それぞれ100点）を生成し、np.meshgrid を用いて2Dグリッドに展開します。

3. トーラスの座標計算: 以下のパラメトリック方程式を用いて、トーラスのX、Y、Z座標を計算します。 $\(X = (R + r \cos\theta) \cos\phi\)\( \)\(Y = (R + r \cos\theta) \sin\phi\)\( \)\(Z = r \sin\theta\)$

4. カスタムカラーマップの定義:

   • colors = [(1, 0.5, 0.5), (0, 1, 0), (1, 0.5, 0.5)] という色のリストを定義します。これは薄い赤、緑、薄い赤のグラデーションを表します。

   • make_color_map 関数を使用して、phi の値に基づいてこのカスタムカラーマップをトーラス表面に適用するためのカラーマップデータ (color_map) を生成します。

5. 3Dプロットの準備:

   • plt.figure() で新しいMatplotlibフィギュアを作成します。

   • fig.add_subplot(111, projection='3d') を使用して3Dプロット用のAxesオブジェクト ax を追加します。

6. トーラスのプロット:

   • plot_surface3d 関数を呼び出し、計算された X, Y, Z 座標と、先に生成した color_map を facecolors として指定してトーラスを表面プロットとして描画します。エッジは描画せず (edgecolor = 'none')、透明度 0.7、シェーディング True を設定します。

7. 画像の保存と表示:

   • plt.savefig('torus.png') を使用して、生成されたプロットを torus.png というファイル名で画像として保存します。

   • plt.show() を呼び出し、プロットウィンドウを表示します。

これにより、色付きの3Dトーラスが画面に表示され、同時に画像ファイルとして保存されます。