Metadata-Version: 2.4
Name: gcdrnet
Version: 0.1.0
Summary: Appearance enhancement for camera-captured document images (GCDRNet, IEEE TAI 2023)
Project-URL: Homepage, https://github.com/ersoyfilinte/GCDRNet
Project-URL: Repository, https://github.com/ersoyfilinte/GCDRNet
Project-URL: Paper, https://1drv.ms/f/s!Ak15mSdV3Wy4iYkeUK0TYUAajBPaBQ?e=BzXbk3
Project-URL: Issues, https://github.com/ersoyfilinte/GCDRNet/issues
Author: Jiaxin Zhang, Lingyu Liang, Kai Ding, Fengjun Guo, Lianwen Jin
Maintainer: ersoyfilinte
Keywords: deep-learning,document-enhancement,document-image,image-restoration,ocr-preprocessing,pytorch,shadow-removal,unext
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: opencv-python-headless>=4.10
Requires-Dist: timm<2,>=1.0
Requires-Dist: torch>=2.6
Requires-Dist: torchvision>=0.21
Requires-Dist: tqdm>=4.66
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/ersoyfilinte/GCDRNet/main/figs/architecture.png">
</p>

# GCDRNet

Inference code and a pip-installable library for our paper
[**Appearance Enhancement for Camera-captured Document Images in the Wild**](https://1drv.ms/f/s!Ak15mSdV3Wy4iYkeUK0TYUAajBPaBQ?e=BzXbk3),
accepted for IEEE Transactions on Artificial Intelligence.

GCDRNet enhances the appearance of camera-captured document images by chaining two
networks: **GCNet** predicts a shadow/illumination map and **DRNet** restores the
shadow-corrected image.

## Install

```bash
pip install gcdrnet
```

For GPU support, install a CUDA build of PyTorch from the PyTorch index first (the
plain PyPI install gives you the CPU wheels on most platforms):

```bash
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
pip install gcdrnet
```

From a clone (development install):

```bash
pip install -e ".[dev]"
```

Tested on Python 3.13 with PyTorch 2.11 + CUDA 12.8; requires Python ≥ 3.10 and PyTorch ≥ 2.6.

## Model weights

The weights (~110 MB total) are **not** bundled in the package. They are resolved
lazily the first time you load a model, in this order:

1. an explicit path you pass,
2. `$GCDRNET_CHECKPOINTS_DIR` or `./checkpoints/<name>/checkpoint.pkl` (the repo layout),
3. the on-disk cache (`$GCDRNET_CACHE` or `~/.cache/gcdrnet`),
4. a download from `$GCDRNET_GCNET_URL` / `$GCDRNET_DRNET_URL` (default: the GitHub release).

You can always download the weights manually from the
[paper's link](https://1drv.ms/f/s!Ak15mSdV3Wy4iYkeUK0TYUAajBPaBQ?e=BzXbk3) and place
them as:

```
checkpoints/gcnet/checkpoint.pkl
checkpoints/drnet/checkpoint.pkl
```

or point the library at your own host:

```bash
export GCDRNET_GCNET_URL=https://example.com/gcnet.pkl
export GCDRNET_DRNET_URL=https://example.com/drnet.pkl
```

## Library usage

```python
import cv2
from gcdrnet import GCDRNet

# Loads weights (explicit path, ./checkpoints/, cache, or download — in that order)
model = GCDRNet.from_pretrained(device="cuda")

# BGR ndarray in, BGR ndarray out (OpenCV convention)
enhanced = model.enhance(cv2.imread("doc.jpg"))
cv2.imwrite("doc_enhanced.png", enhanced)

# Convenience helpers
model.enhance_file("doc.jpg", "doc_enhanced.png")   # file in, file out
model.enhance_folder("distorted", "enhanced")        # batch a folder
```

Explicit checkpoint paths:

```python
model = GCDRNet.from_checkpoints(
    gcnet="checkpoints/gcnet/checkpoint.pkl",
    drnet="checkpoints/drnet/checkpoint.pkl",
    device="cpu",
)
```

One-off call with a lazily-loaded, cached default model:

```python
from gcdrnet import enhance_image
enhanced = enhance_image("doc.jpg")   # ndarray or path in, ndarray out
```

Inference runs at the image's native resolution, so GPU memory scales with image
size (~0.6 GiB per megapixel). Images that do not fit are retried automatically on
the CPU (disable with `model.enhance(img, cpu_fallback=False)`).

## Command line

The package installs a `gcdrnet` console command (equivalent to `python -m gcdrnet`):

```bash
gcdrnet --input ./distorted --output ./enhanced
gcdrnet --input ./distorted --output ./enhanced --device cpu
gcdrnet --gcnet path/to/gcnet.pkl --drnet path/to/drnet.pkl
```

From a clone without installing, the historical entry point still works:

```bash
python infer.py --input ./distorted --output ./enhanced
```

Runs on the GPU when one is available and falls back to the CPU otherwise.

## RealDAE

RealDAE (**Real**-world **D**ocument Image **A**ppearance **E**nhancement) is a
real-world dataset designed explicitly for camera-captured document images in the
wild. It contains 600 pairs of degraded camera-captured document images and
corresponding manually enhanced ground-truths (aligned at the pixel level). It can be
downloaded [here](https://1drv.ms/u/s!Ak15mSdV3Wy4iYh8iqUs0tOb4rJpzw?e=m0XBCJ). Some
examples are illustrated below.
<p align="center">
  <img src="https://raw.githubusercontent.com/ersoyfilinte/GCDRNet/main/figs/example.png">
</p>

## Citation

If you are using our code and data, please cite our paper.

```bibtex
@article{zhang2023appearance,
title={Appearance Enhancement for Camera-captured Document Images in the Wild},
author={Zhang, Jiaxin and Liang, Lingyu and Ding, Kai and Guo, Fengjun and Jin, Lianwen},
journal={IEEE Transactions on Artificial Intelligence},
year={2023}}
```
