フレームワーク API リファレンス

このページは nyxpy.framework.* の公開 API のうち、マクロ実装者が直接使う面を docstring と型ヒントから生成する。

マクロライフサイクル

Bases: ABC

NyX マクロの基底クラス。

サブクラスは initialize(), run(), finalize() を実装します。 description, display_name, tags, args_schema, settings_path は一覧表示、検索、設定読み込みに使うメタデータです。

description `class-attribute` `instance-attribute`

description = ''

一覧表示向けの短い説明文。

display_name `class-attribute` `instance-attribute`

display_name = None

GUI や一覧表示で使う表示名。未指定の場合はクラス名が使われます。

tags `class-attribute` `instance-attribute`

tags = []

検索・分類用のタグ。

args_schema `class-attribute` `instance-attribute`

args_schema = None

実行引数を検証する schema。未指定の場合は raw args が渡ります。

settings_path `class-attribute` `instance-attribute`

settings_path = None

マクロごとの設定ファイル path。str は resource: / project: / マクロ本体相対 path、Path は絶対 path またはマクロ本体相対 path として扱います。

initialize `abstractmethod`

initialize(cmd, args)

マクロ実行前の初期化処理を実装します。

設定値の変換、画像資材の読み込み、実行状態の初期化を行います。 args_schema が設定されている場合、args は検証済みの辞書です。

run `abstractmethod`

run(cmd)

マクロの本処理を実装します。

コントローラー操作、待機、キャプチャ、通知、ログは cmd 経由で行います。

finalize `abstractmethod`

finalize(cmd)

マクロ実行後の後片付けを実装します。

押下状態の解除や終了ログなど、失敗時にも安全に実行できる処理を置きます。

Command

Bases: ABC

マクロから実行環境を操作するための公開 API。

コントローラー操作、待機、ログ、キャプチャ、asset の読み込み、 artifact の保存と読み戻し、通知はこのインターフェース経由で行います。

artifact_dir_name `abstractmethod` `property`

artifact_dir_name

実行ごとの artifact 保存先を切り替えるための directory segment。

ArtifactScope.RUN の保存先ディレクトリ名です。値は {timestamp}_{short_id} 形式です。マクロ側で実行ごとのサブディレクトリ名を組み立てる場合にも使えます。

Returns:

Type	Description
`str`	現在の実行に対応する artifact ディレクトリ名。

press `abstractmethod`

press(*keys, dur=0.1, wait=0.1)

指定されたキーを押下します。

押下時間と待機時間を指定することができます。

Parameters:

Name	Type	Description	Default
`keys`	`KeyType`	押下するキー。	`()`
`dur`	`float`	押下時間（秒）。	`0.1`
`wait`	`float`	押下後の待機時間（秒）。	`0.1`

hold `abstractmethod`

hold(*keys)

指定されたキーを押し続けます。より厳密には、現在のキー入力の内部状態を破棄し、指定されたキー入力に変更します。

これは、連続的な入力を必要とする場合に使用されます。

Parameters:

Name	Type	Description	Default
`keys`	`KeyType`	押し続けるキー。	`()`

release `abstractmethod`

release(*keys)

指定されたキーを解放します。

これは、押下または保持されたキーを解放するために使用されます。すべてのキーを解放する場合は、引数を省略できます。

Parameters:

Name	Type	Description	Default
`keys`	`KeyType`	解放するキー。省略時は全解除。	`()`

wait `abstractmethod`

wait(wait)

指定秒数だけ待機します。

実装は待機中も中断要求を確認します。長い処理では time.sleep() を直接使わず、このメソッドを使います。

Parameters:

Name	Type	Description	Default
`wait`	`float`	待機時間（秒）。	required

stop `abstractmethod`

stop()

マクロの実行を中断します。

これは、ユーザーが中断要求を行った場合に使用されます。

log `abstractmethod`

log(*values, sep=' ', end='\n', level='DEBUG')

ログ出力を行います。

Parameters:

Name	Type	Description	Default
`values`	`object`	ログに出力する値。	`()`
`sep`	`str`	値の区切り文字。	`' '`
`end`	`str`	ログの末尾に追加する文字列。	`'\n'`
`level`	`str`	ログレベル。`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`。	`'DEBUG'`

capture `abstractmethod`

capture(crop_region=None, grayscale=False)

キャプチャデバイスからHD解像度(1280x720) にリスケールしたスクリーンショットを取得し、必要に応じてクロップ及びグレースケール変換を行います。

3DS のアスペクトボックス入力では、3DS 画面本体は (x=340, y=0, width=600, height=720) として扱います。 3DS の下画面実領域は (x=400, y=360, width=480, height=360) です。

Parameters:

Name	Type	Description	Default
`crop_region`	`tuple[int, int, int, int] \| None`	クロップする領域の指定 `(x, y, width, height)`。	`None`
`grayscale`	`bool`	グレースケール変換を行うか。	`False`

Returns:

Type	Description
`MatLike`	キャプチャした画像データ。

Raises:

Type	Description
`FrameNotReadyError`	フレームがまだ取得できない場合。
`ValueError`	クロップ領域がフレームサイズ (1280x720) を超える場合。

load_img `abstractmethod`

load_img(filename, *, grayscale=False)

画像 asset を読み込みます。

読み込み対象は resources/<macro_id>/assets とマクロパッケージ内 assets です。実行中に生成した画像 artifact は探索しません。生成物を読み戻す場合は load_artifact_img() を使います。

Parameters:

Name	Type	Description	Default
`filename`	`str \| Path`	資材 root からの相対パス。例: `"image.png"`。	required
`grayscale`	`bool`	グレースケール変換を行うか。	`False`

Returns:

Type	Description
`MatLike`	読み込んだ画像データ。

Raises:

Type	Description
`ResourcePathError`	`filename` が不正な path の場合。
`ResourceNotFoundError`	探索 root に画像資材が存在しない場合。
`ResourceReadError`	OpenCV 画像として読み込めない場合。

load_blob `abstractmethod`

load_blob(filename)

バイナリ asset を読み込みます。

読み込み対象は resources/<macro_id>/assets とマクロパッケージ内 assets です。実行中に生成した bytes 形式の artifact は探索しません。生成物を読み戻す場合は load_artifact_blob() を使います。

Parameters:

Name	Type	Description	Default
`filename`	`str \| Path`	資材 root からの相対パス。例: `"data.bin"`。	required

Returns:

Type	Description
`bytes`	読み込んだ bytes データ。

Raises:

Type	Description
`ResourcePathError`	`filename` が不正な path の場合。
`ResourceNotFoundError`	探索 root に資材が存在しない場合。
`ResourceReadError`	bytes データを読み込めない場合。

save_artifact_img `abstractmethod`

save_artifact_img(
    filename,
    image,
    *,
    scope=ArtifactScope.RUN,
    overwrite=None,
    atomic=None,
)

画像 artifact を保存します。

保存先の既定は resources/<macro_id>/artifacts/<artifact_dir_name> 配下です。実行をまたいで同じ名前の artifact を再利用したい場合は scope=ArtifactScope.STABLE を指定します。

Parameters:

Name	Type	Description	Default
`filename`	`str \| Path`	artifact scope を基準にした相対パス。例: `"debug/frame.png"`。	required
`image`	`MatLike`	保存する画像データ。	required
`scope`	`ArtifactScope`	保存先 scope。	`RUN`
`overwrite`	`OverwritePolicy \| None`	同名ファイルがある場合の処理。`None` は store の既定値を使う。	`None`
`atomic`	`bool \| None`	atomic write を使うかどうか。`None` は store の既定値を使う。	`None`

Returns:

Type	Description
`ResourceRef`	保存した artifact の参照。

Raises:

Type	Description
`ResourcePathError`	`filename` が不正な path の場合。
`ResourceAlreadyExistsError`	上書き禁止の保存先が既に存在する場合。
`ResourceWriteError`	画像を書き込めない場合。

save_artifact_blob `abstractmethod`

save_artifact_blob(
    filename,
    data,
    *,
    scope=ArtifactScope.RUN,
    overwrite=None,
    atomic=None,
)

バイナリ artifact を保存します。

テキストはエンコード済み、JSON はシリアライズ済みの bytes として渡します。保存先の既定は resources/<macro_id>/artifacts/<artifact_dir_name> 配下です。

Parameters:

Name	Type	Description	Default
`filename`	`str \| Path`	artifact scope を基準にした相対パス。例: `"result/data.csv"`。	required
`data`	`bytes`	保存する bytes データ。	required
`scope`	`ArtifactScope`	保存先 scope。	`RUN`
`overwrite`	`OverwritePolicy \| None`	同名ファイルがある場合の処理。`None` は store の既定値を使う。	`None`
`atomic`	`bool \| None`	atomic write を使うかどうか。`None` は store の既定値を使う。	`None`

Returns:

Type	Description
`ResourceRef`	保存した artifact の参照。

Raises:

Type	Description
`ResourcePathError`	`filename` が不正な path の場合。
`ResourceAlreadyExistsError`	上書き禁止の保存先が既に存在する場合。
`ResourceWriteError`	bytes データを書き込めない場合。

load_artifact_img `abstractmethod`

load_artifact_img(
    artifact, *, scope=ArtifactScope.RUN, grayscale=False
)

画像 artifact を読み戻します。

