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

ライブラリの機能や目的

tkopengl.py は、PythonのPyOpenGLとGLUTライブラリを利用して3Dグラフィックスの描画を簡素化するためのユーティリティライブラリです。主に以下の機能を提供します。

• 基本的な3Dプリミティブの描画: テキスト、球体、円柱、矢印といった一般的な3Dオブジェクトを、指定した位置、色、サイズ、透明度で簡単に描画する関数を提供します。

• OpenGLウィンドウ管理: PyOpenGLおよびGLUTを用いた3D描画のためのウィンドウの初期化、ビューポート設定、プロジェクション（透視投影）設定を行います。

• インタラクティブな視点操作: マウスのドラッグによるシーンの回転、キーボードによる拡大縮小や移動といった基本的なカメラ操作をサポートし、ユーザーが3Dシーンを自由に探索できるようにします。

• ライティングとマテリアルの設定: シーンにリアリティを与えるための光源（GL_LIGHT0）と、オブジェクトのマテリアル特性（環境光、拡散反射、鏡面反射、輝き）を初期設定します。

• 解決する課題: OpenGLの低レベルなAPIを直接操作することなく、より高レベルな関数やクラスを通じて3Dシーンを構築・操作できる環境を提供します。特に、分子構造や結晶構造のような科学的な3Dモデルを素早く可視化し、インタラクティブに操作したい場合に有用です。

importする方法

tkopengl.py ライブラリを他のPythonプログラムから利用するには、以下の方法でimportします。

import tkopengl

または、特定の関数やクラスのみをimportすることも可能です。

from tkopengl import tkOpenGL, draw_sphere

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

tkopengl.py は、いくつかの非標準ライブラリに依存しています。これらは pip コマンドを使用してインストールできます。

• numpy: 数値計算、特にベクトル演算に使用されます。

  pip install numpy
  

• PyOpenGL: PythonからOpenGL APIを呼び出すためのバインディングです。

• PyOpenGL_accelerate: PyOpenGLの高速化のために推奨されます。

  pip install PyOpenGL PyOpenGL_accelerate
  

• Pillow (PIL): tkOpenGL クラスの save_image メソッドで使用されますが、tkopengl.py ソースコード内で明示的に PIL または Image のimport文がありません。save_image 機能を利用する場合は、別途インストールが必要です。

  pip install Pillow
  

importできる変数と関数

tkopengl.py ライブラリからは、以下の関数とクラスをimportして使用できます。このライブラリには、直接importできるモジュールレベルの変数は定義されていません。

グローバル関数

draw_text(text, x, y, z, sx, sy, sz, R=0.5, G=0.5, B=0.5)

• 動作: 指定された3D座標にビットマップテキストを描画します。テキストの色とスケールを設定できます。

• 引数:

  • text (str): 描画する文字列。

  • x, y, z (float): テキストの描画開始位置のワールド座標。

  • sx, sy, sz (float): テキストの拡大縮小率。

  • R, G, B (float, オプション): テキストの色（赤、緑、青成分、\(0.0\)から\(1.0\)）。デフォルトは(0.5, 0.5, 0.5)（グレー）。

• 戻り値: なし

draw_sphere(x, y, z, radius, R=1.0, G=0.0, B=0.0, alpha=1.0, slices=10, stacks=10)

• 動作: 指定された3D座標に球体を描画します。色、透明度、および球体の解像度を設定できます。マテリアル設定を使用して色を適用します。

• 引数:

  • x, y, z (float): 球体の中心のワールド座標。

  • radius (float): 球体の半径。

  • R, G, B (float, オプション): 球体の色（赤、緑、青成分、\(0.0\)から\(1.0\)）。デフォルトは(1.0, 0.0, 0.0)（赤）。

  • alpha (float, オプション): 球体の透明度（\(0.0\)から\(1.0\)）。デフォルトは\(1.0\)（不透明）。

  • slices (int, オプション): 球体を構成する経度方向の分割数。デフォルトは\(10\)。

  • stacks (int, オプション): 球体を構成する緯度方向の分割数。デフォルトは\(10\)。

• 戻り値: なし

draw_cylinder(x0, y0, z0, x1, y1, z1, radius=0.1, R=0.5, G=0.5, B=0.5, alpha=1.0, slices=10, stacks=10)

• 動作: 2点間を結ぶ円柱を描画します。色、透明度、半径、および円柱の解像度を設定できます。マテリアル設定を使用して色を適用します。

