---
title: UVDoc-MNN
canonical_url: "https://www.modelscope.cn/models/dr3334/UVDoc-MNN"
md_url: "https://www.modelscope.cn/models/dr3334/UVDoc-MNN.md"
repository: dr3334/UVDoc-MNN
chinese_name: "UVDoc 文档去畸变 MNN FP32"
last_updated: 2026-10-16
license: apache-2.0
downloads: 0
stars: 0
tags:
  - UVDoc
  - MNN
  - document-unwarping
  - fp32
  - int8
  - computer-vision
---

# UVDoc-MNN

> UVDoc-MNN - dr3334 在 ModelScope 开源的模型。PaddlePaddle 官方 UVDoc 权重的第三方 MNN FP32 转换，包含原始转换版和 20 层 SpaceToBatch 图优化版。已在 x86 CPU 验证，ARM 未进行真机验证。用于预测文档去畸变采样网格，需配套前后处理。

dr3334/UVDoc-MNN 是 ModelScope 魔搭社区上的机器学习模型，采用 apache-2.0 许可。

- **Repository**: dr3334/UVDoc-MNN
- **License**: apache-2.0
- **Tags**: UVDoc, MNN, document-unwarping, fp32, int8, computer-vision
- **Downloads**: 0
- **Stars**: 0
- **Last updated**: 2026-10-16

Source: https://www.modelscope.cn/models/dr3334/UVDoc-MNN

---

# UVDoc Grid · MNN（原始 FP32 / 图优化 FP32 / 混合 INT8）

PaddlePaddle 官方 UVDoc 推理权重的第三方 MNN 格式转换，用于文档去畸变的反向采样网格预测。本仓库不是 OCR 识别模型，也没有 PaddlePaddle、UVDoc 原作者或 MNN 的官方背书。

## 2026-10-16 更新：各精度模型怎么选

本次新增经过小规模对照验证的 **INT8 主干 + FP32 回归头混合精度模型**，原来的两个 FP32 文件保持字节不变。以下是本轮新的 x86 测试，不能与后文 2026-10-14 的 Intel 环境历史倍数混用。

| 模型 / 精度 | 发布文件 | 适用情况与边界 |
|---|---|---|
| 原始 FP32 | `uvdoc_grid_fp32_baseline.mnn` | 质量对照与回退基线；保留原始膨胀卷积图。 |
| 图优化 FP32 | `uvdoc_grid_fp32_s2b5_optimized.mnn` | 权重仍为 FP32，20 处 S2B/B2S 图改写；原历史一致性测试通过，代价是较高内存。 |
| 混合 INT8 / FP32 | `uvdoc_int8_baseline_floathead_kl.mnn` | 本轮推荐尝试的轻量版本；43 个卷积执行权重与激活 INT8，最后 2 个坐标回归卷积及下游激活为真正 FP32。须在业务图像和目标设备复验。 |
| 全 INT8 | 不发布权重 | KL 全量量化在 10 张测试图上平均控制点位移约 56.38 px，明显失真，不能当作透明替代品。EMA 备选也在验证阶段淘汰。 |
| FP16 | 未提供 | 本轮没有转换、质量或设备性能验证，不能据此声称支持或加速。 |

混合精度模型大小 **8,262,224 bytes（7.879 MiB）**，相对原始 FP32 30.119 MiB 缩小约 **73.8%**。SHA-256：`7acbe44d83a97929854d5ff683bf573f3c1e4d78cbc682023442f440a8a0b421`。

### 本轮同机性能对照

2026-10-16，Linux x86_64、AMD EPYC 9V74 共享云 CPU，MNN 3.6.1 固定提交 `dbf9ba61b08106a3b43426e295d1a29cb41cc8fe`，AVX512/VNNI，绑定同一组 CPU 0–3。三轮交错批次，预热后每模型每线程档合计 72 次，以下为中位数（ms）。该机器存在调度波动，不能将结果外推到 ARM/Android。

| 模型 | 1 线程推理 | 4 线程推理 | 1 线程流水线 | 4 线程流水线 |
|---|---:|---:|---:|---:|
| 原始 FP32 | 411.96 | 163.71 | 483.96 | 230.55 |
| 图优化 FP32 | 194.04 | 109.06 | 266.15 | 169.49 |
| 混合 INT8，原始膨胀卷积图 | **161.15** | **66.28** | **231.40** | **126.70** |
| 混合 INT8，S2B5 图（仅实验，不另发模型） | 173.20 | 71.10 | 238.66 | 130.98 |

