tkPlot3d プログラム仕様

tkPlot3d.py - 3Dプロット関連のユーティリティ関数を提供するモジュール

概要:

MatplotlibとNumPyを使用して、3Dサーフェス、等値面、散布図、2D等高線プロットなどを描画するための補助関数群を提供します。 カラーマップの作成や3D軸のスケーリング調整など、多様な3D可視化ニーズに対応します。

詳細説明:

このモジュールには、3D空間におけるデータの表現を容易にするための複数の関数が含まれています。 plot_surface3d は一般的な3Dサーフェスプロットを扱い、plot_isosurface3d は`marching_cubes`アルゴリズムを用いてボリュームデータから等値面を抽出・描画します。 また、make_cmap などの関数は、カスタムカラーマップを生成してプロットの視覚表現を豊かにするために使用できます。 軸の統一スケール設定やカラーバーの追加など、プロットの見た目を整えるためのユーティリティも含まれています。

関連リンク:

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

tklib.tkgraphic.tkPlot3d.contour3d(ax, X, Y, F, nbins=50, cmap='viridis', xlabel='X', ylabel='Y', zlabel='Z')

概要: 3D等高線プロットを描画します。

詳細説明:

matplotlib.pyplot.contour3D を使用して、指定された2次元データ F の 3D等高線（または等高線面）プロットを描画します。

パラメータ:

• ax -- (matplotlib.axes.Axes) プロットを描画する3D Axesオブジェクト。

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

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

• F -- (numpy.ndarray) 等高線を描画する2Dデータ。

• nbins -- (int, optional) 等高線の数。デフォルトは50。

• cmap -- (str or matplotlib.colors.Colormap, optional) 使用するカラーマップ。デフォルトは"viridis"。

• xlabel -- (str, optional) X軸のラベル。デフォルトは'X'。

• ylabel -- (str, optional) Y軸のラベル。デフォルトは'Y'。

• zlabel -- (str, optional) Z軸のラベル。デフォルトは'Z'。

戻り値:

(None)

tklib.tkgraphic.tkPlot3d.get_max_xyz(x, y, z)

概要: 3D座標の最大絶対値を取得します。

詳細説明:

与えられたX, Y, Z座標配列から、すべての要素の最大絶対値を計算します。 これにより、3Dプロットの軸範囲を統一するための基準値を得られます。

パラメータ:

• x -- (numpy.ndarray) X座標の配列。

• y -- (numpy.ndarray) Y座標の配列。

• z -- (numpy.ndarray) Z座標の配列。

戻り値:

(float) X, Y, Z座標の最大値の中から最も大きい値。

tklib.tkgraphic.tkPlot3d.main()

概要: トーラスを3Dでプロットするデモンストレーション関数です。

詳細説明:

トーラスのパラメトリック方程式を用いてX, Y, Z座標を生成し、 カスタムカラーマップを適用して3Dサーフェスプロットとして表示します。 結果は画像ファイルとして保存され、画面にも表示されます。

戻り値:

(None)

tklib.tkgraphic.tkPlot3d.make_cmap(colors, cmap_name='custom_cmap', nbins=100)

概要: カスタムカラーマップを作成します。

詳細説明:

指定された色のリストから、matplotlib.colors.ListedColormap (nbinsが少ない場合) または matplotlib.colors.LinearSegmentedColormap を用いてカスタムカラーマップを生成します。

パラメータ:

• colors -- (list) カラーマップを構成する色のリスト。色の形式はmatplotlibが認識するものであれば何でも可（例: 'red', '#FF0000', (1, 0, 0)）。

• cmap_name -- (str, optional) カスタムカラーマップの名前。デフォルトは 'custom_cmap'。

• nbins -- (int, optional) 線形補間を行う際のビン数。`colors`の要素数以下の場合、`ListedColormap`を使用。デフォルトは100。

戻り値:

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

tklib.tkgraphic.tkPlot3d.make_color_map(x, colors, cmap_name='custom_cmap', nbins=100)

概要: データに基づいてカスタムカラーマップを生成し、その色配列を返します。

詳細説明:

make_cmap を利用してカスタムカラーマップを作成し、入力データ x を正規化してその カラーマップを適用したRGBA色の配列を生成します。

パラメータ:

• x -- (numpy.ndarray) カラーマップを適用する数値データ。

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

• cmap_name -- (str, optional) カスタムカラーマップの名前。デフォルトは 'custom_cmap'。

• nbins -- (int, optional) 線形補間を行う際のビン数。デフォルトは100。

戻り値:

(numpy.ndarray) x の各要素に対応するRGBA色値の配列。

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

概要: カラーバーを作成し、プロットに追加します。

詳細説明:

与えられたデータ x とカラーマップ cmap に基づいてカラーバーを生成し、 指定されたAxesオブジェクトに追加します。ラベル、サイズ、ティックなども設定可能です。

パラメータ:

• ax -- (matplotlib.axes.Axes) カラーバーを追加するAxesオブジェクト。

• x -- (numpy.ndarray) カラーマップの正規化に使用するデータ。

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

• vmin -- (float, optional) カラーマップ正規化の最小値。指定されない場合は x の最小値。

• vmax -- (float, optional) カラーマップ正規化の最大値。指定されない場合は x の最大値。

• label -- (str, optional) カラーバーのラベル。

• shrink -- (float, optional) カラーバーの表示サイズの縮小率。デフォルトは0.5。

• aspect -- (float, optional) カラーバーのアスペクト比。デフォルトは10.0。

• ticks -- (list or numpy.ndarray, optional) カラーバーのティック位置。

• ticklabels -- (list of str, optional) カラーバーのティックラベル。

戻り値:

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

tklib.tkgraphic.tkPlot3d.make_colors(x, colors, vmin=None, vmax=None, cmap_name='custom_cmap', nbins=100)

概要: データに基づいて色配列を作成します。

詳細説明:

入力データ x の最小値・最大値（または指定された vmin, vmax）で正規化し、 カスタムカラーマップを適用してRGBA色配列を生成します。

パラメータ:

• x -- (numpy.ndarray) カラーマップを適用する数値データ。

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

• vmin -- (float, optional) カラーマップ正規化の最小値。指定されない場合は x の最小値。

• vmax -- (float, optional) カラーマップ正規化の最大値。指定されない場合は x の最大値。

• cmap_name -- (str, optional) カスタムカラーマップの名前。デフォルトは 'custom_cmap'。

• nbins -- (int, optional) 線形補間を行う際のビン数。デフォルトは100。

戻り値:

(numpy.ndarray) x の各要素に対応するRGBA色値の配列。

tklib.tkgraphic.tkPlot3d.plot_contour2d_xy(ax, x, y, offsetz, f, cmap, levels, alpha)

概要: XY平面に投影された2D等高線プロットを描画します。

詳細説明:

指定されたデータ f に基づいて、X-Y平面に平行な`offsetz`の高さに2D等高線塗りつぶしプロットを描画します。

パラメータ:

• ax -- (matplotlib.axes.Axes) プロットを描画する3D Axesオブジェクト。

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

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

• offsetz -- (float) 等高線プロットを配置するZ軸のオフセット値。

• f -- (numpy.ndarray) 等高線を描画する2Dデータ。

• cmap -- (str or matplotlib.colors.Colormap) 使用するカラーマップ。

• levels -- (int or list) 等高線の数またはレベルのリスト。

• alpha -- (float) 等高線プロットの透明度。

戻り値:

(None)

tklib.tkgraphic.tkPlot3d.plot_contour2d_yz(ax, offsetx, y, z, f, cmap, levels, alpha)

概要: YZ平面に投影された2D等高線プロットを描画します。

詳細説明:

指定されたデータ f に基づいて、Y-Z平面に平行な`offsetx`の位置に2D等高線塗りつぶしプロットを描画します。

パラメータ:

• ax -- (matplotlib.axes.Axes) プロットを描画する3D Axesオブジェクト。

• offsetx -- (float) 等高線プロットを配置するX軸のオフセット値。

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

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

• f -- (numpy.ndarray) 等高線を描画する2Dデータ。

• cmap -- (str or matplotlib.colors.Colormap) 使用するカラーマップ。

• levels -- (int or list) 等高線の数またはレベルのリスト。

• alpha -- (float) 等高線プロットの透明度。

戻り値:

(None)

tklib.tkgraphic.tkPlot3d.plot_contour2d_zx(ax, x, offsety, z, f, cmap, levels, alpha)

概要: ZX平面に投影された2D等高線プロットを描画します。

詳細説明:

指定されたデータ f に基づいて、Z-X平面に平行な`offsety`の位置に2D等高線塗りつぶしプロットを描画します。

パラメータ:

• ax -- (matplotlib.axes.Axes) プロットを描画する3D Axesオブジェクト。

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

• offsety -- (float) 等高線プロットを配置するY軸のオフセット値。

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

• f -- (numpy.ndarray) 等高線を描画する2Dデータ。

• cmap -- (str or matplotlib.colors.Colormap) 使用するカラーマップ。

• levels -- (int or list) 等高線の数またはレベルのリスト。

• alpha -- (float) 等高線プロットの透明度。

戻り値:

(None)

tklib.tkgraphic.tkPlot3d.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)

概要: 関数から計算されたデータに基づき、XYZの各平面に投影された2D等高線プロットを描画します。

