tkplot マニュアル

1. 役割

tkplot は、Matplotlib figureへクリック、最近傍データ表示、注釈、crosshair、点・text移動、popup、button、範囲選択を追加するinteractive helperです。tkPlotEvent が互換facade、RangeSelector がdrag範囲選択を担当します。

2. 推奨import

from tkplot import tkPlotEvent, RangeSelector

3. クリックした最近傍データを表示

import matplotlib.pyplot as plt
import numpy as np
from tkplot import tkPlotEvent

x = np.linspace(0.0, 10.0, 101)
y = np.sin(x)

fig, ax = plt.subplots()
line, = ax.plot(x, y, label="sin")

interactive = tkPlotEvent(plt, distance="r")
interactive.add_data({
    "label": "sin data",
    "plot_type": "2D",
    "axis": ax,
    "data": [line],
})
interactive.register_click(fig)

plt.show()
interactive.disconnect_all()

distance は "r", "x", "y" のいずれかです。距離はaxis表示範囲で規格化されます。

4. dataset辞書

add_data() に最低限必要なキー:

キー

内容

label

dataset表示名

plot_type

"2D", "plot", "scatter" 等

axis

Matplotlib Axes

任意キー:

  • data: Line2DやPathCollection。省略時はaxisから収集。

  • xlist, xlabels: click時に追加表示する対応データ。

  • axis_scale: 距離規格化や座標変換に使う別axis。

  • その他metadata。

5. 範囲選択

import matplotlib.pyplot as plt
from tkplot import RangeSelector

fig, ax = plt.subplots()
ax.plot([0, 1, 2], [1, 3, 2])


def selected(x0, x1, y0, y1):
    xmin, xmax = sorted((x0, x1))
    print("x range:", xmin, xmax)

selector = RangeSelector(
    mode="x",
    axis=ax,
    on_selected=selected,
)
plt.show()
selector.disconnect()

mode="x", "y", "xy" を使えます。callbackへ渡される端点はdrag方向のままで、昇順保証はありません。必要なら sorted() してください。

6. その他のcontroller

tkPlotEvent から次の登録メソッドを利用できます。

  • register_annotation_event()

  • register_move_points_event()

  • register_move_text_event()

  • register_follow_mouse_event()

  • register_popup_menu_event()

  • add_button() / add_stop_button()

これらは内部controllerへ委譲します。詳細なstate fieldと引数はAPIリファレンスを参照してください。

7. lifecycle

Matplotlibのevent connectionを保持するため、interactive objectをlocal一時変数だけにせず、figure表示中は参照を保持してください。

fig._tkplot_event = interactive
fig._range_selector = selector

終了時は disconnect_all() または RangeSelector.disconnect() を呼びます。

8. GUI backend上の注意

  • notebook inline backendではmouse eventの一部が制限されます。

  • popupはTk系環境への依存があります。

  • redrawやdrag中の性能はdata点数とbackendに依存します。

  • tkPlotEvent のconstructor第1引数は matplotlib.pyplot 相当objectです。

9. 生成AI向けコード生成ルール

  1. tkPlotEvent(plt) とし、FigureやAxesを第1引数にしない。

  2. add_data() には label, plot_type, axis を必ず渡す。

  3. Line2Dとscatterではartistデータ取得方法が異なるため、plot_type を正しく指定する。

  4. selector/callback objectの参照をfigure表示中保持する。

  5. 範囲端点の大小を自動保証しない。

  6. GUI終了時にeventをdisconnectする。

  7. 画像保存だけのnoninteractive scriptに不要なevent登録を追加しない。