トラブルシューティング

このページでは、現場でよく起きる症状を逆引きできるようにまとめています。各項目は「症状 → 考えられる原因 → 対処（操作と数値）」の順に並べています。まず近い症状を探し、対処の手順を上から順に試してください。詳しい解説は各項目末尾のリンク先を参照してください。

調整中はビューワーで確認する

パラメータを変えたときは、メインタブの「表示」メニューで 点群・ブロブ・プレイヤー をオンにして、リアルタイムで効果を確かめながら進めると失敗が少なくなります。詳しくは ビューワーの使い方 を参照してください。

複数人が1つのブロブに見える

近くに立った複数人が1人としてまとめて検出され、Player数が増えない症状です。

考えられる原因

• クラスタリング距離（cluster_distance）が大きく、隣の人の点群までつないでしまっている。
• 背景差分の閾値（background_tolerance）が大きく、人と人の間の床まで前景として残ってしまっている。

対処

手順	パラメータ	現状値	試す値	効果
1	cluster_distance	0.10	0.05	近接した点群を分離しやすくする
2	min_cluster_points	3	5	細かいノイズ塊をブロブにしない
3	background_tolerance	0.03	0.02	人の間の床を前景として拾わない

注意

cluster_distance を下げすぎると、今度は1人が複数のブロブに割れることがあります。人型が2つに割れ始める手前で止めてください。

詳しい解説 → ブロブ検出パラメータ

Player ID が入れ替わる

人が交差したり一瞬重なったりしたときに、Player ID が別の人に移ってしまう症状です。受信側で「同じ人なのにIDが変わった」「2人のIDが入れ替わった」ように見えます。

考えられる原因

• マッチング距離（max_match_distance）が大きく、フレーム間で別の人と取り違えている。
• 位置がジッター（小刻みに揺れる）していて、トラッカーが安定して追えていない。
• 一時的なノイズや遮蔽で、ブロブが1フレーム消えてIDが解放されている。

対処

手順	パラメータ	現状値	試す値	効果
1	max_match_distance	0.5	0.3	遠い別の人へIDが飛び移るのを防ぐ
2	median_window	0（無効）	3〜5	外れ値を除いて位置を安定させる
3	smoothing_mode	none	ema（smoothing_factor 0.7）または one_euro	位置を滑らかにして追跡を安定させる
4	lost_timeout_frames	30	大きめ	一瞬の消失でIDを手放さない
5	max_velocity	0（無制限）	1.0	1m超の瞬間移動（ID飛び）を無視する

ノート

まずは「モニター」タブの トリガーログ でID変化のタイミングを確認すると、交差時に起きているのか、消失時に起きているのか切り分けられます。

詳しい解説 → トラッキングパラメータ

ノイズ・誤検出が多い

人がいないのにブロブやプレイヤーが現れる、点群がチラチラして検出が不安定、といった症状です。

考えられる原因

• 最小クラスタ点数（min_cluster_points）が小さく、わずかな点でもブロブになっている。
• 背景差分の閾値（background_tolerance）が小さすぎて、センサの測定誤差まで前景として拾っている。
• 位置にジッターがあり、出力が安定しない。

対処

手順	パラメータ	現状値	試す値	効果
1	min_cluster_points	3	5〜8	小さなノイズ塊をブロブにしない
2	background_tolerance	0.03	0.04〜0.05	測定誤差を前景として拾わない
3	median_window	0（無効）	3〜5	突発的な外れ値を除去する
4	new_blob_confirm_frames	3	大きめ	一瞬だけのノイズをPlayer化しない
5	min_blob_radius / max_blob_radius	0.01 / 1.0	検出対象に合わせて調整	想定サイズ外の塊を無視する

ヒント

min_cluster_points や background_tolerance を上げすぎると、本来検出したい小さな対象（指先・細い棒など）まで見落とします。ノイズが消える最小限の値に留めてください。検出対象に近いプリセット（細い棒 / 手 / 人体）から始めると調整が楽です。

背景差分が原因の場合は、後述の「背景差分がおかしい」も確認してください。

詳しい解説 → ブロブ検出パラメータ / トラッキングパラメータ

OSCが届かない

LiTouchは検出できているのに、受信側ソフト（TouchDesigner / Max / Pure Data など）にOSCが届かない症状です。

考えられる原因