詳細説明:

ユーザー定義関数 func を使用してX, Y, Z軸の各断層面におけるデータを計算し、 それぞれの平面（YZ、XY、ZX）に2D等高線塗りつぶしプロットを描画します。

パラメータ:

• ax -- (matplotlib.axes.Axes) プロットを描画する3D Axesオブジェクト。

• func -- (callable) (x, y, z) を引数にとり、スカラー値を返す関数。

• minx -- (float) 座標範囲の最小値。

• maxx -- (float) 座標範囲の最大値。

• nmesh -- (int, optional) メッシュの点数。デフォルトは100。

• posx -- (float, optional) YZ平面プロット用のX軸固定位置。デフォルトは0.1。

• posy -- (float, optional) ZX平面プロット用のY軸固定位置。デフォルトは0.1。

• posz -- (float, optional) XY平面プロット用のZ軸固定位置。デフォルトは0.1。

• offsetx -- (float, optional) YZ平面プロットのX軸オフセット。指定されない場合は`minx`。

• offsety -- (float, optional) ZX平面プロットのY軸オフセット。指定されない場合は`maxx`。

• offsetz -- (float, optional) XY平面プロットのZ軸オフセット。指定されない場合は`minx`。

• cmap -- (str or matplotlib.colors.Colormap, optional) 使用するカラーマップ。

• levels -- (int or list, optional) 等高線の数またはレベルのリスト。デフォルトは20。

• alpha -- (float, optional) 等高線プロットの透明度。デフォルトは0.3。

戻り値:

(None)

tklib.tkgraphic.tkPlot3d.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)

概要: 3Dボリュームデータから等値面を描画します。

詳細説明:

skimage.measure.marching_cubes を使用して、3Dボリュームデータ F から指定された レベルの等値面を抽出し、3D Axes上に描画します。位相データに基づくカスタムカラーリングや、 凡例の追加もサポートします。

パラメータ:

• ax -- (matplotlib.axes.Axes) プロットを描画する3D Axesオブジェクト。

• X -- (numpy.ndarray) X座標のグリッドデータ。軸範囲設定に使用。

• Y -- (numpy.ndarray) Y座標のグリッドデータ。軸範囲設定に使用。

• Z -- (numpy.ndarray) Z座標のグリッドデータ。軸範囲設定に使用。

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

• levels -- (list or float) 描画する等値面のレベル（値）のリスト。単一の値も可。

• origin -- (tuple) ボリュームデータの原点 (x, y, z)。

• spacing -- (tuple) ボリュームデータの各軸方向のサンプル間隔 (dx, dy, dz)。

• colors -- (list or str, optional) 等値面の色リスト（カスタムカラーマップが指定されていない場合）。

• edgecolor -- (str or tuple, optional) 等値面のエッジの色。デフォルトは'k' (黒)。

• alpha -- (float, optional) 等値面の透明度。デフォルトは0.3。

• linewidth -- (float, optional) 等値面のエッジの線の太さ。デフォルトは0.1。

• phase -- (numpy.ndarray, optional) 位相情報を含む3Dボリュームデータ。カスタムカラーリングに使用。

• custom_colors -- (list, optional) 位相に基づいて色付けするためのカスタムカラーリスト。

• nbins -- (int, optional) カスタムカラーマップ生成時のビン数。デフォルトは100。

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

• minx -- (float, optional) X軸の最小範囲。指定されない場合は X から自動計算。

• maxx -- (float, optional) X軸の最大範囲。指定されない場合は X から自動計算。

• miny -- (float, optional) Y軸の最小範囲。指定されない場合は Y から自動計算。

• maxy -- (float, optional) Y軸の最大範囲。指定されない場合は Y から自動計算。

• minz -- (float, optional) Z軸の最小範囲。指定されない場合は Z から自動計算。

• maxz -- (float, optional) Z軸の最大範囲。指定されない場合は Z から自動計算。

戻り値:

(None)

tklib.tkgraphic.tkPlot3d.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散布図を描画します。

詳細説明:

指定されたX, Y, Z座標データに基づいて、3Dの散布図を描画します。 マーカーの種類、サイズ、色、透明度などを設定できます。

パラメータ:

• ax -- (matplotlib.axes.Axes) プロットを描画する3D Axesオブジェクト。

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

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

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

• minx -- (float) X軸の最小範囲。

• maxx -- (float) X軸の最大範囲。

• miny -- (float) Y軸の最小範囲。

• maxy -- (float) Y軸の最大範囲。

• minz -- (float) Z軸の最小範囲。

• maxz -- (float) Z軸の最大範囲。

• cmap -- (str or matplotlib.colors.Colormap, optional) 色付けに使用するカラーマップ。

