tkplotevent プログラム仕様

概要: Matplotlibのプロットイベントを処理し、インタラクティブな機能を提供するユーティリティモジュール。 詳細説明:

本モジュールは、TkinterとMatplotlibを連携させ、プロット上で様々なインタラクティブ操作を可能にするための クラスとメソッドを提供します。具体的には、以下の機能を含みます。 - プロット上での範囲選択 (RangeSelector) - データ点のクリックイベント処理と情報表示 - ポップアップメニューの表示 - プロット上のテキストやマーカーのドラッグ移動 - マウスカーソルに追従する補助線やマーカー - mplcursorsによるデータアノテーション これにより、ユーザーはより直感的にMatplotlibのグラフと対話できるようになります。

関連リンク: tkplotevent_usage

class tklib.tkgraphic.tkplotevent.RangeSelector(mode='x', axis=None, color='red', linestyle='dashed', linewidth=0.5, print_level=1)

ベースクラス: object

概要: Matplotlibのプロット上で範囲選択を可能にするクラス。 詳細説明:

マウスドラッグによりX軸またはY軸、あるいは両方の範囲を視覚的に選択し、その選択範囲をコンソールに出力します。 選択された範囲は、指定されたスタイル（色、線種、線幅）の補助線で表示されます。

finalize()

概要: 範囲選択操作を確定する。 詳細説明:

最終的な選択範囲の終点を補助線に設定し、print_levelが0より大きい場合は、 選択されたX軸またはY軸の範囲をコンソールに出力します。 その後、キャンバスを再描画し、movingフラグをFalseにリセットします。

on_mouse_move(event)

概要: マウスが移動したときのイベントハンドラ。 詳細説明:

範囲選択が進行中の場合、マウスの位置に応じて選択範囲の終点を更新します。 対応する補助線（X軸用またはY軸用）をリアルタイムで描画し、キャンバスを再描画します。

引数:

param event:

matplotlib.backend_bases.MouseEvent, Matplotlibのマウスイベントオブジェクト。

type event:

matplotlib.backend_bases.MouseEvent

on_press(event)

概要: マウスのボタンが押されたときのイベントハンドラ。 詳細説明:

イベントが左クリックで、かつ現在のAxes内で発生した場合に、選択開始点を記録します。 その後、対応する補助線（X軸用またはY軸用）を表示し、キャンバスを再描画します。

引数:

param event:

matplotlib.backend_bases.MouseEvent, Matplotlibのマウスイベントオブジェクト。

type event:

matplotlib.backend_bases.MouseEvent

on_release(event)

概要: マウスのボタンが離されたときのイベントハンドラ。 詳細説明:

範囲選択が進行中の場合、マウスが離された位置を最終的な選択範囲の終点として記録します。 その後、finalizeメソッドを呼び出して選択操作を確定します。

引数:

param event:

matplotlib.backend_bases.MouseEvent, Matplotlibのマウスイベントオブジェクト。

type event:

matplotlib.backend_bases.MouseEvent

set_mode(mode)

概要: 選択モード（X軸、Y軸、または両方）を設定する。 詳細説明:

内部フラグ (mode_x, mode_y) を更新し、表示される補助線 (vline0, vline1, hline0, hline1) の可視性を制御します。 補助線が存在しない場合は、ここで初期化されます。

引数:

param mode:

str, 選択する軸を指定 ('x', 'y', 'xy' のいずれか)。

type mode:

str

class tklib.tkgraphic.tkplotevent.tkPlotEvent(plt, distance='r', **args)

ベースクラス: tkObject

概要: Matplotlibのプロットイベントを処理し、インタラクティブな機能を提供するユーティリティクラス。 詳細説明:

本クラスは、データ点のクリックイベント処理、ポップアップメニュー、移動可能なテキスト/点の管理、 マウス追従カーソル、データアノテーションなど、Matplotlibのプロットをよりインタラクティブにするための 多岐にわたる機能を提供します。tklib.tkobject.tkObjectを継承し、パラメータ管理も行います。

