🕹

Joystick 2D

Sources
运行在线示例 免费 · 无需注册 · 直接在浏览器中运行

Joystick2D 模块在画布上提供了一个交互式二维双轴摇杆控件,支持在实时仿真期间同时协调控制两个维度的输出信号。拖动圆形摇杆手柄可实时输出水平 XX 与垂直 YY 的二维偏转信号,非常适用于四旋翼无人机姿态指令(横滚与俯仰)、移动机器人线速度与转向角、云台伺服机构或双轴受力扰动等控制场景。该模块具备单位圆径向饱和限幅机制、可配置的增益缩放因子,以及可选的自动弹簧回中功能。

数学模型

用户在画布上将手柄拖动至像素相对位移坐标 (dx,dy)(d_x, d_y)。归一化偏转矢量在单位圆内进行径向约束:

r=dx2+dy2,(xnorm,ynorm)={(dx,dy),r≤1(dxr,dyr),r>1r = \sqrt{d_x^2 + d_y^2}, \quad (x_{\text{norm}}, y_{\text{norm}}) = \begin{cases} (d_x, d_y), & r \le 1 \\ \left(\frac{d_x}{r}, \frac{d_y}{r}\right), & r > 1 \end{cases}

从右侧两个输出端口(xx 和 yy)输出的物理信号由缩放增益 gain (KK) 乘算获得:

xout(t)=K⋅xnorm(t)yout(t)=K⋅ynorm(t)\begin{aligned} x_{\text{out}}(t) &= K \cdot x_{\text{norm}}(t) \\ y_{\text{out}}(t) &= K \cdot y_{\text{norm}}(t) \end{aligned}

当 springReturn = true 时,释放鼠标或触摸按压将使归一化偏转量立即归零:

(xnorm,ynorm)←(0.0,0.0)(x_{\text{norm}}, y_{\text{norm}}) \leftarrow (0.0, 0.0)

当 springReturn = false 时,摇杆手柄将保持在最后一次拖动释放的位置。

输入与输出

Direction ID Label 类型 Status
← Out x X number Output
← Out y Y number Output

参数

参数 Label 类型 默认值 描述
valueX X Value number 0 Current X deflection — written by the on-canvas knob. Bounded with Y to the unit circle (|(x,y)| ≤ 1).
valueY Y Value number 0 Current Y deflection — written by the on-canvas knob. Bounded with X to the unit circle (|(x,y)| ≤ 1).
gain Gain number 1 Output scale: out = deflection × gain
springReturn Spring Return boolean true Snap the knob back to (0,0) when released

使用示例

示例 1: 四旋翼无人机横滚角与俯仰角的手动遥控

交互式控制多旋翼无人机的姿态角设定值。配置参数 gain = 30.0(度)并设置 springReturn = true。将端口 xx 连接至横滚角控制器设定值,端口 yy 连接至俯仰角控制器设定值。用户可实时操纵无人机飞行姿态;松开摇杆手柄后,无人机自动恢复水平平衡。

示例 2: 差速驱动移动机器人的遥控遥测导航

遥控地面自主移动小车。端口 yy 作为前进线速度指令 (vv),配置 gain = 2.0 (m/s);端口 xx 作为偏航角速度指令 (ω\omega),配置 gain = 1.5 (rad/s)。松开手柄即刻安全刹停车辆。

说明与最佳实践

  • 单位圆径向限幅: 对角线偏转被严格限制在矢量模长 x2+y2≤1\sqrt{x^2 + y^2} \le 1 之内,有效避免了对角线过驱现象(例如 ∣(1,1)∣=2≈1.414|(1, 1)| = \sqrt{2} \approx 1.414)。
  • 自动实时同步: 引入 Joystick2D 模块会自动将仿真速率锁定为物理实时时钟同步步进,保证流畅的人机交互体验。
  • 弹簧回中与油门保持模式: 关闭弹簧回中功能(springReturn = false)适用于油门操纵杆或工作点偏置调节,无需操作人员持续按住鼠标。
  • 完美兼容触控与鼠标: 在桌面端鼠标拖拽与移动端/平板触控屏上均具备出色的交互灵敏度。

相关模块

  • Slider: 单轴线性交互式滑块控件。
  • KeyboardInput: 键盘按键输入模块,可通过方向键或 WASD 键实时发送控制信号。
  • XYPlot: 二维轨迹与相平面交互图示仪。
  • Gain: 独立缩放各个信号通道增益的比例环节。