artifact に ResourceRef を渡した場合は、その参照が示す path を読み込みます。文字列または Path の場合のみ、scope に応じて現在実行中の artifact または stable artifact を解決します。

Parameters:

Name	Type	Description	Default
`artifact`	`ResourceRef \| str \| Path`	保存時に返された `ResourceRef`、または artifact scope を基準にした相対パス。	required
`scope`	`ArtifactScope`	`artifact` が相対パスの場合の読み込み元 scope。	`RUN`
`grayscale`	`bool`	グレースケール変換を行うか。	`False`

Returns:

Type	Description
`MatLike`	読み込んだ画像データ。

Raises:

Type	Description
`ResourcePathError`	`artifact` の path が不正な場合。
`ResourceNotFoundError`	artifact が存在しない場合。
`ResourceReadError`	OpenCV 画像として読み込めない場合。

load_artifact_blob `abstractmethod`

load_artifact_blob(artifact, *, scope=ArtifactScope.RUN)

バイナリ artifact を読み戻します。

Parameters:

Name	Type	Description	Default
`artifact`	`ResourceRef \| str \| Path`	保存時に返された `ResourceRef`、または artifact scope を基準にした相対パス。	required
`scope`	`ArtifactScope`	`artifact` が相対パスの場合の読み込み元 scope。	`RUN`

Returns:

Type	Description
`bytes`	読み込んだ bytes データ。

Raises:

Type	Description
`ResourcePathError`	`artifact` の path が不正な場合。
`ResourceNotFoundError`	artifact が存在しない場合。
`ResourceReadError`	bytes データとして読み込めない場合。

keyboard `abstractmethod`

keyboard(text)

指定されたテキスト(英数字)をキーボード入力として送信します。

プロトコルが対応していない場合は、文字ごとに typekey に委譲されます。

Parameters:

Name	Type	Description	Default
`text`	`str`	送信するテキスト。	required

type `abstractmethod`

type(key)

指定されたキーを個別のキーボード入力として送信します。

これは個々のキーの押下・解放操作を表します。

Parameters:

Name	Type	Description	Default
`key`	`KeyCode \| SpecialKeyCode`	送信する通常キーまたは特殊キーのキーコード。	required

notify `abstractmethod`

notify(text, img=None)

外部サービスへ通知を送信する

touch

touch(x, y, dur=0.1, wait=0.1)

3DS touch 対応プロトコルで touch down / wait / touch up を行います。

touch_down

touch_down(x, y)

3DS touch 対応プロトコルで指定座標を押し続けます。

touch_up

touch_up()

3DS touch 対応プロトコルで touch 入力を離します。

disable_sleep

disable_sleep(enabled=True)

対応プロトコルでスリープ制御を切り替えます。

定数

定数モジュールパッケージ

このパッケージはNyXプロジェクト全体で使用される各種定数を定義します。

Button

Bases: IntEnum

コントローラーのボタンを表す定数

Hat

Bases: IntEnum

コントローラーの方向キー（HAT）を表す定数

ThreeDSButton

Bases: IntEnum

3DS 固有のボタンを表す定数。対応プロトコルでのみ使用できます。

TouchState `dataclass`

3DS タッチパネルの入力状態。座標は 320x240 の touch 座標です。

down `classmethod`

down(x, y)

指定座標を押している状態を返します。

up `classmethod`

up()

タッチ入力を離した状態を返します。

KeyboardOp

Bases: IntEnum

キーボード操作の種類を表す列挙型

KeyCode

Bases: int

キーボードの通常キーのキーコードを表すクラス

SpecialKeyCode

Bases: IntEnum

キーボードの特殊キーのキーコードを定義します。

特殊キー（ENTER, ESCAPE, BACKSPACE, TAB, SPACEなど）を定義します。また、日本語キーボード固有の半角・全角なども含みます

ScaleRounding

Bases: StrEnum

座標拡大縮小時の丸め方法。

ScreenPoint `dataclass`

画面上の 1 点。

ScreenRect `dataclass`

画面上の矩形。

ScreenSize `dataclass`

画面サイズ。

TouchPoint `dataclass`

3DS touch パネル上の 1 点。範囲は 0..319, 0..239 です。

LStick

コントローラーの左スティックの位置を表すクラス

RStick

コントローラーの右スティックの位置を表すクラス

aspect_fit_rect

aspect_fit_rect(source_size, target_size)

縦横比を保って target size 内に収めた表示矩形を返します。

cropped_hd_point_to_3ds_touch

cropped_hd_point_to_3ds_touch(point, crop_region)

切り出し済み HD 座標を元の HD 座標へ戻して touch 座標へ変換します。

cropped_normalized_point_to_3ds_touch

cropped_normalized_point_to_3ds_touch(point, crop_region)

切り出し済み正規化座標を 3DS touch 座標へ変換します。

