パラメータ一覧

このページは、LiTouchの設定値を一覧で確認するためのリファレンスです。各パラメータの 意味・範囲・初期値 をセクションごとの表にまとめています。操作手順や調整の考え方は、各表のあとのリンク先（操作ページ）を参照してください。

設定ファイルの保存先

すべての設定は config.toml に自動保存されます。UIで変更すると即座に書き込まれるため、通常は手で編集する必要はありません。

OS	パス
macOS	`~/Library/Application Support/li-touch/config.toml`
Windows	`%APPDATA%\li-touch\config.toml`

Plane（検出面）

処理パイプラインの基本単位です。床・壁などの検出面ごとに1つ作ります。

フィールド	型 / 範囲	初期値	説明
`id`	文字列	自動	Planeの一意なID
`name`	文字列	`Plane 1` 等	表示名（ダブルクリックで変更）
`enabled`	真偽	`true`	このPlaneの処理を有効にするか
`mode`	`"player"` / `"contour"`	`"player"`	出力モード。プレイヤー検出か輪郭点列か

操作 → 複数Planeの運用

Sensor（センサ）

各Planeに割り当てるHokuyo LiDARデバイスの設定です。複数台を同時に接続できます。

フィールド	型 / 範囲	初期値	説明
`id`	文字列	自動	センサの一意なID
`plane_id`	文字列	自動	所属するPlaneのID
`ip`	文字列	`"192.168.0.10"`	センサのIPアドレス
`port`	整数	`10940`	センサのポート番号
`position`	`[x, y]`（m）	`[0, 0]`	センサの設置位置（ワールド座標）
`rotation`	度	`0`	センサの設置角度
`invert`	真偽	`false`	左右反転（倒立設置時に使用）
`enabled`	真偽	`true`	このセンサを使用するか

操作 → センサの接続 / センサのアライン

Merge（マージ）

Plane内の複数センサの点群を1つの座標系に統合する際のパラメータです。通常は初期値のままで問題ありません。

フィールド	型 / 範囲	初期値	説明
`distance_threshold`	m	`0.05`	重複点とみなす距離。これより近い点はまとめる

操作 → 複数センサとマージ

BlobDetector（ブロブ検出）

背景差分とクラスタリングで物体の塊（ブロブ）を検出するパラメータです。

フィールド	型 / 範囲	初期値	説明
`background_enabled`	真偽	`true`（ON）	背景差分の有効 / 無効
`background_tolerance`	`0.01`〜`0.5`（m）	`0.03`	背景との距離差分の閾値。敏感すぎたら上げ、見落とすなら下げる
`cluster_distance`	`0.02`〜`1.0`（m）	`0.10`	クラスタリング距離の閾値。接近時に分離したいなら下げ、つなぎすぎなら上げる
`min_cluster_points`	`1`〜`100`	`3`	ブロブとみなす最小点数。高くするとノイズに強いが感度が落ちる
`max_cluster_points`	`10`〜`5000`	`500`	ブロブとみなす最大点数。大きな物体を分割したいなら下げる
`min_blob_radius`	`0`〜`1.0`（m）	`0.01`	これ未満の半径のブロブを無視（既定で10mm未満を無視）
`max_blob_radius`	`0.01`〜`5.0`（m）	`1.0`	これを超える半径のブロブを無視（既定で1m超を無視）

操作 → ブロブ検出パラメータ

Tracker（トラッキング）

フレーム間でブロブを追跡し、Player ID を割り当てるパラメータです。

フィールド	型 / 範囲	初期値	説明
`enabled`	真偽	`true`（ON）	トラッキングの有効 / 無効
`max_match_distance`	`0.05`〜`5.0`（m）	`0.5`	フレーム間で同一とみなす最大距離。IDが入れ替わるなら下げる
`lost_timeout_frames`	`1`〜`300`	`30`	消失からID解放までのフレーム数。一時ノイズでIDが消えるのを防ぐ
`new_blob_confirm_frames`	`1`〜`60`	`3`	新規Player確定までのフレーム数。ノイズをPlayer化したくないなら上げる
`use_prediction`	真偽	`true`（ON）	速度予測の有効 / 無効。通常はON
`max_players`	`1`〜`128`	`16`	最大同時トラッキング数。多人数なら増やす（CPUコスト増）
`max_velocity`	`0`〜`2.0`（m）	`0`（無制限）	1フレームの最大移動量。`1.0` で1m超の瞬間移動を無視（ID飛び防止）
`median_window`	`0`〜`9`	`0`（無効）	メディアンフィルタの窓。`3`〜`5` でジッター除去
`smoothing_mode`	`none` / `ema` / `one_euro`	`none`	位置スムージングの方式
`smoothing_factor`	`0`〜`0.95`	`0.5`	EMAの平滑係数。高いほど慣性が強い
`one_euro_min_cutoff`	`0.01`〜`10`（Hz）	`1.0`	One Euro最小カットオフ。ジッター除去の強さ
`one_euro_beta`	`0`〜`1.0`	`0.007`	One Euro速度係数。高速移動への追従
`one_euro_d_cutoff`	`0.1`〜`10`（Hz）	`1.0`	One Euro微分カットオフ
`trim_start_frames`	`0`〜`60`	`0`	新規確定直後の出力抑制フレーム数。OSC誤送信防止
`trim_end_frames`	`0`〜`60`	`0`	消失時の末尾ノイズ除去の遅延フレーム数。消失時のガタつき防止

