fredcallagan/uvdoc-grid-onnx

UVDoc Grid Output - Document Unwarping ONNX Model

This is an ONNX export of the UVDoc document unwarping model, modified to output a coordinate grid instead of an image. This enables high-resolution document unwarping via cv2.remap().

Model Description

UVDoc is a deep learning model for correcting perspective distortion and curvature in photographed documents. Unlike the PaddlePaddle ONNX variant that outputs a fixed 288x288 image, this version outputs a coordinate mapping grid that can be applied to images of any resolution.

Key Difference: Grid Output vs Image Output

Approach	Output	Quality
Image-output models	288x288 RGB image	Poor (must upscale)
This grid-output model	45x31 coordinate grid	Native resolution

Model Details

• Architecture: UVDoc (ResNet-based encoder-decoder)
• Input: (1, 3, 720, 496) - RGB image, normalized [0, 1]
• Output: (1, 2, 45, 31) - Coordinate grid in [-1, 1] range
• ONNX Opset: 16
• Size: ~30 MB

Input Specifications

Property	Value
Shape	(batch, 3, 720, 496)
Format	RGB (not BGR)
Range	[0, 1] (normalized)
Layout	NCHW (batch, channels, height, width)

Output Specifications

Property	Value
Shape	(batch, 2, 45, 31)
Channels	2 (x, y coordinates)
Range	[-1, 1] (normalized coordinates)
Layout	NCHW (batch, channels, height, width)

Usage

With ONNX Runtime (Python)

import cv2
import numpy as np
import onnxruntime as ort

# Load model
session = ort.InferenceSession("UVDoc_grid.onnx", providers=['CPUExecutionProvider'])

# Load and preprocess image
image = cv2.imread("warped_document.jpg")
h_orig, w_orig = image.shape[:2]

# Prepare model input (720x496 RGB normalized)
img_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
resized = cv2.resize(img_rgb, (496, 720))  # width, height
blob = resized.astype(np.float32) / 255.0
blob = np.transpose(blob, (2, 0, 1))[None]  # (1, 3, 720, 496)

# Run inference
result = session.run(None, {'image': blob})[0]  # (1, 2, 45, 31)

# Convert grid to remap coordinates
grid = np.transpose(result[0], (1, 2, 0))  # (45, 31, 2)
grid_up = cv2.resize(grid, (w_orig, h_orig), interpolation=cv2.INTER_LINEAR)

map_x = ((grid_up[..., 0] + 1) / 2) * (w_orig - 1)
map_y = ((grid_up[..., 1] + 1) / 2) * (h_orig - 1)

# Apply unwarping to original high-res image
unwarped = cv2.remap(
    image,
    map_x.astype(np.float32),
    map_y.astype(np.float32),
    interpolation=cv2.INTER_CUBIC,
    borderMode=cv2.BORDER_REPLICATE
)

cv2.imwrite("unwarped_document.jpg", unwarped)

With HuggingFace Hub

from huggingface_hub import hf_hub_download

model_path = hf_hub_download(
    repo_id="YOUR_USERNAME/uvdoc-grid-onnx",
    filename="UVDoc_grid.onnx"
)

Training Details

This model was not retrained. It is a direct ONNX export of the original UVDoc weights from tanguymagne/UVDoc, with a wrapper to output only the 2D coordinate grid (discarding the 3D shape output).

Original Model

• Paper: UVDoc: Neural Grid-based Document Unwarping
• Authors: Floor Verhoeven, Tanguy Magne, Olga Sorkine-Hornung (ETH Zurich)
• Published: SIGGRAPH Asia 2023
• Original Repository: tanguymagne/UVDoc

Limitations

• Input must be resized to 720x496 for inference (grid output is always 45x31)
• Works best on documents with visible text/content (needs features for grid estimation)
• May not handle extreme perspective distortions well
• CPU inference takes ~100-200ms per image

Citation

If you use this model, please cite the original UVDoc paper:

@inproceedings{UVDoc,
    title={{UVDoc}: Neural Grid-based Document Unwarping},
    author={Floor Verhoeven and Tanguy Magne and Olga Sorkine-Hornung},
    booktitle = {SIGGRAPH ASIA, Technical Papers},
    year = {2023},
    url={https://doi.org/10.1145/3610548.3618174}
}

License

This ONNX export is provided under the Apache 2.0 license. The original UVDoc model is also Apache 2.0 licensed. See the original repository for full license details.