add_button(button_region=[0.15, 0.95, 0.1, 0.03], plot_region=[0.92, 0.15], text='stop', color='#f8e58c', hovercolor='#38b48b', callback=None)

概要: MatplotlibのFigureにボタンを追加する。 詳細説明:

指定された領域にボタンを作成し、クリックされたときのコールバック関数を設定します。 プロット領域を調整し、ボタンが重ならないように配置します。

引数:

param button_region:

list, ボタンを配置するAxesの領域を[left, bottom, width, height]の形式で指定。単位はFigureの割合。

type button_region:

list

param plot_region:

list, ボタン追加後のプロット領域調整のための領域を[top, bottom]の形式で指定。単位はFigureの割合。

type plot_region:

list

param text:

str, ボタンに表示するテキスト。

type text:

str

param color:

str, ボタンの背景色 (CSSカラー名またはHEXコード)。

type color:

str

param hovercolor:

str, マウスオーバー時のボタンの背景色。

type hovercolor:

str

param callback:

callable, ボタンがクリックされたときに呼び出される関数。指定しない場合はbutton_clickが使われる。

type callback:

callable

戻り値:

returns:

matplotlib.widgets.Button, 作成されたMatplotlibのButtonオブジェクト。

rtype:

matplotlib.widgets.Button

add_data(axis_inf={})

概要: プロットデータをイベント処理用に登録する。 詳細説明:

与えられたデータ情報（axis_inf辞書）を内部リストself.axis_infに追加します。 プロットタイプ（'2D', 'plot', 'scatter'）に応じてデータ構造を統一し、 X軸/Y軸のラベル情報も Axes オブジェクトから取得または設定します。 無効なplot_typeが指定された場合はエラーメッセージを出力し終了します。

引数:

param axis_inf:

dict, プロットに関する情報を含む辞書。必須キー: 'plot_type', 'axis', 'data'。 オプションキー: 'xlabel', 'ylabel', 'x', 'y' (plot_type='scatter'の場合)。

type axis_inf:

dict

戻り値:

returns:

dict, 登録されたaxis_inf辞書。

rtype:

dict

add_stop_button(button_region=[0.15, 0.95, 0.1, 0.03], plot_region=[0.92, 0.15], label='stop', color='#f8e58c', hovercolor='#38b48b', on_stop_clicked=None)

概要: プロットに停止ボタンを追加する。 詳細説明:

ユーザーが処理を中断できるように、指定された領域にボタンを配置します。 ボタンは自身の状態を持ち、テキストを変更する機能も持ちます。 tkStopButtonクラスのインスタンスがself.stop_buttonに格納されます。

引数:

param button_region:

list, ボタンを配置するAxesの領域を[left, bottom, width, height]の形式で指定。単位はFigureの割合。

type button_region:

list

param plot_region:

list, ボタン追加後のプロット領域調整のための領域を[top, bottom]の形式で指定。単位はFigureの割合。

type plot_region:

list

param label:

str, ボタンに表示するテキスト。

type label:

str

param color:

str, ボタンの背景色。

type color:

str

param hovercolor:

str, マウスオーバー時のボタンの背景色。

type hovercolor:

str

param on_stop_clicked:

callable, ボタンがクリックされたときに呼び出されるカスタムコールバック関数。指定しない場合はデフォルトのon_clickが使われる。

type on_stop_clicked:

callable

button_click(e)

概要: ボタンクリックイベントのデフォルトハンドラ。 詳細説明:

stop_flagをTrueに設定し、外部のループなどの処理を停止させることを意図します。

引数:

param e:

matplotlib.backend_bases.MouseEvent, イベントオブジェクト。

type e:

matplotlib.backend_bases.MouseEvent

convert_coord(x0, y0, axis_s, axis_t)

概要: あるAxes座標から別のAxes座標へ点を変換する。 詳細説明:

異なるスケールや範囲を持つAxes間で点の位置を相対的に変換する際に使用されます。 例えば、twinx()やtwiny()で作成されたAxes間で座標を変換する場合に有用です。

引数:

param x0:

float, 変換元のX座標。

type x0:

float

param y0:

float, 変換元のY座標。

type y0:

float

param axis_s:

matplotlib.axes.Axes, 変換元のAxesオブジェクト。

type axis_s:

matplotlib.axes.Axes

param axis_t:

matplotlib.axes.Axes, 変換先のAxesオブジェクト。

type axis_t:

matplotlib.axes.Axes

戻り値:

returns:

tuple: (float, float), 変換後の(x1, y1)座標。 tuple: (None, None), 入力が無効な場合。

rtype:

tuple

display_data(iinf, idata, idx, hit_axisinf=None)

概要: 指定されたデータ点の情報をコンソールに表示する。 詳細説明:

find_nearest_dataによって見つかったデータ点の詳細（ラベル、座標、関連情報など）を整形し、 コンソールに出力します。xlistやxlabelsが存在する場合、追加のデータ属性も表示します。

引数:

param iinf:

int, 検出されたデータが属するself.axis_infリストのインデックス。

type iinf:

int

param idata:

int, 検出されたデータが属するdataリストのインデックス。

type idata:

int

param idx:

int, 検出されたデータ点そのもののインデックス。

type idx:

int

param hit_axisinf:

dict, 検出されたデータ点を含むaxis_inf辞書（オプション）。指定しない場合はself.axis_inf[iinf]が使用される。

type hit_axisinf:

dict or None

finalize_button(text='finished')

概要: 停止ボタンのテキストを更新する。 詳細説明:

主に処理完了後にボタンの表示を変更するために使用されます。 このメソッドが呼び出される前に、add_buttonまたはadd_stop_buttonでボタンが追加されている必要があります。

引数:

param text:

str, ボタンに表示する新しいテキスト。

type text:

str

find_nearest_data(x, y, itarget_list, hit_axisinf_list)

概要: 指定された座標に最も近いデータ点を見つける。 詳細説明:

複数のAxesとデータセットの中から、マウスクリック位置に最も近いデータ点を特定します。 距離計算は、self.distance ('r': 半径, 'x': X軸方向, 'y': Y軸方向) に基づいて行われます。 twinx/yなどで異なるスケールのAxesがある場合でも、座標変換を考慮して正しい距離を計算します。

引数:

param x:

float, マウスクリックのX座標 (イベント発生Axesの座標系)。

type x:

float

param y:

float, マウスクリックのY座標 (イベント発生Axesの座標系)。

type y:

float

param itarget_list:

list, 検索対象のself.axis_inf内のAxesのインデックスリスト。

type itarget_list:

list

param hit_axisinf_list:

list, 検索対象のAxes情報辞書 (axis_inf) のリスト。

type hit_axisinf_list:

list

戻り値:

returns:

tuple: (iinf_hit, idata_hit, ihit, minr2) - iinf_hit: int, 検出されたデータが属する self.axis_infリストのインデックス。idata_hit: int, 検出されたデータが属するdataリストの インデックス。ihit: int, 検出されたデータ点そのもののインデックス。minr2: float, 最小距離の二乗。 tuple: (None, None, None, None), 検出可能なデータ点が見つからない場合。

rtype:

tuple

find_target_axes(event, axes=None)

概要: マウスクリックイベントが発生したAxesオブジェクトを特定する。 詳細説明:

イベントのinaxesプロパティと登録されたAxesオブジェクトを比較し、 イベントが発生したAxesとそのインデックス（またはaxis_inf辞書）を返します。 axes引数が指定された場合はそのリストから検索し、指定されない場合は内部のself.axis_infから検索します。

引数:

param event:

matplotlib.backend_bases.MouseEvent, Matplotlibのマウスイベントオブジェクト。

type event:

matplotlib.backend_bases.MouseEvent

param axes:

