Metadata-Version: 2.4
Name: hintauc
Version: 0.2.1
Summary: Deterministic region-based hint generation (DHT) and Hint-AUC evaluation for line-art colorization
Author: Koki Madono
License-Expression: MIT
Project-URL: Homepage, https://github.com/MADONOKOUKI/DetFill-with-DHT
Project-URL: Repository, https://github.com/MADONOKOUKI/DetFill-with-DHT
Project-URL: Issues, https://github.com/MADONOKOUKI/DetFill-with-DHT/issues
Project-URL: Paper, https://doi.org/10.1109/TVCG.2026.3738401
Keywords: line art,colorization,evaluation,hint generation,Hint-AUC,diffusion
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: opencv-python
Requires-Dist: scikit-image>=0.19
Requires-Dist: fil_finder<1.8,>=1.7
Requires-Dist: astropy<6,>=5.0
Requires-Dist: pillow
Provides-Extra: perceptual
Requires-Dist: torch; extra == "perceptual"
Requires-Dist: torchvision; extra == "perceptual"
Requires-Dist: lpips; extra == "perceptual"
Requires-Dist: open_clip_torch; extra == "perceptual"
Requires-Dist: transformers; extra == "perceptual"
Requires-Dist: dreamsim; extra == "perceptual"
Requires-Dist: torchmetrics; extra == "perceptual"
Requires-Dist: dists-pytorch; extra == "perceptual"
Requires-Dist: torch-fidelity; extra == "perceptual"
Dynamic: license-file

# DetFill-with-DHT: Deterministic Hints and Hint-AUC for Line Art Colorization

[![IEEE TVCG 2026](https://img.shields.io/badge/IEEE%20TVCG-2026-blue)](https://doi.org/10.1109/TVCG.2026.3738401)
[![DOI](https://img.shields.io/badge/DOI-10.1109%2FTVCG.2026.3738401-blue)](https://doi.org/10.1109/TVCG.2026.3738401)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](docs/setup.md)
[![PyTorch 2.5](https://img.shields.io/badge/PyTorch-2.5-ee4c2c)](docs/setup.md)
[![PyPI](https://img.shields.io/pypi/v/hintauc)](https://pypi.org/project/hintauc/)
[![Releases](https://img.shields.io/github/v/release/MADONOKOUKI/DetFill-with-DHT)](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases)

Official implementation of **"Hint-AUC: Deterministic Region-based Hint Generation for Line Art Colorization
Evaluation"**, IEEE Transactions on Visualization and Computer Graphics (TVCG), 2026.

[Koki Madono](https://madonokouki.github.io/) · [Yuan Mingcheng](https://esslab.jp/en/members/) · [Edgar Simo-Serra](https://esslab.jp/~ess/) — Waseda University

[Paper](https://doi.org/10.1109/TVCG.2026.3738401) · [Library on PyPI](https://pypi.org/project/hintauc/) · [Checkpoints and data](https://github.com/MADONOKOUKI/DetFill-with-DHT/releases)

![Deterministic hint generation pipeline](assets/readme/dht_pipeline.png)

Hint-based line art colorization is usually evaluated with randomly sampled colour hints, so the scores change from
run to run. This repository provides **DHT**, a deterministic hint generator that turns an illustration into the same
scribble and dot hints every time; **Hint-AUC**, one score over the whole range of hint ratios, from no hints to fully
hinted; and **DetFill**, a pixel-space diffusion colorization model trained with these hints. All checkpoints, the
evaluation inputs and the scripts that reproduce the paper are released.

## Getting started

- **Installation** — see [Setup](docs/setup.md). The library is one command (`pip install hintauc`); DetFill and
  the reproduction scripts use a conda environment that the scripts create for you.
- **Model zoo** — see [Model zoo](checkpoints/README.md): every released checkpoint and data file with its size,
  SHA-256, download link and the paper item it belongs to.
- **Reproducing the paper** — see [Reproducing the paper](reproduce/README.md): Fig. 9 with one command (the
  Replicability-Stamp script), every table rebuilt from the released metrics, every experiment re-run on example
  images, full table rows, and training.
- **Added features (since the paper) for improving our library** — see [Added features](docs/added_features.md).
- **How it works** — see [Detailed explanation](docs/detail_explanation.md): each component, what is bit-exact and
  what is not.

## Quick start

```python
import hintauc

hints = hintauc.generate_hints("illustration.png", size=64)        # image -> deterministic hints
color, mask = hints.at_ratio(0.10, hint_type="scribble")           # hints of the largest 10 % of the regions
hints.save("out/illustration")                                     # files in the DetFill data layout

evaluator = hintauc.Evaluator(metrics=("psnr", "lpips", "dreamsim"))
print(evaluator("colorized.png", "ground_truth.png"))              # the paper's metrics
```

- Command line: `hintauc generate image.png --ratio 0.1` and `hintauc eval pred_dir gt_dir --metrics mse psnr ssim`.
- DetFill inference over the hint-ratio grid: `cd detfill && GPU=0 bash run_inference.sh scribble`
  (data layout and options in [detfill/README.md](detfill/README.md)).
- Fig. 9 of the paper from a fresh checkout: `bash replicability/run.sh` (about 3 minutes on a GPU).

## Repository structure

```
docs/              setup, added features, detailed explanation
replicability/     one-command reproduction of Fig. 9 (Replicability-Stamp entry point)
reproduce/         reproduction package: scripts/, examples/, expected/ (released metrics), data/, paper_experiments/
hintauc/           the library: hints.py, metrics.py, auc.py, cli.py
detfill/           the DetFill model (BBDM fork): training, inference, configs
hint_generation/   original research scripts behind the library
evaluation/        original evaluation scripts
checkpoints/       model zoo: inventory of all released files with hashes
assets/            images for this page; representative image for the Replicability Stamp
```

## License

MIT License ([LICENSE](LICENSE)); third-party components are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
`detfill/` is built on [BBDM](https://github.com/xuekt98/BBDM) (MIT). Released data files are derived from
Danbooru2021 illustrations and are provided for non-commercial research use only.

## Contributing

Contributions are welcome. See [contributing](CONTRIBUTING.md) and the [code of conduct](CODE_OF_CONDUCT.md).

## Citing

```bibtex
@article{madono2026hintauc,
  title   = {Hint-AUC: Deterministic Region-based Hint Generation for Line Art Colorization Evaluation},
  author  = {Madono, Koki and Mingcheng, Yuan and Simo-Serra, Edgar},
  journal = {IEEE Transactions on Visualization and Computer Graphics},
  year    = {2026},
  doi     = {10.1109/TVCG.2026.3738401}
}
```