• 引数:

  • x0, y0, z0 (float): 円柱の開始点のワールド座標。

  • x1, y1, z1 (float): 円柱の終了点のワールド座標。

  • radius (float, オプション): 円柱の半径。デフォルトは\(0.1\)。

  • R, G, B (float, オプション): 円柱の色（赤、緑、青成分、\(0.0\)から\(1.0\)）。デフォルトは(0.5, 0.5, 0.5)（グレー）。

  • alpha (float, オプション): 円柱の透明度（\(0.0\)から\(1.0\)）。デフォルトは\(1.0\)（不透明）。

  • slices (int, オプション): 円柱を構成する円周方向の分割数。デフォルトは\(10\)。

  • stacks (int, オプション): 円柱を構成する高さ方向の分割数。デフォルトは\(10\)。

• 戻り値: なし

draw_arrow(x0, y0, z0, x1, y1, z1, radius=0.1, arrow_h=0.2, arrow_r=0.2, R=1.0, G=0.0, B=0.0, alpha=0.5, slices=10, stacks=10)

• 動作: 2点間を結ぶ矢印を描画します。円柱部分と円錐部分で構成されます。色、透明度、半径、矢頭のサイズ、および解像度を設定できます。マテリアル設定を使用して色を適用します。

• 引数:

  • x0, y0, z0 (float): 矢印の開始点のワールド座標。

  • x1, y1, z1 (float): 矢印の終了点のワールド座標。

  • radius (float, オプション): 矢印の軸部分（円柱）の半径。デフォルトは\(0.1\)。

  • arrow_h (float, オプション): 矢頭（円錐）の高さ。デフォルトは\(0.2\)。

  • arrow_r (float, オプション): 矢頭（円錐）の底面の半径。デフォルトは\(0.2\)。

  • R, G, B (float, オプション): 矢印の色（赤、緑、青成分、\(0.0\)から\(1.0\)）。デフォルトは(1.0, 0.0, 0.0)（赤）。

  • alpha (float, オプション): 矢印の透明度（\(0.0\)から\(1.0\)）。デフォルトは\(0.5\)。

  • slices (int, オプション): 矢印の円周方向の分割数。デフォルトは\(10\)。

  • stacks (int, オプション): 矢印の高さ方向の分割数。デフォルトは\(10\)。

• 戻り値: なし

クラス

class tkOpenGL

• 動作: OpenGLウィンドウの管理、初期化、マウス・キーボードによる視点操作、オブジェクト描画のための基本設定を提供します。

• __init__(self, app=None, center=[0, 0, 0], fcenter=[0.0, 0.0, 0.0], title=b"Crystal Structure", window_w=800, window_h=600, color_bg=[1.0, 1.0, 1.0, 1.0], nslices=32, nstacks=32, debug=False)

  • 動作: tkOpenGL クラスのインスタンスを初期化します。ウィンドウサイズ、背景色、中心点、デバッグモードなどを設定します。

  • 引数:

    • app (Any, オプション): アプリケーションインスタンス。現状は内部で使われていません。

    • center (list of float, オプション): シーンの中心座標。視点設定の基準となる。デフォルトは[0, 0, 0]。

    • fcenter (list of float, オプション): 浮動小数点形式のシーンの中心座標。現状は内部で使われていません。デフォルトは[0.0, 0.0, 0.0]。

    • title (bytes, オプション): ウィンドウのタイトル。デフォルトはb"Crystal Structure"。

    • window_w (int, オプション): ウィンドウの幅（ピクセル）。デフォルトは\(800\)。

    • window_h (int, オプション): ウィンドウの高さ（ピクセル）。デフォルトは\(600\)。

    • color_bg (list of float, オプション): 背景色（RGBA、\(0.0\)から\(1.0\)）。デフォルトは[1.0, 1.0, 1.0, 1.0]（白）。

    • nslices (int, オプション): 球体や円柱の分割数に関する設定と思われますが、現状は内部で使われていません。デフォルトは\(32\)。

    • nstacks (int, オプション): 球体や円柱の分割数に関する設定と思われますが、現状は内部で使われていません。デフォルトは\(32\)。

    • debug (bool, オプション): デバッグモードを有効にするか。Trueの場合、マウスやキーボードのイベント時に情報がコンソールに出力されます。デフォルトはFalse。

  • 戻り値: なし

• init_canvas(self, color_bg=None, title=None)

  • 動作: OpenGLコンテキストとGLUTウィンドウを初期化し、基本的なグラフィック設定（背景色、ブレンド、デプステスト、ライティング）を行います。

  • 引数:

    • color_bg (list of float, オプション): 背景色（RGBA）。指定しない場合はインスタンスのself.color_bgを使用。

    • title (bytes, オプション): ウィンドウのタイトル。指定しない場合はインスタンスのself.titleを使用。

  • 戻り値: なし

