V0.4.0加入锁定二维码
This commit is contained in:
@@ -1,99 +1,134 @@
|
||||
# QFT · 超速二维码文件传输 v0.3.0-rc3
|
||||
# QFT · 超速二维码文件传输 v0.4.0-rc2
|
||||
|
||||
Windows + Android 双向候选版。两个方向采用不同链路:
|
||||
Windows + Android 双向候选版。v0.4 的核心目标不是继续堆“4 码理论吞吐”,而是解决 Android 端实际识别慢的问题:**删除 2×2/4 通道,改成一个大二维码 + 动态 ROI 锁定 + 高频局部解码**。
|
||||
|
||||
- **Windows → Android:纯光学**。文件数据只经过 Windows 屏幕 → Android 摄像头;不使用 Wi‑Fi、蓝牙、局域网或互联网。
|
||||
- **Android → Windows:扫码本地直连**。Windows 选择保存目录并启动 QFT Direct 临时 Wi‑Fi/接收服务;Android 扫码后请求配网、自动发现电脑,然后并行分块上传。文件不经过外网。
|
||||
两个方向仍然采用不同链路:
|
||||
|
||||
> rc3 是性能/兼容性候选版。仓库内的协议、二维码、并行上传、UDP 发现、内存预算与 Kotlin 关键源文件测试已通过;真正的 Windows Wi‑Fi Direct 驱动、Windows 防火墙、60Hz 显示器与不同 Android 相机组合仍必须在真实设备上做验收,详见 `TEST_REPORT.md`。
|
||||
- **Windows → Android:纯光学**。文件数据只经过 Windows 屏幕 → Android 摄像头;Wi‑Fi、蓝牙、局域网和互联网都不参与文件数据传输。
|
||||
- **Android → Windows:扫码本地直连**。Windows 选择保存目录并启动 QFT Direct/LAN 接收服务;Android 扫码、配网、自动发现电脑,然后并行分块上传,不经过外网。
|
||||
|
||||
## v0.3.0-rc3 针对性优化
|
||||
> rc2 已完成协议、图像合成解码、ROI、并行上传、UDP 发现、内存预算和关键 Kotlin 源码测试。当前生成环境没有真实 Windows 显示器、Android 相机或 Wi‑Fi Direct 适配器,因此物理 30/45/60 FPS 和真实扫码配网仍需在你的设备上跑 `VERIFY_WINDOWS_HOST.ps1` 后做最终验收;详见 `TEST_REPORT.md`。
|
||||
|
||||
### 1. Windows → Android:最高 60 FPS 显示目标
|
||||
## v0.4 光学链路改动
|
||||
|
||||
- Windows UI 支持 `1~60 FPS`,提供 15/30/60 与“极速预设”。
|
||||
- 默认 **4 QR/页 + 60 FPS**,每次刷新最多承载 4 个独立 QFT1 数据帧。
|
||||
- 单 QR payload 默认 900 B;理论原始文件载荷约 `900 × 4 × 60 = 216,000 B/s`(约 210.9 KiB/s),实际速度取决于显示器刷新率、Android 相机 FPS、曝光/滚动快门和识别率。
|
||||
- Android 光学扫描采用 1280×720 分析帧、4 象限并行 ZXing 解码、`KEEP_ONLY_LATEST`、Y 平面直接读取且不再整帧旋转。
|
||||
- Windows 预编码使用 Rayon 多核并行;GPU 纹理复用,不再每帧创建新的纹理对象。
|
||||
- UI 动态显示目标 FPS、实际页面 FPS、理论载荷和 Android 实际“相机 FPS / 有效 QR/s”。
|
||||
### 单码替代 4 码
|
||||
|
||||
### 2. 文件与内存优化
|
||||
4 码已从主链路彻底删除。原因是实际手机相机里,每个 QR 变小后会同时带来:
|
||||
|
||||
- Windows 光学源文件不做整文件 mmap;使用定位读取,避免大文件被整体映射/触碰进工作集。
|
||||
- 预编码缓存硬设计目标:整进程约 **≤ 1100 MiB**。
|
||||
- 4 QR / 960px 模式缓存最多 192 页,估算约 **675 MiB**;另为 UI、WGPU/GPU staging、线程栈、二维码临时对象和系统 I/O 留出余量。
|
||||
- Android → Windows 每个文件内部最高 **8 路并行**。
|
||||
- 分块根据文件大小自适应:小文件 4 MiB、中型 8 MiB、大文件 16 MiB;每个 worker 仅使用约 1 MiB 应用层 I/O buffer。
|
||||
- Windows 端预分配 `.qftpart`,多个独立文件句柄按 offset 写入,完成后 SHA-256 校验并原子改名。
|
||||
- 每模块像素下降;
|
||||
- finder 搜索次数增加;
|
||||
- Android 同帧多次 ZXing 解码;
|
||||
- 更高的摩尔纹/滚动快门敏感度;
|
||||
- Windows 理论 B/s 提升,但 Android “有效新帧/s”可能反而下降。
|
||||
|
||||
### 3. Android → Windows:连接速度/稳定性
|
||||
v0.4 把全部屏幕和解码预算投入一个大 QR。
|
||||
|
||||
扫码二维码升级到更短的 `QFTPAIR2`:
|
||||
### QFT2 + Base45 低密度帧
|
||||
|
||||
- 短字段 JSON + Base64URL。
|
||||
- 配对 QR 使用中等级纠错,候选测试为 QR version 10。
|
||||
- QFT Direct 二维码携带一个快速 endpoint hint,同时保留真实 Wi‑Fi 网关、UDP 发现与当前子网扫描作为 fallback。
|
||||
- Android 配对扫描分辨率降到 640×480,优先 GlobalHistogram 快速路径;失败才周期性使用 HybridBinarizer。
|
||||
- Android 连接 Wi‑Fi 后不立即假定网络可用,而是等待真实 IPv4/route。
|
||||
- 电脑发现顺序:
|
||||
1. QR endpoint hint;
|
||||
2. `QFTDISC2` UDP 发现;
|
||||
3. Android 真实 Wi‑Fi gateway;
|
||||
4. 常见 Windows Direct 地址;
|
||||
5. 当前实际子网最多 /24 的并发 fallback 扫描。
|
||||
- 所有 HTTP 请求绑定到扫码建立的 `Network`,避免手机 4G/5G/其他 Wi‑Fi 抢路由。
|
||||
- Android Manifest 同时启用 local cleartext network security config;QFTPAIR 解析器仍只允许 literal private/local IPv4 + 本次 session token。
|
||||
活跃光学协议升级为 `QFT2:`:
|
||||
|
||||
### 4. Android 7 → 最新
|
||||
- 二进制帧仍包含 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 和有效新帧率。
|
||||
|
||||
- `minSdk = 24`(Android 7.0)。
|
||||
- Android 10+:`WifiNetworkSpecifier` local-only 配网。
|
||||
- Android 7~9:`WifiManager/WifiConfiguration` 兼容路径。
|
||||
- Android 13+:`NEARBY_WIFI_DEVICES`。
|
||||
- Android 7~12:位置权限兼容。
|
||||
- Android 7~9 光学保存:`WRITE_EXTERNAL_STORAGE` + `Downloads/QFT`。
|
||||
- Android 10+ 光学保存:MediaStore Downloads。
|
||||
Android 仍保留 QFT1 解析用于旧发送端兼容。
|
||||
|
||||
## Windows → Android 使用
|
||||
## Android 识别优化
|
||||
|
||||
1. Windows:进入 `电脑 → Android`。
|
||||
2. 选择文件。
|
||||
3. 建议先用 `30 FPS / 4 码` 验证,再切 `60 FPS / 4 码`。
|
||||
4. Android:`电脑 → 手机 → 开始光学接收`。
|
||||
5. 让 2×2 QR 区域尽量完整占据手机取景框。
|
||||
6. Android UI 会实时显示相机分析 FPS 和有效 QR/s;若识别偏低,靠近屏幕或把 Windows 降为 30 FPS。
|
||||
7. 收齐后自动 SHA-256 校验并保存。
|
||||
### Acquire → Lock → Expand → Reacquire
|
||||
|
||||
## Android → Windows 使用
|
||||
扫描器状态机现在是:
|
||||
|
||||
1. Windows:`Android → 电脑`。
|
||||
2. 选择接收文件夹。
|
||||
3. 默认选择 `QFT Direct`。
|
||||
4. 点击“启动接收并生成二维码”。
|
||||
5. Windows 保持该页面开启。若 Windows Defender Firewall 首次询问网络访问,请允许 QFT 访问**专用网络**。
|
||||
6. Android:`手机 → 电脑 → 扫码连接电脑`。
|
||||
7. 首次连接具体 QFT Direct AP 时,Android 系统可能要求确认该本地 Wi‑Fi。
|
||||
8. App 自动完成 endpoint/UDP/gateway/subnet 发现,出现“已连接电脑”后选择文件并开始传输。
|
||||
```text
|
||||
搜索大二维码
|
||||
↓
|
||||
ZXing finder points
|
||||
↓
|
||||
建立方形 ROI
|
||||
↓
|
||||
后续只复制/解码 ROI
|
||||
↓
|
||||
轻微移动:平滑跟随
|
||||
↓
|
||||
连续 miss:逐级扩大 ROI
|
||||
↓
|
||||
持续丢失:重新全局搜索
|
||||
```
|
||||
|
||||
如果电脑没有可用 Wi‑Fi Direct 适配器,可切换 Windows 的“当前局域网”备用模式。
|
||||
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
|
||||
|
||||
需要 Rust stable MSVC + Visual C++ Build Tools / Windows SDK。
|
||||
|
||||
```powershell
|
||||
cd windows
|
||||
cargo check
|
||||
cargo test
|
||||
cargo build --release
|
||||
cargo run --release
|
||||
```
|
||||
|
||||
### Android
|
||||
|
||||
当前构建栈:compileSdk/targetSdk 35、minSdk 24、JDK 17。
|
||||
JDK 17,compileSdk/targetSdk 35,minSdk 24:
|
||||
|
||||
```powershell
|
||||
cd android
|
||||
@@ -106,26 +141,18 @@ APK:
|
||||
|
||||
## 字体
|
||||
|
||||
Windows UI 优先读取:
|
||||
Windows UI 优先读取 `windows/assets/qft-ui.ttf`,也可用 `QFT_FONT_PATH` 指向你自己的中文 TTF。仓库不附带第三方字体文件。
|
||||
|
||||
`windows/assets/qft-ui.ttf`
|
||||
|
||||
也可设置 `QFT_FONT_PATH` 指向支持中文的 TTF。项目不会分发第三方字体文件。
|
||||
|
||||
## 验证
|
||||
|
||||
开发侧测试:
|
||||
## 自动验证
|
||||
|
||||
```bash
|
||||
python scripts/run_all_selftests.py
|
||||
python scripts/optical_image_decode_selftest.py
|
||||
python scripts/local_transfer_integration_selftest.py
|
||||
```
|
||||
|
||||
Windows 真机环境可运行根目录:
|
||||
Windows 主机建议直接:
|
||||
|
||||
```powershell
|
||||
.\VERIFY_WINDOWS_HOST.ps1
|
||||
```
|
||||
|
||||
详细结果与尚未能在当前生成环境自动验证的硬件项目见 `TEST_REPORT.md`。
|
||||
它会继续执行 Rust `cargo check/test/build` 和 Android Gradle 单测/APK 构建。物理相机/屏幕和 Wi‑Fi Direct 项目见 `TEST_REPORT.md`。
|
||||
|
||||
Reference in New Issue
Block a user