diff --git a/IMPLEMENTATION_STATUS.md b/IMPLEMENTATION_STATUS.md index 9a8cd20..377b42a 100644 --- a/IMPLEMENTATION_STATUS.md +++ b/IMPLEMENTATION_STATUS.md @@ -1,55 +1,67 @@ -# QFT v0.3.0-rc3 implementation status +# QFT v0.4.0-rc2 implementation status ## Windows → Android optical -- [x] QFT1 manifest/data/end wire format +- [x] QFT2 manifest/data/end frame format +- [x] QFT2 Base45 text layer; Android Result.text decode +- [x] QFT1 legacy receive compatibility - [x] CRC32 per frame + SHA-256 whole file -- [x] 1 QR / 4 QR per page -- [x] Windows target refresh 1~60 FPS -- [x] 4-code default, 900-byte payload +- [x] **single large QR only**; 2×2 / 4-channel removed +- [x] default 450-byte DATA payload +- [x] QR-L + complete 4-module quiet zone +- [x] Windows target display 5~60 FPS +- [x] draggable control/QR split pane +- [x] focus-QR mode and QR zoom - [x] Rayon background pre-encoding -- [x] reused egui GPU TextureHandle +- [x] reused egui GPU TextureHandle / NEAREST sampling - [x] positioned source reads; no whole-file mmap -- [x] bounded pre-render cache; 1.1GiB process design ceiling -- [x] Android 4-region concurrent decoder -- [x] CameraX KEEP_ONLY_LATEST -- [x] no whole-frame rotation/copy in hot path -- [x] runtime scan FPS / decoded QR/s status -- [x] synthetic 4/4 visual QR decode test -- [ ] physical 60Hz/120Hz monitor × multiple Android camera hardware matrix +- [x] bounded pre-render cache; 1100 MiB process design budget +- [x] Android centered acquisition + finder-point ROI lock +- [x] smoothed moving ROI + progressive miss expansion/reacquire +- [x] dynamic overlay: search/green lock/yellow miss/outside dim +- [x] lock-centered periodic AF/AE +- [x] Android 640×480 ImageAnalysis + KEEP_ONLY_LATEST +- [x] Camera2Interop advertised AE FPS range request up to 60 +- [x] automatic fallback when an OEM rejects explicit FPS/stream combination +- [x] reusable Y-plane `GrayFrameBuffer` +- [x] GlobalHistogram hot path + sparse Hybrid fallback +- [x] duplicate decoded optical frames suppressed before assembler +- [x] runtime camera FPS / decoded/s / distinct-new-frame/s / decode-ms UI +- [x] synthetic QFT2 v15 full-frame + ROI visual decode test +- [ ] physical 30/45/60Hz display × Android camera throughput matrix ## Android → Windows - [x] QFTPAIR2 compact pairing QR - [x] persistent per-PC Direct AP identity + per-session token -- [x] one fast endpoint hint in Direct pairing QR -- [x] Windows Wi-Fi Direct Legacy AP code +- [x] Windows Wi-Fi Direct Legacy AP implementation - [x] Android 10+ WifiNetworkSpecifier path - [x] Android 7~9 legacy Wi-Fi path - [x] wait for actual IPv4/link route before discovery - [x] UDP QFTDISC2 receiver discovery -- [x] directed broadcast + real gateway discovery -- [x] bounded /24 concurrent subnet fallback +- [x] QR endpoint + gateway + directed broadcast + subnet fallback +- [x] HTTP bound to selected Android Network - [x] local cleartext network security config -- [x] private/local IPv4 + session-token validation -- [x] Parallel v2 upload init/chunk/finish -- [x] adaptive 4/8/16 MiB chunk size +- [x] local/private IPv4 + session-token validation +- [x] Parallel v2 init/chunk/finish +- [x] adaptive 4/8/16 MiB chunks - [x] up to 8 Android workers per file -- [x] Windows concurrent positioned writes +- [x] Windows positioned concurrent writes - [x] temporary `.qftpart`, final SHA-256 and rename -- [x] legacy single-stream fallback -- [x] loopback UDP + HTTP + 8-worker integration test +- [x] loopback UDP + HTTP + out-of-order parallel integration test - [ ] physical Windows Wi-Fi Direct adapter / driver / firewall matrix ## Android compatibility - [x] minSdk 24 (Android 7.0) -- [x] legacy WRITE_EXTERNAL_STORAGE path <= Android 9 +- [x] WRITE_EXTERNAL_STORAGE <= Android 9 - [x] MediaStore Downloads >= Android 10 - [x] ACCESS_FINE_LOCATION compatibility <= Android 12 - [x] NEARBY_WIFI_DEVICES >= Android 13 - [x] no `java.util.Base64` dependency in app source -- [x] key Kotlin protocol/pairing/upload/scanner source syntax tests in the build environment -- [ ] APK installation/runtime matrix on Android 7/8/9/10/11/12/13/14/15/16+ physical/emulated devices +- [x] host Kotlin QFT2/Base45 + LockRect runtime smoke +- [x] host Kotlin QrAnalyzer type-check with CameraX/ZXing-shaped stubs +- [ ] real Android Gradle APK build in this container (SDK unavailable here) +- [ ] install/runtime matrix on physical Android 7→latest devices -See `TEST_REPORT.md` for exact test evidence and limitations. +See `TEST_REPORT.md` and `TEST_RESULTS.txt` for executed evidence and limitations. diff --git a/README.md b/README.md index 3123247..709043a 100644 --- a/README.md +++ b/README.md @@ -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`。 diff --git a/TEST_REPORT.md b/TEST_REPORT.md index 534910d..6965d51 100644 --- a/TEST_REPORT.md +++ b/TEST_REPORT.md @@ -1,182 +1,202 @@ -# QFT v0.3.0-rc3 test report +# QFT v0.4.0-rc2 test report Date: 2026-08-10 -This report deliberately separates **tests actually executed in the current build environment** from **hardware acceptance that cannot be truthfully simulated here**. +This report separates **tests actually executed in the current environment** from **physical hardware acceptance that cannot be simulated here**. + +## What this RC changes + +The rc2 optical path is deliberately simpler than v0.3: + +- 2×2 / 4-channel QR removed; +- one large QR only; +- QFT2 + Base45 text layer; +- 450-byte DATA payload; +- Android 640×480 analysis; +- centered acquisition → finder-point ROI lock → progressive expansion → reacquire; +- reusable Y-plane buffer; +- GlobalHistogram fast hot path with sparse Hybrid fallback; +- duplicate displayed frames suppressed before the file assembler; +- dynamic lock overlay and movement-triggered AF/AE; +- Windows draggable split pane / focus-QR mode. + +Android→Windows QFTPAIR2/discovery/parallel upload remains and is regression-tested. ## Executed and passed -### Optical protocol recovery +### 1. QFT2 optical loss recovery — PASS Command: -`python scripts/protocol_selftest.py` +```text +python scripts/protocol_selftest.py +``` + +Representative result from the final source: + +```text +PASS QFT2/Base45 single-QR: 1200123 bytes, 2667 chunks, +22% frame loss, recovered in 6 rounds; QR-L v15 vs legacy Base64 v18, +12px/module@1024, text=722 chars, theoretical payload=26.4 KiB/s +``` + +Verified: + +- Base45 known vectors; +- QFT2 magic/version/header; +- CRC32; +- 450 B DATA chunks; +- continuous replay after 22% synthetic whole-frame loss; +- exact file reconstruction; +- final SHA-256 equality; +- representative QFT2 QR density below the old QFT1/Base64 comparison. + +Theoretical payload is `450 × 60 = 27,000 B/s`; it is not a claim of physical camera throughput. + +### 2. Synthetic camera-frame decode and ROI — PASS + +Command: + +```text +python scripts/optical_image_decode_selftest.py +``` + +The test renders a 722-character QFT2/Base45 QR-L v15, places it into a 640×480 grayscale camera-like frame, applies 3° rotation and light Gaussian blur, then decodes both the full frame and a representative locked crop. + +Typical final runs were approximately: + +```text +full frame ≈ 4.2–4.7 ms/decode +locked ROI ≈ 2.8–2.9 ms/decode +ROI area ≈ 45–46% of frame +``` + +Both paths returned the exact QFT2 text. Timing varies by host and decoder cache state; this is a host-side directional benchmark, **not Android CameraX FPS**. + +### 3. Single-channel / Android static guards — PASS + +Commands: + +```text +python scripts/android_compat_selftest.py +python scripts/single_channel_guard_selftest.py +``` + +Verified in the final source: + +- `minSdk = 24`; +- no 2×2/4-lane Windows optical sender path; +- no four-reader Android optical decoder path; +- one large QFT2/Base45 QR; +- 450 B default DATA payload; +- 640×480 ImageAnalysis; +- `STRATEGY_KEEP_ONLY_LATEST`; +- Camera2Interop AE FPS request + no-explicit-FPS fallback when OEM binding rejects it; +- `QRCodeReader` only; +- ROI-only locked Y copy; +- grow-only reusable luma scratch buffer; +- lock smoothing / dynamic overlay / lock-centered refocus; +- QFT2/Base45 parsing + QFT1 legacy parsing; +- Android 7~9 and Android 10+ Wi-Fi branches; +- no `java.util.Base64` dependency in app source. + +### 4. Host Kotlin QFT2/ROI runtime — PASS + +`kotlin_host_smoke.py` compiled and executed the actual final: + +- `Base45.kt`; +- `Base64Url.kt`; +- `Protocol.kt`; +- `LockRect.kt`. Result: -- 2,500,123-byte random file -- 900-byte chunks -- 4 QR/page -- target 60 pages/s model -- synthetic 24% whole-page loss + 14% per-lane QR loss -- reconstructed exact original file in 9 rounds -- final SHA-256 identical -- representative frame: QR v25, ~3 rendered pixels/module at native 960px page -- theoretical raw file payload: ~210.9 KiB/s +```text +PASS Kotlin QFT2/Base45 protocol + ROI lock smoothing +``` -**PASS** +This test caught and fixed an earlier Kotlin expression-body compile error in `QftProtocol.parseText()` before packaging. -### Synthetic visual QR decode +### 5. Host Kotlin QrAnalyzer compile smoke — PASS -Command: - -`python scripts/optical_image_decode_selftest.py` - -Result in this environment: - -- 4/4 high-density QFT optical QR symbols decoded from one 960×960 synthetic page using libzbar/pyzbar -- QFTPAIR2 QR-M decoded after synthetic 7° rotation plus light Gaussian blur - -**PASS** - -This proves generated QR geometry/data is decodable under a synthetic image path; it does **not** prove a particular monitor/camera can decode 60 physical refreshes per second. - -### QFTPAIR2 size / QR density - -Command: - -`python scripts/pairing_selftest.py` +The same test compiles the final `QrAnalyzer.kt`, `GrayFrame.kt`, `LockRect.kt` and `ScannerLockState.kt` against minimal CameraX/ZXing-shaped JVM stubs. Result: -- QFTPAIR2: 207 characters with one Direct-AP endpoint hint -- older QFTPAIR1 comparison: 368 characters -- v2 size: 56.2% of v1 -- medium-error-correction QR: version 10 -- encode/decode round-trip exact +```text +PASS Kotlin QrAnalyzer compile smoke with CameraX/ZXing-shaped stubs +``` -**PASS** +This checks Kotlin type/signature consistency of the ROI scanner without claiming it replaces a real Android SDK build. -### Parallel local-file chunk reconstruction +### 6. Android→Windows regression tests — PASS -Command: +`run_all_selftests.py` also passed: -`python scripts/parallel_upload_selftest.py` +- QFTPAIR2: 207 chars vs old 368-char test payload, QR-M v10 in the model; +- UDP discovery request/response token + port round trip; +- 8-worker parallel reconstruction of ~64 MiB; +- 8 MiB chunks / 1 MiB worker I/O; +- loopback UDP discovery + authenticated HTTP + out-of-order chunk upload; +- ~40 MiB final reconstruction with identical SHA-256. -Result: +### 7. Memory budget model — PASS -- ~64 MiB random file -- 8 MiB test chunks -- 8 worker threads -- 1 MiB worker I/O buffers -- out-of-order positioned writes -- final SHA-256 identical +The guard models the Windows single-QR 1024×1024 RGBA pre-render queue: -**PASS** +```text +192 frames × ~4 MiB = 768 MiB managed cache ++ 96 MiB transient allowance +< 1100 MiB design ceiling +``` -### End-to-end local protocol integration +This is a design-budget check, not an OS-enforced RSS hard cap. GPU/runtime allocators can add platform-specific memory. -Command: +## Important implementation decisions validated during rc2 -`python scripts/local_transfer_integration_selftest.py` +### QFT2 uses Result.text, not ZXing rawBytes -Result: +The active path is Base45 text. Android reconstructs the QFT binary frame from `Result.text`. The code does not depend on ZXing `Result.rawBytes` representing the original byte-mode payload. -- QFTDISC2 UDP request/response -- session-token authenticated `/qft/ping` -- Parallel-v2 init -- out-of-order chunk POSTs using 8 workers -- finish -- exact reconstructed file and SHA-256 match +### Duplicate camera hits are not duplicate assembler work -**PASS** +At 45/60 display FPS, a camera can observe the same displayed QR in multiple exposures. rc2 still counts every successful decode in diagnostics, but only a changed QFT2 text fingerprint is delivered to `SessionAssembler`. -### Standalone UDP discovery +### AF/AE does not run on a fixed periodic timer -Command: +The scanner performs initial focus/metering, then re-meters after first lock or material ROI movement. A stationary locked QR does not force AF/AE every few seconds, reducing focus-pumping risk. -`python scripts/udp_discovery_selftest.py` +## Not executable in this environment -QFTDISC2 / QFTHERE2 token and port round-trip. +The current generation environment does not contain the Windows MSVC Rust toolchain, Android SDK, a physical Android camera, a Windows display or a Windows Wi-Fi Direct adapter. Therefore the following are **not claimed as passed here**: -**PASS** +1. Windows `cargo check/test/build --release` for rc2. +2. Android Gradle `:app:testDebugUnitTest :app:assembleDebug` against the real Android SDK. +3. Actual 30/45/60 displayed FPS → CameraX/ZXing effective new-frame throughput. +4. Lock acquisition/reacquisition timing on Android 7 and different phone camera pipelines. +5. PreviewView overlay mapping on every OEM sensor/crop/rotation combination. +6. Real Windows QFT Direct adapter / driver / firewall behavior. -### Memory-budget model +The package remains an **RC** until those physical checks pass. -Command: +## Required physical acceptance -`python scripts/memory_budget_selftest.py` +Run: -Result: +```powershell +.\VERIFY_WINDOWS_HOST.ps1 +``` -- 4QR 960px pre-render page ≈ 3.5156 MiB as Color32 -- maximum cache page cap 192 → ≈ 675 MiB -- conservative extra transient test allowance remains below the 1100 MiB design ceiling -- whole source file is no longer memory-mapped +Then use a small optical file and record Android's UI values at Windows 30, 45 and 60 FPS: -**PASS (design-budget test)** +- camera FPS; +- successful decode/s; +- distinct new-frame/s; +- average decode ms; +- lock area percentage; +- time to first lock; +- time to reacquire after a small phone movement. -This is not an OS-level hard RSS limiter. GPU drivers, allocator fragmentation and platform runtime memory vary; the implementation intentionally leaves several hundred MiB headroom instead of allocating a full 1 GiB cache. +Keep the Windows FPS setting that produces the highest **distinct new-frame/s**, not necessarily the highest display FPS. -### Android compatibility/static guards - -Command: - -`python scripts/android_compat_selftest.py` - -Checked: - -- minSdk 24 -- API 29 modern/legacy Wi-Fi split -- Android 7~9 storage path -- Android <=12 location permission -- Android 13+ nearby-WiFi permission -- network security config for local HTTP -- gateway/directed-broadcast/subnet discovery fallbacks -- 8-worker upload -- 640×480 pairing scan + 1280×720 optical analysis -- KEEP_ONLY_LATEST -- no full-frame rotate in scanner hot path -- no `java.util.Base64` dependency in main Android source - -**PASS** - -### Kotlin source checks executed - -Using `kotlinc-jvm 1.9.0` plus small Android/JSON stubs where necessary: - -- `Base64Url.kt + Protocol.kt` runtime parser test: **PASS** -- `PairingProtocol.kt` syntax/type test: **PASS** -- `UploadClient.kt + PairingProtocol.kt` syntax/type test: **PASS** -- `GrayFrame.kt + QrAnalyzer.kt` syntax/type test: **PASS** -- `WifiConnector.kt` syntax/type test across the modern/legacy branches: **PASS** - -These tests caught and fixed an earlier `ExecutorCompletionService.submit` source error before packaging rc3. - -## Not executable in the current Linux build sandbox - -The following are hardware/OS-specific and therefore are **not claimed as passed** here: - -1. Windows `cargo check/build` against the Windows MSVC/WinRT target. -2. Actual `WiFiDirectAdvertisementPublisher` start on a Windows Wi-Fi adapter. -3. Windows Defender Firewall private-network approval behavior. -4. Android Gradle APK build against a local Android SDK in this sandbox. -5. Android 7/8/9/10/11/12/13/14/15/16+ install/runtime matrix. -6. Real monitor → real camera optical performance at 30/60Hz, different brightness, rolling shutter and autofocus conditions. -7. Real Wi-Fi Direct throughput across different NIC/phone vendors. - -For those reasons **v0.3.0-rc3 remains an RC, not a final stable release**. - -## Required physical acceptance before marking stable - -Run `VERIFY_WINDOWS_HOST.ps1`, then at minimum: - -- Windows 10/11 + Android 7/9/10/13/latest available devices. -- Optical files: 10 KiB, 1 MiB, 10 MiB at 30 FPS and 60 FPS. -- Verify Android UI actual camera FPS / QR/s and final SHA-256. -- Android→Windows QFT Direct: first-time pairing, repeat pairing, reconnect after Wi-Fi loss. -- Test with Windows Firewall prompt accepted and with “current LAN” fallback. -- Upload 10 MiB, 500 MiB, and >2 GiB files; verify final SHA-256 and memory usage. -- Observe Windows working set during optical 60 FPS; if host-specific RSS exceeds 1.1 GiB, reduce the pre-encode cache slider (default 384 MiB) and record the device/driver combination. - -Only after this matrix is passed should the RC label be removed. +For file correctness, verify 100 KiB, 1 MiB and 10 MiB optical transfers by final SHA-256. For Android→Windows, repeat first-time Direct pairing, second pairing, Wi-Fi reconnect and LAN fallback. diff --git a/TEST_RESULTS.txt b/TEST_RESULTS.txt index 74e25ea..786d41c 100644 --- a/TEST_RESULTS.txt +++ b/TEST_RESULTS.txt @@ -1,8 +1,10 @@ -QFT v0.3.0-rc3 test execution log -UTC 2026-08-10 06:48:06 +QFT v0.4.0-rc2 test results +UTC 2026-08-10T08:45:56Z == protocol_selftest.py == -PASS optical: 2500123 bytes, 2778 chunks, 4 QR/page @ 60 FPS, 24% page loss + 14% lane loss, recovered in 9 rounds; QR v25, 3px/module, frame chars=1243, theoretical payload=210.9 KiB/s +PASS QFT2/Base45 single-QR: 1200123 bytes, 2667 chunks, 22% frame loss, recovered in 6 rounds; QR-L v15 vs legacy Base64 v18, 12px/module@1024, text=722 chars, theoretical payload=26.4 KiB/s +== optical_image_decode_selftest.py == +PASS synthetic QFT2 lock: QR-L v15, 722 chars; full=4.1ms, lockedROI=2.8ms, ROI area=45.3% == pairing_selftest.py == PASS pairing: QFTPAIR2=207 chars vs v1=368 chars (56.2%), QR-M version=10 == parallel_upload_selftest.py == @@ -10,20 +12,14 @@ PASS parallel upload: 67121209 bytes, 8 MiB chunks, 8 workers, 1 MiB worker I/O, == udp_discovery_selftest.py == PASS UDP discovery: request/response token+port round-trip from 127.0.0.1 == local_transfer_integration_selftest.py == -PASS loopback Parallel v2 integration: UDP discovery + HTTP auth + 6 out-of-order chunks / 8 workers; 41955385 bytes SHA-256 identical in 0.22s +PASS loopback Parallel v2 integration: UDP discovery + HTTP auth + 6 out-of-order chunks / 8 workers; 41955385 bytes SHA-256 identical in 0.19s == memory_budget_selftest.py == -PASS memory budget: 4QR cache=192 pages/675.0 MiB; 1QR cache=192 pages/423.0 MiB; hard design ceiling=1100 MiB +PASS memory budget: single-QR cache=192 frames/768.0 MiB + 96 MiB transient allowance < 1100 MiB == android_compat_selftest.py == -PASS Android compatibility/static guards: minSdk24, API29 split, legacy storage/location, Android13 nearby-WiFi, cleartext local config, subnet fallback, fast scanner paths -ALL CORE PYTHON SELFTESTS PASSED -PASS synthetic QR decode: 4/4 optical QR v25 decoded from 960px page in 48.3 ms; QFTPAIR2 QR-M v10 decoded after 7deg rotate+blur in 1.7 ms - -Kotlin runtime: Base64Url + QFT1 -PASS Kotlin Base64Url + QFT1 parser - -Kotlin syntax: PairingProtocol + UploadClient -PASS Kotlin syntax: PairingProtocol.kt + UploadClient.kt -Kotlin syntax: GrayFrame + QrAnalyzer -PASS Kotlin syntax: GrayFrame.kt + QrAnalyzer.kt -Kotlin syntax: WifiConnector -PASS Kotlin syntax: WifiConnector.kt +PASS Android static guards: API24+, 640x480 single-QR ROI, reusable luma buffer, QFT2/Base45 text parse, dynamic lock/refocus, Camera2 FPS request, legacy/new Wi-Fi compatibility +== single_channel_guard_selftest.py == +PASS single-channel guard: one large QFT2/Base45 QR, 450B chunks, no 2x2/4-lane path, Android locked-ROI text decode only +== kotlin_host_smoke.py == +PASS Kotlin QFT2/Base45 protocol + ROI lock smoothing +PASS Kotlin QrAnalyzer compile smoke with CameraX/ZXing-shaped stubs +ALL HOST SELFTESTS PASSED diff --git a/VERIFY_WINDOWS_HOST.ps1 b/VERIFY_WINDOWS_HOST.ps1 index b65d087..e186c3a 100644 --- a/VERIFY_WINDOWS_HOST.ps1 +++ b/VERIFY_WINDOWS_HOST.ps1 @@ -1,20 +1,26 @@ $ErrorActionPreference = 'Stop' $Root = Split-Path -Parent $MyInvocation.MyCommand.Path -Write-Host "== QFT v0.3.0-rc3 Windows host verification ==" -ForegroundColor Cyan +Write-Host "== QFT v0.4.0-rc2 Windows host verification ==" -ForegroundColor Cyan if (Get-Command python -ErrorAction SilentlyContinue) { Write-Host "[1/4] Core protocol/selftests" & python "$Root\scripts\run_all_selftests.py" + if ($LASTEXITCODE -ne 0) { + Write-Host "If Python reports missing qrcode/cv2, run: python -m pip install -r `"$Root\scripts\requirements-test.txt`"" -ForegroundColor Yellow + throw "repository Python selftests failed" + } } else { Write-Warning "python not found; skipping repository Python selftests" } -Write-Host "[2/4] Windows Rust compile" +Write-Host "[2/4] Windows Rust compile/test/release" Push-Location "$Root\windows" try { & cargo check if ($LASTEXITCODE -ne 0) { throw "cargo check failed" } + & cargo test + if ($LASTEXITCODE -ne 0) { throw "cargo test failed" } & cargo build --release if ($LASTEXITCODE -ne 0) { throw "cargo build --release failed" } } finally { Pop-Location } @@ -33,5 +39,5 @@ try { Write-Host "[4/4] Artifact locations" -ForegroundColor Cyan Write-Host "Windows EXE: $Root\windows\target\release\qft-windows.exe" Write-Host "Android APK: $Root\android\app\build\outputs\apk\debug\app-debug.apk" -Write-Host "\nHOST BUILD VERIFICATION PASSED" -ForegroundColor Green +Write-Host "`nHOST BUILD VERIFICATION PASSED" -ForegroundColor Green Write-Host "Next: perform the physical display/camera and Wi-Fi Direct acceptance matrix in TEST_REPORT.md." diff --git a/android/app/build.gradle.kts b/android/app/build.gradle.kts index fc3daa7..e690cf8 100644 --- a/android/app/build.gradle.kts +++ b/android/app/build.gradle.kts @@ -12,8 +12,8 @@ android { applicationId = "com.qft.optical" minSdk = 24 targetSdk = 35 - versionCode = 8 - versionName = "0.3.0-rc3" + versionCode = 10 + versionName = "0.4.0-rc2" testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" } diff --git a/android/app/src/main/java/com/qft/optical/Base45.kt b/android/app/src/main/java/com/qft/optical/Base45.kt new file mode 100644 index 0000000..6376148 --- /dev/null +++ b/android/app/src/main/java/com/qft/optical/Base45.kt @@ -0,0 +1,41 @@ +package com.qft.optical + +/** RFC 9285 Base45 decoder. Alphabet maps directly to QR alphanumeric mode. */ +object Base45 { + private const val ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:" + private val reverse = IntArray(128) { -1 }.apply { + ALPHABET.forEachIndexed { index, c -> this[c.code] = index } + } + + fun decode(text: String): ByteArray? { + if (text.isEmpty()) return ByteArray(0) + if (text.length % 3 == 1) return null + val out = ByteArray((text.length / 3) * 2 + if (text.length % 3 == 2) 1 else 0) + var i = 0 + var o = 0 + while (i + 2 < text.length) { + val a = value(text[i]) ?: return null + val b = value(text[i + 1]) ?: return null + val c = value(text[i + 2]) ?: return null + val n = a + b * 45 + c * 45 * 45 + if (n > 0xFFFF) return null + out[o++] = (n / 256).toByte() + out[o++] = (n % 256).toByte() + i += 3 + } + if (i < text.length) { + val a = value(text[i]) ?: return null + val b = value(text[i + 1]) ?: return null + val n = a + b * 45 + if (n > 0xFF) return null + out[o++] = n.toByte() + } + return if (o == out.size) out else out.copyOf(o) + } + + private fun value(c: Char): Int? { + if (c.code >= reverse.size) return null + val v = reverse[c.code] + return if (v >= 0) v else null + } +} diff --git a/android/app/src/main/java/com/qft/optical/GrayFrame.kt b/android/app/src/main/java/com/qft/optical/GrayFrame.kt index 936dde1..b225fa0 100644 --- a/android/app/src/main/java/com/qft/optical/GrayFrame.kt +++ b/android/app/src/main/java/com/qft/optical/GrayFrame.kt @@ -2,42 +2,63 @@ package com.qft.optical import androidx.camera.core.ImageProxy -/** - * Copies only the Y plane. - * - * QFT deliberately keeps the camera buffer in sensor orientation. QR finder - * patterns are rotation independent, and the optical 2x2 layout is still a 2x2 - * layout after a 90° rotation. Avoiding a second full-frame rotate/copy removes - * almost half of the memory traffic in the scanner hot path on portrait phones. - */ -data class GrayFrame(val width: Int, val height: Int, val luma: ByteArray) { - companion object { - fun from(image: ImageProxy): GrayFrame { - val plane = image.planes[0] - val src = plane.buffer.duplicate() - val rowStride = plane.rowStride - val pixelStride = plane.pixelStride - val w = image.width - val h = image.height - val raw = ByteArray(w * h) +/** Dense Y-plane crop used by ZXing. */ +data class GrayFrame( + val width: Int, + val height: Int, + val luma: ByteArray, + val originX: Int, + val originY: Int, + val fullWidth: Int, + val fullHeight: Int, + val rotationDegrees: Int, +) - if (pixelStride == 1 && rowStride == w) { - src.position(0) - src.get(raw, 0, raw.size) - } else if (pixelStride == 1) { - for (y in 0 until h) { - src.position(y * rowStride) - src.get(raw, y * w, w) - } - } else { - for (y in 0 until h) { - val rowStart = y * rowStride - for (x in 0 until w) { - raw[y * w + x] = src.get(rowStart + x * pixelStride) - } +/** + * Reusable luminance scratch buffer. ImageAnalysis calls the analyzer serially, + * so one grow-only byte array is enough for the full hot path. This avoids a + * ByteArray allocation for every camera frame and materially reduces GC on + * Android 7/8 class devices. + */ +class GrayFrameBuffer { + private var scratch = ByteArray(0) + + fun capture(image: ImageProxy, requested: LockRect? = null): GrayFrame { + val plane = image.planes[0] + val src = plane.buffer.duplicate() + val rowStride = plane.rowStride + val pixelStride = plane.pixelStride + val fullW = image.width + val fullH = image.height + val crop = (requested ?: LockRect(0, 0, fullW, fullH)).clamp(fullW, fullH) + val needed = crop.width * crop.height + if (scratch.size < needed) scratch = ByteArray(needed) + + if (pixelStride == 1) { + for (y in 0 until crop.height) { + val sourceOffset = (crop.top + y) * rowStride + crop.left + src.position(sourceOffset) + src.get(scratch, y * crop.width, crop.width) + } + } else { + for (y in 0 until crop.height) { + val rowStart = (crop.top + y) * rowStride + val dst = y * crop.width + for (x in 0 until crop.width) { + scratch[dst + x] = src.get(rowStart + (crop.left + x) * pixelStride) } } - return GrayFrame(w, h, raw) } + + return GrayFrame( + width = crop.width, + height = crop.height, + luma = scratch, + originX = crop.left, + originY = crop.top, + fullWidth = fullW, + fullHeight = fullH, + rotationDegrees = image.imageInfo.rotationDegrees, + ) } } diff --git a/android/app/src/main/java/com/qft/optical/LockRect.kt b/android/app/src/main/java/com/qft/optical/LockRect.kt new file mode 100644 index 0000000..ddec208 --- /dev/null +++ b/android/app/src/main/java/com/qft/optical/LockRect.kt @@ -0,0 +1,100 @@ +package com.qft.optical + +import kotlin.math.abs +import kotlin.math.max +import kotlin.math.min + +/** + * Pure geometry used by the optical scanner. Kept Android-free so it can be + * unit tested on the host JVM. + */ +data class LockRect( + val left: Int, + val top: Int, + val width: Int, + val height: Int, +) { + val right: Int get() = left + width + val bottom: Int get() = top + height + + fun clamp(frameWidth: Int, frameHeight: Int): LockRect { + val l = left.coerceIn(0, (frameWidth - 1).coerceAtLeast(0)) + val t = top.coerceIn(0, (frameHeight - 1).coerceAtLeast(0)) + val r = right.coerceIn(l + 1, frameWidth.coerceAtLeast(l + 1)) + val b = bottom.coerceIn(t + 1, frameHeight.coerceAtLeast(t + 1)) + return LockRect(l, t, r - l, b - t) + } + + fun expand(frameWidth: Int, frameHeight: Int, factor: Float): LockRect { + val f = factor.coerceAtLeast(1f) + val cx = left + width / 2f + val cy = top + height / 2f + val w = (width * f).toInt().coerceAtLeast(96) + val h = (height * f).toInt().coerceAtLeast(96) + return LockRect((cx - w / 2f).toInt(), (cy - h / 2f).toInt(), w, h) + .clamp(frameWidth, frameHeight) + } + + + fun smoothToward(target: LockRect, alpha: Float): LockRect { + val a = alpha.coerceIn(0f, 1f) + fun mix(x: Int, y: Int) = (x + (y - x) * a).toInt() + return LockRect( + mix(left, target.left), + mix(top, target.top), + mix(width, target.width), + mix(height, target.height), + ) + } + + fun areaFraction(frameWidth: Int, frameHeight: Int): Float { + val total = frameWidth.toLong() * frameHeight.toLong() + if (total <= 0L) return 1f + return ((width.toLong() * height.toLong()).toDouble() / total.toDouble()).toFloat() + } + + fun materiallyDiffers(other: LockRect?): Boolean { + if (other == null) return true + val d = abs(left - other.left) + abs(top - other.top) + + abs(width - other.width) + abs(height - other.height) + return d > max(width, height) / 18 + } + + companion object { + /** + * ZXing normally returns the finder-pattern centers. Their bounding box + * is smaller than the full symbol, so enlarge to roughly 1.28x and force + * a square ROI. This keeps the complete quiet zone while discarding most + * of the camera frame after lock-on. + */ + fun fromPoints( + points: List>, + frameWidth: Int, + frameHeight: Int, + ): LockRect? { + if (points.size < 3 || frameWidth < 2 || frameHeight < 2) return null + val minX = points.minOf { it.first } + val maxX = points.maxOf { it.first } + val minY = points.minOf { it.second } + val maxY = points.maxOf { it.second } + val span = max(maxX - minX, maxY - minY) + if (span < 24f) return null + val side = (span * 1.28f).toInt().coerceAtLeast(128) + val cx = (minX + maxX) * 0.5f + val cy = (minY + maxY) * 0.5f + return LockRect( + (cx - side / 2f).toInt(), + (cy - side / 2f).toInt(), + side, + side, + ).clamp(frameWidth, frameHeight) + } + + fun centeredSearch(frameWidth: Int, frameHeight: Int, fraction: Float = 0.92f): LockRect { + val f = fraction.coerceIn(0.5f, 1f) + val w = (frameWidth * f).toInt().coerceAtLeast(1) + val h = (frameHeight * f).toInt().coerceAtLeast(1) + return LockRect((frameWidth - w) / 2, (frameHeight - h) / 2, w, h) + } + } +} diff --git a/android/app/src/main/java/com/qft/optical/MainActivity.kt b/android/app/src/main/java/com/qft/optical/MainActivity.kt index 844428a..99ec78b 100644 --- a/android/app/src/main/java/com/qft/optical/MainActivity.kt +++ b/android/app/src/main/java/com/qft/optical/MainActivity.kt @@ -5,9 +5,13 @@ import android.content.pm.PackageManager import android.content.res.ColorStateList import android.graphics.Color import android.graphics.drawable.GradientDrawable +import android.hardware.camera2.CameraCharacteristics +import android.hardware.camera2.CameraManager +import android.hardware.camera2.CaptureRequest import android.net.Network import android.os.Build import android.os.Bundle +import android.util.Range import android.util.Size import android.view.Gravity import android.view.ViewGroup @@ -19,6 +23,10 @@ import android.widget.ScrollView import android.widget.TextView import androidx.activity.ComponentActivity import androidx.activity.result.contract.ActivityResultContracts +import androidx.annotation.OptIn +import androidx.camera.camera2.interop.Camera2Interop +import androidx.camera.camera2.interop.ExperimentalCamera2Interop +import androidx.camera.core.Camera import androidx.camera.core.CameraSelector import androidx.camera.core.FocusMeteringAction import androidx.camera.core.ImageAnalysis @@ -39,8 +47,14 @@ class MainActivity : ComponentActivity() { private lateinit var assembler: SessionAssembler private var cameraProvider: ProcessCameraProvider? = null + private var activeCamera: Camera? = null + private var lastLockFocusAt = 0L + private var lastLockFocusX = -1f + private var lastLockFocusY = -1f private var currentAnalyzer: QrAnalyzer? = null + private var qrLockOverlay: QrLockOverlay? = null private var scannerStatsText: TextView? = null + private var scannerLockText: TextView? = null private var scannerMode = ScannerMode.NONE private var pendingScannerMode = ScannerMode.NONE private val pairConsumed = AtomicBoolean(false) @@ -126,8 +140,8 @@ class MainActivity : ComponentActivity() { root.addView(modeCard( title = "电脑 → 手机", - badge = "光学零网络 · 4码并行 · 60FPS显示", - body = "手机摄像头连续读取电脑动态二维码。Wi-Fi、蓝牙、局域网和互联网都不参与文件数据传输。", + badge = "光学零网络 · 单码锁定 · QFT2低密度字母数字QR · 最高60FPS显示", + body = "手机先搜索并锁定一个大二维码,之后只分析锁定区域。QFT2 使用 Base45 让 QR 保持字母数字模式并降低模块密度;Wi-Fi、蓝牙、局域网和互联网都不参与文件数据传输。", buttonLabel = "开始光学接收", ) { requestScanner(ScannerMode.OPTICAL) }) root.addView(space(16)) @@ -139,7 +153,7 @@ class MainActivity : ComponentActivity() { ) { requestScanner(ScannerMode.PAIR) }) root.addView(space(22)) root.addView(text("本机设备:$receiverDeviceLabel", 13f, MUTED)) - root.addView(text("QFT v0.3.0-rc3 · Android 7+ 到最新", 12f, MUTED)) + root.addView(text("QFT v0.4.0-rc2 · Android 7+ 到最新", 12f, MUTED)) setContentView(ScrollView(this).apply { setBackgroundColor(BG); addView(root) }) } @@ -158,6 +172,7 @@ class MainActivity : ComponentActivity() { } } + @OptIn(markerClass = [ExperimentalCamera2Interop::class]) private fun startScanner(mode: ScannerMode) { scannerMode = mode pairConsumed.set(false) @@ -166,19 +181,30 @@ class MainActivity : ComponentActivity() { future.addListener({ val provider = future.get() cameraProvider = provider - val preview = Preview.Builder().build().also { it.surfaceProvider = previewView.surfaceProvider } - val profile = if (mode == ScannerMode.PAIR) QrAnalyzer.Profile.PAIR_FAST else QrAnalyzer.Profile.OPTICAL_MULTI + val requestedFps = chooseCameraFpsRange() + + // CameraX 1.4.x ImageAnalysis.Builder has no public setTargetFrameRate(). + // Apply a range actually advertised by the selected back camera via + // Camera2Interop to both bound use cases. + val previewBuilder = Preview.Builder() + Camera2Interop.Extender(previewBuilder).setCaptureRequestOption( + CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE, + requestedFps, + ) + val preview = previewBuilder.build().also { it.surfaceProvider = previewView.surfaceProvider } + + val profile = if (mode == ScannerMode.PAIR) QrAnalyzer.Profile.PAIR_FAST else QrAnalyzer.Profile.OPTICAL_LOCKED currentAnalyzer?.close() val analyzer = QrAnalyzer( profile = profile, - onTexts = { values -> + onCode = { code -> when (scannerMode) { - ScannerMode.OPTICAL -> values.forEach(assembler::acceptText) - ScannerMode.PAIR -> values.firstOrNull { PairingProtocol.isPairingText(it) }?.let(::acceptPairCode) + ScannerMode.OPTICAL -> assembler.acceptText(code.text) + ScannerMode.PAIR -> if (PairingProtocol.isPairingText(code.text)) acceptPairCode(code.text) ScannerMode.NONE -> Unit } }, - onStats = { cameraFps, decodedFps -> + onStats = { cameraFps, decodedFps, distinctFps, decodeMs -> runOnUiThread { val quality = when (mode) { ScannerMode.PAIR -> when { @@ -187,38 +213,152 @@ class MainActivity : ComponentActivity() { else -> "相机帧率偏低" to WARNING } ScannerMode.OPTICAL -> when { - decodedFps >= cameraFps.coerceAtLeast(1.0) * 1.5 -> "光学链路稳定" to SUCCESS - decodedFps >= 5.0 -> "可接收 · 建议保持手机稳定" to ACCENT - else -> "识别偏低 · 靠近屏幕或降低 Windows FPS" to WARNING + distinctFps >= 18.0 -> "新帧吞吐良好" to SUCCESS + distinctFps >= 8.0 -> "可接收 · 继续保持二维码稳定" to ACCENT + decodedFps >= 8.0 -> "重复帧较多 · 尝试 Windows 30/45 FPS" to WARNING + else -> "识别偏低 · 放大 Windows 二维码或降到 30 FPS" to WARNING } ScannerMode.NONE -> "空闲" to MUTED } - scannerStatsText?.text = "%s · 相机 %.1f FPS · 有效 QR %.1f/s".format(quality.first, cameraFps, decodedFps) + scannerStatsText?.text = if (mode == ScannerMode.OPTICAL) { + "%s · 相机 %.1f FPS · 解码 %.1f/s · 新帧 %.1f/s · %.1fms/次".format( + quality.first, cameraFps, decodedFps, distinctFps, decodeMs + ) + } else { + "%s · 相机 %.1f FPS · 解码 %.1f/s · %.1fms/次".format(quality.first, cameraFps, decodedFps, decodeMs) + } scannerStatsText?.setTextColor(quality.second) } }, + onLock = { lock -> + runOnUiThread { + qrLockOverlay?.update(lock) + if (mode == ScannerMode.OPTICAL) { + if (lock.locked && lock.misses == 0) maybeRefocusLockedQr() + scannerLockText?.text = if (lock.locked) { + val lockHint = if (lock.misses == 0) "稳定锁定" else "保持锁定 · miss ${lock.misses}" + "$lockHint · 仅分析 ${(lock.searchAreaFraction * 100f).toInt().coerceIn(1, 100)}% 画面" + } else { + "区域锁定:搜索中 · 让单个大二维码占取景框 50% 以上" + } + scannerLockText?.setTextColor( + if (!lock.locked) ACCENT else if (lock.misses == 0) SUCCESS else WARNING + ) + } + } + }, ) currentAnalyzer = analyzer - val targetSize = if (mode == ScannerMode.PAIR) Size(640, 480) else Size(1280, 720) - val analysis = ImageAnalysis.Builder() + + // v0.4 single large QR is intentionally analyzed at 640x480. With the + // QR occupying most of the view this still leaves several camera + // pixels/module, while substantially reducing Y-copy + ZXing work. + val targetSize = Size(640, 480) + val analysisBuilder = ImageAnalysis.Builder() .setTargetResolution(targetSize) .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST) - .build() - .also { it.setAnalyzer(cameraExecutor, analyzer) } + Camera2Interop.Extender(analysisBuilder).setCaptureRequestOption( + CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE, + requestedFps, + ) + val analysis = analysisBuilder.build().also { it.setAnalyzer(cameraExecutor, analyzer) } + provider.unbindAll() - val camera = provider.bindToLifecycle(this, CameraSelector.DEFAULT_BACK_CAMERA, preview, analysis) - // Screen QR benefits from an immediate center AF/AE metering pass. - try { - val point = previewView.meteringPointFactory.createPoint(0.5f, 0.5f) - val action = FocusMeteringAction.Builder( - point, - FocusMeteringAction.FLAG_AF or FocusMeteringAction.FLAG_AE, - ).setAutoCancelDuration(5, TimeUnit.SECONDS).build() - camera.cameraControl.startFocusAndMetering(action) - } catch (_: Exception) {} + val camera = try { + provider.bindToLifecycle(this, CameraSelector.DEFAULT_BACK_CAMERA, preview, analysis).also { + scannerStatsText?.text = "相机请求 ${requestedFps.lower}~${requestedFps.upper} FPS · 等待首帧…" + } + } catch (_: Exception) { + // Some old/OEM devices advertise a Camera2 FPS range that is not + // accepted together with the selected CameraX stream combination. + // Retry without the explicit AE range rather than failing scanner + // startup; KEEP_ONLY_LATEST + ROI still provides the fast path. + provider.unbindAll() + val fallbackPreview = Preview.Builder().build().also { + it.surfaceProvider = previewView.surfaceProvider + } + val fallbackAnalysis = ImageAnalysis.Builder() + .setTargetResolution(targetSize) + .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST) + .build().also { it.setAnalyzer(cameraExecutor, analyzer) } + scannerStatsText?.text = "设备拒绝显式高帧率请求 · 已回退相机自动 FPS · 等待首帧…" + provider.bindToLifecycle( + this, + CameraSelector.DEFAULT_BACK_CAMERA, + fallbackPreview, + fallbackAnalysis, + ) + } + activeCamera = camera + + previewView.post { + if (previewView.width <= 0 || previewView.height <= 0) return@post + try { + val point = previewView.meteringPointFactory.createPoint( + previewView.width * 0.5f, + previewView.height * 0.5f, + ) + val action = FocusMeteringAction.Builder( + point, + FocusMeteringAction.FLAG_AF or FocusMeteringAction.FLAG_AE, + ).setAutoCancelDuration(5, TimeUnit.SECONDS).build() + camera.cameraControl.startFocusAndMetering(action) + } catch (_: Exception) {} + } }, mainExecutor) } + private fun maybeRefocusLockedQr() { + val camera = activeCamera ?: return + val center = qrLockOverlay?.lockedCenterInView() ?: return + if (previewView.width <= 0 || previewView.height <= 0) return + + // Do not force an AF/AE cycle every few seconds while the phone is + // stationary: focus pumping can temporarily destroy QR contrast. + // Re-meter only on the first lock or after the locked region moved + // materially in the preview. + val threshold = minOf(previewView.width, previewView.height) * 0.10f + val dx = center.x - lastLockFocusX + val dy = center.y - lastLockFocusY + val moved = lastLockFocusX < 0f || dx * dx + dy * dy >= threshold * threshold + if (!moved) return + + val now = android.os.SystemClock.elapsedRealtime() + if (now - lastLockFocusAt < 1200L) return + lastLockFocusAt = now + lastLockFocusX = center.x + lastLockFocusY = center.y + try { + val point = previewView.meteringPointFactory.createPoint(center.x, center.y) + val action = FocusMeteringAction.Builder( + point, + FocusMeteringAction.FLAG_AF or FocusMeteringAction.FLAG_AE, + ).setAutoCancelDuration(2, TimeUnit.SECONDS).build() + camera.cameraControl.startFocusAndMetering(action) + } catch (_: Exception) {} + } + + private fun chooseCameraFpsRange(): Range { + return try { + val manager = getSystemService(android.content.Context.CAMERA_SERVICE) as CameraManager + val characteristics = manager.cameraIdList + .asSequence() + .map { manager.getCameraCharacteristics(it) } + .firstOrNull { it.get(CameraCharacteristics.LENS_FACING) == CameraCharacteristics.LENS_FACING_BACK } + val ranges = characteristics?.get(CameraCharacteristics.CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES) + ?.toList().orEmpty() + ranges + .filter { it.upper <= 60 && it.lower <= 30 } + .maxWithOrNull(compareBy> { it.upper }.thenBy { it.lower }) + ?: ranges.filter { it.upper <= 60 } + .maxWithOrNull(compareBy> { it.upper }.thenBy { it.lower }) + ?: ranges.maxWithOrNull(compareBy> { it.upper }.thenBy { it.lower }) + ?: Range(30, 30) + } catch (_: Exception) { + Range(30, 30) + } + } + private fun buildCameraUi(mode: ScannerMode): FrameLayout { val root = FrameLayout(this).apply { setBackgroundColor(Color.BLACK) } previewView = PreviewView(this).apply { @@ -226,6 +366,8 @@ class MainActivity : ComponentActivity() { scaleType = PreviewView.ScaleType.FILL_CENTER } root.addView(previewView, FrameLayout.LayoutParams(-1, -1)) + qrLockOverlay = QrLockOverlay(this) + root.addView(qrLockOverlay, FrameLayout.LayoutParams(-1, -1)) val top = LinearLayout(this).apply { orientation = LinearLayout.HORIZONTAL @@ -245,20 +387,25 @@ class MainActivity : ComponentActivity() { background = rounded(0xE80C0E12.toInt(), 18) } deviceText = text( - if (mode == ScannerMode.OPTICAL) "接收设备:$receiverDeviceLabel\n发送设备:等待 QFT1 MANIFEST…" + if (mode == ScannerMode.OPTICAL) "接收设备:$receiverDeviceLabel\n发送设备:等待 QFT2 MANIFEST…" else "目标:等待 QFTPAIR2 配对二维码", 14f, Color.WHITE ) statusText = text( - if (mode == ScannerMode.OPTICAL) "把电脑动态二维码完整放进取景框" + if (mode == ScannerMode.OPTICAL) "让电脑的单个大二维码占取景框 50% 以上,识别后会自动锁定区域" else "扫描 Windows“手机传电脑”页面上的二维码", 14f, MUTED ) progress = ProgressBar(this, null, android.R.attr.progressBarStyleHorizontal).apply { max = 1000; progress = 0 } panel.addView(deviceText) panel.addView(statusText, matchWrap(top = 7)) + scannerLockText = text( + if (mode == ScannerMode.OPTICAL) "区域锁定:搜索中" else "配对识别:快速模式", + 12f, ACCENT + ) + panel.addView(scannerLockText, matchWrap(top = 6)) scannerStatsText = text("相机分析:等待首帧…", 12f, ACCENT) - panel.addView(scannerStatsText, matchWrap(top = 6)) + panel.addView(scannerStatsText, matchWrap(top = 4)) panel.addView(progress, LinearLayout.LayoutParams(-1, dp(8)).apply { topMargin = dp(12) }) root.addView(panel, FrameLayout.LayoutParams(-1, -2, Gravity.BOTTOM).apply { leftMargin = dp(12); rightMargin = dp(12); bottomMargin = dp(12) @@ -514,9 +661,16 @@ class MainActivity : ComponentActivity() { private fun stopCamera() { try { cameraProvider?.unbindAll() } catch (_: Exception) {} cameraProvider = null + activeCamera = null + lastLockFocusAt = 0L + lastLockFocusX = -1f + lastLockFocusY = -1f currentAnalyzer?.close() currentAnalyzer = null + qrLockOverlay?.clear() + qrLockOverlay = null scannerStatsText = null + scannerLockText = null scannerMode = ScannerMode.NONE } diff --git a/android/app/src/main/java/com/qft/optical/Protocol.kt b/android/app/src/main/java/com/qft/optical/Protocol.kt index 8370f92..72564ea 100644 --- a/android/app/src/main/java/com/qft/optical/Protocol.kt +++ b/android/app/src/main/java/com/qft/optical/Protocol.kt @@ -32,18 +32,30 @@ data class Manifest( ) object QftProtocol { - const val PREFIX = "QFT1:" - private const val VERSION = 1 + const val PREFIX = "QFT2:" + private const val LEGACY_PREFIX = "QFT1:" + /** Active QFT2 path: Base45 keeps the QR in compact alphanumeric mode. */ fun parseText(text: String): QftFrame? { - if (!text.startsWith(PREFIX)) return null - val binary = try { - Base64Url.decode(text.substring(PREFIX.length)) ?: return null - } catch (_: IllegalArgumentException) { - return null + return when { + text.startsWith(PREFIX) -> { + val binary = Base45.decode(text.substring(PREFIX.length)) ?: return null + parseBinary(binary, expectedMagic = "QFT2", expectedVersion = 2) + } + text.startsWith(LEGACY_PREFIX) -> { + val binary = try { + Base64Url.decode(text.substring(LEGACY_PREFIX.length)) ?: return null + } catch (_: IllegalArgumentException) { + return null + } + parseBinary(binary, expectedMagic = "QFT1", expectedVersion = 1) + } + else -> null } - if (binary.size < 28) return null + } + private fun parseBinary(binary: ByteArray, expectedMagic: String, expectedVersion: Int): QftFrame? { + if (binary.size < 28) return null val bodySize = binary.size - 4 val expectedCrc = ByteBuffer.wrap(binary, bodySize, 4) .order(ByteOrder.BIG_ENDIAN) @@ -52,12 +64,10 @@ object QftProtocol { if (crc != expectedCrc) return null val bb = ByteBuffer.wrap(binary, 0, bodySize).order(ByteOrder.BIG_ENDIAN) - val magic = ByteArray(4).also(bb::get) - if (!magic.contentEquals(byteArrayOf('Q'.code.toByte(), 'F'.code.toByte(), 'T'.code.toByte(), '1'.code.toByte()))) { - return null - } + val magic = ByteArray(4).also(bb::get).toString(Charsets.US_ASCII) + if (magic != expectedMagic) return null val version = bb.get().toInt() and 0xff - if (version != VERSION) return null + if (version != expectedVersion) return null val kind = try { FrameKind.fromWire(bb.get().toInt() and 0xff) } catch (_: Exception) { return null } val sessionId = bb.long val seq = bb.int.toLong() and 0xffff_ffffL @@ -90,7 +100,6 @@ object QftProtocol { .trim() .ifBlank { "Windows-PC" } } else { - // Backward compatibility with v0.1/v0.1.2 manifests. "Windows-PC" } diff --git a/android/app/src/main/java/com/qft/optical/QrAnalyzer.kt b/android/app/src/main/java/com/qft/optical/QrAnalyzer.kt index 53ab4bd..ca34dca 100644 --- a/android/app/src/main/java/com/qft/optical/QrAnalyzer.kt +++ b/android/app/src/main/java/com/qft/optical/QrAnalyzer.kt @@ -2,40 +2,76 @@ package com.qft.optical import androidx.camera.core.ImageAnalysis import androidx.camera.core.ImageProxy -import com.google.zxing.BarcodeFormat import com.google.zxing.BinaryBitmap -import com.google.zxing.DecodeHintType -import com.google.zxing.MultiFormatReader import com.google.zxing.PlanarYUVLuminanceSource +import com.google.zxing.Result import com.google.zxing.common.GlobalHistogramBinarizer import com.google.zxing.common.HybridBinarizer -import java.util.concurrent.Callable -import java.util.concurrent.Executors +import com.google.zxing.qrcode.QRCodeReader +/** One decoded QR result. QFT2 optical frames are consumed from text (Base45). */ +data class DecodedQr( + val text: String, + val rawBytes: ByteArray?, +) + +/** + * Single-channel high-frequency scanner. + * + * Acquisition: centered crop -> occasional full-frame search. + * Locked: only copy/decode the QR ROI, with progressive expansion on misses. + * + * The old four-reader/2x2 path is intentionally gone. One large QR gives the + * camera more pixels/module and lets the decoder spend CPU on one useful code. + */ class QrAnalyzer( private val profile: Profile, - private val onTexts: (List) -> Unit, - private val onStats: (cameraFramesPerSecond: Double, decodedPerSecond: Double) -> Unit = { _, _ -> }, + private val onCode: (DecodedQr) -> Unit, + private val onStats: ( + cameraFramesPerSecond: Double, + decodedPerSecond: Double, + distinctPerSecond: Double, + averageDecodeMs: Double, + ) -> Unit = { _, _, _, _ -> }, + private val onLock: (ScannerLockState) -> Unit = {}, ) : ImageAnalysis.Analyzer { - enum class Profile { PAIR_FAST, OPTICAL_MULTI } + enum class Profile { PAIR_FAST, OPTICAL_LOCKED } - private val readers = Array(5) { newReader() } - private val decodePool = Executors.newFixedThreadPool(Runtime.getRuntime().availableProcessors().coerceIn(2, 4)) + private val reader = QRCodeReader() + private val grayBuffer = GrayFrameBuffer() private var frameCounter = 0L private var decodedCounter = 0L + private var distinctCounter = 0L + private var lastFingerprint: Int? = null + private var decodeNanos = 0L + private var decodeAttempts = 0L private var windowStarted = android.os.SystemClock.elapsedRealtime() + private var lockRegion: LockRect? = null + private var lockMisses = 0 + private var lastReportedLock: LockRect? = null + private var lastLockFlag = false + override fun analyze(image: ImageProxy) { try { - val gray = GrayFrame.from(image) frameCounter++ - val results = when (profile) { - Profile.PAIR_FAST -> decodePair(gray) - Profile.OPTICAL_MULTI -> decodeOptical(gray) - }.distinct() - if (results.isNotEmpty()) { - decodedCounter += results.size - onTexts(results) + val result = when (profile) { + Profile.PAIR_FAST -> decodePair(image) + Profile.OPTICAL_LOCKED -> decodeOptical(image) + } + if (result != null) { + decodedCounter++ + val text = result.text.orEmpty() + val fingerprint = text.hashCode() + val isNew = lastFingerprint != fingerprint + if (isNew) { + distinctCounter++ + lastFingerprint = fingerprint + // Dynamic optical frames often remain on screen for more than + // one camera exposure. Do not feed duplicates into the file + // assembler/UI; decoding stats still count the successful hit. + onCode(DecodedQr(text, result.rawBytes)) + } } reportStatsIfNeeded() } finally { @@ -43,120 +79,180 @@ class QrAnalyzer( } } - private fun decodePair(gray: GrayFrame): List { - // QFTPAIR2 is intentionally compact. Try a cheap centered GlobalHistogram - // pass first, then the full frame every time so off-axis scans do not wait - // several frames. HybridBinarizer is reserved for every third miss. - val marginX = (gray.width * 0.08).toInt() - val marginY = (gray.height * 0.08).toInt() - decodeRegion( - gray, marginX, marginY, gray.width - marginX * 2, gray.height - marginY * 2, - readers[0], hybridFallback = false, - )?.let { return listOf(it) } - decodeRegion(gray, 0, 0, gray.width, gray.height, readers[0], hybridFallback = false) - ?.let { return listOf(it) } - if (frameCounter % 3L == 0L) { - decodeRegion(gray, 0, 0, gray.width, gray.height, readers[0], hybridFallback = true) - ?.let { return listOf(it) } + private fun decodePair(image: ImageProxy): Result? { + // Pairing QR is static. Center-first keeps the common path cheap while + // still allowing off-center framing every second frame. + val center = LockRect.centeredSearch(image.width, image.height, 0.82f) + val centered = grayBuffer.capture(image, center) + decodeDense(centered, hybrid = false)?.let { return it } + + if (frameCounter % 2L == 0L) { + val full = grayBuffer.capture(image) + decodeDense(full, hybrid = false)?.let { return it } + if (frameCounter % 6L == 0L) decodeDense(full, hybrid = true)?.let { return it } } - return emptyList() + return null } - private fun decodeOptical(gray: GrayFrame): List { - // v0.3 Windows can present a 2x2 grid. Decode quadrants concurrently. - // 8% overlap tolerates perspective/centering error around the middle. - val overlapX = (gray.width * 0.08).toInt() - val overlapY = (gray.height * 0.08).toInt() - val halfW = gray.width / 2 - val halfH = gray.height / 2 - val regions = arrayOf( - intArrayOf(0, 0, (halfW + overlapX).coerceAtMost(gray.width), (halfH + overlapY).coerceAtMost(gray.height)), - intArrayOf((halfW - overlapX).coerceAtLeast(0), 0, gray.width - (halfW - overlapX).coerceAtLeast(0), (halfH + overlapY).coerceAtMost(gray.height)), - intArrayOf(0, (halfH - overlapY).coerceAtLeast(0), (halfW + overlapX).coerceAtMost(gray.width), gray.height - (halfH - overlapY).coerceAtLeast(0)), - intArrayOf((halfW - overlapX).coerceAtLeast(0), (halfH - overlapY).coerceAtLeast(0), gray.width - (halfW - overlapX).coerceAtLeast(0), gray.height - (halfH - overlapY).coerceAtLeast(0)), + private fun decodeOptical(image: ImageProxy): Result? { + val current = lockRegion + if (current != null) { + // Fast hot path: only copy/decode the locked ROI. Most phones spend + // far less time here than repeatedly scanning the entire frame. + val crop = grayBuffer.capture(image, current) + decodeDense(crop, hybrid = false)?.let { result -> + lockMisses = 0 + updateLockFromResult(result, crop) + return result + } + + lockMisses++ + // HybridBinarizer is slower but more robust against moire/exposure. + // Use it sparingly rather than doubling work on every camera frame. + if (lockMisses % 4 == 0) { + decodeDense(crop, hybrid = true)?.let { result -> + lockMisses = 0 + updateLockFromResult(result, crop) + return result + } + } + + // Follow small hand movement without immediately returning to a + // costly full-frame search. Only unlock after sustained misses. + if (lockMisses == 3 || lockMisses == 6) { + lockRegion = current.expand( + image.width, + image.height, + if (lockMisses == 3) 1.20f else 1.45f, + ) + publishLock(image, locked = true) + } + if (lockMisses >= 10) { + lockRegion = null + lockMisses = 0 + publishLock(image, locked = false) + } + return null + } + + // Acquire: center-first, full frame every second camera frame. At the + // default 640x480 analysis size this is substantially cheaper than the + // previous 960x540 + four-region search. + val search = LockRect.centeredSearch(image.width, image.height, 0.84f) + val centered = grayBuffer.capture(image, search) + decodeDense(centered, hybrid = false)?.let { result -> + updateLockFromResult(result, centered) + return result + } + + if (frameCounter % 2L == 0L) { + val full = grayBuffer.capture(image) + decodeDense(full, hybrid = false)?.let { result -> + updateLockFromResult(result, full) + return result + } + if (frameCounter % 6L == 0L) { + decodeDense(full, hybrid = true)?.let { result -> + updateLockFromResult(result, full) + return result + } + } + } + publishLock(image, locked = false) + return null + } + + private fun decodeDense(gray: GrayFrame, hybrid: Boolean): Result? { + if (gray.width < 96 || gray.height < 96) return null + val source = PlanarYUVLuminanceSource( + gray.luma, + gray.width, + gray.height, + 0, + 0, + gray.width, + gray.height, + false, ) - val tasks = regions.mapIndexed { index, r -> - Callable { - decodeRegion(gray, r[0], r[1], r[2], r[3], readers[index], hybridFallback = false) - } - } - val found = try { - decodePool.invokeAll(tasks).mapNotNull { future -> - try { future.get() } catch (_: Exception) { null } - } - } catch (_: Exception) { - emptyList() - } - if (found.isNotEmpty()) return found - - // Backward-compatible single-QR fallback. Limit the expensive hybrid - // pass to every third frame so low-end Android 7 devices stay responsive. - return if (frameCounter % 3L == 0L) { - decodeRegion(gray, 0, 0, gray.width, gray.height, readers[4], hybridFallback = true) - ?.let(::listOf) ?: emptyList() - } else emptyList() - } - - private fun decodeRegion( - gray: GrayFrame, - left: Int, - top: Int, - width: Int, - height: Int, - reader: MultiFormatReader, - hybridFallback: Boolean, - ): String? { - if (width < 80 || height < 80) return null - val source = try { - PlanarYUVLuminanceSource( - gray.luma, gray.width, gray.height, - left.coerceAtLeast(0), top.coerceAtLeast(0), - width.coerceAtMost(gray.width - left.coerceAtLeast(0)), - height.coerceAtMost(gray.height - top.coerceAtLeast(0)), - false, - ) - } catch (_: Exception) { return null } - - try { - return reader.decodeWithState(BinaryBitmap(GlobalHistogramBinarizer(source)))?.text - } catch (_: Exception) { - if (!hybridFallback) return null - } finally { - reader.reset() - } + val started = System.nanoTime() + decodeAttempts++ return try { - reader.decodeWithState(BinaryBitmap(HybridBinarizer(source)))?.text + val bitmap = if (hybrid) { + BinaryBitmap(HybridBinarizer(source)) + } else { + BinaryBitmap(GlobalHistogramBinarizer(source)) + } + reader.decode(bitmap) } catch (_: Exception) { null } finally { + decodeNanos += System.nanoTime() - started reader.reset() } } + private fun updateLockFromResult(result: Result, gray: GrayFrame) { + if (profile != Profile.OPTICAL_LOCKED) return + val points = result.resultPoints + ?.map { (it.x + gray.originX) to (it.y + gray.originY) } + .orEmpty() + val measured = LockRect.fromPoints(points, gray.fullWidth, gray.fullHeight) + ?: lockRegion + ?: LockRect.centeredSearch(gray.fullWidth, gray.fullHeight, 0.62f) + // Smooth small finder-point jitter so the crop and on-screen overlay do + // not visibly vibrate while a dynamic QR is changing every frame. + val next = lockRegion?.smoothToward(measured, 0.30f) ?: measured + val changed = next.materiallyDiffers(lockRegion) + lockRegion = next + lockMisses = 0 + if (changed || !lastLockFlag) { + publishLock( + frameWidth = gray.fullWidth, + frameHeight = gray.fullHeight, + rotationDegrees = gray.rotationDegrees, + locked = true, + ) + } + } + + private fun publishLock(image: ImageProxy, locked: Boolean) { + publishLock(image.width, image.height, image.imageInfo.rotationDegrees, locked) + } + + private fun publishLock(frameWidth: Int, frameHeight: Int, rotationDegrees: Int, locked: Boolean) { + val region = lockRegion + val changed = locked != lastLockFlag || region?.materiallyDiffers(lastReportedLock) == true || + (!locked && lastReportedLock != null) + if (!changed && frameCounter % 15L != 0L) return + lastLockFlag = locked + lastReportedLock = region + onLock( + ScannerLockState( + locked = locked, + region = region, + frameWidth = frameWidth, + frameHeight = frameHeight, + rotationDegrees = rotationDegrees, + misses = lockMisses, + searchAreaFraction = region?.areaFraction(frameWidth, frameHeight) ?: 1f, + ) + ) + } + private fun reportStatsIfNeeded() { val now = android.os.SystemClock.elapsedRealtime() val elapsed = now - windowStarted if (elapsed < 1000L) return val seconds = elapsed / 1000.0 - onStats(frameCounter / seconds, decodedCounter / seconds) + val averageMs = if (decodeAttempts == 0L) 0.0 else decodeNanos / 1_000_000.0 / decodeAttempts + onStats(frameCounter / seconds, decodedCounter / seconds, distinctCounter / seconds, averageMs) frameCounter = 0 decodedCounter = 0 + distinctCounter = 0 + decodeNanos = 0 + decodeAttempts = 0 windowStarted = now } - fun close() { - decodePool.shutdownNow() - } - - companion object { - private fun newReader() = MultiFormatReader().apply { - setHints( - mapOf( - DecodeHintType.POSSIBLE_FORMATS to listOf(BarcodeFormat.QR_CODE), - DecodeHintType.TRY_HARDER to false, - DecodeHintType.CHARACTER_SET to "UTF-8", - ) - ) - } - } + fun close() = Unit } diff --git a/android/app/src/main/java/com/qft/optical/QrLockOverlay.kt b/android/app/src/main/java/com/qft/optical/QrLockOverlay.kt new file mode 100644 index 0000000..3ffb9bd --- /dev/null +++ b/android/app/src/main/java/com/qft/optical/QrLockOverlay.kt @@ -0,0 +1,154 @@ +package com.qft.optical + +import android.content.Context +import android.graphics.Canvas +import android.graphics.Color +import android.graphics.Paint +import android.graphics.Path +import android.graphics.PointF +import android.graphics.RectF +import android.view.View +import kotlin.math.max + +/** Visualizes the ROI that the decoder is actually using. */ +class QrLockOverlay(context: Context) : View(context) { + private val stroke = Paint(Paint.ANTI_ALIAS_FLAG).apply { + style = Paint.Style.STROKE + strokeWidth = resources.displayMetrics.density * 3f + } + private val shade = Paint(Paint.ANTI_ALIAS_FLAG).apply { + style = Paint.Style.FILL + color = 0x66000000 + } + private val fill = Paint(Paint.ANTI_ALIAS_FLAG).apply { + style = Paint.Style.FILL + color = 0x1600E5A8 + } + private val sweep = Paint(Paint.ANTI_ALIAS_FLAG).apply { + style = Paint.Style.STROKE + strokeWidth = resources.displayMetrics.density + color = 0x9920E3A2.toInt() + } + private var state: ScannerLockState? = null + + fun update(next: ScannerLockState) { + state = next + invalidate() + } + + fun clear() { + state = null + invalidate() + } + + fun lockedCenterInView(): PointF? { + val s = state ?: return null + val region = s.region ?: return null + if (!s.locked || width <= 0 || height <= 0) return null + val rect = mapRegionToView(region, s) + return PointF(rect.centerX(), rect.centerY()) + } + + override fun onDraw(canvas: Canvas) { + super.onDraw(canvas) + val s = state + if (s == null || width <= 0 || height <= 0) { + drawSearchGuide(canvas) + return + } + val region = s.region + if (!s.locked || region == null) { + drawSearchGuide(canvas) + return + } + + val rect = mapRegionToView(region, s) + val radius = resources.displayMetrics.density * 14f + stroke.color = if (s.misses <= 2) 0xFF20E3A2.toInt() else 0xFFFFC857.toInt() + val pulse = ((android.os.SystemClock.uptimeMillis() / 180L) % 2L).toFloat() + stroke.strokeWidth = resources.displayMetrics.density * (if (pulse < 0.5f) 2.6f else 3.4f) + canvas.drawRoundRect(rect, radius, radius, fill) + + val outside = Path().apply { + fillType = Path.FillType.EVEN_ODD + addRect(0f, 0f, width.toFloat(), height.toFloat(), Path.Direction.CW) + addRoundRect(rect, radius, radius, Path.Direction.CW) + } + canvas.drawPath(outside, shade) + canvas.drawRoundRect(rect, radius, radius, stroke) + drawCorners(canvas, rect, stroke) + + // Lightweight dynamic sweep shows that the *locked ROI* is the active + // decoder area. This only animates the overlay; it never touches camera + // pixels or the ImageAnalysis thread. + val phase = (android.os.SystemClock.uptimeMillis() % 1200L) / 1200f + val scanY = rect.top + rect.height() * phase + sweep.color = if (s.misses <= 2) 0x9920E3A2.toInt() else 0x99FFC857.toInt() + canvas.drawLine(rect.left + rect.width() * 0.08f, scanY, rect.right - rect.width() * 0.08f, scanY, sweep) + postInvalidateDelayed(100L) + } + + private fun drawSearchGuide(canvas: Canvas) { + val side = minOf(width, height) * 0.72f + val rect = RectF( + (width - side) / 2f, + (height - side) / 2f, + (width + side) / 2f, + (height + side) / 2f, + ) + stroke.color = 0xCCFFFFFF.toInt() + stroke.strokeWidth = resources.displayMetrics.density * 2f + drawCorners(canvas, rect, stroke) + } + + private fun drawCorners(canvas: Canvas, rect: RectF, paint: Paint) { + val len = minOf(rect.width(), rect.height()) * 0.12f + val p = Path() + p.moveTo(rect.left, rect.top + len); p.lineTo(rect.left, rect.top); p.lineTo(rect.left + len, rect.top) + p.moveTo(rect.right - len, rect.top); p.lineTo(rect.right, rect.top); p.lineTo(rect.right, rect.top + len) + p.moveTo(rect.left, rect.bottom - len); p.lineTo(rect.left, rect.bottom); p.lineTo(rect.left + len, rect.bottom) + p.moveTo(rect.right - len, rect.bottom); p.lineTo(rect.right, rect.bottom); p.lineTo(rect.right, rect.bottom - len) + canvas.drawPath(p, paint) + } + + private fun mapRegionToView(region: LockRect, s: ScannerLockState): RectF { + val fw = s.frameWidth.toFloat().coerceAtLeast(1f) + val fh = s.frameHeight.toFloat().coerceAtLeast(1f) + val l = region.left / fw + val t = region.top / fh + val r = region.right / fw + val b = region.bottom / fh + + val corners = arrayOf( + rotate(l, t, s.rotationDegrees), rotate(r, t, s.rotationDegrees), + rotate(l, b, s.rotationDegrees), rotate(r, b, s.rotationDegrees), + ) + val minX = corners.minOf { it.first } + val maxX = corners.maxOf { it.first } + val minY = corners.minOf { it.second } + val maxY = corners.maxOf { it.second } + + val rotatedW = if (s.rotationDegrees % 180 == 0) s.frameWidth.toFloat() else s.frameHeight.toFloat() + val rotatedH = if (s.rotationDegrees % 180 == 0) s.frameHeight.toFloat() else s.frameWidth.toFloat() + // PreviewView uses FILL_CENTER: scale to fill then crop equally. + val scale = max(width / rotatedW.coerceAtLeast(1f), height / rotatedH.coerceAtLeast(1f)) + val renderedW = rotatedW * scale + val renderedH = rotatedH * scale + val offsetX = (width - renderedW) / 2f + val offsetY = (height - renderedH) / 2f + + return RectF( + offsetX + minX * renderedW, + offsetY + minY * renderedH, + offsetX + maxX * renderedW, + offsetY + maxY * renderedH, + ) + } + + private fun rotate(x: Float, y: Float, degrees: Int): Pair = when ((degrees % 360 + 360) % 360) { + 90 -> (1f - y) to x + 180 -> (1f - x) to (1f - y) + 270 -> y to (1f - x) + else -> x to y + } +} diff --git a/android/app/src/main/java/com/qft/optical/ScannerLockState.kt b/android/app/src/main/java/com/qft/optical/ScannerLockState.kt new file mode 100644 index 0000000..eab63f2 --- /dev/null +++ b/android/app/src/main/java/com/qft/optical/ScannerLockState.kt @@ -0,0 +1,11 @@ +package com.qft.optical + +data class ScannerLockState( + val locked: Boolean, + val region: LockRect?, + val frameWidth: Int, + val frameHeight: Int, + val rotationDegrees: Int, + val misses: Int, + val searchAreaFraction: Float, +) diff --git a/android/app/src/main/java/com/qft/optical/SessionAssembler.kt b/android/app/src/main/java/com/qft/optical/SessionAssembler.kt index df479a8..621466f 100644 --- a/android/app/src/main/java/com/qft/optical/SessionAssembler.kt +++ b/android/app/src/main/java/com/qft/optical/SessionAssembler.kt @@ -30,9 +30,11 @@ class SessionAssembler( @Synchronized fun acceptText(text: String) { - val frame = QftProtocol.parseText(text) ?: return - if (completedSession == frame.sessionId) return + acceptFrame(QftProtocol.parseText(text) ?: return) + } + private fun acceptFrame(frame: QftFrame) { + if (completedSession == frame.sessionId) return when (frame.kind) { FrameKind.MANIFEST -> acceptManifest(frame) FrameKind.DATA -> acceptData(frame) diff --git a/android/app/src/test/java/com/qft/optical/LockRectTest.kt b/android/app/src/test/java/com/qft/optical/LockRectTest.kt new file mode 100644 index 0000000..25e0f47 --- /dev/null +++ b/android/app/src/test/java/com/qft/optical/LockRectTest.kt @@ -0,0 +1,35 @@ +package com.qft.optical + +import org.junit.Assert.assertTrue +import org.junit.Test + +class LockRectTest { + @Test fun finderPointsProduceBoundedSquareRoi() { + val lock = LockRect.fromPoints( + listOf(300f to 180f, 660f to 180f, 300f to 540f), + 960, + 720, + ) ?: error("lock missing") + assertTrue(lock.width == lock.height) + assertTrue(lock.left >= 0 && lock.top >= 0) + assertTrue(lock.right <= 960 && lock.bottom <= 720) + assertTrue(lock.areaFraction(960, 720) < 0.36f) + } + + @Test fun missesCanExpandRoiWithoutLeavingFrame() { + val base = LockRect(250, 100, 420, 420) + val expanded = base.expand(960, 540, 1.35f) + assertTrue(expanded.width >= base.width) + assertTrue(expanded.left >= 0 && expanded.top >= 0) + assertTrue(expanded.right <= 960 && expanded.bottom <= 540) + } + + @Test fun smoothingReducesLockJitter() { + val a = LockRect(100, 100, 300, 300) + val b = LockRect(140, 130, 340, 340) + val smoothed = a.smoothToward(b, 0.25f) + assertTrue(smoothed.left in 101..139) + assertTrue(smoothed.top in 101..129) + assertTrue(smoothed.width in 301..339) + } +} diff --git a/android/app/src/test/java/com/qft/optical/ProtocolTest.kt b/android/app/src/test/java/com/qft/optical/ProtocolTest.kt index eaff9ff..2f5c0bf 100644 --- a/android/app/src/test/java/com/qft/optical/ProtocolTest.kt +++ b/android/app/src/test/java/com/qft/optical/ProtocolTest.kt @@ -4,35 +4,30 @@ import org.junit.Assert.* import org.junit.Test import java.nio.ByteBuffer import java.nio.ByteOrder -import java.util.Base64 import java.util.zip.CRC32 class ProtocolTest { @Test - fun parsesDataFrameAndRejectsCorruption() { + fun base45KnownVectors() { + assertArrayEquals("AB".toByteArray(), Base45.decode("BB8")) + assertArrayEquals("Hello!!".toByteArray(), Base45.decode("%69 VD92EX0")) + assertArrayEquals("base-45".toByteArray(), Base45.decode("UJCLQE7W581")) + } + + @Test + fun parsesQft2DataFrameAndRejectsCorruption() { val payload = byteArrayOf(1, 2, 3, 4, 5) - val text = encode(kind = 2, session = 7L, seq = 9, total = 11, payload = payload) + val text = encodeQft2(kind = 2, session = 7L, seq = 9, total = 11, payload = payload) val f = QftProtocol.parseText(text)!! assertEquals(FrameKind.DATA, f.kind) assertEquals(7L, f.sessionId) assertEquals(9L, f.seq) assertArrayEquals(payload, f.payload) - val corrupted = text.dropLast(1) + if (text.last() == 'A') "B" else "A" + val corrupted = text.dropLast(1) + if (text.last() == '0') "1" else "0" assertNull(QftProtocol.parseText(corrupted)) } - @Test - fun parsesCrossLanguageKnownVector() { - val text = "QFT1:UUZUMQECAQIDBAUGBwgAAAADAAAACgAJaGVsbG8tcWZ0XhNTAg" - val f = QftProtocol.parseText(text)!! - assertEquals(FrameKind.DATA, f.kind) - assertEquals(0x0102030405060708L, f.sessionId) - assertEquals(3L, f.seq) - assertEquals(10L, f.totalChunks) - assertEquals("hello-qft", f.payload.toString(Charsets.UTF_8)) - } - @Test fun parsesManifestSenderDevice() { val name = "test.txt".toByteArray() @@ -41,26 +36,25 @@ class ProtocolTest { val payload = ByteBuffer.allocate(8 + 2 + 32 + 2 + name.size + 2 + device.size) .order(ByteOrder.BIG_ENDIAN) .putLong(1234L) - .putShort(700.toShort()) + .putShort(450.toShort()) .put(sha) .putShort(name.size.toShort()) .put(name) .putShort(device.size.toShort()) .put(device) .array() - val text = encode(kind = 1, session = 77L, seq = 0, total = 2, payload = payload) - val frame = QftProtocol.parseText(text)!! - val manifest = QftProtocol.parseManifest(frame)!! + val text = encodeQft2(kind = 1, session = 77L, seq = 0, total = 3, payload = payload) + val manifest = QftProtocol.parseManifest(QftProtocol.parseText(text)!!)!! assertEquals("DESKTOP-ZHY", manifest.senderDevice) assertEquals("test.txt", manifest.fileName) assertEquals(1234L, manifest.fileSize) - assertEquals(700, manifest.chunkSize) + assertEquals(450, manifest.chunkSize) } - private fun encode(kind: Int, session: Long, seq: Int, total: Int, payload: ByteArray): String { + private fun encodeQft2(kind: Int, session: Long, seq: Int, total: Int, payload: ByteArray): String { val bb = ByteBuffer.allocate(24 + payload.size + 4).order(ByteOrder.BIG_ENDIAN) - bb.put("QFT1".toByteArray()) - bb.put(1) + bb.put("QFT2".toByteArray()) + bb.put(2) bb.put(kind.toByte()) bb.putLong(session) bb.putInt(seq) @@ -70,6 +64,25 @@ class ProtocolTest { val bodyLen = bb.position() val crc = CRC32().apply { update(bb.array(), 0, bodyLen) }.value bb.putInt(crc.toInt()) - return "QFT1:" + Base64.getUrlEncoder().withoutPadding().encodeToString(bb.array()) + return "QFT2:" + base45Encode(bb.array()) + } + + private fun base45Encode(data: ByteArray): String { + val alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:" + val out = StringBuilder((data.size * 3 + 1) / 2) + var i = 0 + while (i + 1 < data.size) { + val value = (data[i].toInt() and 0xff) * 256 + (data[i + 1].toInt() and 0xff) + out.append(alphabet[value % 45]) + out.append(alphabet[(value / 45) % 45]) + out.append(alphabet[value / 2025]) + i += 2 + } + if (i < data.size) { + val value = data[i].toInt() and 0xff + out.append(alphabet[value % 45]) + out.append(alphabet[value / 45]) + } + return out.toString() } } diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md index 108a706..64d6873 100644 --- a/docs/PROTOCOL.md +++ b/docs/PROTOCOL.md @@ -1,86 +1,88 @@ -# QFT protocol overview · v0.3.0-rc3 +# QFT protocol notes — v0.4.0-rc2 -## QFT1 — Windows → Android optical stream +## 1. Windows → Android optical: QFT2 -Wire text: +Active display text: -`QFT1:` +```text +QFT2: +``` -Binary frame fields: +Base45 is used because its alphabet fits QR alphanumeric encoding, while Android can consume a normal ZXing `Result.text`. The receiver also keeps legacy `QFT1:` parsing for old senders. -- magic `QFT1` -- protocol version -- frame kind: MANIFEST / DATA / END -- session id -- sequence index -- total chunks -- payload length -- payload -- CRC32 +### Binary frame -MANIFEST contains file name, file size, chunk size, total chunks, SHA-256 and Windows sender-device name. DATA frames are replayed cyclically; Android de-duplicates chunks and waits for missing chunks in later rounds. No Android→Windows feedback channel is used in optical mode. +```text +magic 4 "QFT2" +version 1 2 +kind 1 1=MANIFEST / 2=DATA / 3=END +session 8 u64 BE +sequence 4 u32 BE +total 4 u32 BE +payloadLen 2 u16 BE +payload N +crc32 4 u32 BE over everything before crc32 +``` -v0.3 defaults: 900-byte DATA payload, 4 QR/page, target up to 60 pages/s. +### MANIFEST payload -## QFTPAIR2 — Android → Windows pairing +```text +fileSize 8 u64 BE +chunkSize 2 u16 BE +sha256 32 +fileNameLen 2 u16 BE +fileName N UTF-8 +senderLen 2 u16 BE +senderDevice N UTF-8 +``` -Text: +### Optical parameters in rc2 -`QFTPAIR2:` +- one QR per display frame; +- DATA payload: **450 B**; +- QR error correction: L; +- full 4-module quiet zone; +- Windows display target: 5~60 FPS, default 45; +- synthetic representative DATA frame: 722 text chars / QR-L v15; +- theoretical payload at 60 display FPS: 27,000 B/s ≈ 26.4 KiB/s before camera misses/replay. -Compact JSON keys: +Sender continuously loops `MANIFEST → DATA 0..N-1 → END`. Android deduplicates by sequence number and reconstructs once all chunks are present. No reverse ACK/network channel exists for this direction. -- `v`: 2 -- `s`: one-time session token -- `n`: Windows device name -- `p`: receiver TCP port -- `e`: local HTTP endpoint hints; Direct AP normally carries one short hint -- `w`: optional `[ssid, passphrase]` for QFT Direct +## 2. Android optical ROI state machine -QFTPAIR1 remains parser-compatible for older QR payloads. +```text +ACQUIRE + center search + occasional full frame + ↓ success +LOCKED + copy Y-plane ROI only + GlobalHistogram every frame + sparse Hybrid fallback + ↓ finder points + smooth ROI position/size + ↓ misses + expand ROI + ↓ sustained misses +REACQUIRE +``` -Android treats pairing QR as untrusted. HTTP endpoint hints must be literal private/local IPv4 addresses on the advertised port. Every `/qft/*` request must carry the one-time `X-QFT-Token` session value. +The overlay is derived from the same ROI used by the decoder, so the green/yellow box is not decorative—it reflects the actual analysis area. -## Receiver discovery +## 3. Android → Windows pairing -UDP request to port 39392: +`QFTPAIR2` remains the active pairing format from v0.3. It contains local-only session/network metadata. Android validates the pairing endpoint as a literal local/private IPv4 and binds subsequent discovery/upload to the selected local `Network`. -`QFTDISC2:` +Discovery order includes QR hint, UDP `QFTDISC2`, gateway/direct candidates and bounded current-subnet fallback. -Windows response: +## 4. Android → Windows upload -`QFTHERE2::` +Parallel v2 flow: -Android combines UDP result with QR hint, the actual connected Wi-Fi gateway, common Windows local addresses and a bounded current-subnet fallback scan. +```text +POST /qft/upload/init +POST /qft/upload/chunk (parallel, offset based) +POST /qft/upload/finish +``` -## Parallel v2 upload - -### Ping - -`GET /qft/ping` - -Headers include `X-QFT-Token` and encoded Android device name. - -### Init - -`POST /qft/upload/init` - -Headers include file name, file size and desired chunk size. Android requests 4/8/16 MiB depending on file size; Windows clamps accepted chunks to 1~16 MiB. - -Response includes `upload_id`, accepted `chunk_size`, and `total_chunks`. - -### Chunk - -`POST /qft/upload/chunk//` - -Body is exactly that file range. Up to eight Android workers send distinct chunks concurrently. Windows writes each accepted chunk to the preallocated `.qftpart` file at its deterministic offset. - -### Finish - -`POST /qft/upload/finish/` - -Windows rejects finish while chunks are missing. Once complete it computes SHA-256, renames the temporary file to its final unique name, and returns success. - -### Compatibility - -`POST /qft/upload` remains the single-stream fallback for old clients or content providers that cannot sustain seekable parallel reads. +Windows preallocates a `.qftpart`, writes chunks at explicit offsets, verifies SHA-256, then renames to the final file. Per-file worker count is capped at 8; chunk size is selected from 4/8/16 MiB by file size. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 836075a..16df714 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,58 +1,16 @@ -# Roadmap +# QFT Roadmap -## V0.1 — 单 QR 无网络链路(当前) +## v0.4 physical validation -- Windows 选择文件 -- 单 QR 动画 -- Android CameraX 连续识别 -- CRC32 -- SHA-256 -- 重复帧去重 -- 多轮补洞 -- 保存 Downloads/QFT +1. Use **450 B / single QR** as the baseline and measure real-phone distinct new-frame/s at Windows 30 / 45 / 60 FPS. +2. Record lock acquisition time, locked ROI area, camera FPS, successful decode/s, distinct new-frame/s and reacquire time per device. +3. Only after real-device data exists, test nearby DATA payloads (e.g. 390 / 450 / 510 B) and keep the value with the highest *effective* file throughput rather than the highest theoretical bytes/frame. +4. Add optional Windows FPS presets chosen from observed Android effective new-frame/s; the optical transport itself remains strictly one-way. +5. Tune focus/exposure behavior across LCD/OLED and 60/120 Hz panels. -目标不是速度,而是证明:**飞行模式下可稳定完整恢复真实文件**。 +## Later -## V0.2 — 扫码稳定性 - -- 自动曝光/对焦锁定 -- 只分析中央 ROI -- 720p/1080p 自适应 -- 帧序号抖动统计 -- 自动 FPS 调节 -- QR 版本/纠错级别动态选择 -- Android 前台常亮、屏幕方向锁定 - -## V0.3 — 多 QR - -- Windows 2x2 -> 3x3 网格 -- Android 一帧多码检测 -- 每个位置独立 lane -- lane interleave,避免同一丢帧损失连续数据 - -## V0.4 — Fountain / RaptorQ - -- source block / symbol -- 无需等待指定 seq -- 达到恢复阈值即可完成 -- 发送端持续产生 repair symbols -- 删除“整文件循环重播”的尾部等待 - -## V0.5 — QFT Visual Code - -- 固定四角定位 -- 自定义二值网格 -- BCH/LDPC 内层纠错 -- SIMD 二值化与采样 -- 60/120 FPS -- 标定显示器刷新率与相机 rolling shutter - -## V0.6 — Android -> Windows - -这个方向因 PC 可能无摄像头,使用 App P2P: - -- 同 LAN -- 临时热点 -- Wi-Fi Direct(可用平台) -- QUIC -- 不经过外网/云端 +- Fountain/RaptorQ to reduce whole-playlist replay cost without a reverse ACK channel. +- Native SIMD/custom visual decoder if ZXing remains the dominant bottleneck. +- Optional custom QFT Visual Code after the single-QR baseline is measured. +- iOS/macOS/Linux clients. diff --git a/scripts/android_compat_selftest.py b/scripts/android_compat_selftest.py index 45fc131..db3aaa4 100644 --- a/scripts/android_compat_selftest.py +++ b/scripts/android_compat_selftest.py @@ -1,27 +1,27 @@ #!/usr/bin/env python3 from pathlib import Path import re -ROOT = Path(__file__).resolve().parents[1] -gradle = (ROOT/'android/app/build.gradle.kts').read_text() -manifest = (ROOT/'android/app/src/main/AndroidManifest.xml').read_text() -wifi = (ROOT/'android/app/src/main/java/com/qft/optical/WifiConnector.kt').read_text() -upload = (ROOT/'android/app/src/main/java/com/qft/optical/UploadClient.kt').read_text() -main = (ROOT/'android/app/src/main/java/com/qft/optical/MainActivity.kt').read_text() -gray = (ROOT/'android/app/src/main/java/com/qft/optical/GrayFrame.kt').read_text() -security = (ROOT/'android/app/src/main/res/xml/network_security_config.xml').read_text() - -assert re.search(r'minSdk\s*=\s*24', gradle) +ROOT=Path(__file__).resolve().parents[1] +gradle=(ROOT/'android/app/build.gradle.kts').read_text(); manifest=(ROOT/'android/app/src/main/AndroidManifest.xml').read_text() +wifi=(ROOT/'android/app/src/main/java/com/qft/optical/WifiConnector.kt').read_text(); upload=(ROOT/'android/app/src/main/java/com/qft/optical/UploadClient.kt').read_text() +main=(ROOT/'android/app/src/main/java/com/qft/optical/MainActivity.kt').read_text(); analyzer=(ROOT/'android/app/src/main/java/com/qft/optical/QrAnalyzer.kt').read_text() +gray=(ROOT/'android/app/src/main/java/com/qft/optical/GrayFrame.kt').read_text(); protocol=(ROOT/'android/app/src/main/java/com/qft/optical/Protocol.kt').read_text(); base45=(ROOT/'android/app/src/main/java/com/qft/optical/Base45.kt').read_text(); overlay=(ROOT/'android/app/src/main/java/com/qft/optical/QrLockOverlay.kt').read_text(); security=(ROOT/'android/app/src/main/res/xml/network_security_config.xml').read_text() +assert re.search(r'minSdk\s*=\s*24',gradle) assert 'WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="28"' in manifest -assert 'ACCESS_FINE_LOCATION" android:maxSdkVersion="32"' in manifest -assert 'NEARBY_WIFI_DEVICES' in manifest -assert 'networkSecurityConfig="@xml/network_security_config"' in manifest -assert 'cleartextTrafficPermitted="true"' in security -assert 'Build.VERSION.SDK_INT >= 29' in wifi and 'connectLegacy' in wifi -assert 'subnetEndpoints' in wifi and 'directedBroadcast' in wifi -assert 'MAX_WORKERS = 8' in upload and 'QFTDISC2:' in upload and 'workers = 24' in upload and 'desiredChunkSize' in upload and 'CHUNK_LARGE' in upload -assert 'Size(640, 480)' in main and 'Size(1280, 720)' in main -assert 'STRATEGY_KEEP_ONLY_LATEST' in main -assert 'rotate90' not in gray and 'image.imageInfo.rotationDegrees' not in gray -all_kotlin = '\n'.join(path.read_text() for path in (ROOT/'android/app/src/main/java/com/qft/optical').glob('*.kt')) +assert 'ACCESS_FINE_LOCATION" android:maxSdkVersion="32"' in manifest and 'NEARBY_WIFI_DEVICES' in manifest +assert 'networkSecurityConfig="@xml/network_security_config"' in manifest and 'cleartextTrafficPermitted="true"' in security +assert 'Build.VERSION.SDK_INT >= 29' in wifi and 'connectLegacy' in wifi and 'subnetEndpoints' in wifi and 'directedBroadcast' in wifi +assert 'MAX_WORKERS = 8' in upload and 'QFTDISC2:' in upload +assert 'val targetSize = Size(640, 480)' in main and 'Size(960, 540)' not in main +assert 'Camera2Interop.Extender' in main and 'CONTROL_AE_TARGET_FPS_RANGE' in main and 'STRATEGY_KEEP_ONLY_LATEST' in main +assert '设备拒绝显式高帧率请求' in main and 'fallbackAnalysis' in main +assert 'OPTICAL_LOCKED' in analyzer and 'OPTICAL_MULTI' not in analyzer and 'QRCodeReader' in analyzer and 'MultiFormatReader' not in analyzer +assert 'LockRect.fromPoints' in analyzer and 'grayBuffer.capture(image, current)' in analyzer +assert 'GrayFrameBuffer' in gray and 'scratch = ByteArray(0)' in gray +assert 'Base45.decode' in protocol and 'QFT2' in protocol and 'looksLikeBinaryFrame' not in protocol +assert 'lockedCenterInView' in overlay and 'postInvalidateDelayed' in overlay and 'maybeRefocusLockedQr' in main +assert 'assembler.acceptText(code.text)' in main and 'acceptBinary' not in main +assert 'BB8' in base45 or 'ALPHABET' in base45 +all_kotlin='\n'.join(path.read_text() for path in (ROOT/'android/app/src/main/java/com/qft/optical').glob('*.kt')) assert 'java.util.Base64' not in all_kotlin -print('PASS Android compatibility/static guards: minSdk24, API29 split, legacy storage/location, Android13 nearby-WiFi, cleartext local config, subnet fallback, fast scanner paths') +print('PASS Android static guards: API24+, 640x480 single-QR ROI, reusable luma buffer, QFT2/Base45 text parse, dynamic lock/refocus, Camera2 FPS request, legacy/new Wi-Fi compatibility') diff --git a/scripts/kotlin_host_smoke.py b/scripts/kotlin_host_smoke.py new file mode 100644 index 0000000..4d903fa --- /dev/null +++ b/scripts/kotlin_host_smoke.py @@ -0,0 +1,52 @@ +#!/usr/bin/env python3 +"""Host-side Kotlin smoke tests. Uses kotlinc if present; does not require Android SDK.""" +from pathlib import Path +import shutil, subprocess, tempfile, textwrap, os + +ROOT=Path(__file__).resolve().parents[1] +K=ROOT/'android/app/src/main/java/com/qft/optical' +kotlinc=shutil.which('kotlinc') +if not kotlinc: + print('SKIP Kotlin host smoke: kotlinc not installed (Android Gradle tests still cover these files on a dev host)') + raise SystemExit(0) + +def run(args): + env=os.environ.copy(); env.setdefault('TERM','xterm') + p=subprocess.run(args, text=True, capture_output=True, env=env) + if p.returncode: + print(p.stdout); print(p.stderr); raise SystemExit(p.returncode) + +with tempfile.TemporaryDirectory() as td: + td=Path(td) + smoke=td/'Smoke.kt' + smoke.write_text(textwrap.dedent(r''' + package com.qft.optical + import java.nio.ByteBuffer + import java.nio.ByteOrder + import java.util.zip.CRC32 + fun b45e(data: ByteArray): String { val a="0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:"; val o=StringBuilder(); var i=0; while(i+1; val imageInfo:ImageInfo; fun close(); interface PlaneProxy { val buffer:ByteBuffer; val rowStride:Int; val pixelStride:Int }; interface ImageInfo { val rotationDegrees:Int } } + ''')) + (td/'com/google/zxing/Zxing.kt').write_text('package com.google.zxing\nopen class LuminanceSource(val width:Int,val height:Int)\nclass PlanarYUVLuminanceSource(data:ByteArray,dataWidth:Int,dataHeight:Int,left:Int,top:Int,width:Int,height:Int,reverseHorizontal:Boolean):LuminanceSource(width,height)\nclass BinaryBitmap(val binarizer:Any)\ndata class ResultPoint(val x:Float,val y:Float)\nclass Result(val text:String?="",val rawBytes:ByteArray?=null,val resultPoints:Array?=null)\n') + (td/'com/google/zxing/common/Common.kt').write_text('package com.google.zxing.common\nimport com.google.zxing.LuminanceSource\nclass GlobalHistogramBinarizer(source:LuminanceSource)\nclass HybridBinarizer(source:LuminanceSource)\n') + (td/'com/google/zxing/qrcode/QRCodeReader.kt').write_text('package com.google.zxing.qrcode\nimport com.google.zxing.BinaryBitmap\nimport com.google.zxing.Result\nclass QRCodeReader { fun decode(bitmap:BinaryBitmap):Result=Result(); fun reset(){} }\n') + out=td/'analyzer.jar' + sources=[td/'android/os/SystemClock.kt',td/'androidx/camera/core/Core.kt',td/'com/google/zxing/Zxing.kt',td/'com/google/zxing/common/Common.kt',td/'com/google/zxing/qrcode/QRCodeReader.kt',K/'LockRect.kt',K/'ScannerLockState.kt',K/'GrayFrame.kt',K/'QrAnalyzer.kt'] + run([kotlinc,*map(str,sources),'-d',str(out)]) + print('PASS Kotlin QrAnalyzer compile smoke with CameraX/ZXing-shaped stubs') diff --git a/scripts/memory_budget_selftest.py b/scripts/memory_budget_selftest.py index 538bae4..49db3ea 100644 --- a/scripts/memory_budget_selftest.py +++ b/scripts/memory_budget_selftest.py @@ -2,16 +2,9 @@ MAX_CACHE_MIB = 768 MAX_PAGES = 192 HARD_MIB = 1100 - -def calc(side): - bpp = side * side * 4 - pages = max(4, min(MAX_PAGES, MAX_CACHE_MIB * 1024 * 1024 // bpp)) - managed = pages * bpp / (1024 * 1024) - return pages, managed - -p4, m4 = calc(960) -p1, m1 = calc(760) -# Include a conservative 64 MiB transient batch/decoder allowance in this design-level bound. -assert m4 + 64 < HARD_MIB -assert m1 + 64 < HARD_MIB -print(f"PASS memory budget: 4QR cache={p4} pages/{m4:.1f} MiB; 1QR cache={p1} pages/{m1:.1f} MiB; hard design ceiling={HARD_MIB} MiB") +SIDE = 1024 +bpp = SIDE * SIDE * 4 +pages = max(4, min(MAX_PAGES, MAX_CACHE_MIB * 1024 * 1024 // bpp)) +managed = pages * bpp / (1024 * 1024) +assert managed + 96 < HARD_MIB +print(f"PASS memory budget: single-QR cache={pages} frames/{managed:.1f} MiB + 96 MiB transient allowance < {HARD_MIB} MiB") diff --git a/scripts/optical_image_decode_selftest.py b/scripts/optical_image_decode_selftest.py index 142e026..ac54024 100644 --- a/scripts/optical_image_decode_selftest.py +++ b/scripts/optical_image_decode_selftest.py @@ -1,55 +1,51 @@ #!/usr/bin/env python3 -"""Synthetic visual-path smoke test for the 4-QR optical page and QFTPAIR2. -Requires: qrcode, numpy, opencv-python, pyzbar/libzbar. -This is intentionally not a substitute for a real display/camera test. -""" -import base64, json, os, time +"""Synthetic QFT2/Base45 single-QR acquisition/ROI smoke test. Not a physical camera test.""" +import binascii, os, struct, time import cv2 import numpy as np import qrcode from pyzbar.pyzbar import decode as zdecode, ZBarSymbol -from qrcode.constants import ERROR_CORRECT_L, ERROR_CORRECT_M +from qrcode.constants import ERROR_CORRECT_L +B45="0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:" +def b45(data): + out=[]; i=0 + while i+1 < len(data): + v=data[i]*256+data[i+1]; out += [B45[v%45],B45[(v//45)%45],B45[v//2025]]; i+=2 + if iQIIH",0x1020304050607080,7,1000,len(payload))+payload +raw=body+struct.pack(">I",binascii.crc32(body)&0xffffffff) +text="QFT2:"+b45(raw) +qr=qrcode.QRCode(version=None,error_correction=ERROR_CORRECT_L,box_size=1,border=4) +qr.add_data(text); qr.make(fit=True) +assert qr.version <= 15, qr.version +mat=np.asarray(qr.get_matrix(),dtype=np.uint8) +# Make the large single code fill ~70% of the 480px analysis height. +scale=max(1,340//mat.shape[0]) +symbol=((1-np.kron(mat,np.ones((scale,scale),np.uint8)))*255).astype(np.uint8) +canvas=np.full((480,640),255,np.uint8) +side=symbol.shape[0]; x=max(8,(640-side)//2); y=max(8,(480-side)//2) +canvas[y:y+side,x:x+side]=symbol +rot=cv2.getRotationMatrix2D((320,240),3.0,1.0) +frame=cv2.warpAffine(canvas,rot,(640,480),borderValue=255) +frame=cv2.GaussianBlur(frame,(3,3),0.35) +expected=text.encode() +found=zdecode(frame,symbols=[ZBarSymbol.QRCODE]); assert any(r.data==expected for r in found) +r=next(r for r in found if r.data==expected) +pad=int(max(r.rect.width,r.rect.height)*0.08) +l=max(0,r.rect.left-pad); t=max(0,r.rect.top-pad); rr=min(frame.shape[1],r.rect.left+r.rect.width+pad); bb=min(frame.shape[0],r.rect.top+r.rect.height+pad) +roi=frame[t:bb,l:rr] +assert any(z.data==expected for z in zdecode(roi,symbols=[ZBarSymbol.QRCODE])) +area=roi.size/frame.size; assert area < 0.80 -# Four data QR symbols at the same density used by v0.3 (about 1243 chars/frame). -texts = ["QFT1:" + base64.urlsafe_b64encode(os.urandom(928)).decode().rstrip("=") for _ in range(4)] -canvas = np.full((960, 960), 255, np.uint8) -gutter = 15 -cell = (960 - gutter * 3) // 2 -for idx, text in enumerate(texts): - img, version = make_qr(text, ERROR_CORRECT_L, cell) - row, col = divmod(idx, 2) - x = gutter + col * (cell + gutter) + (cell - img.shape[1]) // 2 - y = gutter + row * (cell + gutter) + (cell - img.shape[0]) // 2 - canvas[y:y+img.shape[0], x:x+img.shape[1]] = img -started = time.perf_counter() -found = {r.data.decode() for r in zdecode(canvas, symbols=[ZBarSymbol.QRCODE])} -elapsed = time.perf_counter() - started -assert found == set(texts), (len(found), len(texts)) - -# Pairing QR: downscale + rotate + slight blur to exercise acquisition margin. -v2 = { - "v":2,"s":"qft_test_session_128bit_XY","n":"DESKTOP-QFT","p":39393, - "e":["http://192.168.137.1:39393"], - "w":["QFT-DESKTOP-abc123","3xamplePassw0rd"], -} -raw = json.dumps(v2, separators=(",", ":"), ensure_ascii=False).encode() -pair_text = "QFTPAIR2:" + base64.urlsafe_b64encode(raw).decode().rstrip("=") -pair, pair_ver = make_qr(pair_text, ERROR_CORRECT_M, 520) -pair = cv2.resize(pair, (260, 260), interpolation=cv2.INTER_NEAREST) -rot = cv2.getRotationMatrix2D((130, 130), 7.0, 1.0) -pair = cv2.warpAffine(pair, rot, (300, 300), borderValue=255) -pair = cv2.GaussianBlur(pair, (3, 3), 0.5) -started2 = time.perf_counter() -pair_found = [r.data.decode() for r in zdecode(pair, symbols=[ZBarSymbol.QRCODE])] -elapsed2 = time.perf_counter() - started2 -assert pair_text in pair_found -print(f"PASS synthetic QR decode: 4/4 optical QR v{version} decoded from 960px page in {elapsed*1000:.1f} ms; " - f"QFTPAIR2 QR-M v{pair_ver} decoded after 7deg rotate+blur in {elapsed2*1000:.1f} ms") +def avg_ms(img,loops=40): + started=time.perf_counter() + for _ in range(loops): zdecode(img,symbols=[ZBarSymbol.QRCODE]) + return (time.perf_counter()-started)*1000/loops +full_ms=avg_ms(frame); roi_ms=avg_ms(roi) +assert roi_ms < full_ms*1.15 +print(f"PASS synthetic QFT2 lock: QR-L v{qr.version}, {len(text)} chars; full={full_ms:.1f}ms, lockedROI={roi_ms:.1f}ms, ROI area={area*100:.1f}%") diff --git a/scripts/protocol_selftest.py b/scripts/protocol_selftest.py index 1ffc6be..42be27a 100644 --- a/scripts/protocol_selftest.py +++ b/scripts/protocol_selftest.py @@ -3,96 +3,114 @@ import base64, binascii, hashlib, math, os, random, struct import qrcode from qrcode.constants import ERROR_CORRECT_L -PREFIX = "QFT1:" -CHUNK = 900 -LANES = 4 +PREFIX = "QFT2:" +LEGACY_PREFIX = "QFT1:" +CHUNK = 450 DISPLAY_FPS = 60 +B45 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:" -def enc(kind, sid, seq, total, payload=b""): +def b45encode(data: bytes) -> str: + out=[] + i=0 + while i+1 < len(data): + v=data[i]*256+data[i+1] + out += [B45[v%45], B45[(v//45)%45], B45[v//2025]] + i += 2 + if i < len(data): + v=data[i] + out += [B45[v%45], B45[v//45]] + return ''.join(out) + + +def b45decode(text: str) -> bytes: + rev={c:i for i,c in enumerate(B45)} + out=bytearray(); i=0 + while i < len(text): + rem=len(text)-i + if rem == 1: raise ValueError('bad Base45 length') + if rem >= 3: + v=rev[text[i]] + 45*rev[text[i+1]] + 2025*rev[text[i+2]] + if v > 0xffff: raise ValueError('overflow') + out += bytes((v//256, v%256)); i += 3 + else: + v=rev[text[i]] + 45*rev[text[i+1]] + if v > 0xff: raise ValueError('overflow') + out.append(v); i += 2 + return bytes(out) + + +def enc_binary(kind, sid, seq, total, payload=b""): + body = b"QFT2" + bytes([2, kind]) + struct.pack(">QIIH", sid, seq, total, len(payload)) + payload + crc = binascii.crc32(body) & 0xFFFFFFFF + return body + struct.pack(">I", crc) + + +def enc_text(kind, sid, seq, total, payload=b""): + return PREFIX + b45encode(enc_binary(kind, sid, seq, total, payload)) + + +def legacy_text(kind, sid, seq, total, payload=b""): body = b"QFT1" + bytes([1, kind]) + struct.pack(">QIIH", sid, seq, total, len(payload)) + payload crc = binascii.crc32(body) & 0xFFFFFFFF - return PREFIX + base64.urlsafe_b64encode(body + struct.pack(">I", crc)).decode().rstrip("=") + raw=body+struct.pack(">I",crc) + return LEGACY_PREFIX + base64.urlsafe_b64encode(raw).decode().rstrip('=') -def dec(text): +def dec_text(text): assert text.startswith(PREFIX) - b64 = text[len(PREFIX):] - raw = base64.urlsafe_b64decode(b64 + "=" * (-len(b64) % 4)) + raw=b45decode(text[len(PREFIX):]) body, crc_raw = raw[:-4], raw[-4:] assert (binascii.crc32(body) & 0xFFFFFFFF) == struct.unpack(">I", crc_raw)[0] - assert body[:4] == b"QFT1" and body[4] == 1 - kind = body[5] - sid, seq, total, plen = struct.unpack(">QIIH", body[6:24]) - payload = body[24:] - assert len(payload) == plen - return kind, sid, seq, total, payload + assert body[:4] == b"QFT2" and body[4] == 2 + kind=body[5] + sid,seq,total,plen=struct.unpack(">QIIH", body[6:24]) + payload=body[24:] + assert len(payload)==plen + return kind,sid,seq,total,payload -def test_qr_density(sample): - qr = qrcode.QRCode(version=None, error_correction=ERROR_CORRECT_L, box_size=1, border=4) - qr.add_data(sample) - qr.make(fit=True) - modules_with_quiet = qr.modules_count + 8 - canvas = 960 - gutter = max(12, min(24, canvas // 64)) - cell = (canvas - gutter * 3) // 2 - module_px = cell // modules_with_quiet - assert module_px >= 3, (qr.version, qr.modules_count, cell, module_px) - return qr.version, module_px, len(sample) +def qr_info(sample: str): + qr=qrcode.QRCode(version=None,error_correction=ERROR_CORRECT_L,box_size=1,border=4) + qr.add_data(sample); qr.make(fit=True) + modules_with_quiet=qr.modules_count+8 + return qr.version, 1024//modules_with_quiet, modules_with_quiet def main(): + assert b45encode(b"AB") == "BB8" and b45decode("BB8") == b"AB" + assert b45encode(b"Hello!!") == "%69 VD92EX0" and b45decode("%69 VD92EX0") == b"Hello!!" + assert b45encode(b"base-45") == "UJCLQE7W581" and b45decode("UJCLQE7W581") == b"base-45" + random.seed(20260810) - data = os.urandom(2_500_123) - digest = hashlib.sha256(data).digest() - total = math.ceil(len(data) / CHUNK) - sid = 0x1234567890ABCDEF - name = b"sample.bin" - device = b"DESKTOP-QFT" - manifest = ( - struct.pack(">QH", len(data), CHUNK) - + digest - + struct.pack(">H", len(name)) + name - + struct.pack(">H", len(device)) + device - ) - playlist = [enc(1, sid, 0, total, manifest)] - playlist += [enc(2, sid, i, total, data[i*CHUNK:(i+1)*CHUNK]) for i in range(total)] - playlist += [enc(3, sid, 0, total)] - pages = [playlist[i:i+LANES] for i in range(0, len(playlist), LANES)] + data=os.urandom(1_200_123); digest=hashlib.sha256(data).digest() + total=math.ceil(len(data)/CHUNK); sid=0x1234567890ABCDEF + name=b"sample.bin"; device=b"DESKTOP-QFT" + manifest=struct.pack(">QH",len(data),CHUNK)+digest+struct.pack(">H",len(name))+name+struct.pack(">H",len(device))+device + playlist=[enc_text(1,sid,0,total,manifest)] + playlist += [enc_text(2,sid,i,total,data[i*CHUNK:(i+1)*CHUNK]) for i in range(total)] + playlist += [enc_text(3,sid,0,total)] - version, module_px, chars = test_qr_density(playlist[min(2, len(playlist)-1)]) + sample=playlist[min(2,len(playlist)-1)] + version,module_px,modules=qr_info(sample) + legacy=legacy_text(2,sid,0,total,os.urandom(480)) + legacy_version,legacy_px,_=qr_info(legacy) + assert version <= 15,(version,len(sample)) + assert module_px >= 10,(version,modules,module_px) + assert version < legacy_version,(version,legacy_version) - got = [None] * total - rounds = 0 - manifests = 0 - # Model both whole-camera-frame losses and per-lane decode failures. + got=[None]*total; rounds=0 while any(x is None for x in got): rounds += 1 - for page in pages: - if random.random() < 0.24: # display page/camera frame missed - continue - for text in page: - if random.random() < 0.14: # one quadrant not decoded - continue - kind, rsid, seq, rtotal, payload = dec(text) - assert rsid == sid and rtotal == total - if kind == 1: - manifests += 1 - elif kind == 2 and got[seq] is None: - got[seq] = payload + for text in playlist: + if random.random() < 0.22: continue + kind,rsid,seq,rtotal,payload=dec_text(text) + assert rsid==sid and rtotal==total + if kind==2 and got[seq] is None: got[seq]=payload assert rounds < 60 + rebuilt=b''.join(got)[:len(data)] + assert rebuilt==data and hashlib.sha256(rebuilt).digest()==digest + rate=CHUNK*DISPLAY_FPS + print(f"PASS QFT2/Base45 single-QR: {len(data)} bytes, {total} chunks, 22% frame loss, recovered in {rounds} rounds; QR-L v{version} vs legacy Base64 v{legacy_version}, {module_px}px/module@1024, text={len(sample)} chars, theoretical payload={rate/1024:.1f} KiB/s") - rebuilt = b"".join(got)[:len(data)] - assert rebuilt == data - assert hashlib.sha256(rebuilt).digest() == digest - raw_rate = CHUNK * LANES * DISPLAY_FPS - print( - f"PASS optical: {len(data)} bytes, {total} chunks, {LANES} QR/page @ {DISPLAY_FPS} FPS, " - f"24% page loss + 14% lane loss, recovered in {rounds} rounds; " - f"QR v{version}, {module_px}px/module, frame chars={chars}, theoretical payload={raw_rate/1024:.1f} KiB/s" - ) - - -if __name__ == "__main__": - main() +if __name__=='__main__': main() diff --git a/scripts/requirements-test.txt b/scripts/requirements-test.txt new file mode 100644 index 0000000..1595425 --- /dev/null +++ b/scripts/requirements-test.txt @@ -0,0 +1,4 @@ +qrcode>=7.4 +numpy>=1.24 +opencv-python>=4.8 +pyzbar>=0.1.9 diff --git a/scripts/run_all_selftests.py b/scripts/run_all_selftests.py index a96fbdf..2d6e220 100644 --- a/scripts/run_all_selftests.py +++ b/scripts/run_all_selftests.py @@ -4,14 +4,17 @@ from pathlib import Path root = Path(__file__).resolve().parent scripts = [ 'protocol_selftest.py', + 'optical_image_decode_selftest.py', 'pairing_selftest.py', 'parallel_upload_selftest.py', 'udp_discovery_selftest.py', 'local_transfer_integration_selftest.py', 'memory_budget_selftest.py', 'android_compat_selftest.py', + 'single_channel_guard_selftest.py', + 'kotlin_host_smoke.py', ] for name in scripts: print(f'== {name} ==', flush=True) subprocess.run([sys.executable, str(root/name)], check=True) -print('ALL CORE PYTHON SELFTESTS PASSED') +print('ALL HOST SELFTESTS PASSED') diff --git a/scripts/single_channel_guard_selftest.py b/scripts/single_channel_guard_selftest.py new file mode 100644 index 0000000..d0eb973 --- /dev/null +++ b/scripts/single_channel_guard_selftest.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python3 +from pathlib import Path +ROOT=Path(__file__).resolve().parents[1] +main=(ROOT/'windows/src/main.rs').read_text() +cache=(ROOT/'windows/src/optical_cache.rs').read_text() +qr=(ROOT/'windows/src/qr.rs').read_text() +protocol=(ROOT/'windows/src/protocol.rs').read_text() +base45=(ROOT/'windows/src/base45.rs').read_text() +analyzer=(ROOT/'android/app/src/main/java/com/qft/optical/QrAnalyzer.kt').read_text() +android_protocol=(ROOT/'android/app/src/main/java/com/qft/optical/Protocol.kt').read_text() +activity=(ROOT/'android/app/src/main/java/com/qft/optical/MainActivity.kt').read_text() +assert 'render_qr_grid' not in qr+cache+main +assert 'self.optical.lanes' not in main +assert 'OPTICAL_MULTI' not in analyzer +assert 'newFixedThreadPool' not in analyzer +assert 'DEFAULT_CHUNK_SIZE: u16 = 450' in main +assert 'source.text_frame(page_index)' in cache and 'render_qr_fitted' in cache +assert 'QFT2:' in protocol and 'base45::encode' in protocol and 'EcLevel::L' in qr +assert 'Base45.decode' in android_protocol and 'QFT2' in android_protocol +assert 'assembler.acceptText(code.text)' in activity and 'acceptBinary' not in activity +assert 'grayBuffer.capture(image, current)' in analyzer and 'fingerprint = text.hashCode()' in analyzer +assert 'BB8' in base45 and 'UJCLQE7W581' in base45 +print('PASS single-channel guard: one large QFT2/Base45 QR, 450B chunks, no 2x2/4-lane path, Android locked-ROI text decode only') diff --git a/windows/Cargo.lock b/windows/Cargo.lock index 7fee14f..aaf2497 100644 --- a/windows/Cargo.lock +++ b/windows/Cargo.lock @@ -2587,7 +2587,7 @@ checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea" [[package]] name = "qft-windows" -version = "0.3.0" +version = "0.4.0-rc2" dependencies = [ "anyhow", "base64", diff --git a/windows/Cargo.toml b/windows/Cargo.toml index dbcec68..0f72030 100644 --- a/windows/Cargo.toml +++ b/windows/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "qft-windows" -version = "0.3.0" +version = "0.4.0-rc2" edition = "2024" rust-version = "1.95" diff --git a/windows/src/base45.rs b/windows/src/base45.rs new file mode 100644 index 0000000..10870b7 --- /dev/null +++ b/windows/src/base45.rs @@ -0,0 +1,37 @@ +const ALPHABET: &[u8; 45] = b"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:"; + +/// RFC 9285 Base45. Its alphabet is fully supported by QR alphanumeric mode, +/// so the QR encoder can use fewer modules than Base64 text for the same +/// binary QFT frame while still giving Android a normal Result.text string. +pub fn encode(input: &[u8]) -> String { + if input.is_empty() { + return String::new(); + } + let mut out = String::with_capacity((input.len() * 3 + 1) / 2); + let mut i = 0usize; + while i + 1 < input.len() { + let value = input[i] as usize * 256 + input[i + 1] as usize; + out.push(ALPHABET[value % 45] as char); + out.push(ALPHABET[(value / 45) % 45] as char); + out.push(ALPHABET[value / (45 * 45)] as char); + i += 2; + } + if i < input.len() { + let value = input[i] as usize; + out.push(ALPHABET[value % 45] as char); + out.push(ALPHABET[value / 45] as char); + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn known_vectors() { + assert_eq!(encode(b"AB"), "BB8"); + assert_eq!(encode(b"Hello!!"), "%69 VD92EX0"); + assert_eq!(encode(b"base-45"), "UJCLQE7W581"); + } +} diff --git a/windows/src/main.rs b/windows/src/main.rs index 31e0f13..d1172e8 100644 --- a/windows/src/main.rs +++ b/windows/src/main.rs @@ -1,3 +1,4 @@ +mod base45; mod direct_ap; mod optical_cache; mod pairing; @@ -16,9 +17,9 @@ use std::{ time::{Duration, Instant}, }; -const DEFAULT_CHUNK_SIZE: u16 = 900; +const DEFAULT_CHUNK_SIZE: u16 = 450; const UI_FONT_NAME: &str = "qft-ui"; -const APP_VERSION: &str = "0.3.0-rc3"; +const APP_VERSION: &str = "0.4.0-rc2"; fn main() -> eframe::Result { let options = eframe::NativeOptions { @@ -50,8 +51,11 @@ struct OpticalState { round: u64, playing: bool, fps: f32, - lanes: usize, cache_mib: usize, + control_width: f32, + qr_zoom: f32, + focus_qr: bool, + advanced_open: bool, last_advance: Instant, fps_window_started: Instant, displayed_in_window: u32, @@ -105,14 +109,17 @@ impl QftApp { page_index: 0, round: 0, playing: false, - fps: 60.0, - lanes: 4, - cache_mib: 384, + fps: 45.0, + cache_mib: 256, + control_width: 330.0, + qr_zoom: 1.0, + focus_qr: false, + advanced_open: false, last_advance: Instant::now(), fps_window_started: Instant::now(), displayed_in_window: 0, actual_page_fps: 0.0, - status: "选择文件后开始光学发送。默认 4 码/页 · 60 FPS,缓存不足时会自动停在当前页等待。".into(), + status: "选择文件后开始光学发送。v0.4 使用单个大二维码 + QFT2/Base45 低密度 450B 数据块,优先提高 Android 有效识别率。".into(), }, receive: ReceiveState { save_dir: None, @@ -209,118 +216,180 @@ impl QftApp { self.optical.last_advance = Instant::now(); self.optical_advance(ctx); } - // Keep the UI scheduler hot enough for a 60 Hz display without busy-spinning. ctx.request_repaint_after((interval / 3).max(Duration::from_millis(1))); } ui.horizontal_wrapped(|ui| { - ui.heading("电脑 → Android · 光学极速模式"); + ui.heading("电脑 → Android · 单码锁定极速模式"); ui.separator(); ui.label("屏幕 → 摄像头 · 0 网络"); + ui.separator(); + if ui.button(if self.optical.focus_qr { "退出专注二维码" } else { "专注二维码" }).clicked() { + self.optical.focus_qr = !self.optical.focus_qr; + } }); ui.add_space(8.0); - ui.group(|ui| { + if self.optical.focus_qr { ui.horizontal_wrapped(|ui| { - if ui.button("选择文件").clicked() { self.optical_pick_file(ctx); } - ui.label("刷新率"); - ui.add(egui::Slider::new(&mut self.optical.fps, 1.0..=60.0).suffix(" FPS").step_by(1.0)); - if ui.small_button("15").clicked() { self.optical.fps = 15.0; } - if ui.small_button("30").clicked() { self.optical.fps = 30.0; } - if ui.small_button("60").clicked() { self.optical.fps = 60.0; } - if ui.small_button("极速预设").clicked() { - self.optical.fps = 60.0; - self.optical.lanes = 4; - self.optical.cache_mib = 384; - self.optical.playing = false; - self.restart_optical_pipeline(); - let _ = self.optical_render_first(ctx); - } - }); - - let old_lanes = self.optical.lanes; - let old_cache = self.optical.cache_mib; - ui.horizontal_wrapped(|ui| { - ui.label("视觉并行"); - ui.radio_value(&mut self.optical.lanes, 1, "1 码/页 · 兼容"); - ui.radio_value(&mut self.optical.lanes, 4, "4 码/页 · 极速"); - ui.separator(); - ui.label("预编码缓存"); - ui.add(egui::Slider::new(&mut self.optical.cache_mib, 64..=optical_cache::MAX_MANAGED_CACHE_MIB) - .suffix(" MiB").step_by(64.0)); - }); - ui.small(format!( - "QFT 只允许预编码缓存使用最多 {} MiB,为进程/GPU/系统缓冲预留空间,目标整进程不超过约 {} MiB。", - optical_cache::MAX_MANAGED_CACHE_MIB, optical_cache::HARD_PROCESS_BUDGET_MIB - )); - if old_lanes != self.optical.lanes || old_cache != self.optical.cache_mib { - self.optical.playing = false; - self.restart_optical_pipeline(); - let _ = self.optical_render_first(ctx); - } - - let enabled = self.optical.source.is_some(); - ui.horizontal_wrapped(|ui| { - if ui.add_enabled(enabled, egui::Button::new(if self.optical.playing { "暂停" } else { "开始播放" })).clicked() { - if !self.optical.playing && self.optical.prefetch.is_none() { - self.restart_optical_pipeline(); - } + let enabled = self.optical.source.is_some(); + if ui.add_enabled(enabled, egui::Button::new(if self.optical.playing { "暂停" } else { "播放" })).clicked() { + if !self.optical.playing && self.optical.prefetch.is_none() { self.restart_optical_pipeline(); } self.optical.playing = !self.optical.playing; self.optical.last_advance = Instant::now(); self.optical.fps_window_started = Instant::now(); self.optical.displayed_in_window = 0; } - if ui.add_enabled(enabled, egui::Button::new("回到第 1 页")).clicked() { + ui.label(format!("{:.0} FPS", self.optical.fps)); + ui.add(egui::Slider::new(&mut self.optical.qr_zoom, 0.65..=1.0).text("二维码占比").show_value(false)); + ui.small("控制区已收起,尽可能把屏幕面积留给二维码"); + }); + ui.separator(); + self.optical_qr_panel(ui); + return; + } + + let available = ui.available_size(); + let min_qr_width = 360.0_f32.min(available.x * 0.55); + let max_control = (available.x - min_qr_width - 12.0).max(240.0); + self.optical.control_width = self.optical.control_width.clamp(240.0, max_control); + let split_height = ui.available_height().max(420.0); + + ui.horizontal(|ui| { + ui.allocate_ui_with_layout( + egui::vec2(self.optical.control_width, split_height), + egui::Layout::top_down(egui::Align::Min), + |ui| { + egui::ScrollArea::vertical().show(ui, |ui| { + self.optical_controls(ui, ctx); + }); + }, + ); + + let (bar_rect, bar_response) = ui.allocate_exact_size( + egui::vec2(8.0, split_height), + egui::Sense::drag(), + ); + let bar_color = if bar_response.dragged() || bar_response.hovered() { + ui.visuals().widgets.active.bg_fill + } else { + ui.visuals().widgets.inactive.bg_fill + }; + ui.painter().rect_filled(bar_rect.shrink2(egui::vec2(2.0, 0.0)), 3.0, bar_color); + if bar_response.dragged() { + let dx = ui.input(|i| i.pointer.delta().x); + self.optical.control_width = (self.optical.control_width + dx).clamp(240.0, max_control); + ctx.request_repaint(); + } + bar_response.on_hover_text("拖动压缩/展开控制区,右侧二维码会自动放大"); + + ui.allocate_ui_with_layout( + egui::vec2(ui.available_width(), split_height), + egui::Layout::top_down(egui::Align::Center), + |ui| self.optical_qr_panel(ui), + ); + }); + } + + fn optical_controls(&mut self, ui: &mut egui::Ui, ctx: &egui::Context) { + ui.group(|ui| { + ui.heading("发送控制"); + ui.horizontal_wrapped(|ui| { + if ui.button("选择文件").clicked() { self.optical_pick_file(ctx); } + let enabled = self.optical.source.is_some(); + if ui.add_enabled(enabled, egui::Button::new(if self.optical.playing { "暂停" } else { "开始播放" })).clicked() { + if !self.optical.playing && self.optical.prefetch.is_none() { self.restart_optical_pipeline(); } + self.optical.playing = !self.optical.playing; + self.optical.last_advance = Instant::now(); + self.optical.fps_window_started = Instant::now(); + self.optical.displayed_in_window = 0; + } + if ui.add_enabled(enabled, egui::Button::new("回到第1帧")).clicked() { self.optical.playing = false; self.restart_optical_pipeline(); let _ = self.optical_render_first(ctx); } }); + + ui.add_space(6.0); + ui.label("显示刷新率"); + ui.add(egui::Slider::new(&mut self.optical.fps, 5.0..=60.0).suffix(" FPS").step_by(1.0)); + ui.horizontal_wrapped(|ui| { + if ui.small_button("稳定 30").clicked() { self.optical.fps = 30.0; } + if ui.small_button("平衡 45").clicked() { self.optical.fps = 45.0; } + if ui.small_button("最高 60").clicked() { self.optical.fps = 60.0; } + }); + ui.small("Android 会先全屏搜索一次,然后锁定单个二维码区域进行局部高频解码;60 FPS 是显示目标,实际有效识别率由手机相机决定。"); }); + ui.add_space(8.0); + ui.group(|ui| { + ui.heading("二维码可读性"); + ui.label(format!("单码 · 每块 {} B · QFT2/Base45 · QR-L · 完整静区", DEFAULT_CHUNK_SIZE)); + ui.add(egui::Slider::new(&mut self.optical.qr_zoom, 0.65..=1.0).text("画面占比")); + ui.small("v0.4 已彻底删除 4 码模式;QFT2 使用 Base45 让 QR 进入字母数字模式,比旧 Base64 文本更低密度。默认 450 B 数据块仍保持较低 QR 版本,让 Android 更容易稳定锁定。"); + }); + + ui.add_space(8.0); + ui.checkbox(&mut self.optical.advanced_open, "高级设置"); + if self.optical.advanced_open { + ui.group(|ui| { + let old_cache = self.optical.cache_mib; + ui.label("预编码缓存"); + ui.add(egui::Slider::new(&mut self.optical.cache_mib, 64..=optical_cache::MAX_MANAGED_CACHE_MIB) + .suffix(" MiB").step_by(64.0)); + ui.small(format!( + "托管缓存最多 {} MiB;整进程设计预算约 {} MiB。缓存只影响二维码预编码是否跟得上,不会把整个文件读进内存。", + optical_cache::MAX_MANAGED_CACHE_MIB, optical_cache::HARD_PROCESS_BUDGET_MIB + )); + if old_cache != self.optical.cache_mib { + self.optical.playing = false; + self.restart_optical_pipeline(); + let _ = self.optical_render_first(ctx); + } + }); + } + ui.add_space(8.0); if let Some(source) = self.optical.source.as_ref() { let m = &source.manifest; - let pages = source.total_pages(self.optical.lanes); - let logical_fps = self.optical.fps as f64 * self.optical.lanes as f64; - let payload_rate = logical_fps * m.chunk_size as f64; - ui.columns(3, |cols| { - cols[0].group(|ui| { - ui.small("传输"); - ui.heading(format!("{:.0} FPS", self.optical.fps)); - ui.label(format!("{} 码/页 · {:.0} 逻辑帧/s", self.optical.lanes, logical_fps)); - }); - cols[1].group(|ui| { - ui.small("实测显示"); - ui.heading(format!("{:.1} 页/s", self.optical.actual_page_fps)); - ui.label(format!("理论载荷 ≈ {}/s", human_bytes(payload_rate as u64))); - }); - cols[2].group(|ui| { - ui.small("内存策略"); - ui.heading(format!("{} MiB", self.optical.cache_mib)); - let cap = self.optical.prefetch.as_ref().map(|p| p.capacity_pages).unwrap_or(0); - let page_mib = self.optical.prefetch.as_ref().map(|p| p.estimated_page_mib).unwrap_or(0.0); - ui.label(format!("预编码最多 {cap} 页 · {page_mib:.1} MiB/页 · 定位读取")); - }); + let pages = source.total_playlist_frames().max(1); + let payload_rate = self.optical.fps as f64 * m.chunk_size as f64; + ui.group(|ui| { + ui.small("实时状态"); + ui.heading(format!("{:.1} 页/s", self.optical.actual_page_fps)); + ui.label(format!("理论载荷 ≈ {}/s", human_bytes(payload_rate as u64))); + let cap = self.optical.prefetch.as_ref().map(|p| p.capacity_pages).unwrap_or(0); + let page_mib = self.optical.prefetch.as_ref().map(|p| p.estimated_page_mib).unwrap_or(0.0); + ui.small(format!("预编码缓存:{} MiB · 最多 {cap} 帧 · {page_mib:.1} MiB/帧", self.optical.cache_mib)); + ui.separator(); + ui.label(format!("设备:{} → Android", m.sender_device)); + ui.label(format!("文件:{} · {}", m.file_name, human_bytes(m.file_size))); + ui.label(format!("帧:{}/{} · 完整轮次:{}", self.optical.page_index + 1, pages, self.optical.round)); + ui.small(format!("SHA-256:{}", hex_sha256(&m.sha256))); }); - ui.add_space(6.0); - ui.label(format!("传输设备:{} → Android 光学接收端", m.sender_device)); - ui.label(format!("文件:{} · {}", m.file_name, human_bytes(m.file_size))); - ui.small(format!("源路径:{}", source.path().display())); - ui.label(format!("数据块:{} · 当前页:{}/{} · 完整轮次:{}", m.total_chunks, self.optical.page_index + 1, pages, self.optical.round)); - ui.small(format!("SHA-256:{}", hex_sha256(&m.sha256))); } + ui.add_space(6.0); ui.label(&self.optical.status); - ui.separator(); + } + + fn optical_qr_panel(&mut self, ui: &mut egui::Ui) { if let Some(texture) = &self.optical.texture { let avail = ui.available_size(); - let side = avail.x.min(avail.y).min(680.0).max(320.0); - ui.vertical_centered(|ui| { ui.image((texture.id(), egui::vec2(side, side))); }); + let reserved = if self.optical.focus_qr { 4.0 } else { 28.0 }; + let base = avail.x.min((avail.y - reserved).max(220.0)).max(220.0); + let side = (base * self.optical.qr_zoom).clamp(220.0, base); + ui.vertical_centered(|ui| { + ui.image((texture.id(), egui::vec2(side, side))); + if !self.optical.focus_qr { + ui.small("拖动左侧分隔条可继续放大二维码;也可点击顶部“专注二维码”占满可用区域。"); + } + }); } else { ui.vertical_centered(|ui| { - ui.add_space(100.0); + ui.add_space(120.0); ui.heading("请选择一个文件"); - ui.label("极速模式会在后台并行预编码二维码;手机仍可处于飞行模式。") + ui.label("单个大二维码会在这里显示,Android 识别后自动锁定区域。"); }); } } @@ -437,7 +506,7 @@ impl QftApp { if let Err(e) = self.optical_render_first(ctx) { self.optical.status = format!("生成二维码失败:{e:#}"); } else { - self.optical.status = "文件已载入。默认 4 码/页 · 60 FPS;低端手机若有效 QR/s 明显偏低,可降到 30 FPS。".into(); + self.optical.status = "文件已载入。默认单个大二维码 · QFT2/Base45 450B 数据块 · 45 FPS;可按手机能力切到 30 或 60 FPS。".into(); } } Err(e) => self.optical.status = format!("读取文件失败:{e:#}"), @@ -445,7 +514,7 @@ impl QftApp { } fn optical_canvas_side(&self) -> usize { - if self.optical.lanes == 4 { 960 } else { 760 } + 1024 } fn restart_optical_pipeline(&mut self) { @@ -455,7 +524,6 @@ impl QftApp { let Some(source) = self.optical.source.clone() else { return }; self.optical.prefetch = Some(OpticalPrefetcher::start( source, - self.optical.lanes, self.optical_canvas_side(), self.optical.cache_mib, )); @@ -463,8 +531,8 @@ impl QftApp { fn optical_render_first(&mut self, ctx: &egui::Context) -> anyhow::Result<()> { let Some(source) = self.optical.source.as_ref() else { return Ok(()) }; - let texts = source.text_page(0, self.optical.lanes)?; - let image = qr::render_qr_grid(&texts, self.optical_canvas_side())?; + let text = source.text_frame(0)?; + let image = qr::render_qr_fitted(&text, self.optical_canvas_side())?; self.set_optical_texture(ctx, image); self.optical.page_index = 0; self.optical.round = 0; @@ -507,7 +575,7 @@ impl QftApp { self.optical.status = if self.optical.actual_page_fps + 3.0 < self.optical.fps as f64 && self.optical.actual_page_fps > 1.0 { "实际页面速率低于目标:可降低 FPS 或把缓存调高;文件数据仍会循环补帧。".into() } else { - "正在光学发送 · 4 码模式会把一页拆成四个独立 QR 并行解码。".into() + "正在光学发送 · 单个大二维码,Android 锁定后仅在二维码 ROI 内高频解码。".into() }; } Err(std::sync::mpsc::TryRecvError::Empty) => { diff --git a/windows/src/optical_cache.rs b/windows/src/optical_cache.rs index eb4f9de..51a71e3 100644 --- a/windows/src/optical_cache.rs +++ b/windows/src/optical_cache.rs @@ -11,14 +11,12 @@ use std::{ time::Duration, }; -/// Keep the managed pre-render cache comfortably below the user's 1.1 GiB -/// whole-process ceiling. egui, GPU staging, Rust stacks and OS buffers still -/// need headroom, so QFT never intentionally reserves the entire 1.1 GiB. +/// Managed pre-render cache stays below the requested whole-process ceiling. pub const HARD_PROCESS_BUDGET_MIB: usize = 1100; pub const MAX_MANAGED_CACHE_MIB: usize = 768; const MIN_CACHE_MIB: usize = 64; const MAX_CACHE_PAGES: usize = 192; -const PREENCODE_BATCH: usize = 8; +const PREENCODE_BATCH: usize = 12; pub struct EncodedPage { pub page_index: u32, @@ -38,12 +36,10 @@ pub struct OpticalPrefetcher { impl OpticalPrefetcher { pub fn start( source: Arc, - lanes: usize, canvas_side: usize, requested_cache_mib: usize, ) -> Self { let cache_mib = requested_cache_mib.clamp(MIN_CACHE_MIB, MAX_MANAGED_CACHE_MIB); - // ColorImage uses Color32 pixels: approximately four bytes per pixel. let bytes_per_page = canvas_side.saturating_mul(canvas_side).saturating_mul(4).max(1); let budget_bytes = cache_mib.saturating_mul(1024 * 1024); let capacity_pages = (budget_bytes / bytes_per_page).clamp(4, MAX_CACHE_PAGES); @@ -52,11 +48,10 @@ impl OpticalPrefetcher { let stop = Arc::new(AtomicBool::new(false)); let stop_worker = stop.clone(); - // Render several consecutive pages in one Rayon batch. At 4 QR/page this - // lets all CPU cores work across both pages and QR lanes and is much more - // likely to keep a 60 Hz presentation queue full than a single-page loop. + // Single QR on screen, but multiple *future frames* are encoded in + // parallel so the display thread can still target 60 Hz. let thread = thread::spawn(move || { - let total_pages = source.total_pages(lanes).max(1); + let total_pages = source.total_playlist_frames().max(1); let mut next_page = 0u32; let mut next_round = 0u64; while !stop_worker.load(Ordering::Relaxed) { @@ -74,8 +69,8 @@ impl OpticalPrefetcher { .into_par_iter() .filter_map(|(order, page_index, round)| { if stop_worker.load(Ordering::Relaxed) { return None; } - let texts = source.text_page(page_index, lanes).ok()?; - let image = qr::render_qr_grid(&texts, canvas_side).ok()?; + let text = source.text_frame(page_index).ok()?; + let image = qr::render_qr_fitted(&text, canvas_side).ok()?; Some((order, EncodedPage { page_index, round, image })) }) .collect(); @@ -86,7 +81,6 @@ impl OpticalPrefetcher { continue; } - // Reorder the parallel batch explicitly before queueing. for (_, mut item) in rendered { loop { match tx.try_send(item) { diff --git a/windows/src/protocol.rs b/windows/src/protocol.rs index f4cccd4..84646b0 100644 --- a/windows/src/protocol.rs +++ b/windows/src/protocol.rs @@ -1,8 +1,7 @@ +use crate::base45; use anyhow::{bail, Context, Result}; -use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine as _}; use crc32fast::hash as crc32; use rand::RngCore; -use rayon::prelude::*; use sha2::{Digest, Sha256}; use std::{ fs::File, @@ -10,8 +9,8 @@ use std::{ path::{Path, PathBuf}, }; -pub const PREFIX: &str = "QFT1:"; -pub const VERSION: u8 = 1; +pub const PREFIX: &str = "QFT2:"; +pub const VERSION: u8 = 2; #[derive(Clone, Copy, Debug)] #[repr(u8)] @@ -55,12 +54,7 @@ impl TransferSource { bail!("file requires too many chunks"); } - // Keep a single read-only file handle and use positioned reads for each - // optical chunk. This avoids mapping/touching a multi-GB file into the - // process working set, so the bounded QR prefetch cache remains the - // dominant managed memory consumer. let sha256 = hash_file_streaming(&file)?; - let mut rng = rand::rng(); let session_id = rng.next_u64(); let file_name = path @@ -93,43 +87,17 @@ impl TransferSource { self.manifest.total_chunks.saturating_add(2) } - pub fn total_pages(&self, lanes: usize) -> u32 { - let lanes = lanes.max(1) as u32; - let frames = self.total_playlist_frames(); - (frames + lanes - 1) / lanes - } - - /// Returns 1..=4 QFT text frames for one visual page. QR encodes are generated - /// in parallel by rayon; file bytes are read with positioned reads so workers - /// do not contend on a shared seek cursor and large files are not memory-mapped. - pub fn text_page(&self, page_index: u32, lanes: usize) -> Result> { - let lanes = lanes.clamp(1, 4); - let total = self.total_playlist_frames(); - let start = page_index.saturating_mul(lanes as u32); - if start >= total { - bail!("page index out of range"); - } - let indices: Vec = (0..lanes) - .map(|lane| start + lane as u32) - .filter(|idx| *idx < total) - .collect(); - indices - .into_par_iter() - .map(|idx| self.text_frame(idx)) - .collect() - } - /// playlist_index: 0=manifest, 1..=N=data, N+1=end - pub fn text_frame(&self, playlist_index: u32) -> Result { + pub fn binary_frame(&self, playlist_index: u32) -> Result> { let n = self.manifest.total_chunks; if playlist_index == 0 { - return Ok(encode_manifest(&self.manifest)); + return Ok(encode_manifest_binary(&self.manifest)); } if playlist_index >= 1 && playlist_index <= n { - return self.encode_data(playlist_index - 1); + return self.encode_data_binary(playlist_index - 1); } if playlist_index == n + 1 { - return Ok(encode_frame( + return Ok(encode_frame_binary( FrameKind::End, self.manifest.session_id, 0, @@ -140,7 +108,15 @@ impl TransferSource { bail!("playlist index out of range") } - fn encode_data(&self, seq: u32) -> Result { + /// QFT2 uses Base45 because the whole alphabet is legal in QR alphanumeric + /// mode. This is close to raw byte efficiency without relying on ZXing's + /// rawBytes interpretation, and Android can consume Result.text directly. + pub fn text_frame(&self, playlist_index: u32) -> Result { + let binary = self.binary_frame(playlist_index)?; + Ok(format!("{PREFIX}{}", base45::encode(&binary))) + } + + fn encode_data_binary(&self, seq: u32) -> Result> { let offset = seq as u64 * self.manifest.chunk_size as u64; let remaining = self.manifest.file_size.saturating_sub(offset); let len = remaining.min(self.manifest.chunk_size as u64) as usize; @@ -148,7 +124,7 @@ impl TransferSource { if len > 0 { read_exact_at(&self.file, &mut payload, offset)?; } - Ok(encode_frame( + Ok(encode_frame_binary( FrameKind::Data, self.manifest.session_id, seq, @@ -158,7 +134,7 @@ impl TransferSource { } } -fn encode_manifest(m: &Manifest) -> String { +fn encode_manifest_binary(m: &Manifest) -> Vec { let name = m.file_name.as_bytes(); let name_len = name.len().min(u16::MAX as usize) as u16; let device = m.sender_device.as_bytes(); @@ -173,7 +149,7 @@ fn encode_manifest(m: &Manifest) -> String { payload.extend_from_slice(&name[..name_len as usize]); payload.extend_from_slice(&device_len.to_be_bytes()); payload.extend_from_slice(&device[..device_len as usize]); - encode_frame( + encode_frame_binary( FrameKind::Manifest, m.session_id, 0, @@ -182,16 +158,16 @@ fn encode_manifest(m: &Manifest) -> String { ) } -pub fn encode_frame( +pub fn encode_frame_binary( kind: FrameKind, session_id: u64, seq: u32, total_chunks: u32, payload: &[u8], -) -> String { +) -> Vec { assert!(payload.len() <= u16::MAX as usize); let mut binary = Vec::with_capacity(28 + payload.len()); - binary.extend_from_slice(b"QFT1"); + binary.extend_from_slice(b"QFT2"); binary.push(VERSION); binary.push(kind as u8); binary.extend_from_slice(&session_id.to_be_bytes()); @@ -201,7 +177,7 @@ pub fn encode_frame( binary.extend_from_slice(payload); let crc = crc32(&binary); binary.extend_from_slice(&crc.to_be_bytes()); - format!("{PREFIX}{}", URL_SAFE_NO_PAD.encode(binary)) + binary } pub fn hex_sha256(bytes: &[u8; 32]) -> String { @@ -236,7 +212,9 @@ fn hash_file_streaming(file: &File) -> Result<[u8; 32]> { let mut buf = vec![0u8; 4 * 1024 * 1024]; loop { let n = input.read(&mut buf).context("read input for sha256")?; - if n == 0 { break; } + if n == 0 { + break; + } hasher.update(&buf[..n]); } Ok(hasher.finalize().into()) @@ -245,7 +223,9 @@ fn hash_file_streaming(file: &File) -> Result<[u8; 32]> { fn read_exact_at(file: &File, mut out: &mut [u8], mut offset: u64) -> Result<()> { while !out.is_empty() { let n = read_at_once(file, out, offset)?; - if n == 0 { bail!("unexpected EOF at offset {offset}"); } + if n == 0 { + bail!("unexpected EOF at offset {offset}"); + } offset = offset.saturating_add(n as u64); let (_, rest) = out.split_at_mut(n); out = rest; diff --git a/windows/src/qr.rs b/windows/src/qr.rs index 349f1e5..eec82fa 100644 --- a/windows/src/qr.rs +++ b/windows/src/qr.rs @@ -1,60 +1,22 @@ use anyhow::{Context, Result}; use eframe::egui::ColorImage; use qrcode::{types::Color, EcLevel, QrCode}; -use rayon::prelude::*; const QUIET_MODULES: usize = 4; -/// Render exact black/white pixels with an explicit quiet zone. -pub fn render_qr(text: &str, scale: usize) -> Result { +/// Active optical renderer. QFT2/Base45 text uses only QR alphanumeric +/// characters, allowing the QR encoder to choose a compact alphanumeric data +/// mode. Exact integer module pixels + full quiet zone maximize camera clarity. +pub fn render_qr_fitted(text: &str, target_side: usize) -> Result { let code = QrCode::with_error_correction_level(text.as_bytes(), EcLevel::L) .context("QR payload too large")?; - let modules = code.width(); - let scale = scale.max(1); - let side_modules = modules + QUIET_MODULES * 2; - let side_px = side_modules * scale; - let gray = render_code_gray(&code, side_px); - Ok(ColorImage::from_gray([side_px, side_px], &gray)) + let modules = code.width() + QUIET_MODULES * 2; + let scale = (target_side / modules).max(1); + let side = modules * scale; + Ok(ColorImage::from_gray([side, side], &render_code_gray(&code, side))) } -/// Render 1..=4 independent QR symbols into one fixed-size optical page. -/// A 2x2 page quadruples the number of logical QFT frames presented per -/// display refresh while keeping every symbol standards-compliant. -pub fn render_qr_grid(texts: &[String], canvas_side: usize) -> Result { - let count = texts.len().clamp(1, 4); - if count == 1 { - return render_qr_fitted(&texts[0], canvas_side.max(320)); - } - - let canvas_side = canvas_side.max(640); - let gutter = (canvas_side / 64).clamp(12, 24); - let cell = (canvas_side - gutter * 3) / 2; - let rendered: Vec<(usize, Vec)> = texts[..count] - .par_iter() - .map(|text| render_qr_gray_fitted(text, cell)) - .collect::>>()?; - - let mut canvas = vec![255u8; canvas_side * canvas_side]; - for (index, (side, gray)) in rendered.into_iter().enumerate() { - let col = index % 2; - let row = index / 2; - let cell_x = gutter + col * (cell + gutter); - let cell_y = gutter + row * (cell + gutter); - let x0 = cell_x + (cell.saturating_sub(side)) / 2; - let y0 = cell_y + (cell.saturating_sub(side)) / 2; - for y in 0..side { - let dst = (y0 + y) * canvas_side + x0; - let src = y * side; - canvas[dst..dst + side].copy_from_slice(&gray[src..src + side]); - } - } - Ok(ColorImage::from_gray([canvas_side, canvas_side], &canvas)) -} - - -/// Pairing QR favors scan reliability over maximum capacity. QFTPAIR2 is kept -/// deliberately short, so medium error correction still yields a low-version -/// symbol that phones acquire faster at imperfect angles. +/// Pairing QR stays static and uses M error correction for first-scan reliability. pub fn render_pair_qr(text: &str, target_side: usize) -> Result { let code = QrCode::with_error_correction_level(text.as_bytes(), EcLevel::M) .context("pair QR payload too large")?; @@ -64,38 +26,20 @@ pub fn render_pair_qr(text: &str, target_side: usize) -> Result { Ok(ColorImage::from_gray([side, side], &render_code_gray(&code, side))) } -pub fn render_qr_fitted(text: &str, target_side: usize) -> Result { - let (side, gray) = render_qr_gray_fitted(text, target_side)?; - Ok(ColorImage::from_gray([side, side], &gray)) -} - -fn render_qr_gray_fitted(text: &str, target_side: usize) -> Result<(usize, Vec)> { - let code = QrCode::with_error_correction_level(text.as_bytes(), EcLevel::L) - .context("QR payload too large")?; - let modules = code.width() + QUIET_MODULES * 2; - let scale = (target_side / modules).max(1); - let side = modules * scale; - Ok((side, render_code_gray(&code, side))) -} - -fn render_code_gray(code: &QrCode, side_px: usize) -> Vec { - let modules = code.width(); - let side_modules = modules + QUIET_MODULES * 2; - let scale = (side_px / side_modules).max(1); - let actual_side = side_modules * scale; +fn render_code_gray(code: &QrCode, side: usize) -> Vec { + let qr_width = code.width(); + let modules = qr_width + QUIET_MODULES * 2; + let scale = (side / modules).max(1); + let actual_side = modules * scale; let mut gray = vec![255u8; actual_side * actual_side]; - let colors = code.to_colors(); - - for y in 0..modules { - for x in 0..modules { - if colors[y * modules + x] != Color::Dark { - continue; - } - let x0 = (x + QUIET_MODULES) * scale; - let y0 = (y + QUIET_MODULES) * scale; - for py in y0..y0 + scale { + for y in 0..qr_width { + for x in 0..qr_width { + if code[(x, y)] != Color::Dark { continue; } + let px0 = (x + QUIET_MODULES) * scale; + let py0 = (y + QUIET_MODULES) * scale; + for py in py0..py0 + scale { let row = py * actual_side; - gray[row + x0..row + x0 + scale].fill(0); + gray[row + px0..row + px0 + scale].fill(0); } } }