cropped_normalized_point_to_normalized

cropped_normalized_point_to_normalized(point, crop_region)

切り出し済み正規化座標を元の正規化座標へ戻します。

hd_capture_point_to_3ds_touch

hd_capture_point_to_3ds_touch(point)

1280x720 HD キャプチャ座標の下画面上の点を touch 座標へ変換します。

hd_capture_point_to_normalized

hd_capture_point_to_normalized(point)

1280x720 HD キャプチャ座標を 3DS 正規化座標へ変換します。

normalized_point_to_3ds_touch

normalized_point_to_3ds_touch(point)

400x480 正規化座標の下画面上の点を 320x240 touch 座標へ変換します。

normalized_point_to_cropped

normalized_point_to_cropped(point, crop_region)

正規化座標を指定領域で切り出した後の座標へ変換します。

normalized_point_to_hd_capture

normalized_point_to_hd_capture(point)

3DS 正規化座標を 1280x720 HD キャプチャ座標へ変換します。

preview_point_to_3ds_touch

preview_point_to_3ds_touch(point, *, preview_size)

GUI プレビュー座標を 3DS touch 座標へ変換します。

preview_point_to_hd_capture

preview_point_to_hd_capture(
    point,
    *,
    preview_size,
    hd_capture_size=THREEDS_HD_CAPTURE_SIZE,
)

Preview 表示座標を HD キャプチャ座標へ戻します。

preview_touch_rect

preview_touch_rect(preview_size)

Preview 表示上の 3DS touch 下画面領域を返します。

project_hd_rect_to_preview

project_hd_rect_to_preview(rect, *, preview_size)

HD キャプチャ上の矩形を preview 表示座標へ投影します。

scale_point

scale_point(
    point,
    *,
    source_size,
    target_size=THREEDS_CAPTURE_SIZE,
    rounding=ScaleRounding.FLOOR,
)

点を source size から target size へ拡大縮小します。

scaled_source_point_to_3ds_touch

scaled_source_point_to_3ds_touch(point, *, source_size)

任意サイズの入力画像座標を 3DS touch 座標へ変換します。

touch_point_to_3ds_hd_capture

touch_point_to_3ds_hd_capture(point)

3DS touch 座標を HD キャプチャ下画面上の座標へ変換します。

touch_point_to_3ds_normalized

touch_point_to_3ds_normalized(point)

3DS touch 座標を正規化下画面座標へ変換します。

try_cropped_hd_point_to_3ds_touch

try_cropped_hd_point_to_3ds_touch(point, crop_region)

切り出し済み HD 座標を touch 座標へ変換し、範囲外なら None を返します。

try_cropped_normalized_point_to_3ds_touch

try_cropped_normalized_point_to_3ds_touch(
    point, crop_region
)

切り出し済み正規化座標を touch 座標へ変換し、範囲外なら None を返します。

try_hd_capture_point_to_3ds_touch

try_hd_capture_point_to_3ds_touch(point)

HD キャプチャ座標を touch 座標へ変換し、範囲外なら None を返します。

try_normalized_point_to_3ds_touch

try_normalized_point_to_3ds_touch(point)

変換できる場合は touch 座標、範囲外なら None を返します。

try_preview_point_to_3ds_touch

try_preview_point_to_3ds_touch(point, *, preview_size)

GUI プレビュー座標を touch 座標へ変換し、範囲外なら None を返します。

try_preview_point_to_hd_capture

try_preview_point_to_hd_capture(
    point,
    *,
    preview_size,
    hd_capture_size=THREEDS_HD_CAPTURE_SIZE,
)

Preview 表示座標を HD キャプチャ座標へ戻し、範囲外なら None を返します。

try_scaled_source_point_to_3ds_touch

try_scaled_source_point_to_3ds_touch(point, *, source_size)

任意サイズの入力画像座標を touch 座標へ変換し、範囲外なら None を返します。

validate_3ds_touch_point

validate_3ds_touch_point(point)

3DS touch 座標の範囲を検証します。範囲外は ValueError です。

画像処理

画像処理モジュール

このモジュールは、OpenCVの画像形式オブジェクトを受け取ってテンプレートマッチングとOCR処理を行うためのシンプルなAPIを提供します。

ImageProcessingError

Bases: Exception

画像処理に関連するエラーの基底クラス。

InvalidImageError

Bases: ImageProcessingError

無効な画像データを受け取った場合のエラー。

OCREngineNotFoundError

Bases: OCRError

OCR エンジンを初期化できない場合のエラー。

OCRError

Bases: ImageProcessingError

OCR 処理でのエラー。

OCRProcessingError

Bases: OCRError

OCR 処理中のエラー。

TemplateMatchingError

Bases: ImageProcessingError

テンプレートマッチング処理でのエラー。

