AirControl v1.3.0
本版本重点提升近距离手部与指尖稳定性、输入响应速度、裁剪放大可靠性，并完善配置、打包和自动化测试流程。
This release focuses on near-range hand and fingertip stability, lower input latency, more reliable crop zoom, and a stronger configuration, packaging, and automated testing workflow.
主要亮点 / Highlights
1. 手部与指尖精度 / Hand and Fingertip Precision
- 保留亚像素关键点坐标：避免过早取整造成的细微移动丢失，让近距离慢速移动更加连续。
Sub-pixel landmark coordinates are preserved, preventing small movements from being lost through premature rounding and improving fine near-range motion. - 修正 One Euro 自适应滤波：速度估计改为基于原始观测值，减少滤波延迟被重复反馈的问题，在稳定性和跟手性之间取得更好的平衡。
The One Euro adaptive filter was corrected so speed estimation uses raw observations, reducing feedback-induced lag while retaining jitter suppression. - 鼠标指针采用加权关键点：不再只依赖单一指尖点，而是融合中指尖及相邻关节，降低指尖识别波动造成的光标抖动。
Pointer control now uses weighted landmarks, blending the middle fingertip with nearby joints instead of relying on one unstable point. - 新增精度回归测试：覆盖亚像素坐标、滤波响应和加权指针计算，防止后续修改重新引入抖动问题。
New precision regression tests cover sub-pixel coordinates, filter response, and weighted pointer calculations.
2. 裁剪放大与超分辨率 / Crop Zoom and Super Resolution
- 增强手部丢失后的重新捕获：裁剪区域连续漏检时会周期性回到完整画面检测，更快找回移出局部区域的手。
Faster hand reacquisition periodically retries full-frame detection after crop misses, recovering hands that leave the local crop sooner. - 稳定超分辨率档位切换：加入切换稳定机制，避免在临界尺寸附近频繁启停超分辨率模型。
Super-resolution switching is stabilized, preventing rapid model toggling near size thresholds. - Real-ESRGAN 按需加载：仅在用户明确选择对应模式时加载，避免默认占用大量 CPU、GPU 与内存资源。
Real-ESRGAN is loaded on demand only when explicitly selected, avoiding unnecessary CPU, GPU, and memory use.
3. 板书与全局手势 / Drawing and Global Gestures
- 强化落笔与抬笔状态机：改善侧手、拇指遮挡和短暂识别波动时的笔迹连续性，减少误落笔和断触。
Drawing state transitions were hardened to improve stroke continuity during side views, thumb occlusion, and brief recognition fluctuations. - 全局模式切换更可靠：🤟 保持切换模式的识别器持续观察真实帧，不会因绘图状态或临时预测帧而错误触发。
Global 🤟 mode switching is more reliable because the recognizer continues to observe real frames instead of stale or predicted input. - 轨迹录制默认关闭：
draw_record_trace默认为false，正常使用不会持续生成大型轨迹诊断文件。
Trace recording is disabled by default withdraw_record_trace=false, preventing diagnostic trace files from growing during normal use.
4. 延迟与运行性能 / Latency and Runtime Performance
- 最新帧优先处理：采集线程只保留最新摄像头帧，推理繁忙时自动丢弃过时帧，减少操作“拖尾”。
Latest-frame processing drops stale camera frames when inference is busy, reducing accumulated input lag. - UI 背压控制：限制待处理界面更新，防止帧信号在主线程队列中堆积。
UI backpressure prevents frame updates from accumulating in the main-thread event queue. - 优化图像转换路径：采用直接的 BGR 到 Qt 图像转换，减少不必要的内存复制与颜色转换。
The image conversion path is streamlined with direct BGR-to-Qt conversion, reducing unnecessary copying and conversion work. - 更确定的退出流程：摄像头、推理线程、录制器和语音服务会按顺序释放，降低退出卡住或残留后台进程的概率。
Shutdown is now deterministic, releasing camera, inference, recorder, and voice resources in a controlled order.
5. 配置与稳定性 / Configuration and Reliability
- 原子化保存配置：先写入临时文件再替换正式配置，降低断电或异常退出造成配置损坏的风险。
Configuration is saved atomically, reducing corruption risk during crashes or interrupted writes. - 配置 Schema 校验：错误类型或越界参数会回退到安全默认值，并记录警告而不是导致程序启动失败。
Schema-based validation falls back to safe defaults for invalid values instead of failing at startup. - 统一运行时资源路径：开发环境和 PyInstaller 打包环境使用一致的资源定位逻辑。
Runtime resource paths are unified across source and PyInstaller builds. - 安全重载追踪器与语音命令：运行时配置切换的清理和重建流程更加完整。
Tracker and voice-command reloads are safer, with more complete cleanup and reconstruction during runtime changes. - 改进原始帧诊断能力：出现识别问题时可以记录更有用的输入信息，便于复现和调试。
Raw-frame diagnostics were improved to make recognition issues easier to reproduce and investigate.
6. 打包、测试与持续集成 / Packaging, Testing, and CI
- 重构 Windows PyInstaller 打包配置，并加入无需摄像头或麦克风的
--self-test自检模式。
The Windows PyInstaller configuration was reworked and now includes a hardware-free--self-testmode. - 新增 GitHub Actions 持续集成，在 Python 3.10 和 3.12 环境自动运行检查。
GitHub Actions CI now validates the project on Python 3.10 and 3.12. - 本次发布验证结果：134 项测试通过，另有 132 项子测试通过；Ruff 静态检查、Python 编译检查、PyInstaller 打包和可执行文件自检均通过。
Release verification completed with 134 tests and 132 subtests passing, plus successful Ruff linting, Python compilation, PyInstaller packaging, and executable self-test.
升级说明 / Upgrade Notes
- 建议升级后先使用默认配置测试；旧配置会经过校验，不合法的字段会自动回退。
Test with the default settings after upgrading; existing configuration is validated and invalid fields fall back automatically. Real-ESRGAN_x2plus.onnx约 67 MB，因 GitHub 源码仓库体积限制未纳入版本控制。需要 Real-ESRGAN 模式时，请将该文件放在项目根目录；普通模式和其他功能不依赖它。
Real-ESRGAN_x2plus.onnxis approximately 67 MB and is not tracked in the source repository because of repository size concerns. Place it in the project root when using a Real-ESRGAN mode; normal modes and other features do not require it.- 完整安装、模型配置和打包说明请参阅 README。
See the README for full installation, model setup, and packaging instructions.