相对已经优化过的 FP32，推荐混合版推理加速为 **1.20×（1 线程）/ 1.65×（4 线程）**，对应延迟降低约 17.0% / 39.2%；4 线程流水线降低 25.2%。4 线程推理 P10/P90：图优化 FP32 78.01/146.01 ms，混合版 53.95/79.27 ms。

流水线包括图像解码、预处理、张量拷贝、推理、原图分辨率 warp 及 uint8 转换；**不包含模型/session 创建、输出编码和写盘**。四线程新进程峰值 RSS：原始 FP32 **151.91 MiB**，图优化 FP32 **180.69 MiB**，混合版 **78.38 MiB**。RSS 含模型加载、输入解码和五次推理，不是 MNN session 内存估计。

### 质量验证与局限

使用 32 张校准、4 张验证、10 张最终留出测试图，按出版物来源拆分，量化流程中互不重叠；最终测试不用于选尺度或候选。图像来自官方 UVDoc 伪照片合成样本，另加 1 张真实拍摄书页作独立压力检查；不是完整公开基准集，也未证明这些图片未用于原始模型训练。

推荐混合版相对原始 FP32，在 10 张留出图（宽 832–1043、高 1148–1309）上：
- 每图平均控制点位移的均值 **0.559 原图像素**；最差单图 P95 **1.488 px**；全部点最大 **2.317 px**。
- 平均矫正图 MAE **2.183/255**，平均 PSNR **32.55 dB**。
- 10 张均通过预先锁定的小规模工程门槛：每图 mean≤1、P95≤2、max≤5 px；测得重复输出一致，1/4 线程结果接近。
- 真实书页（1100×708）：mean **0.615**、P95 **1.636**、max **2.612 px**。

这是对 FP32 的保真度，**不是几何真值准确率，也不是 OCR CER/识别准确率**。样本少且文档类型有限；位移随原图尺寸缩放。已检查对照图，但并非对所有生产图像的视觉质量保证。未测试 ARM、Android、GPU/NPU，也未跑 MNN 全引擎回归；部署前应先逐图对照，再测本机性能。FP32 始终保留为质量回退。

### 实现、复现和许可边界

仅 `skip_quant_op_names` 可能保留头部 INT8 激活元数据而导致坐标截断。本版通过 `float_tail.cpp` 保留/恢复最后两个浮点卷积，并清除其下游输出的 quantInfo；运行时审计确认实际为 **43 个整数卷积 + 2 个浮点卷积**。不需要修改 MNN 推理引擎源码。该 x86 INT8 路径直接膨胀卷积优于 S2B/B2S 额外改写，因此发布直接图版本。

新增 `uvdoc_int8_reproduction_source.zip` 包含量化/构建/推理/评估源码、数据来源与拆分标识、方法及数值报告。使用仓库原始 FP32 文件作为输入，按包内说明构建 MNN 并以自己有权处理的图像重新校准。模型的输入输出仍为 FP32，外部协议和下文前后处理约定不变；INT8 是内部计算精度，不能直接喂 uint8。

不上传校准/验证/测试照片、矫正图或运行库。原权重许可、来源、归属及下文权利链局限继续适用；数据集软件 MIT 许可不能推定覆盖所有第三方页面纹理和照片。本次新增辅助代码及 MNN 依赖许可见源码包说明。失败的全 INT8 仅保留复现实验代码和数值记录，不提供其权重下载。

---

## 原 FP32 发布说明与历史验证（2026-10-14）

以下保留原 FP32 转换、图优化与历史验证说明；其中“本轮发布整理”指 2026-10-14 的 FP32 发布，不指上面的 2026-10-16 新量化测试。

## 两个模型怎么选

| 文件 | 内容 | 大小 / SHA-256 |
| --- | --- | --- |
| `uvdoc_grid_fp32_baseline.mnn` | 已验证的原始 FP32 转换版，内存占用较低 | 31,581,956 bytes；`daa02297e339fdb26b921c9f11cd5a39fb08fa0f92445bf39cd381ff9dc33c3d` |
| `uvdoc_grid_fp32_s2b5_optimized.mnn` | 在同一权重上改写 20 个 5×5 dilation=3 卷积，已在下述 x86 CPU 配置验证 | 31,588,668 bytes；`9d1ad29c2f72d650b2950d17924a90219973018dc589e5cd1e283759f4cf79ba` |

两个文件只是为发布清楚命名，分别对应原产物 `uvdoc_grid_fp32.mnn` 和 `uvdoc_grid_fp32_s2b5.mnn`。本轮发布整理仅恢复已有产物、校验字节、整理文档与源码，没有重新运行模型或新增性能测试。