list, 検索対象となるAxesオブジェクトのリスト（オプション）。指定しない場合は内部のself.axis_infを使用。

type axes:

list or None

戻り値:

returns:

tuple: (itargets, hit_axisinfs) - itargets: list or int, ターゲットAxesのインデックスのリスト、 または単一のインデックス。hit_axisinfs: list or matplotlib.axes.Axes, ターゲットAxes情報 （axis_inf辞書）のリスト、または単一のAxesオブジェクト。tuple: (None, None), ターゲットAxesが見つからない場合。

rtype:

tuple

layout(show=False)

概要: プロットのレイアウトを調整する。 詳細説明:

plt.subplots_adjustを使用して、add_buttonなどで設定されたplot_regionに基づきプロット領域を調整します。 showがTrueの場合、プロットを表示または一時停止します。

引数:

param show:

bool, Trueの場合、プロットを表示または一時停止する。

type show:

bool

onclick(event)

概要: マウスクリックイベントのデフォルトハンドラ。 詳細説明:

クリックされた位置に最も近いデータ点を見つけ、その情報をコンソールに表示します。 find_target_axesとfind_nearest_dataを使用してデータ点を特定し、 display_dataで情報を整形して出力します。

引数:

param event:

matplotlib.backend_bases.MouseEvent, Matplotlibのマウスイベントオブジェクト。

type event:

matplotlib.backend_bases.MouseEvent

ondraw(event)

概要: 再描画イベントのデフォルトハンドラ。 詳細説明:

プロットが再描画されたときにメッセージを出力します。

引数:

param event:

matplotlib.backend_bases.DrawEvent, Matplotlibの描画イベントオブジェクト。

type event:

matplotlib.backend_bases.DrawEvent

onkey(event)

概要: キーボードプレスイベントのデフォルトハンドラ。 詳細説明:

'q'キーが押されたときに、関連するFigureを閉じます。

引数:

param event:

matplotlib.backend_bases.KeyEvent, Matplotlibのキーイベントオブジェクト。

type event:

matplotlib.backend_bases.KeyEvent

onpick(event)

概要: ピックイベントのデフォルトハンドラ。 詳細説明:

クリックされたアーティスト（線、テキストなど）のラベルをコンソールに表示します。 event.artistがget_textまたはget_labelメソッドを持つ場合にのみ処理を行います。

引数:

param event:

matplotlib.backend_bases.PickEvent, Matplotlibのピックイベントオブジェクト。

type event:

matplotlib.backend_bases.PickEvent

prepare_annotation()

概要: mplcursorsを用いたアノテーション表示機能の準備を行う。 詳細説明:

mplcursorsに必要な内部変数を初期化し、アノテーション表示対象となるラインを登録するための ヘルパー関数add_lineを提供します。これにより、複数のラインに対するアノテーションを管理できます。

prepare_move_points()

概要: プロット上の点を移動させる機能の準備を行う。 詳細説明:

移動対象の点を管理するためのgco (Graphics Object) を初期化し、 プロットに移動可能な点を追加するためのヘルパー関数addを提供します。

prepare_move_text(fig=None)

概要: プロット上のテキストやアノテーションを移動させる機能の準備を行う。 詳細説明:

移動可能なテキストやアノテーションの情報を管理するためのリストtext_infを初期化し、 これらをプロットに追加するためのヘルパー関数add_annotationとadd_textを提供します。 座標がDataFrame形式の場合の処理や、自動でY軸範囲内に配置するロジックも含まれます。

引数:

param fig:

matplotlib.figure.Figure, イベントを登録するMatplotlibのFigureオブジェクト（オプション）。

type fig:

matplotlib.figure.Figure or None

prepare_popup_menu(fig, parent=None)

概要: ポップアップメニューの準備を行う。 詳細説明:

TkinterのMenuウィジェットを作成し、これをself.popup_menu.menuに格納します。 メニュー項目を追加するためのヘルパー関数add_menuも提供されます。 parentが指定されない場合、非表示のルートTkinterウィンドウが作成されます。

