# DocQuad 产品需求文档 (PRD) v1.0
## 1. 产品概述
**DocQuad** 是一款基于 Rust 2024 开发的高性能、轻量级文档边缘检测库。它旨在解决安卓及跨平台开发中，引入 OpenCV 等大型视觉库导致的包体积臃肿、JNI 调用开销大、内存拷贝频繁等痛点。
* **核心定位**：提供从原始像素流到文档四边形顶点坐标的“最短路径”。
* **设计哲学**：不重复造轮子，通过极致的算法组合与零拷贝内存管理实现高性能。
---
## 2. 目标用户与应用场景
* **目标用户**：安卓应用开发者（移动办公、证件扫描、票据管理类 App）、桌面端高性能扫描工具开发者。
* **应用场景**：
* **实时相机预览流**：在 30fps 的相机流中实时追踪文档边框。
* **静态照片处理**：高分辨率照片的精准文档切边。
* **嵌入式/WASM 场景**：在资源受限的环境下进行几何形状识别。
---
## 3. 功能需求 (Functional Requirements)
### 3.1 核心检测流程
1. **内存适配 (Memory Adaptation)**：支持传入带有 `row_stride` 的原始 Y 通道数据（专门适配 Android CameraX）。
2. **边缘检测 (Edge Detection)**：
* 利用 `fast-canny` 算子提取二值化特征。
* 支持基于图像直方图统计的**自适应阈值计算**。
3. **轮廓提取 (Contour Extraction)**：
* 实现 Suzuki-Abe 算法，从二值图中识别闭合的拓扑路径。
4. **形状拟合与筛选 (Quad Fitting)**：
* 运用 Douglas-Peucker 算法简化轮廓。
* 自动锁定图像中**面积最大且符合凸性约束**的四边形。
5. **坐标排序与纠偏 (Sorting & Perspective)**：
* 统一输出 `[左上, 右上, 右下, 左下]` 的顶点顺序。
* 计算并输出 $3 \times 3$ **单应性矩阵 (Homography Matrix)**。
### 3.2 数学模型支持
库需要能够计算透视变换所需的核心参数。设检测到的顶点为 $(u, v)$，目标矩形顶点为 $(x, y)$，变换关系遵循：
$$\begin{bmatrix} x' \\ y' \\ w' \end{bmatrix} = \mathbf{H} \begin{bmatrix} u \\ v \\ 1 \end{bmatrix}$$
其中 $\mathbf{H}$ 为 $3 \times 3$ 矩阵，由 `glam` 的 SIMD 指令加速计算。
---
## 4. 非功能需求 (Non-Functional Requirements)
### 4.1 性能目标 (Performance)
* **实时性**：在主流 Android 设备（如 2024 年后的中端机）上，处理 1080p 单帧数据耗时应控制在 **15ms** 以内。
* **内存开销**：除了必要的中间二值图缓存外，不再额外分配大型堆空间。
* **零拷贝**：图像输入阶段必须实现 Zero-copy，直接读取外部缓冲区地址。
### 4.2 交付产物 (Deliverables)
* **轻量级动态库**：编译后的 `.so` (arm64-v8a) 目标大小应小于 **2MB**。
* **跨平台核心**：不包含任何平台相关的私有库（如 Android NDK 硬件加速库），确保 100% 纯 Rust 跨平台。
### 4.3 安全性 (Safety)
* **内存安全**：利用 Rust 的所有权模型和 `bytemuck` 的类型安全检查，确保处理非法内存地址时返回 `Error` 而非崩溃。
---
## 5. 技术堆栈 (Technical Stack)
| **语言版本** | **Rust 2024** | 利用最新的语言特性与编译器优化。 |
| **边缘检测** | **fast-canny** | 已实现 SIMD 加速的成熟算子。 |
| **内存/矩阵** | **ndarray / glam** | 处理 Stride 布局的最优解及极致的数学运算。 |
| **几何逻辑** | **geo / geo-types** | 工业级几何算法支持，无缝对接多边形拟合。 |
| **数据映射** | **bytemuck** | 保证 JNI 与内存切片转换的零开销与安全性。 |
---
## 6. 路线图 (Roadmap)
### 第一阶段：MVP (最小可行性产品)
* 实现 `DocBuffer` 的 Stride 访问逻辑。
* 集成 `fast-canny` 并实现自适应阈值。
* 完成 Suzuki-Abe 算法提取轮廓并输出四个顶点。
### 第二阶段：性能优化
* 引入 **多尺度检测策略**（在大分辨率下先降采样找框，再回原图精修）。
* 针对 PC 端引入 `rayon` 并行加速。
### 第三阶段：生态集成
* 提供标准的 FFI 接口文档。
* 提供 Android JNI 层参考实现示例。
---
## 7. 成功标准
* `DocQuad` 在处理速度上优于同等条件的 OpenCV-Android 实现（计入 JNI 转换开销）。
* 库的二进制增量不显著影响宿主 App 的安装包大小。
* 在复杂背景（如桌面杂物）下，文档识别率达到传统视觉算法的主流水平（>90% 典型场景）。
---