配套 `uvdoc_mnn_reproduction_source.zip` 包含网格推理、C++ 前后处理、Paddle→ONNX 转换、固定图改写、权重审计与成对计时源码。具体构建和复现步骤见包内 `README.md`。仓库不包含样图、样图推理输出、原始运行日志、MNN 运行库二进制或 ARM 实验包。

## 输入输出及前后处理

| 项目 | 协议 |
| --- | --- |
| 输入名 | `image_712x488` |
| 输入 | `[1,3,712,488]`，float32，NCHW，BGR；uint8 转 float32 后乘 float32(1/255) |
| 输出名 | `grid_45x31` |
| 输出 | `[1,2,45,31]`，float32；通道 0=x，通道 1=y，归一化反向采样坐标 |

仅支持 batch=1 和固定 H=712、W=488 的核心输入；`.mnn` 文件本身不输出矫正后的图像。输入图像须按 `align_corners=True` 双线性插值缩放。输出网格按同一坐标约定放大至原图大小，再以 bilinear、zeros padding、align_corners=True 采样原图。负坐标取 floor，四个邻点分别判断边界；BGR→RGB，乘 255 后直接 uint8 截断。

请配合源码包中的 `uvdoc_math.cpp` 前后处理。OpenCV 默认 resize 的坐标约定及常用 remap 插值表不保证与此浮点逐点实现相同。正常 MNN 推理不依赖 Paddle；Paddle 仅用于转换和参考验证。

## 来源、转换和优化范围