引数:

param fig:

matplotlib.figure.Figure, メニューを関連付けるMatplotlibのFigureオブジェクト。

type fig:

matplotlib.figure.Figure

param parent:

tkinter.Tk or tkinter.Toplevel, Tkinterの親ウィジェット（オプション）。

type parent:

tkinter.Tk or tkinter.Toplevel or None

register_annotation_event(fig, activate=True, on_mouse_move=None, on_click=None, print_level=0)

概要: mplcursorsを使用してプロット上のデータ点にアノテーションを表示するイベントを登録する。 詳細説明:

マウスのホバーやクリックに応じてデータ点に関する情報を表示する機能を提供します。 twinx/yを使用したAxesにも対応しており、座標変換を考慮して正しい情報が表示されます。 アノテーションの表示/非表示やフォーマットを細かく制御できます。

引数:

param fig:

matplotlib.figure.Figure, イベントを登録するMatplotlibのFigureオブジェクト。

type fig:

matplotlib.figure.Figure

param activate:

bool, 初期状態でアノテーション機能をアクティブにするかどうか。

type activate:

bool

param on_mouse_move:

callable, カスタムのマウス移動イベントハンドラ（オプション）。

type on_mouse_move:

callable or None

param on_click:

callable, カスタムのクリックイベントハンドラ（オプション）。

type on_click:

callable or None

param print_level:

int, クリック時に情報をコンソールに出力するレベル。

type print_level:

int

register_click(fig, event='button_press_event', callback=None)

概要: マウスクリックイベントにコールバック関数を登録する。 詳細説明:

register_eventを使用して、デフォルトでonclickメソッドを呼び出します。 カスタムのコールバック関数を指定することも可能です。

引数:

param fig:

matplotlib.figure.Figure, イベントを登録するMatplotlibのFigureオブジェクト。

type fig:

matplotlib.figure.Figure

param event:

str, 登録するイベントの種類（デフォルトは"button_press_event"）。

type event:

str

param callback:

callable, イベント発生時に呼び出されるカスタム関数（オプション）。

type callback:

callable or None

register_event(fig, event='button_press_event', callback=None)

概要: 指定されたMatplotlibイベントにコールバック関数を登録する汎用メソッド。 詳細説明:

MatplotlibのFigureCanvasから特定のイベントを捕捉し、ユーザー定義の関数を呼び出します。 これにより、様々な種類のインタラクティブなイベントハンドリングを柔軟に設定できます。

引数:

param fig:

matplotlib.figure.Figure, イベントを登録するMatplotlibのFigureオブジェクト。

type fig:

matplotlib.figure.Figure

param event:

str, 登録するイベントの種類（例: "button_press_event", "key_press_event"）。

type event:

str

param callback:

callable, イベント発生時に呼び出される関数。指定しない場合はデフォルトのハンドラが使用される。

type callback:

callable or None

register_follow_mouse_event(fig, activate=True, on_mouse_move=None, print_level=0)

概要: マウスカーソルに追従する補助線やマーカーを表示するイベントを登録する。 詳細説明:

マウスの動きに合わせて、指定されたAxes上にカーソルのX/Y座標を示す補助線またはマーカーを リアルタイムで描画します。複数のAxesに同時に表示することも可能です。 activateメソッドで追従機能のアクティブ/非アクティブを切り替えられます。

引数:

param fig:

matplotlib.figure.Figure, イベントを登録するMatplotlibのFigureオブジェクト。

type fig:

matplotlib.figure.Figure

param activate:

bool, 初期状態で追従機能をアクティブにするかどうか。

type activate:

bool

param on_mouse_move:

callable, カスタムのマウス移動イベントハンドラ（オプション）。

type on_mouse_move:

callable or None

param print_level:

int, 未使用。

type print_level:

int

register_key(fig, event='key_press_event', callback=None)

