Files
QFT/README.md
T
2026-08-11 13:43:31 +08:00

159 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# QFT · 超速二维码文件传输 v0.4.7
Windows + Android 双向候选版。v0.4 的核心目标不是继续堆“4 码理论吞吐”,而是解决 Android 端实际识别慢的问题:**删除 2×2/4 通道,改成一个大二维码 + 动态 ROI 锁定 + 高频局部解码**。
两个方向仍然采用不同链路:
- **Windows → Android:纯光学**。文件数据只经过 Windows 屏幕 → Android 摄像头;Wi‑Fi、蓝牙、局域网和互联网都不参与文件数据传输。
- **Android → Windows:扫码本地直连**。Windows 选择保存目录并启动 QFT Direct/LAN 接收服务;Android 扫码、配网、自动发现电脑,然后并行分块上传,不经过外网。
> v0.4.7 已完成协议、图像合成解码、ROI、双向并发传输、UDP 发现、内存预算和关键 Kotlin 源码测试。当前生成环境没有真实 Windows 显示器、Android 相机或 Wi‑Fi Direct 适配器,因此物理 30/45/60 FPS 和真实扫码配网仍需在你的设备上跑 `VERIFY_WINDOWS_HOST.ps1` 后做最终验收;详见 `TEST_REPORT.md`。
## v0.4 光学链路改动
### 单码替代 4 码
4 码已从主链路彻底删除。原因是实际手机相机里,每个 QR 变小后会同时带来:
- 每模块像素下降;
- finder 搜索次数增加;
- Android 同帧多次 ZXing 解码;
- 更高的摩尔纹/滚动快门敏感度;
- Windows 理论 B/s 提升,但 Android “有效新帧/s”可能反而下降。
v0.4 把全部屏幕和解码预算投入一个大 QR。
### QFT2 + Base45 低密度帧
活跃光学协议升级为 `QFT2:`:
- 二进制帧仍包含 session / sequence / total / payload / CRC32;
- 文本层使用 RFC 9285 Base45;
- Base45 字符集属于 QR 字母数字模式可编码范围;
- DATA payload 默认 **450 B**;
- QR 使用 L 级纠错和完整 4-module quiet zone;
- 合成测试中的 450 B DATA 帧为 **QR-L v15**,旧 QFT1/Base64 480 B 对照约为 v18;
- 60 显示帧/s 的理论纯 payload 为 `450 × 60 = 27,000 B/s ≈ 26.4 KiB/s`,真实速度取决于相机真实分析 FPS 和有效新帧率。
Android 仍保留 QFT1 解析用于旧发送端兼容。
## Android 识别优化
### Acquire → Lock → Expand → Reacquire
扫描器状态机现在是:
```text
搜索大二维码
↓
ZXing finder points
↓
建立方形 ROI
↓
后续只复制/解码 ROI
↓
轻微移动:平滑跟随
↓
连续 miss:逐级扩大 ROI
↓
持续丢失:重新全局搜索
```
Android UI 会实时画出真正使用的锁定区域:
- 未锁定:白色搜索角标;
- 稳定锁定:绿色框 + 外围暗化;
- 临时 miss:黄色框;
- 锁定区域随 finder points 平滑移动,减少抖动;
- 锁定后周期性在 ROI 中心重新触发 AF/AE。
### 高频解码热路径
- `ImageAnalysis` 固定为 **640×480**;
- `STRATEGY_KEEP_ONLY_LATEST`,不追赶过时相机帧;
- Camera2Interop 从后摄实际公布的 AE FPS ranges 里选择最高不超过 60 的范围,并同时应用到 Preview/ImageAnalysis;若 OEM 拒绝该流组合,会自动回退相机默认 FPS,而不是让扫描器启动失败;
- 单个 `QRCodeReader`,无 4-reader 线程池;
- 锁定后只复制 Y 平面 ROI;
- `GrayFrameBuffer` 复用 grow-only `ByteArray`,降低 Android 7/8 GC;
- 常态使用 `GlobalHistogramBinarizer`;Hybrid 只在周期性 miss 时兜底;
- 重复显示帧虽然计入“成功解码”,但不再重复送入文件 assembler;UI 单独显示“解码/s”和“新帧/s”。
## Windows 光学 UI
Windows 光传页面已经改成“二维码优先”:
- 左侧控制区 / 右侧二维码区;
- 中间分隔条可拖动,压缩控制区后 QR 自动变大;
- “专注二维码”一键收起大部分控制 UI;
- QR 画面占比可调;
- FPS 5~60,快捷 30 / 45 / 60;
- 单个大 QR,NEAREST 纹理采样,避免插值模糊;
- 1024×1024 预编码画布,使用整数 module 像素和完整静区;
- 后台 Rayon 并行预编码未来帧,前台只复用一个 GPU TextureHandle。
推荐初次真机测试从 **30 FPS** 开始,看 Android 的“新帧/s”,再切 45、60。目标不是 Windows 数字最大,而是 Android **实际新帧/s 最大**。
## Android → Windows
v0.3 的稳定性优化继续保留:
- QFTPAIR2 紧凑配对 QR;
- QFT Direct 或当前局域网;
- Android 10+ `WifiNetworkSpecifier`;Android 7~9 legacy Wi-Fi;
- 扫码连接后 UDP `QFTDISC2` 快速发现;
- gateway / endpoint / 当前子网 fallback;
- HTTP 请求明确绑定扫码建立的 `Network`;
- 单文件最高 8 worker 并行;
- 4/8/16 MiB 自适应上传块;
- Windows positioned writes + `.qftpart` + SHA-256 + 最终 rename。
## Android 版本
- `minSdk = 24`,即 Android 7.0;
- Android 7~9:旧 Wi-Fi 与 Downloads 写入兼容;
- Android 10+:WifiNetworkSpecifier + MediaStore;
- Android 13+:NEARBY_WIFI_DEVICES 权限。
## 构建
### Windows
```powershell
cd windows
cargo check
cargo test
cargo build --release
cargo run --release
```
### Android
JDK 17,compileSdk/targetSdk 35,minSdk 24:
```powershell
cd android
.\gradlew.bat :app:testDebugUnitTest :app:assembleDebug
```
APK:
`android/app/build/outputs/apk/debug/app-debug.apk`
## 字体
Windows UI 优先读取 `windows/assets/qft-ui.ttf`,也可用 `QFT_FONT_PATH` 指向你自己的中文 TTF。仓库不附带第三方字体文件。
## 自动验证
```bash
python scripts/run_all_selftests.py
```
Windows 主机建议直接:
```powershell
.\VERIFY_WINDOWS_HOST.ps1
```
它会继续执行 Rust `cargo check/test/build` 和 Android Gradle 单测/APK 构建。物理相机/屏幕和 Wi‑Fi Direct 项目见 `TEST_REPORT.md`。