• save_image(self, filename, width, height)

  • 動作: 現在のOpenGLバッファの内容を画像ファイルとして保存します。このメソッドを使用するにはPillowライブラリが必要です。

  • 引数:

    • filename (str): 保存するファイル名（例: "output.png"）。

    • width (int): 保存する画像の幅。

    • height (int): 保存する画像の高さ。

  • 戻り値: なし

• camera_distance(self, W, D, H, fov_y)

  • 動作: 指定されたワールドの寸法と垂直視野角に基づいて、カメラがオブジェクト全体をフレームに収めるために必要な距離を計算します。

  • 引数:

    • W (float): シーンの幅。

    • D (float): シーンの奥行き。

    • H (float): シーンの高さ。

    • fov_y (float): 垂直方向の視野角（度）。

  • 戻り値: float - カメラとシーンの中心間の距離。

• init_projection(self, width, height)

  • 動作: プロジェクション行列を設定し、ビューポートとカメラの初期位置を定義します。ライティングのための光源位置も設定します。

  • 引数:

    • width (int): ウィンドウの幅。

    • height (int): ウィンドウの高さ。

  • 戻り値: なし

• reshape(self, w, h)

  • 動作: ウィンドウサイズが変更されたときに呼び出されるコールバック関数。ビューポートとプロジェクションを再設定します。

  • 引数:

    • w (int): 新しいウィンドウの幅。

    • h (int): 新しいウィンドウの高さ。

  • 戻り値: なし

• mouse(self, button, state, x, y)

  • 動作: マウスイベント（ボタンのクリックや離す）が発生したときに呼び出されるコールバック関数。左クリックの状態を追跡し、マウスドラッグによる回転の基準点を設定します。

  • 引数:

    • button (int): 押された/離されたマウスボタン（例: GLUT_LEFT_BUTTON）。

    • state (int): ボタンの状態（GLUT_DOWNまたはGLUT_UP）。

    • x, y (int): マウスカーソルのスクリーン座標。

  • 戻り値: なし

• motion(self, x, y)

  • 動作: マウスがドラッグされたときに呼び出されるコールバック関数。マウスの動きに応じてシーンの回転角度（angle_x, angle_z）を更新し、再描画を要求します。

  • 引数:

    • x, y (int): マウスカーソルのスクリーン座標。

  • 戻り値: なし

• keyboard(self, key, x, y)

  • 動作: キーボードのキーが押されたときに呼び出されるコールバック関数。特定のキー入力に応じて、シーンのスケール（scale）や位置（model_x, model_y, model_z）を調整し、再描画を要求します。

    • u/U: 拡大

    • d/D: 縮小

    • h/H: X軸方向へ移動（左）

    • l/L: X軸方向へ移動（右）

    • j/J: Z軸方向へ移動（奥）

    • k/K: Z軸方向へ移動（手前）

    • </, : Y軸方向へ移動（下）

    • >/. : Y軸方向へ移動（上）

  • 引数:

    • key (bytes): 押されたキーのASCII値（バイト形式）。

    • x, y (int): キーが押されたときのマウスカーソルのスクリーン座標。

  • 戻り値: なし

• key_pressed(key, x, y)

  • 動作: スペースキーが押されたときにアニメーションの実行状態（animation_running）を切り替えるコールバック関数。注意: このメソッドはselfを引数に取っておらず、現状ではインスタンスメソッドとして正しく機能しません。

  • 引数:

    • key (bytes): 押されたキーのASCII値（バイト形式）。

    • x, y (int): キーが押されたときのマウスカーソルのスクリーン座標。

  • 戻り値: なし

• start_animation()

  • 動作: アニメーションを明示的に開始します。self.animation_runningをTrueに設定します。注意: このメソッドはselfを引数に取っておらず、現状ではインスタンスメソッドとして正しく機能しません。

  • 引数: なし

  • 戻り値: なし

• stop_animation(self)

  • 動作: アニメーションを停止します。self.animation_runningをFalseに設定します。

  • 引数: なし

  • 戻り値: なし

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

tkopengl.py は if __name__ == "__main__": ブロックを含んでいないため、このスクリプトを直接実行しても、特定のデモンストレーションやテストコードは実行されません。ライブラリとして他のプログラムからimportされて利用されることを想定しています。