概要: キーボードプレスイベントにコールバック関数を登録する。 詳細説明:

register_eventを使用して、デフォルトでonkeyメソッドを呼び出します。 カスタムのコールバック関数を指定することも可能です。

引数:

param fig:

matplotlib.figure.Figure, イベントを登録するMatplotlibのFigureオブジェクト。

type fig:

matplotlib.figure.Figure

param event:

str, 登録するイベントの種類（デフォルトは"key_press_event"）。

type event:

str

param callback:

callable, イベント発生時に呼び出されるカスタム関数（オプション）。

type callback:

callable or None

register_move_points_event(fig)

概要: プロット上のマーカーをドラッグして移動させるイベントを登録する。 詳細説明:

マウスイベントを監視し、ピックされたマーカーをドラッグ中に移動させることができます。 これにより、プロット上の特定のデータ点をインタラクティブに操作することが可能になります。

引数:

param fig:

matplotlib.figure.Figure, イベントを登録するMatplotlibのFigureオブジェクト。

type fig:

matplotlib.figure.Figure

register_move_text_event(fig=None, activate=False)

概要: プロット上のテキストやアノテーションをドラッグして移動させるイベントを登録する。 詳細説明:

マウスのボタンプレス、リリース、移動イベントを監視し、選択されたテキスト/アノテーションの位置を リアルタイムで更新します。activateメソッドで移動機能のアクティブ/非アクティブを切り替えられます。 twinx/yなどで異なるAxesを使用している場合も座標変換して移動を処理します。

引数:

param fig:

matplotlib.figure.Figure, イベントを登録するMatplotlibのFigureオブジェクト（オプション）。

type fig:

matplotlib.figure.Figure or None

param activate:

bool, 初期状態で移動機能をアクティブにするかどうか。

type activate:

bool

register_pick(fig, event='pick_event', callback=None)

概要: ピックイベントにコールバック関数を登録する。 詳細説明:

register_eventを使用して、デフォルトでonpickメソッドを呼び出します。 カスタムのコールバック関数を指定することも可能です。

引数:

param fig:

matplotlib.figure.Figure, イベントを登録するMatplotlibのFigureオブジェクト。

type fig:

matplotlib.figure.Figure

param event:

str, 登録するイベントの種類（デフォルトは"pick_event"）。

type event:

str

param callback:

callable, イベント発生時に呼び出されるカスタム関数（オプション）。

type callback:

callable or None

register_popup_menu_event(on_click=None)

概要: 右クリックイベントにポップアップメニューを表示する機能を登録する。 詳細説明:

Matplotlibの'button_press_event'を監視し、イベントが右クリック（ボタン3）の場合に、 tk_popupメソッドを使ってTkinterのポップアップメニューをマウスカーソルの位置に表示します。 カスタムのon_clickハンドラを指定することも可能です。

引数:

param on_click:

callable, カスタムのクリックイベントハンドラ（オプション）。デフォルトは右クリックでメニュー表示。

type on_click:

callable or None

register_redraw(fig, event='draw_event', callback=None)

概要: 再描画イベントにコールバック関数を登録する。 詳細説明:

register_eventを使用して、デフォルトでondrawメソッドを呼び出します。 カスタムのコールバック関数を指定することも可能です。

引数:

param fig:

matplotlib.figure.Figure, イベントを登録するMatplotlibのFigureオブジェクト。

type fig:

matplotlib.figure.Figure

param event:

str, 登録するイベントの種類（デフォルトは"draw_event"）。

type event:

str

param callback:

callable, イベント発生時に呼び出されるカスタム関数（オプション）。

type callback:

callable or None

remove(index)

概要: axis_infリストからデータを削除する。 詳細説明:

引数indexが整数の場合はリストのインデックスとして、文字列の場合は'label'キーの値として解釈し、 対応するデータ情報をself.axis_infリストから削除します。

引数:

param index:

int or str, 削除するデータのインデックス（整数）またはラベル（文字列）。

type index:

int or str