04-功能详解

功能详解

TUIO 1.1 协议详解

TUIO 1.1 定义了以下 OSC 消息集合：

2D 光标 (2Dcur) — 触摸和拖拽事件：
/tuio/2Dcur source
/tuio/2Dcur alive ...
/tuio/2Dcur set
/tuio/2Dcur fseq

2D 物体 (2Dobj) — fiducial 标记：
/tuio/2Dobj source
/tuio/2Dobj alive ...
/tuio/2Dobj set
/tuio/2Dobj fseq

关键概念

每个触控点或物体在生命周期内拥有唯一的 SID（Session ID）。当触控点/物体首次出现时分配新 SID，消失后该 SID 不再使用。

Alive 机制

每帧发送一个 /alive 消息，列出当前所有活跃的 SID。接收端对比当前帧和上一帧的 alive 列表，确定哪些 SID 是新增、保持或已移除。

典型的帧序列：

/tuio/2Dcur alive 0 1 2        ← 当前活跃: SID 0,1,2
/tuio/2Dcur set 0 0.5 0.3 ...  ← SID 0 的位置
/tuio/2Dcur set 1 0.7 0.6 ...  ← SID 1 的位置
/tuio/2Dcur set 2 0.2 0.8 ...  ← SID 2 的位置
/tuio/2Dcur fseq 42             ← 帧编号

坐标系统

TUIO 使用归一化坐标（0.0 ~ 1.0）：
X: 0.0 = 左边缘，1.0 = 右边缘
Y: 0.0 = 上边缘，1.0 = 下边缘
原点在左上角

NexTuio 画布自动完成像素坐标到归一化坐标的转换。

光标模式详解

构建 alive 列表（所有活跃光标 SID）
发送 source 消息（每会话一次）
发送 alive 消息
对每个活跃光标发送 set 消息（含位置、速度）
发送 fseq 消息（帧序号递增）

速度计算

NexTuio 自动计算光标移动速度（dx, dy）和加速度（motionAccel），基于连续帧的位置变化。

物体模式详解

物体模式模拟 reacTIVision 风格的 fiducial 标记识别。每个物体有：
SID：唯一会话 ID
CID（Class ID）：标记类型（0-255），对应不同的 fiducial 图案
位置：归一化坐标 (x, y)
角度：标记旋转角度（弧度，0-2π）

物体生命周期

创建：点击画布 → 设置 CID 和角度 → 物体加入 alive 列表
更新：拖拽/旋转 → 定时发送 set 消息更新位置/角度
销毁：右键删除 → 物体从 alive 列表移除

多点触控模式详解

多点触控使用锚点（Anchor）管理多手指状态：
每个锚点有唯一的 SID
按下添加锚点，移动更新位置，抬起移除锚点
alive 列表维护所有活跃锚点

同时触控数

当前版本不限制同时触控数，受限于操作系统和硬件性能。实际应用中 2-10 个触控点较为常见。

接收端工作流程

UDP 数据到达监听端口
    ↓
解析 OSC 消息
    ↓
判断消息类型 (2Dcur / 2Dobj)
    ↓
更新内部状态 (alive + set)
    ↓
刷新对象树 (50ms 定时器)
    ↓
更新画布渲染
    ↓
日志记录

Alive 解析

接收端对比每次的 alive 列表：
新增：当前 alive 中有但上一帧没有 → 创建新对象
保持：两帧都在 → 更新位置
移除：上一帧有但当前没有 → 删除对象

坐标转换

画布像素坐标 ↔ TUIO 归一化坐标的转换：
x_tuio = x_pixel / canvas_width
y_tuio = y_pixel / canvas_height

程序自动完成转换，用户操作画布时看到的是像素空间。

对象树刷新

对象树通过 50ms 定时器刷新，平衡实时性和性能。在高速触控场景下可能存在轻微延迟。