tkPlot3d.py

ライブラリの機能や目的

このライブラリは、MatplotlibとNumPyを使用して3D空間におけるデータの可視化を容易にするためのユーティリティ関数群を提供するモジュールです。

主な機能として、一般的な3Dサーフェスプロットの描画、marching_cubes アルゴリズムを用いたボリュームデータからの等値面（アイソサーフェス）の抽出・描画、3D等高線プロット、散布図、そして2D平面への投影プロットなどが含まれます。

また、カスタムカラーマップの作成、3D軸のスケールやアスペクト比の統一設定、カラーバーの追加や光源効果（シェーディング）の設定など、プロットの視覚的な表現を整え、分析しやすくするための多彩な補助機能を備えており、3Dデータ表現に関する多様な課題を解決することを目的としています。

importする方法

このライブラリを他のプログラムから利用するには、通常のPythonモジュールと同様に import 文を使用します。パスが通っているディレクトリに本ファイルを配置したうえで、以下のようにインポートします。

# モジュール全体をインポートする場合
import tkPlot3d

# 特定の関数のみをインポートする場合
from tkPlot3d import plot_surface3d, plot_isosurface3d, make_cmap

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

本ライブラリは以下の非標準ライブラリに依存しています。

numpy
matplotlib
scikit-image (コード内の skimage として使用)

これらのライブラリがインストールされていない場合は、以下の pip コマンドを実行してインストールしてください。

pip install numpy matplotlib scikit-image

importできる変数と関数

本モジュールでは公開用の変数は定義されておらず、関数のみが提供されています。関数内に記述されたドキュメント（ソースコード中では3重引用符で囲まれています）に基づき、各関数の動作と引数・戻り値を説明します。

`get_max_xyz(x, y, z)`

動作: 与えられた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)`

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

引数:

ax (matplotlib.axes.Axes): 対象となる3D Axesオブジェクト。
maxx (float): 各軸の最大絶対値。[-maxx, maxx] の範囲に設定されます。

戻り値:

(None)

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

動作: 指定された色のリストからカスタムカラーマップを生成します。

引数:

colors (list): カラーマップを構成する色のリスト。
cmap_name (str, optional): カスタムカラーマップの名前。デフォルトは 'custom_cmap'。
nbins (int, optional): 線形補間を行う際のビン数。デフォルトは100。

戻り値:

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

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

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

引数:

x (numpy.ndarray): カラーマップを適用する数値データ。
colors (list): カラーマップを構成する色のリスト。
cmap_name (str, optional): カスタムカラーマップの名前。デフォルトは 'custom_cmap'。
nbins (int, optional): 線形補間を行う際のビン数。デフォルトは100。

戻り値:

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

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

動作: 入力データ x の最小値・最大値（または指定された値）で正規化し、カスタムカラーマップを適用して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色値の配列。

`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): カラーマップ正規化の最小値。
vmax (float, optional): カラーマップ正規化の最大値。
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): 作成されたカラーバーオブジェクト。

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

動作: 指定されたデータに対して光源効果を設定し、シェーディングされた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'。

戻り値:

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

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

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

引数:

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): 作成されたカラーバーオブジェクト。

`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')`

動作: X, Y, Z座標データに基づいて、3Dの曲面プロットを描画します。色、透明度、シェーディングなどのオプションが適用可能です。

引数:

ax (matplotlib.axes.Axes): プロットを描画する3D Axesオブジェクト。
X, Y, Z (numpy.ndarray): 各軸の座標データ。
color (str or tuple, optional): サーフェスの単一色。
cmap (str or matplotlib.colors.Colormap, optional): サーフェスの色付けに使用するカラーマップ。
facecolors (numpy.ndarray, optional): 各面の色を指定するRGBAカラー配列。
edgecolor (str or tuple, optional): エッジの色。デフォルトは'black'。
alpha (float, optional): 透明度。デフォルトは0.7。
shade (bool, optional): シェーディングの有無。デフォルトはTrue。
xlabel, ylabel, zlabel (str, optional): 各軸のラベル。

戻り値:

(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)`

動作: 3Dボリュームデータから指定されたレベルの等値面を抽出し、描画します。

引数:

ax (matplotlib.axes.Axes): 描画する3D Axesオブジェクト。
X, Y, Z (numpy.ndarray): 軸範囲設定用グリッドデータ。
F (numpy.ndarray): 等値面を抽出する3Dボリュームデータ。
levels (list or float): 描画する等値面のレベル。
origin (tuple): 原点座標。
spacing (tuple): サンプル間隔。
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): カスタムカラーマップのビン数。
cmap_name (str, optional): カスタムカラーマップの名前。
minx, maxx など (float, optional): 各軸の範囲設定用パラメータ。

戻り値:

(None)

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

動作: 指定された2次元データの3D等高線プロットを描画します。

引数:

ax (matplotlib.axes.Axes): 3D Axesオブジェクト。
X, Y (numpy.ndarray): XおよびY座標データ。
F (numpy.ndarray): 等高線を描画する2Dデータ。
nbins (int, optional): 等高線の数。デフォルトは50。
cmap (str or matplotlib.colors.Colormap, optional): カラーマップ。デフォルトは"viridis"。
xlabel, ylabel, zlabel (str, optional): 各軸のラベル。

戻り値:

(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散布図を描画します。

引数:

ax (matplotlib.axes.Axes): 3D Axesオブジェクト。
x, y, z (numpy.ndarray): 座標データ。
minx, maxx など (float): 各軸の描画範囲。
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): 散布図コレクションオブジェクト。

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

動作: 指定されたデータに基づいて、X-Y平面に平行な高さに2D等高線プロットを投影・描画します。

引数:

ax (matplotlib.axes.Axes): 3D Axesオブジェクト。
x, y (numpy.ndarray): 座標データ。
offsetz (float): 配置するZ軸のオフセット値。
f (numpy.ndarray): 2Dデータ。
cmap (str or matplotlib.colors.Colormap): カラーマップ。
levels (int or list): 等高線の数やレベル。
alpha (float): 透明度。

戻り値:

(None)

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

動作: Y-Z平面に平行な位置に2D等高線プロットを投影・描画します。引数と戻り値はXY版に準じます。

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

動作: Z-X平面に平行な位置に2D等高線プロットを投影・描画します。引数と戻り値はXY版に準じます。

`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等高線塗りつぶしプロットを描画します。

引数:

ax (matplotlib.axes.Axes): 3D Axesオブジェクト。
func (callable): (x, y, z) を引数にとりスカラー値を返す関数。
minx, maxx (float): 座標範囲。
nmesh (int, optional): メッシュの点数。デフォルトは100。
posx, posy, posz (float, optional): 各平面プロット用の固定座標位置。
offsetx, offsety, offsetz (float, optional): 各平面プロットのオフセット位置。
cmap (str or matplotlib.colors.Colormap, optional): カラーマップ。
levels (int or list, optional): 等高線のレベル設定。デフォルトは20。
alpha (float, optional): 透明度。デフォルトは0.3。

戻り値:

(None)

`main()`

動作: トーラスを3Dでプロットするデモンストレーションを実行します。パラメトリック方程式を用いて座標を生成し、カスタムカラーマップを適用して画像として保存および表示を行います。

引数: なし

戻り値: (None)

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

本ファイルをメインスクリプトとして直接実行した場合（python tkPlot3d.py）、デモンストレーション用の main() 関数が呼び出されます。

実行されると、以下のパラメトリック方程式を用いてトーラス（ドーナツ形状）のX, Y, Z座標が生成されます。

\[X = (R + r \cos(\theta)) \cos(\phi)\]

\[Y = (R + r \cos(\theta)) \sin(\phi)\]

\[Z = r \sin(\theta)\]

生成された3Dデータには、薄い赤、青、薄い赤というグラデーションを持つ独自のカラーマップが適用され、plot_surface3d 関数によって3Dサーフェスプロットが描画されます。

最終的に描画されたプロットは、カレントディレクトリに torus.png という画像ファイルとして保存されると同時に、画面上に可視化ウィンドウとして表示されます。

D:/git/sphinx/tkProg/source/Quantum/tkPlot3d.py

ライブラリの機能や目的

importする方法

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

importできる変数と関数

get_max_xyz(x, y, z)

set_cubic_scale(ax, maxx)

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

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

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

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

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

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

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')

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)

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

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)

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

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

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

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)

main()

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

`get_max_xyz(x, y, z)`

`set_cubic_scale(ax, maxx)`

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

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

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

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

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

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

`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')`

`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)`

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

`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)`

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

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

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

`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)`

`main()`