ThresholdNotMetError

Bases: ImageProcessingError

テンプレートマッチング結果が閾値を満たさない場合のエラー。

OCRProcessor

PaddleOCR を使う OCR 処理クラス。

通常のインスタンス生成 (OCRProcessor(language)) に加え、 get_instance(language) で言語ごとにキャッシュされたシングルトンインスタンスを取得できる。 PaddleOCR のモデルロード・初回推論コストを複数箇所で共有したい場合は get_instance の利用を推奨する。

get_instance `classmethod`

get_instance(language='ja')

言語ごとにキャッシュされたインスタンスを返す。

同じ language に対しては常に同一インスタンスが返される。スレッドセーフ。

Parameters:

Name	Type	Description	Default
`language`	`str`	認識言語。`"ja"` または `"en"`。	`'ja'`

Returns:

Type	Description
`OCRProcessor`	キャッシュ済みの `OCRProcessor`。

clear_cache `classmethod`

clear_cache()

キャッシュを全クリアする (テスト用)。

recognize_text

recognize_text(image)

テキスト認識を実行します。

Parameters:

Name	Type	Description	Default
`image`	`MatLike`	認識対象画像。	required

Returns:

Type	Description
`list[OCRResult]`	認識結果のリスト。

get_best_text

get_best_text(image)

最も信頼度の高いテキストを取得します。

Parameters:

Name	Type	Description	Default
`image`	`MatLike`	認識対象画像。	required

Returns:

Type	Description
`str`	最も信頼度の高いテキスト。見つからない場合は空文字列。

extract_digits

extract_digits(image)

画像から数字のみを認識して返します。

Parameters:

Name	Type	Description	Default
`image`	`MatLike`	認識対象画像。	required

Returns:

Type	Description
`str`	認識された数字文字列。

OCRResult `dataclass`

OCR 認識結果。

ImageProcessor

1 枚の OpenCV 画像に対する画像処理 API。

テンプレートマッチング、OCR、用途別前処理をまとめて呼び出す入口です。 image が None または空画像の場合は InvalidImageError を送出します。

contains_template

contains_template(
    template,
    threshold=0.8,
    method=cv2.TM_CCOEFF_NORMED,
    preprocess=False,
)

指定されたテンプレートが画像内に含まれるかを判定します。

Parameters:

Name	Type	Description	Default
`template`	`MatLike`	テンプレート画像。	required
`threshold`	`float`	マッチング閾値。	`0.8`
`method`	`int`	マッチング手法。	`TM_CCOEFF_NORMED`
`preprocess`	`bool`	前処理を行うか。	`False`

Returns:

Type	Description
`bool`	テンプレートが含まれている場合は `True`。

find_template

find_template(
    template,
    threshold=0.8,
    method=cv2.TM_CCOEFF_NORMED,
    preprocess=False,
)

テンプレートマッチングを実行し、最良の一致を返します。

Parameters:

Name	Type	Description	Default
`template`	`MatLike`	テンプレート画像。	required
`threshold`	`float`	マッチング閾値。	`0.8`
`method`	`int`	マッチング手法。	`TM_CCOEFF_NORMED`
`preprocess`	`bool`	前処理を行うか。	`False`

Returns:

Type	Description
`MatchResult`	マッチング結果。

get_text

get_text(language='ja', region=None, preprocess=False)

画像からテキストを認識し、最も信頼度の高い文字列を返します。

Parameters:

Name	Type	Description	Default
`language`	`str`	認識言語。`"ja"` または `"en"`。	`'ja'`
`region`	`tuple[int, int, int, int] \| None`	認識領域 `(x, y, width, height)`。指定しない場合は全体。	`None`
`preprocess`	`bool`	OCR 用前処理を行うか。	`False`

Returns:

Type	Description
`str`	認識されたテキスト。見つからない場合は空文字列。

get_digits

get_digits(language='en', region=None, preprocess=False)

画像から数字のみを認識して返します。

Parameters:

Name	Type	Description	Default
`language`	`str`	認識言語。`"ja"` または `"en"`。	`'en'`
`region`	`tuple[int, int, int, int] \| None`	認識領域 `(x, y, width, height)`。指定しない場合は全体。	`None`
`preprocess`	`bool`	OCR 用前処理を行うか。	`False`

Returns:

Type	Description
`str`	認識された数字文字列。

find_text_region_with_template

find_text_region_with_template(
    template,
    roi_offset=(0, 0, 0, 0),
    language="ja",
    template_threshold=0.8,
    preprocess=False,
)

テンプレートマッチングでテキスト領域を特定し、OCR を実行します。

Parameters:

Name	Type	Description	Default
`template`	`MatLike`	テンプレート画像。	required
`roi_offset`	`tuple[int, int, int, int]`	マッチ位置からの相対オフセット `(x_offset, y_offset, w_offset, h_offset)`。	`(0, 0, 0, 0)`
`language`	`str`	OCR 認識言語。	`'ja'`
`template_threshold`	`float`	テンプレートマッチングの閾値。	`0.8`
`preprocess`	`bool`	前処理を行うか。	`False`

Returns:

Type	Description
`str`	認識されたテキスト。

MatchResult `dataclass`

テンプレートマッチングの結果。

ImagePreprocessor

テンプレートマッチングや OCR 向けの画像前処理。

enhance_contrast `staticmethod`

enhance_contrast(
    image, clip_limit=2.0, tile_grid_size=(8, 8)
)

CLAHE でコントラストを強調します。

Parameters:

Name	Type	Description	Default
`image`	`MatLike`	入力画像。	required
`clip_limit`	`float`	クリップ制限値。	`2.0`
`tile_grid_size`	`tuple[int, int]`	タイルグリッドサイズ。	`(8, 8)`

Returns:

Type	Description
`MatLike`	コントラスト強化された画像。

denoise `staticmethod`

denoise(image, strength=7)

ノイズを除去します。

Parameters:

Name	Type	Description	Default
`image`	`MatLike`	入力画像。	required
`strength`	`int`	ノイズ除去強度。	`7`

Returns:

Type	Description
`MatLike`	ノイズ除去された画像。

sharpen `staticmethod`

sharpen(image, kernel_size=5, sigma=1.0, amount=1.0)

アンシャープマスクで輪郭を強調します。

Parameters:

Name	Type	Description	Default
`image`	`MatLike`	入力画像。	required
`kernel_size`	`int`	カーネルサイズ。	`5`
`sigma`	`float`	ガウシアンぼかしのシグマ値。	`1.0`
`amount`	`float`	シャープニング強度。	`1.0`

Returns:

Type	Description
`MatLike`	シャープニングされた画像。

binarize `staticmethod`

binarize(
    image, threshold=None, adaptive=True, inverse=False
)

固定閾値または適応的閾値で二値化します。

Parameters:

Name	Type	Description	Default
`image`	`MatLike`	入力画像。	required
`threshold`	`int \| None`	閾値。`None` の場合は自動決定。	`None`
`adaptive`	`bool`	適応的閾値処理を使用するか。	`True`
`inverse`	`bool`	反転するか。	`False`

Returns:

Type	Description
`MatLike`	二値化された画像。

enhance_for_template_matching `staticmethod`

enhance_for_template_matching(image)

テンプレートマッチング向けの前処理を適用します。

Parameters:

Name	Type	Description	Default
`image`	`MatLike`	入力画像。	required

Returns:

Type	Description
`MatLike`	前処理された画像。

enhance_for_ocr `staticmethod`

enhance_for_ocr(image)

OCR 向けの前処理を適用します。

Parameters:

Name	Type	Description	Default
`image`	`MatLike`	入力画像。	required

Returns:

Type	Description
`MatLike`	前処理された画像。

contains_template

contains_template(
    source_image,
    template_image,
    threshold=0.8,
    method=cv2.TM_CCOEFF_NORMED,
)

指定されたテンプレートが画像内に含まれるかを判定します。

Parameters:

Name	Type	Description	Default
`source_image`	`MatLike`	検索対象の画像。	required
`template_image`	`MatLike`	テンプレート画像。	required
`threshold`	`float`	マッチング閾値。範囲は 0.0-1.0。	`0.8`
`method`	`int`	マッチング手法。`cv2.TM_*` 定数。	`TM_CCOEFF_NORMED`

Returns:

Type	Description
`bool`	テンプレートが含まれている場合は `True`。閾値未達は `False`。

find_template

find_template(
    source_image,
    template_image,
    threshold=0.8,
    method=cv2.TM_CCOEFF_NORMED,
)

テンプレートマッチングを実行し、最良の一致を返します。

Parameters:

Name	Type	Description	Default
`source_image`	`MatLike`	検索対象の画像。	required
`template_image`	`MatLike`	テンプレート画像。	required
`threshold`	`float`	マッチング閾値。範囲は 0.0-1.0。	`0.8`
`method`	`int`	マッチング手法。`cv2.TM_*` 定数。	`TM_CCOEFF_NORMED`

Returns:

Type	Description
`MatchResult`	マッチング結果。

Raises:

Type	Description
`InvalidImageError`	画像データが無効な場合。
`ThresholdNotMetError`	閾値を満たす結果が見つからない場合。
`TemplateMatchingError`	OpenCV の処理に失敗した場合。

リソースと出力

マクロ資材と実行成果物の local file store。

ResourceKind

Bases: StrEnum

資材参照の用途種別。

ResourceSource

Bases: StrEnum

