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

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

tkplotevent.py は、matplotlib を使用して作成されたグラフに、インタラクティブなイベント処理機能を追加するためのPythonライブラリです。tkinter と連携してGUIアプリケーション内で matplotlib プロットを扱う際に、高度なユーザーインタラクション（マウス操作によるデータ選択、情報表示、範囲選択、オブジェクトの移動など）を容易に実装できるように設計されています。

このライブラリの主な機能は以下の通りです。

データポイントのインタラクティブな選択: マウスクリックにより、プロット上の最も近いデータポイントを特定し、その詳細情報をコンソールに表示します。
範囲選択機能 (RangeSelector): マウスドラッグにより、X軸またはY軸、あるいはその両方にわたる選択範囲を視覚的に指定し、その範囲の座標値を取得できます。
動的なアノテーション (mplcursors 連携): マウスカーソルをデータポイントに合わせると、そのデータに関する詳細情報がポップアップ表示される機能を提供します。
オブジェクトの移動: プロット上の特定のテキストアノテーションやデータポイントをマウスでドラッグして移動させることができます。
マウスカーソル追従表示: マウスカーソルの位置にクロスヘアライン（十字線）を表示し、X/Y軸上の現在位置を視覚的に示します。
カスタマイズ可能なポップアップメニュー: 右クリック時に表示されるコンテキストメニューを定義し、ユーザーが特定の操作を実行できるようにします。
ストップボタンの追加: プロットウィンドウに「停止」ボタンを追加し、長期実行されるプロセスをユーザーが中断できるようにします。

このライブラリは、科学技術計算やデータ分析の分野で、ユーザーがグラフから直接情報を取得したり、グラフの表示を操作したりする必要があるインタラクティブなデータ可視化ツールを開発する際に特に有用です。

importする方法

tkplotevent.py ライブラリを他のPythonプログラムからインポートするには、以下のステートメントを使用します。

from tkplotevent import tkPlotEvent, RangeSelector

または、すべての公開オブジェクトをインポートする場合は、以下のようにすることもできます。

import tkplotevent

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

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

numpy: 数値計算を効率的に行うためのライブラリ。
pandas: データ構造とデータ分析ツールを提供するライブラリ。
matplotlib: プロットとグラフ作成のためのライブラリ。
mplcursors: matplotlib のプロットにインタラクティブなデータカーソルとアノテーション機能を追加するライブラリ。

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

pip install numpy pandas matplotlib mplcursors

tklib について: tkplotevent.py は、tklib.tkimport, tklib.tkobject, tklib.tkparams といったモジュールをインポートしています。これらは標準ライブラリではないため、tkplotevent.py が動作するためには、tklib というカスタムライブラリが別途インストールまたはPythonの環境パス上に配置されている必要があります。tklib は、matplotlib と tkinter を組み合わせたGUIアプリケーション開発を支援するためのユーティリティ（ライブラリのインポート管理、基本的なオブジェクト、パラメータ管理など）を提供していると推測されます。tklib のインストール方法は、その配布方法に依存します。

importできる変数と関数

このライブラリからインポートできる主要なクラスとそのメソッドについて説明します。

クラス

`RangeSelector` クラス

プロット上でマウスドラッグによる範囲選択を可能にするクラスです。X軸、Y軸、または両方の範囲を選択できます。

コンストラクタ: __init__(self, mode = 'x', axis = None, color = 'red', linestyle = 'dashed', linewidth = 0.5, print_level = 1) 特定の matplotlib 軸に対して範囲選択機能を初期化します。

引数:
- mode (str, optional): 選択モードを指定します。「'x'」はX軸のみ、「'y'」はY軸のみ、「'xy'」は両軸を選択します。デフォルトは 'x'。
- axis (matplotlib.axes.Axes, optional): 範囲選択を行う対象の matplotlib 軸オブジェクト。デフォルトは None。
- color (str, optional): 選択範囲を示す線の色。デフォルトは 'red'。
- linestyle (str, optional): 選択範囲を示す線のスタイル。デフォルトは 'dashed'。
- linewidth (float, optional): 選択範囲を示す線の太さ。デフォルトは 0.5。
- print_level (int, optional): 選択範囲の情報をコンソールに出力するかどうか。1 で出力、0 で非出力。デフォルトは 1。
戻り値: なし

メソッド:

set_mode(self, mode) 選択モードを設定または変更します。
- 引数:
  - mode (str): 新しい選択モード（'x', 'y', 'xy'）。
- 戻り値: なし
on_press(self, event) マウスボタンが押されたときのイベントハンドラ。選択開始位置を記録し、仮の選択線を表示します。
- 引数:
  - event (matplotlib.backend_bases.MouseEvent): マウスイベントオブジェクト。
- 戻り値: なし
on_mouse_move(self, event) マウスが移動したときのイベントハンドラ。選択中の範囲をリアルタイムで更新し、表示します。
- 引数:
  - event (matplotlib.backend_bases.MouseEvent): マウスイベントオブジェクト。
- 戻り値: なし
on_release(self, event) マウスボタンが離されたときのイベントハンドラ。選択範囲を確定します。
- 引数:
  - event (matplotlib.backend_bases.MouseEvent): マウスイベントオブジェクト。
- 戻り値: なし
finalize(self) 選択範囲を確定し、コンソールに表示します。on_release から呼び出されます。
- 引数: なし
- 戻り値: なし

`tkPlotEvent` クラス

matplotlib のプロットに様々なインタラクティブイベント処理を追加するための中心的なクラスです。tklib.tkobject.tkObject を継承しています。

コンストラクタ: __init__(self, plt, distance = 'r', **args) イベントハンドラ機能を初期化します。

引数:
- plt (matplotlib.pyplot または Figure オブジェクト): matplotlib.pyplot モジュール、または Figure オブジェクト。
- distance (str, optional): 最近接データを検索する際の距離の測り方を指定します。
  - 'r': 半径方向 (Euclidean distance)
  - 'x': X方向のみ
  - 'y': Y方向のみデフォルトは 'r'。
- **args: tklib.tkobject.tkObject のコンストラクタに渡される追加引数。
戻り値: なし