OSCアドレス仕様

このページは、LiTouchが送信するOSCメッセージのアドレスと引数のリファレンスです。受信側ソフト（TouchDesigner / Max / Pure Data など）でアドレスを設計するときに参照してください。実際の送信ON/OFFや送信先設定はメッセージ種別と OSC送信先の設定を参照してください。

アドレスの組み立て方

各メッセージのアドレスは、ゾーンの osc_prefix を先頭に付けて組み立てられます。以下では osc_prefix を {prefix}、Player IDを {id} と表記します。

たとえばゾーンの osc_prefix が /floor/a、Player IDが 1 のとき、位置メッセージのアドレスは次のようになります。

/floor/a/player/1/position

{prefix} はゾーンごとに設定できるため、複数ゾーンを別アドレス空間で受信できます。osc_prefix の設定方法はキャンバスゾーンを参照してください。

Playerモードのアドレス一覧

Planeまたはゾーンが Playerモード のときに送られるメッセージです。各メッセージの送信ON/OFFはメッセージ種別で個別に切り替えられます。

アドレス	引数	意味
`{prefix}/player/count`	整数	ゾーン内のプレイヤー数
`{prefix}/player/{id}/position`	x, y（float, 0〜1）	正規化UV座標による位置
`{prefix}/player/{id}/alive`	生存状態	プレイヤーが存在しているか
`{prefix}/player/{id}/velocity`	速度	プレイヤーの移動速度
`{prefix}/player/{id}/direction`	進行方向	プレイヤーの移動方向
`{prefix}/player/{id}/enter`	進入	プレイヤーがゾーンへ進入した瞬間
`{prefix}/player/{id}/exit`	退出	プレイヤーがゾーンから退出した瞬間

正規化UV座標の意味

position の引数は 正規化UV座標 です。ゾーンの左下を (0, 0)、右上を (1, 1) として、ゾーン内の位置を 0〜1 の範囲で表します。

ゾーンの幅・高さ（メートル）や設置の向きに関わらず、常に 0〜1 で届きます。
受信側は解像度や物理サイズに依存せず扱えます。たとえば position の x をそのまま映像の横位置（画面幅 × x）にマッピングできます。
自由四角形（corners を指定したゾーン）では、ホモグラフィによって台形の投影面でも正しく 0〜1 に正規化されます。

Contourモードのアドレス

PlaneまたはゾーンのモードがContourのときは、プレイヤー単位ではなく 輪郭の点列 を送ります。テスト送信のContourモードでは、ダミーの点列が /points 系のアドレスで送られます。点数はテスト送信の設定で指定できます。

アドレス	引数	意味
`{prefix}/points` 系	点列	輪郭を表す点の並び

詳しい挙動はテスト送信で確認できます → テスト送信

送信レート

送信レートは送信先設定の send_rate で決まります。

設定値	動作
`0.0`（スキャン同期）	センサのスキャンに同期して送信（約40fps）
`30` / `60` / `120`（Hz）	指定レートで線形補間して送信

バンドルモード

bundle_mode をオンにすると、1回の送信に含まれる複数のメッセージを OSCバンドル にまとめて送ります。

同じタイミングのメッセージがまとめて届くため、受信側でフレーム単位の整合が取りやすくなります。
受信側がOSCバンドルに対応していない場合は、オフにして個別メッセージとして送ってください。

設定方法は OSC送信先の設定を参照してください。