- 直接来源：[Paddle 官方 BOS 推理包](https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/UVDoc_infer.tar)。
- 对应 [PaddlePaddle/UVDoc 固定版本](https://huggingface.co/PaddlePaddle/UVDoc/tree/16c3f0ea9c2f0c6a57e24160f7eeaa7574613fa3)，revision `16c3f0ea9c2f0c6a57e24160f7eeaa7574613fa3`。历史核验中，结构、权重和配置的 SHA-256 与该版本一致。
- 原始 `inference.pdiparams`：32,054,311 bytes，SHA-256 `810488899520e0da843b9bd9769ba4949f1c81e357f0eceb12d4a7da459c3eca`。
- 原始 `inference.json`：SHA-256 `2c2bc3e0f15e782cf8f2ad411b5033d99ca504fe88648f8054a5e925ba2336e0`。
- 原始 BOS 压缩包：SHA-256 `15d79c6bcbf738b7e132eedff6ed57c7e834c73cbc140a1fff8fd8ab9c2a35b9`。

原转换于 2026-10-14 完成：PaddlePaddle 3.3.1 从同一静态程序提取网格核心；Paddle2ONNX 2.1.0 导出 opset 17；MNN 3.6.1 固定提交 `92b8e60b8c38b2069a232455622651154b53a519` 转 FP32，`keepInputFormat=1`、`optimizeLevel=1`。原尺寸 resize/grid_sample 放在配套 C++ 前后处理中。没有重训练、更换 checkpoint、降低输入分辨率、量化或改变权重 FP32 精度。

优化版将 20 个 5×5 dilation=3 卷积替换为等价的 SpaceToBatchND → 5×5 dilation=1 VALID 卷积 → BatchToSpaceND，以利用 MNN 现有 Winograd 路径。45 个卷积的 7,887,776 个权重 float 和 4,194 个 bias float 逐位相同，融合激活保留；85 个节点变为 125 个。固定特征尺寸为 178×122、89×61、45×31，图改写不是任意模型或动态尺寸的通用优化器。数学操作等价，FP32 运算顺序可能不同，不保证逐位等价。

此次已验证图优化没有修改 MNN 生产内核，也不需要 ARM Raster 默认关闭补丁。任何 ARM 实验补丁及其包均不随本仓库分发。

## 已有数值验证（2026-10-14）

- 原转换版在 Linux x86_64 CPU FP32、1/4 线程上完成 Paddle→ONNX→MNN 对照、输入/后处理验证、相关 MNN 算子测试。两张历史真实样图的最终 8bit 图相对 Paddle 最大通道差为 1。
- 优化版使用 6 张历史真实样图 × AVX2/AVX512 × 1/4 线程，共 24 种图像/配置组合通过原门禁；相对 Paddle 核心网格最大绝对差最差为 `1.1862e-5`，最终 8bit RGB 最大通道差均为 1；相对原 MNN 最大通道差最差为 2。相同配置重复推理最大差为 0。
- 192 项独立微测覆盖三种真实特征尺寸、带/不带 ReLU、零/常量/固定随机/边角脉冲、两 ISA 和 1/4 线程。关闭 Winograd 的 96 项符合 `|A−B| ≤ 1e-5 + 1e-5|A|`；默认 Winograd 的另外 96 项记录舍入差，单算子最大绝对差可达 0.002337，不能称作任意中间激活都满足 1e-4 的逐元素等价。
- 整体门禁未放宽：网格最大差 <1e-4；原图单轴坐标偏差 <0.25 px；最终 8bit 图 MAE <0.5、PSNR >45 dB；重复网格差 ≤1e-7。这些指标检验转换一致性，不代表 OCR 或通用文档质量水平。

样图、参考输出和原始内部日志均未打包；受限或未经确认可再分发的图片也不提供下载脚本。复现者应使用有权处理的自备图像。源码包提供核心转换、推理和成对测试入口，不声称可以在没有原测试图像的情况下重建全部历史图像指标。

## 已有性能数据（不是本轮新测试）

Linux x86_64、Intel Xeon Platinum 8370C 共享云 CPU，MNN 固定上述提交。每行在同一 ISA 运行库、同输入、同线程下比较原版 A 和优化版 B，单位 ms：

| ISA | 线程 | 原版中位数 | 优化版中位数 | 加速比 |
| --- | ---: | ---: | ---: | ---: |
| AVX2 | 1 | 478.97 | 269.05 | 1.78× |
| AVX2 | 4 | 246.01 | 149.57 | 1.64× |
| AVX512 | 1 | 357.11 | 192.02 | 1.86× |
| AVX512 | 4 | 204.99 | 118.27 | 1.73× |

每配置 3 次独立 session，每次 4 轮预热 + 8 轮保留，共 24 组 A/B，交替 AB/BA；1 线程绑定一个允许的逻辑 CPU，4 线程绑定同一组四个。仅计时 runSession；输入每轮恢复，加载、I/O、输入输出拷贝、resize/warp 和正确性检查均不计入。保留全部样本，没有剔除调度离群值。不同 ISA 的绝对延迟不可用来单独归因图优化效果。

代价是 MNN session 内存估计增加约 28 MB：AVX2 1/4 线程分别由 59.48/59.50 MB 增至 87.85/87.88 MB；AVX512 分别由 70.09/68.38 MB 增至 98.71/97.01 MB。这是 MNN session 估计，既不是 RSS，也不是单模型部署的进程峰值。

## 限制

- 性能与数值实測范围仅为上述 x86 CPU 配置；ARM 相关工作只有源码、静态检查和 host 编译层面的准备，没有 ARM 真机数值或性能测试，不能宣称手机端加速。
- Android、ARM、OpenCL、Vulkan、Metal、MTK NPU 和 FP16 都需在目标设备另行验证；INT8 的新增 x86 结果见上文，其他设备仍未验证。移动端请先逐图对照原版和优化版，再测速度及内存；内存紧张时原版仍有价值。
- 未重新跑完整 DocUNet/UVDoc 基准集，没有 OCR CER 或业务效果保证。模糊、复杂折痕、局部拉伸、手指/背景等问题仍可能存在。

## 许可、归属和来源边界

固定 HF 版本的[官方模型卡](https://huggingface.co/PaddlePaddle/UVDoc/blob/16c3f0ea9c2f0c6a57e24160f7eeaa7574613fa3/README.md)声明 `license: apache-2.0`。此声明针对与本转换源权重哈希匹配的模型仓库，并非仅从 Paddle 推理代码许可推断。`LICENSE` 保留 Apache-2.0 正文；`ATTRIBUTION.md` 记录来源及修改；`UVDoc-MIT.txt` 保留原研究项目 MIT 归属。

Paddle 权重与原作者 checkpoint 的精确关系、完整训练数据谱系和潜在第三方义务尚未完全说明。历史许可核对时，相关 [PaddleX issue #5187](https://github.com/PaddlePaddle/PaddleX/issues/5187)开放且无评论；未答复不是禁止分发的证据，也不等于权利链已全部澄清。本文不提供商用合法性、权属或不侵权保证。

UVDoc 原作者代码 MIT 许可归属 Copyright (c) 2023 Tanguy MAGNE；保留此归属不代表已证明 Paddle 权重与原作者 checkpoint 逐位对应。源码包中的第三方许可及新增辅助代码范围见包内归属说明。

论文：Floor Verhoeven, Tanguy Magne, Olga Sorkine-Hornung. “UVDoc: Neural Grid-based Document Unwarping.” SIGGRAPH Asia 2023. [DOI](https://doi.org/10.1145/3610548.3618174) · [原作者仓库](https://github.com/tanguymagne/UVDoc) · [MNN](https://github.com/alibaba/MNN)