• c -- (numpy.ndarray or str, optional) 各点の色の配列、または単一色。

• norm -- (matplotlib.colors.Normalize, optional) カラーマップの正規化オブジェクト。

• marker -- (str, optional) マーカーのスタイル。デフォルトは'o' (円)。

• size -- (float, optional) マーカーのサイズ。デフォルトは0.5。

• alpha -- (float, optional) マーカーの透明度。デフォルトは1.0。

戻り値:

(matplotlib.collections.PathCollection) 作成された散布図コレクションオブジェクト。

tklib.tkgraphic.tkPlot3d.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サーフェスプロットを描画します。

詳細説明:

与えられたX, Y, Z座標データに基づいて、3Dの曲面または面プロットを描画します。 色、カラーマップ、エッジ色、透明度、シェーディングなどのオプションを設定できます。軸ラベルも設定されます。

パラメータ:

• ax -- (matplotlib.axes.Axes) プロットを描画する3D Axesオブジェクト。

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

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

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

• color -- (str or tuple, optional) サーフェスの単一色。`facecolors`または`cmap`と同時に指定すると上書きされる可能性あり。

• cmap -- (str or matplotlib.colors.Colormap, optional) サーフェスの色付けに使用するカラーマップ。

• facecolors -- (numpy.ndarray, optional) 各面の色を指定するRGBAカラー配列。

• edgecolor -- (str or tuple, optional) サーフェスのエッジの色。デフォルトは'black'。

• alpha -- (float, optional) サーフェスの透明度。0.0（完全透明）から1.0（完全不透明）の範囲。デフォルトは0.7。

• shade -- (bool, optional) 光源によるシェーディングを適用するかどうか。デフォルトはTrue。

• xlabel -- (str, optional) X軸のラベル。デフォルトは'X'。

• ylabel -- (str, optional) Y軸のラベル。デフォルトは'Y'。

• zlabel -- (str, optional) Z軸のラベル。デフォルトは'Z'。

戻り値:

(None)

tklib.tkgraphic.tkPlot3d.set_cubic_scale(ax, maxx)

概要: 3D軸のスケールを立方体状に設定します。

詳細説明:

3DプロットのX, Y, Z軸の表示範囲を、与えられた最大値に基づいて対称な立方体状に設定し、アスペクト比を1:1:1にします。

パラメータ:

• ax -- (matplotlib.axes.Axes) 対象となる3D Axesオブジェクト。

• maxx -- (float) 各軸の最大絶対値。[-maxx, maxx] の範囲に設定されます。

戻り値:

(None)

tklib.tkgraphic.tkPlot3d.set_light(x, azdeg=315, altdeg=45, cmap='viridis', vert_exag=0.1, blend_mode='soft')

概要: 3Dサーフェスプロットのシェーディングに光源効果を設定します。

詳細説明:

matplotlib.colors.LightSource を使用して、指定されたデータ x に対して光源の角度、 カラーマップ、垂直方向の強調、ブレンドモードを適用し、シェーディングされたRGB画像データを生成します。

パラメータ:

• x -- (numpy.ndarray) シェーディングの基となる2Dデータ（高さ情報など）。

• azdeg -- (float, optional) 光源の水平方向の角度（アジマス角）。デフォルトは315度。

• altdeg -- (float, optional) 光源の垂直方向の角度（高度角）。デフォルトは45度。

• cmap -- (str or matplotlib.colors.Colormap, optional) 使用するカラーマップ。デフォルトは"viridis"。

• vert_exag -- (float, optional) 垂直方向の強調係数。デフォルトは0.1。

• blend_mode -- (str, optional) ブレンドモード（'soft', 'hsv', 'overlay'など）。デフォルトは'soft'。

戻り値:

(numpy.ndarray) シェーディングが適用されたRGBカラーデータ。

tklib.tkgraphic.tkPlot3d.show_color_bar(fig, ax, scale, cmap, shrink=0.5, aspect=10.0)

概要: カラーバーを表示します。

詳細説明:

与えられたデータ scale とカラーマップ cmap に基づいてカラーバーを生成し、 指定されたFigureとAxesオブジェクトにアタッチします。

パラメータ:

• fig -- (matplotlib.figure.Figure) カラーバーを配置するFigureオブジェクト。

• ax -- (matplotlib.axes.Axes) カラーバーを関連付けるAxesオブジェクト。

• scale -- (numpy.ndarray) カラーマップの正規化に使用する数値データ。

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

• shrink -- (float, optional) カラーバーの表示サイズの縮小率。デフォルトは0.5。

• aspect -- (float, optional) カラーバーのアスペクト比。デフォルトは10.0。

戻り値:

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