# QFT · 超速二维码文件传输 v0.4.6 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.6 已完成协议、图像合成解码、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`。