操作 → トラッキングパラメータ / パラメータプリセット

CanvasZone（キャンバスゾーン）

Plane座標上の矩形 / 四角形領域です。ゾーン内のプレイヤーを検出し、正規化UV座標を算出します。

フィールド	型 / 範囲	初期値	説明
`id`	文字列	自動	ゾーンの一意なID
`plane_id`	文字列	自動	所属するPlaneのID
`name`	文字列	自動	表示名
`center`	`[x, y]`（m）	`[0, 0]`	ゾーン中心のワールド座標
`width`	m	`1.0`	ゾーンの幅
`height`	m	`1.5`	ゾーンの高さ
`rotation`	度	`0`	ゾーンの回転角
`osc_prefix`	文字列	`"/zone/1"` 等	OSCアドレスの先頭（例: `/floor/a`）
`corners`	4点	省略時は矩形	自由四角形の四隅。指定するとホモグラフィで正規化
`mode`	`"player"` / `"contour"`	`"player"`	ゾーンの出力モード
`triggers`	配列	`[]`	このゾーンに紐づくUDPトリガー
`masks`	配列	`[]`	ポリゴンマスク
`mask_images`	配列	`[]`	イメージマスク

操作 → キャンバスゾーン

MaskPolygon（ポリゴンマスク）

ゾーン内で検出から除外する多角形領域です。

フィールド	型 / 範囲	初期値	説明
`id`	文字列	自動	マスクの一意なID
`name`	文字列	自動	表示名
`vertices`	頂点配列（最少3点・ワールド座標）	既定は正方形	多角形の頂点。辺ダブルクリックで追加、Deleteで削除
`enabled`	真偽	`true`	このマスクを有効にするか

操作 → ポリゴンマスク

MaskImage（イメージマスク）

白黒画像（PNG / JPEG / BMP）で除外領域を定義します。

フィールド	型 / 範囲	初期値	説明
`id`	文字列	自動	マスクの一意なID
`name`	文字列	自動	表示名
`path`	文字列	—	画像パス（`<config>/li-touch/` からの相対。例: `masks/shape.png`）
`threshold`	`0`〜`1`	`0.5`	白黒の判定閾値
`invert`	真偽	`false`	反転（黒通過 / 白除外に切り替え）
`choke_m`	m	`0.0`	マスクの拡縮。正 = erosion（縮小）/ 負 = dilation（拡張）
`enabled`	真偽	`true`	このマスクを有効にするか

操作 → イメージマスク

ZoneTrigger（ゾーントリガー）

ゾーンのイベント発生時に、外部機器へUDPメッセージを送る設定です。

フィールド	型 / 範囲	初期値	説明
`event`	`"OnEnter"` / `"OnExit"` / `"OnNewTouch"`	—	発火条件（進入 / 退出 / 新規タッチ）
`destination`	名前 / IP / ポート / メッセージ	—	送信先と送るメッセージ（例: `PLAY\r\n`）
`cooldown_ms`	整数（ミリ秒）	`0`	連続発火を抑制する待機時間
`enabled`	真偽	`true`	このトリガーを有効にするか

操作 → ゾーントリガー

OSC

OSC送信全体の設定です。

フィールド	型 / 範囲	初期値	説明
`destinations`	配列	`[]`	送信先のリスト（下表参照）
`send_rate`	`0.0` / `30` / `60` / `120`（Hz）	`0.0`	送信レート。`0.0` = スキャン同期（約40fps）、それ以外は線形補間
`bundle_mode`	真偽	`true`	複数メッセージを1つのバンドルにまとめて送る
`messages.player_count`	真偽	—	`player/count` の送信 ON / OFF
`messages.position`	真偽	—	`player/{id}/position` の送信 ON / OFF
`messages.alive`	真偽	—	`alive` の送信 ON / OFF
`messages.velocity`	真偽	—	`velocity` の送信 ON / OFF
`messages.direction`	真偽	—	`direction` の送信 ON / OFF
`messages.enter`	真偽	—	`enter` の送信 ON / OFF
`messages.exit`	真偽	—	`exit` の送信 ON / OFF
`messages.debug`	真偽	—	デバッグメッセージの送信 ON / OFF

操作 → OSC送信先の設定 / メッセージ種別

OSCDestination（送信先）

フィールド	型 / 範囲	初期値	説明
`name`	文字列	—	送信先の表示名
`ip`	文字列	`"127.0.0.1"`	送信先IPアドレス
`port`	整数	`9000`	送信先ポート
`enabled`	真偽	`true`	この送信先を有効にするか

Log（ログ）

フィールド	型 / 範囲	初期値	説明
`level`	`"debug"` / `"info"` / `"warn"` / `"error"`	`"info"`	ログレベル
`file_enabled`	真偽	`false`	ファイル出力の有効 / 無効
`file_max_bytes`	バイト	`1048576`（512KB超でローテーション・1世代）	ログファイルの最大サイズ

操作 → ログ出力

AppSettings（アプリ設定）

フィールド	型 / 範囲	初期値	説明
`start_in_production_mode`	真偽	`false`	起動時に本番モードで開始するか

操作 → 本番モード