• 送信先のIPアドレス・ポートが受信側の待ち受けと一致していない。
• 送信先の「有効」がオフになっている。
• 送りたいメッセージ種別がオフになっている。
• PCのファイアウォールがUDP送信をブロックしている。

対処

ヒント

まず「OSC」タブの テスト送信 で仮想プレイヤーを動かし、受信側に届くか確認してください。テスト送信が届けば、設定は正しく、検出側（背景・ブロブ・ゾーン）の問題に絞り込めます。届かなければ、送信先設定かネットワークの問題です。

1. 送信先設定を確認する。 「OSC」タブの送信先テーブルで、受信側が待ち受けている IPアドレス と ポート（例: 127.0.0.1 / 9000）が正しいか、有効 がオンかを確認します。
2. メッセージ種別を確認する。 受信側で期待しているメッセージ（player/count、position など）がオンになっているか確認します。
3. 送信状態とエラーを確認する。 送信先テーブルの送信状態と、「モニター」タブの システム状態 でOSCの送信失敗件数を確認します。失敗が増えていれば送信先到達性の問題です。
4. ファイアウォールを確認する。 PCのファイアウォールでLiTouchのUDP送信が許可されているか確認します。別PCへ送る場合は、両者が同じネットワークにあるかも確認してください。
5. 本当に送信できているか確認する。 「モニター」タブの OSCモニター で、送信中のアドレスと値がリアルタイムに流れているか確認します。

詳しい解説 → OSC送信先の設定 / テスト送信 / メッセージ種別

センサに接続できない

センサを追加しても接続できない、点群が表示されない症状です。

考えられる原因

• IPアドレス・ポートがセンサの設定と一致していない。
• PCとセンサが同じネットワークにない。
• LANケーブル・電源・センサ本体の問題。

対処

1. 接続状態ドットの色を確認する。 センサ一覧とヘッダーの状態ドットで状態を判断します。

   色	状態	対処
   緑	スキャン中	正常。点群が見えなければ表示メニューで「点群」をオンに
   橙	接続中 / 再接続中	しばらく待つ。橙のままなら下記を確認
   灰	切断	「接続」ボタンを押す
   赤	エラー	IP・ポート・ケーブル・電源を確認

2. IP・ポートを確認する。 工場出荷時は IP 192.168.0.10 / ポート 10940 です。変更している場合はその値を入力します。

3. ネットワークを確認する。 PCとセンサのIPが同じネットワーク（例: 192.168.0.x）にあるか、LANケーブルが正しく挿さっているか、センサの電源が入っているかを確認します。

4. 自動再接続を待つ。 一度接続できていれば、通信が切れてもLiTouchが自動で再接続を試みます（指数バックオフ：1秒から最大30秒間隔）。ネットワーク復旧後に緑へ戻るのを待ちます。

詳しい解説 → センサの接続

背景差分がおかしい

何もないのに点群全体が前景として検出される、または逆に人が立っても検出されない症状です。背景差分の基準が現状と合っていないことが原因です。

考えられる原因

• 背景キャプチャをしていない、または古い。
• センサや設置物を動かした後に背景を取り直していない。
• 背景キャプチャ時に視野内に人や物が残っていた。

対処

注意

背景キャプチャは、検出範囲に人や物が 何も無い状態 で行ってください。人が映ったままキャプチャすると、その人が「背景」として記録され、以降そこに立っても検出されなくなります。

1. 背景を取り直す。 検出範囲を空にして、背景キャプチャの「キャプチャ」を押します。状態表示に「キャプチャ済み（◯秒前 / ◯点 / ◯セル）」と出ることを確認します。
2. 閾値を見直す。 取り直しても合わない場合は background_tolerance（既定 0.03）を調整します。全体が前景になるなら上げ、人が検出されないなら下げます。
3. 背景差分を一時的に切る。 検証目的で background_enabled をオフにすると、背景差分なしの素のクラスタリング結果を確認できます。

詳しい解説 → 背景キャプチャ / ブロブ検出パラメータ

関連ページ

パラメータ一覧 ここで触れた全パラメータの範囲・初期値・意味を表で確認できます。

システム状態 Pipeline・OSC・UDPトリガーの稼働状況とエラーを俯瞰します。

長時間運用とフェイルセーフ 自動再接続・パニック復帰など、止めない運用のための仕組みです。

用語集 ブロブ・トラッカー・背景差分などの用語の定義集です。