資材または成果物が解決された元の場所。

OverwritePolicy

Bases: StrEnum

成果物保存時の既存ファイル処理方針。

ArtifactScope

Bases: StrEnum

Artifact の保存・読み戻し基準。

ResourcePathError

Bases: ResourceError

資材パスが root 外や不正名を指す場合の例外。

ResourceNotFoundError

Bases: ResourceError

指定された資材が探索 root に存在しない場合の例外。

ResourceReadError

Bases: ResourceError

資材ファイルの読み込みに失敗した場合の例外。

ResourceWriteError

Bases: ResourceError

実行成果物の書き込みに失敗した場合の例外。

ResourceAlreadyExistsError

Bases: ResourceWriteError

上書き禁止の出力先が既に存在する場合の例外。

ResourceConfigurationError

Bases: ResourceError

資材 store の設定や出力 mode が不正な場合の例外。

MacroResourceScope `dataclass`

マクロごとの資材探索範囲を表します。

標準資材は resources/<macro_id>/assets に置きます。マクロ本体パッケージ内の assets は、サンプルや配布形態で資材を同梱する場合の代替探索先です。

artifacts_root `property`

artifacts_root

標準 resource root 配下の artifact 保存 root を返します。

from_definition `classmethod`

from_definition(definition, project_root)

マクロ定義から標準資材 root と代替資材 root を組み立てます。

candidate_asset_paths

candidate_asset_paths(name, guard=None)

資材名に対応する候補パスを探索順に返します。

ResourceRef `dataclass`

解決済み資材または実行成果物の参照情報です。

ResourcePathGuard

Bases: Protocol

資材パスが許可された root の内側に収まることを保証する protocol です。

DefaultResourcePathGuard

相対パスだけを許可し、root 外への脱出と Windows 予約名を拒否します。

resolve_under_root

resolve_under_root(root, name)

資材名を root 配下の安全な絶対パスへ解決します。

ResourceStorePort

Bases: ABC

読み取り専用のマクロ資材 store です。

実装は資材名を安全なパスへ解決し、標準資材 root とマクロパッケージ内の assets を探索対象にできます。

RunArtifactStore

Bases: ABC

マクロ実行ごとの artifact store です。

保存先は resources//artifacts 配下に限定します。実装は scope 解決、親ディレクトリ作成、上書き方針、atomic write、 path guard、保存済み参照の記録を扱います。

LocalResourceStore

Bases: ResourceStorePort

ローカルファイルシステム上のマクロ資材 store です。

resolve_asset_path

resolve_asset_path(name)

探索順に資材を解決し、見つからない場合は ResourceNotFoundError にします。

load_image

load_image(name, grayscale=False)

画像資材を OpenCV 画像として読み込みます。

load_blob

load_blob(name)

任意 bytes 資材を読み込みます。

LocalRunArtifactStore

Bases: RunArtifactStore

ローカルファイルシステム上の artifact store です。

artifact_dir_name `property`

artifact_dir_name

実行ごとの artifact directory 名を返します。

artifacts_overflow_count `property`

artifacts_overflow_count

保持上限を超えて RunResult.artifacts から落とした件数を返します。

snapshot

snapshot()

保存済み artifact 参照の現在の snapshot を返します。

resolve_artifact_path

resolve_artifact_path(name, *, scope=ArtifactScope.RUN)

Artifact 名を scope 配下の安全なパスへ解決します。

resolve_output_path

resolve_output_path(name)

内部移行用に run-scoped artifact path を解決します。

save_image

save_image(
    name,
    image,
    *,
    scope=ArtifactScope.RUN,
    overwrite=None,
    atomic=None,
)

画像を artifact root 配下に保存し、保存後の参照情報を返します。

save_blob

save_blob(
    name,
    data,
    *,
    scope=ArtifactScope.RUN,
    overwrite=None,
    atomic=None,
)

任意 bytes を artifact root 配下に保存します。

load_image

load_image(
    artifact, *, scope=ArtifactScope.RUN, grayscale=False
)

画像 artifact を OpenCV 画像として読み戻します。

load_blob

load_blob(artifact, *, scope=ArtifactScope.RUN)

任意 bytes artifact を読み戻します。

例外

framework core の例外 hierarchy。

ErrorKind

Bases: StrEnum

Framework error の分類。

FrameworkError

Bases: Exception

Framework 全体で扱う code/component 付きの基底例外。

MacroStopException

Bases: FrameworkError

既存 import 互換のため維持する中断例外 adapter。

MacroCancelled

Bases: MacroStopException

協調キャンセルによりマクロ実行スレッドで送出される例外。

DeviceError

Bases: FrameworkError

Device や通信処理が失敗した場合の例外。

ResourceError

Bases: FrameworkError

