# tkplot 生成AI投入用コンテキスト

> このファイルは `tkplot` を使うコード生成のため、マニュアルとAPIリファレンスを1ファイルへ統合したものです。API名・引数は下記APIリファレンスを優先し、存在しないAPIを推測で作らないでください。ソースコードが同時に与えられた場合はソースコードを最優先します。

---

# tkplot マニュアル

## 1. 役割

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

## 2. 推奨import

```python
from tkplot import tkPlotEvent, RangeSelector
```

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

```python
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. 範囲選択

```python
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表示中は参照を保持してください。

```python
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登録を追加しない。


---

# tkplot APIリファレンス

> 対象ソース: `tklib2.zip`（解析日: 2026-08-03）。この文書はソースコードを静的解析して生成しています。

## APIの読み方

- **パッケージ公開API**は、原則としてトップレベルの `__all__` に含まれる名前です。
- **モジュールAPI**には、公開名（先頭が `_` でない関数・クラス・メソッド）を列挙しています。
- docstringがないAPIでは、シグネチャとソースパスを一次情報として扱ってください。
- 生成AIは、この文書に存在しない引数・戻り値・メソッドを推測で追加しないでください。

## パッケージ公開API

```python
from tkplot import (
    tkPlotEvent,
    RangeSelector,
)
```

| 名前 | 推奨用途 |
|---|---|
| `tkPlotEvent` | トップレベルから安定してimportできる公開API |
| `RangeSelector` | トップレベルから安定してimportできる公開API |

## モジュール一覧

| モジュール | ソース | 関数 | クラス |
|---|---|---:|---:|
| `tkplot` | `tkplot/__init__.py` | 0 | 0 |
| `tkplot.tkplotevent` | `tkplot/tkplotevent/__init__.py` | 0 | 0 |
| `tkplot.tkplotevent.tkannotation` | `tkplot/tkplotevent/tkannotation.py` | 0 | 1 |
| `tkplot.tkplotevent.tkbuttons` | `tkplot/tkplotevent/tkbuttons.py` | 0 | 2 |
| `tkplot.tkplotevent.tkcoords` | `tkplot/tkplotevent/tkcoords.py` | 1 | 0 |
| `tkplot.tkplotevent.tkcrosshair` | `tkplot/tkplotevent/tkcrosshair.py` | 0 | 1 |
| `tkplot.tkplotevent.tkdataset` | `tkplot/tkplotevent/tkdataset.py` | 0 | 2 |
| `tkplot.tkplotevent.tkeventmanager` | `tkplot/tkplotevent/tkeventmanager.py` | 0 | 1 |
| `tkplot.tkplotevent.tkmovable` | `tkplot/tkplotevent/tkmovable.py` | 0 | 2 |
| `tkplot.tkplotevent.tknearest` | `tkplot/tkplotevent/tknearest.py` | 0 | 2 |
| `tkplot.tkplotevent.tkplotevent` | `tkplot/tkplotevent/tkplotevent.py` | 0 | 1 |
| `tkplot.tkplotevent.tkpopup` | `tkplot/tkplotevent/tkpopup.py` | 0 | 1 |
| `tkplot.tkplotevent.tkrangeselector` | `tkplot/tkplotevent/tkrangeselector.py` | 0 | 1 |
| `tkplot.tkplotevent.tkstate` | `tkplot/tkplotevent/tkstate.py` | 1 | 0 |

## `tkplot`

ソース: `tkplot/__init__.py`

_このモジュールには静的解析で検出された公開関数・クラス・定数はありません。_

## `tkplot.tkplotevent`

ソース: `tkplot/tkplotevent/__init__.py`

_このモジュールには静的解析で検出された公開関数・クラス・定数はありません。_

## `tkplot.tkplotevent.tkannotation`

ソース: `tkplot/tkplotevent/tkannotation.py`

### class `tkAnnotationController`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**コンストラクタ**

```python
tkAnnotationController(events)
```

**メソッド／プロパティ**

#### method `tkAnnotationController.prepare`

```python
def prepare(self)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkAnnotationController.add_line`

```python
def add_line(self, label, axis, ref_axis, x_list, y_list, line, inf_list = None, annotation_format = None, inf_format = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkAnnotationController.activate`

```python
def activate(self, flag = True)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkAnnotationController.register`

```python
def register(self, fig, activate = True, on_mouse_move = None, on_click = None, print_level = 0)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

## `tkplot.tkplotevent.tkbuttons`

ソース: `tkplot/tkplotevent/tkbuttons.py`

### class `tkStopButton`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**コンストラクタ**

```python
tkStopButton(plt, button_region, plot_region, label, color, hovercolor, callback = None)
```

**メソッド／プロパティ**

#### method `tkStopButton.set_text`

```python
def set_text(self, text)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkStopButton.adjust_plot`

```python
def adjust_plot(self, plot_region = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### property `tkStopButton.status`

```python
def status(self)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkStopButton.status`

```python
def status(self, value)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

### class `tkButtonController`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**コンストラクタ**

```python
tkButtonController(plt)
```

**メソッド／プロパティ**

#### method `tkButtonController.add_button`

```python
def add_button(self, button_region = (0.15, 0.95, 0.1, 0.03), text = 'stop', color = '#f8e58c', hovercolor = '#38b48b', callback = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkButtonController.add_stop_button`

```python
def add_stop_button(self, 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)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

## `tkplot.tkplotevent.tkcoords`

ソース: `tkplot/tkplotevent/tkcoords.py`

### function `convert_axes_coordinates`

```python
def convert_axes_coordinates(x, y, source_axis, target_axis)
```

Convert data coordinates between Matplotlib axes via display coordinates.

## `tkplot.tkplotevent.tkcrosshair`

ソース: `tkplot/tkplotevent/tkcrosshair.py`

### class `tkCrosshairController`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**コンストラクタ**

```python
tkCrosshairController(events)
```

**メソッド／プロパティ**

#### method `tkCrosshairController.add`

```python
def add(self, ax, line = 'dashed', width = 0.5, marker = None, size = 3.0, color = 'red')
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkCrosshairController.activate`

```python
def activate(self, flag = True)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkCrosshairController.register`

```python
def register(self, fig, activate = True, on_mouse_move = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

## `tkplot.tkplotevent.tkdataset`

ソース: `tkplot/tkplotevent/tkdataset.py`

### class `tkPlotData`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**データクラス相当の初期化フィールド**

```python
tkPlotData(label: str, plot_type: str, axis: Any, data: list[Any], xlist: Any = None, xlabels: Any = None, axis_scale: Any = None, metadata: dict[str, Any])
```

**フィールド**

| 名前 | 型 | 既定値 |
|---|---|---|
| `label` | `str` | `必須` |
| `plot_type` | `str` | `必須` |
| `axis` | `Any` | `必須` |
| `data` | `list[Any]` | `必須` |
| `xlist` | `Any` | `None` |
| `xlabels` | `Any` | `None` |
| `axis_scale` | `Any` | `None` |
| `metadata` | `dict[str, Any]` | `必須` |

**メソッド／プロパティ**

#### method `tkPlotData.as_legacy_dict`

```python
def as_legacy_dict(self)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

### class `tkDataSetRegistry`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**コンストラクタ**

```python
tkDataSetRegistry()
```

**メソッド／プロパティ**

#### method `tkDataSetRegistry.add`

```python
def add(self, axis_inf = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkDataSetRegistry.remove`

```python
def remove(self, index_or_label)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

## `tkplot.tkplotevent.tkeventmanager`

ソース: `tkplot/tkplotevent/tkeventmanager.py`

### class `tkEventManager`

Own Matplotlib callback IDs and prevent accidental duplicate registration.

**コンストラクタ**

```python
tkEventManager()
```

**メソッド／プロパティ**

#### method `tkEventManager.connect`

```python
def connect(self, fig, event_name, callback, key = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkEventManager.disconnect`

```python
def disconnect(self, key)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkEventManager.disconnect_figure`

```python
def disconnect_figure(self, fig)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkEventManager.disconnect_all`

```python
def disconnect_all(self)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

## `tkplot.tkplotevent.tkmovable`

ソース: `tkplot/tkplotevent/tkmovable.py`

### class `tkMovablePointController`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**コンストラクタ**

```python
tkMovablePointController(events)
```

**メソッド／プロパティ**

#### method `tkMovablePointController.add`

```python
def add(self, ax, x, y, marker = 'o', picker = 15, color = 'red')
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkMovablePointController.register`

```python
def register(self, fig)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

### class `tkMovableTextController`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**コンストラクタ**

```python
tkMovableTextController(events)
```

**メソッド／プロパティ**

#### method `tkMovableTextController.add_text`

```python
def add_text(self, ax, ax_ref, x = None, y = None, x_list = None, y_list = None, x_offset = 0, x_target = None, frac = None, xlim = None, ylim = None, text = 'no name', fontsize = 10, ha = 'center', va = 'center', color = 'black', fc = 'w', ec = 'none', alpha = 0.5)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkMovableTextController.add_annotation`

```python
def add_annotation(self, ax, ax_ref, x = None, y = None, x_list = None, y_list = None, x_offset = 0, x_target = None, frac = None, xlim = None, ylim = None, text = 'no name', fontsize = 10, ha = 'center', va = 'center', color = 'black', fc = 'w', ec = 'none', alpha = 0.5)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkMovableTextController.activate`

```python
def activate(self, flag = True)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkMovableTextController.register`

```python
def register(self, fig = None, activate = False)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

## `tkplot.tkplotevent.tknearest`

ソース: `tkplot/tkplotevent/tknearest.py`

### class `tkHitResult`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**データクラス相当の初期化フィールド**

```python
tkHitResult(dataset_index: int, artist_index: int, data_index: int, distance2: float, x: float, y: float, dataset: dict)
```

**フィールド**

| 名前 | 型 | 既定値 |
|---|---|---|
| `dataset_index` | `int` | `必須` |
| `artist_index` | `int` | `必須` |
| `data_index` | `int` | `必須` |
| `distance2` | `float` | `必須` |
| `x` | `float` | `必須` |
| `y` | `float` | `必須` |
| `dataset` | `dict` | `必須` |

### class `tkNearestFinder`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**コンストラクタ**

```python
tkNearestFinder(distance = 'r')
```

**メソッド／プロパティ**

#### method `tkNearestFinder.find`

```python
def find(self, event, dataset_indices, datasets)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

## `tkplot.tkplotevent.tkplotevent`

ソース: `tkplot/tkplotevent/tkplotevent.py`

### class `tkPlotEvent`

Compatibility-oriented facade for interactive Matplotlib helpers.

**コンストラクタ**

```python
tkPlotEvent(plt, distance = 'r', **kwargs)
```

**メソッド／プロパティ**

#### method `tkPlotEvent.add_data`

```python
def add_data(self, axis_inf = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.remove`

```python
def remove(self, index)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.convert_coord`

```python
def convert_coord(self, x0, y0, axis_s, axis_t)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.find_target_axes`

```python
def find_target_axes(self, event, axes = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.find_nearest_data`

```python
def find_nearest_data(self, x, y, itarget_list, hit_axisinf_list)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.display_data`

```python
def display_data(self, iinf, idata, idx, axis_inf)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.onclick`

```python
def onclick(self, event)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.register_event`

```python
def register_event(self, fig, event = 'button_press_event', callback = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.register_click`

```python
def register_click(self, fig, event = 'button_press_event', callback = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.register_pick`

```python
def register_pick(self, fig, event = 'pick_event', callback = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.register_redraw`

```python
def register_redraw(self, fig, event = 'draw_event', callback = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.register_key`

```python
def register_key(self, fig, event = 'key_press_event', callback = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.onpick`

```python
def onpick(self, event)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.ondraw`

```python
def ondraw(self, event)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.onkey`

```python
def onkey(self, event)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.prepare_annotation`

```python
def prepare_annotation(self)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.register_annotation_event`

```python
def register_annotation_event(self, fig, **kwargs)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.prepare_move_points`

```python
def prepare_move_points(self)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.register_move_points_event`

```python
def register_move_points_event(self, fig)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.prepare_move_text`

```python
def prepare_move_text(self, fig = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.register_move_text_event`

```python
def register_move_text_event(self, fig = None, activate = False)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.register_follow_mouse_event`

```python
def register_follow_mouse_event(self, fig, activate = True, on_mouse_move = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.prepare_popup_menu`

```python
def prepare_popup_menu(self, fig, parent = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.register_popup_menu_event`

```python
def register_popup_menu_event(self, on_click = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.button_click`

```python
def button_click(self, event)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.add_button`

```python
def add_button(self, button_region = (0.15, 0.95, 0.1, 0.03), plot_region = (0.92, 0.15), text = 'stop', color = '#f8e58c', hovercolor = '#38b48b', callback = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.finalize_button`

```python
def finalize_button(self, text = 'finished')
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.add_stop_button`

```python
def add_stop_button(self, **kwargs)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.layout`

```python
def layout(self, show = False)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPlotEvent.disconnect_all`

```python
def disconnect_all(self)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

## `tkplot.tkplotevent.tkpopup`

ソース: `tkplot/tkplotevent/tkpopup.py`

### class `tkPopupController`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**コンストラクタ**

```python
tkPopupController(events)
```

**メソッド／プロパティ**

#### method `tkPopupController.prepare`

```python
def prepare(self, fig, parent = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `tkPopupController.register`

```python
def register(self, on_click = None)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

## `tkplot.tkplotevent.tkrangeselector`

ソース: `tkplot/tkplotevent/tkrangeselector.py`

### class `RangeSelector`

_ソース内docstringはありません。シグネチャと実装を参照してください。_

**コンストラクタ**

```python
RangeSelector(mode = 'x', axis = None, color = 'red', linestyle = 'dashed', linewidth = 0.5, print_level = 1, on_selected = None)
```

**メソッド／プロパティ**

#### method `RangeSelector.set_mode`

```python
def set_mode(self, mode)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `RangeSelector.set_active`

```python
def set_active(self, flag = True)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `RangeSelector.on_press`

```python
def on_press(self, event)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `RangeSelector.on_mouse_move`

```python
def on_mouse_move(self, event)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `RangeSelector.on_release`

```python
def on_release(self, event)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `RangeSelector.finalize`

```python
def finalize(self)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `RangeSelector.clear`

```python
def clear(self)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

#### method `RangeSelector.disconnect`

```python
def disconnect(self)
```

_ソース内docstringはありません。シグネチャと実装を参照してください。_

## `tkplot.tkplotevent.tkstate`

ソース: `tkplot/tkplotevent/tkstate.py`

### function `state`

```python
def state(**kwargs)
```

Create a lightweight mutable state container.