Resource 読み書きや解決が失敗した場合の例外。

ConfigurationError

Bases: FrameworkError, ValueError

設定値、設定ファイル、実行構成が不正な場合の例外。

MacroRuntimeError

Bases: FrameworkError

Macro 実行中の利用者 code 由来の失敗を表す例外。

ErrorInfo `dataclass`

RunResult に保存する framework error の直列化済み情報。

Runtime が依存する入出力 port interface。

FrameNotReadyError

Bases: DeviceError

Frame source がまだ読み出し可能な frame を持たない場合の例外。

FrameReadError

Bases: DeviceError

Frame source からの frame 読み出しに失敗した場合の例外。

ControllerOutputPort

Bases: ABC

Runtime が controller 入力を送るための出力 port。

FrameSourcePort

Bases: ABC

Runtime が最新 frame を取得するための入力 port。

NotificationPort

Bases: ABC

Runtime が外部通知を送るための port。

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

フレームワーク API リファレンス

マクロライフサイクル

description class-attribute instance-attribute

display_name class-attribute instance-attribute

tags class-attribute instance-attribute

args_schema class-attribute instance-attribute

settings_path class-attribute instance-attribute

initialize abstractmethod

run abstractmethod

finalize abstractmethod

Command

artifact_dir_name abstractmethod property

press abstractmethod

hold abstractmethod

release abstractmethod

wait abstractmethod

stop abstractmethod

log abstractmethod

capture abstractmethod

load_img abstractmethod

load_blob abstractmethod

save_artifact_img abstractmethod

save_artifact_blob abstractmethod

load_artifact_img abstractmethod

load_artifact_blob abstractmethod

keyboard abstractmethod

type abstractmethod

notify abstractmethod

touch

touch_down

touch_up

disable_sleep

定数

Button

Hat

ThreeDSButton

TouchState dataclass

down classmethod

up classmethod

KeyboardOp

KeyCode

SpecialKeyCode

ScaleRounding

ScreenPoint dataclass

ScreenRect dataclass

ScreenSize dataclass

TouchPoint dataclass

LStick

RStick

aspect_fit_rect

cropped_hd_point_to_3ds_touch

cropped_normalized_point_to_3ds_touch

cropped_normalized_point_to_normalized

hd_capture_point_to_3ds_touch

hd_capture_point_to_normalized

normalized_point_to_3ds_touch

normalized_point_to_cropped

normalized_point_to_hd_capture

preview_point_to_3ds_touch

preview_point_to_hd_capture

preview_touch_rect

project_hd_rect_to_preview

scale_point

scaled_source_point_to_3ds_touch

touch_point_to_3ds_hd_capture

touch_point_to_3ds_normalized

try_cropped_hd_point_to_3ds_touch

try_cropped_normalized_point_to_3ds_touch

try_hd_capture_point_to_3ds_touch

try_normalized_point_to_3ds_touch

try_preview_point_to_3ds_touch

try_preview_point_to_hd_capture

try_scaled_source_point_to_3ds_touch

validate_3ds_touch_point

画像処理

ImageProcessingError

InvalidImageError

OCREngineNotFoundError

OCRError

OCRProcessingError

description `class-attribute` `instance-attribute`

display_name `class-attribute` `instance-attribute`

tags `class-attribute` `instance-attribute`

args_schema `class-attribute` `instance-attribute`

settings_path `class-attribute` `instance-attribute`

initialize `abstractmethod`

run `abstractmethod`

finalize `abstractmethod`

artifact_dir_name `abstractmethod` `property`

press `abstractmethod`

hold `abstractmethod`

release `abstractmethod`

wait `abstractmethod`

stop `abstractmethod`

log `abstractmethod`

capture `abstractmethod`

load_img `abstractmethod`

load_blob `abstractmethod`

save_artifact_img `abstractmethod`

save_artifact_blob `abstractmethod`

load_artifact_img `abstractmethod`

load_artifact_blob `abstractmethod`

keyboard `abstractmethod`

type `abstractmethod`

notify `abstractmethod`

TouchState `dataclass`

down `classmethod`

up `classmethod`

ScreenPoint `dataclass`

ScreenRect `dataclass`

ScreenSize `dataclass`

TouchPoint `dataclass`

get_instance `classmethod`

clear_cache `classmethod`

OCRResult `dataclass`

MatchResult `dataclass`

enhance_contrast `staticmethod`

denoise `staticmethod`

sharpen `staticmethod`

binarize `staticmethod`

enhance_for_template_matching `staticmethod`

enhance_for_ocr `staticmethod`

MacroResourceScope `dataclass`

artifacts_root `property`

from_definition `classmethod`

ResourceRef `dataclass`

artifact_dir_name `property`

artifacts_overflow_count `property`

ErrorInfo `dataclass`